Architecture

Patcha is a monorepo: a Next.js web app, a FastAPI backend (hook simulation + DEX adapters), a Rust hook runtime, an Anchor hook-executor program, a TypeScript SDK, a CLI, and a VS Code extension.

Requests flow from the web app to the backend through same-origin /api/* route handlers (no cross-origin calls). The Anchor program enforces installed hooks via PDA-derived accounts on Orca Whirlpools and Raydium CLMM pools.

Expanded, public-facing architecture docs are published alongside the open codebase.

Hooks specification

Patcha maps Uniswap v4's ten hook callbacks onto the Solana CLMM lifecycle (Orca Whirlpools and Raydium CLMM). A hook is a small module installed against a pool; the on-chain executor invokes it at the matching point in the pool's lifecycle.

Uniswap v4 callbacks → Solana CLMM trigger

Uniswap v4 callback	Patcha CLMM trigger
beforeInitialize	before pool/position init
afterInitialize	after pool/position init
beforeAddLiquidity	before increaseLiquidity
afterAddLiquidity	after increaseLiquidity
beforeRemoveLiquidity	before decreaseLiquidity
afterRemoveLiquidity	after decreaseLiquidity
beforeSwap	before swap CPI
afterSwap	after swap CPI
beforeDonate	before fee donation
afterDonate	after fee donation

Builtin hooks

Hook	Category	Reacts on
Dynamic Fee	fees	beforeSwap, afterSwap
TimeLock	timing	beforeAddLiquidity, beforeRemoveLiquidity
WhitelistGate	gating	beforeSwap, beforeAddLiquidity
RangeOrder	range	afterSwap
AntiMEV	mev	beforeSwap, afterSwap
KYCGate	kyc	beforeSwap, beforeAddLiquidity

The six builtin hooks and their parameter schemas are shared across the web designer, SDK, CLI, and VS Code extension from a single hook-library package, so all surfaces agree on slugs, parameters, and on-chain encoding.

Reference: Uniswap v4 hooks whitepaper (Uniswap Labs, 2024).

Security notes

Core principles enforced across the on-chain program and the backend.

Anchor PDA + account constraints

• Every privileged account relationship is enforced with has_one and PDA seed derivation rather than runtime address comparison.
• PDA seeds:
  • ["hook_registry"] — global registry
  • ["hook", slug] — per-hook metadata
  • ["installation", pool, slug] — per-pool install (the LP authority signs)
  • ["params", installation] — hook parameters

Secret handling

• Secrets (Helius API key / RPC URL, database and cache URLs, keypair paths) are server-only and never carry a NEXT_PUBLIC_ prefix, so they are never inlined into the client bundle.
• The wallet adapter uses a public RPC only.
• Helius DAS calls are proxied server-side via /api/das/*; the key stays on the server.

CORS

• The backend allows a fixed list of explicit origins (no wildcard) with credentials enabled. The web app talks to its own /api/* route handlers, so browser requests are same-origin.