Architecture

This is a placeholder. The authoritative system architecture — diagram, monorepo layout, data model, API endpoints, Anchor PDA design, and CORS/secret policy — lives in ../_ARCHITECTURE.md.

Expanded, public-facing architecture docs are written in Phase 10.

Hooks specification (placeholder)

Patcha maps Uniswap v4's 10 hook callbacks onto the Solana CLMM lifecycle (Orca Whirlpools, Raydium CLMM). Full signatures and semantics land in Phase 7.

Uniswap v4 callbacks → Solana CLMM mapping

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

The 6 builtin hooks and their parameter schemas are defined in packages/hook-library/src/index.ts.

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

Security notes (placeholder)

Detailed threat model and audit notes land in Phase 7/10. Core principles:

Anchor PDA + account constraints

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

Secret handling

• Secrets (HELIUS_API_KEY, HELIUS_RPC_URL, DATABASE_URL, REDIS_URL, keypair paths) are server-only and never carry a NEXT_PUBLIC_ prefix.
• Wallet adapter uses the public RPC (api.mainnet-beta.solana.com) only.
• Helius DAS calls are proxied server-side via /api/das/* → Railway /das/*.

CORS

• CORS_ORIGINS lists 4 explicit origins, no wildcard, allow_credentials=true.