How orca-so/whirlpools works
Project Type and Purpose
• This is an open-source monorepo for a Solana concentrated-liquidity AMM (“Whirlpools”) and its accompanying SDKs.
• Contains on-chain programs written in Rust under /programs/whirlpool, plus client libraries in TypeScript (/ts-sdk) and Rust (/rust-sdk), legacy SDKs, documentation, examples, and CI/CD scripts.
Key Architectural Layers
a. Client Layer
• /ts-sdk/client & /rust-sdk/client: high-level entry points for end applications (web, bots, scripts).
• Accepts user inputs: create pool, swap, increase/decrease liquidity, harvest rewards, set fees, etc.
b. Core SDK Layer
• /ts-sdk/core & /rust-sdk/core: pure-compute modules — quoting engines, math utilities, type definitions.
• Transforms client requests into low-level instructions and computes optimal parameters (e.g., price ticks, liquidity increments).
c. Auto-Generated Client Layer
• /ts-sdk/client/src/gpa & /src/pda: account parsers, PublicKey derivations, instruction builders.
d. On-Chain Program Layer
• /programs/whirlpool: Anchor-based Rust smart contract implementing state machines, CPI interfaces, event logs, instruction handlers.
• Uses modules: state/, instructions/, manager/, math/, util/.
e. Legacy & Integration Tests
• /legacy-sdk/* & /examples/*: reference implementations and integration test suites against the deployed program.
a. Topmost: Client Applications
b. Next: Client SDK Layer
• Inside, show sub-components:
• Instruction Builders (PDA derivation, input validation)
• Account Parsers (GPA modules)
c. Middle: Core SDK Layer
• Sub-modules: PriceMath, LiquidityMath, SwapQuote, FeeQuote.
d. Lower: On-Chain Program Interface
• “Transaction Instructions” flowing into the Program.
e. Bottom: On-Chain Smart Contract
• instructions/* handlers
• state/* account layouts
• manager/* logic modules
• math/* computational routines
• Event logs or return data can flow back up as confirmations.
Relationships and Cascading Actions
• User triggers client API → SDK validates and builds a transaction.
• SDK calls Core modules to compute optimal parameters.
• Instruction Builders assemble bytes and invoke Solana RPC.
• On-chain program deserializes instruction, runs business logic, mutates state.
• Confirmation and events are returned to client SDK, then surfaced to user.
Architectural Patterns & Principles
• Layered architecture: clear separation between UI/CLI → SDK → Core Compute → On-chain code.
• Modularization: each library/package has a single responsibility (account parsing, math, instruction building, on-chain logic).
• Reuse via Nx monorepo: shared config, CI workflows, changesets across all packages.
• IDL-driven client generation for type safety and versioning.