# orca-so/whirlpools architecture

> Architecture diagram of the GitHub repository orca-so/whirlpools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/orca-so/whirlpools
- Repository: https://github.com/orca-so/whirlpools

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Client Applications" 
        direction TB
        WebApp["Web App"]:::app
        CLI["CLI"]:::app
        Bot["Bot"]:::app
    end

    %% Client SDK Layer
    subgraph "Client SDK Layer" 
        direction TB
        subgraph "TypeScript Client SDK" 
            direction TB
            TS_Index["Entry: index.ts"]:::clientSDK
            TS_GPA["Account Parsers (GPA)"]:::clientSDK
            TS_PDA["PDA Derivations"]:::clientSDK
        end
        subgraph "Rust Client SDK" 
            direction TB
            Rust_Index["Entry: lib.rs"]:::clientSDK
            Rust_GPA["Account Parsers (GPA)"]:::clientSDK
            Rust_PDA["PDA Derivations"]:::clientSDK
        end
    end

    %% Core SDK Layer
    subgraph "Core SDK Layer"
        direction TB
        subgraph "TypeScript Core SDK" 
            direction TB
            TS_Core["Core Library"]:::core
            TS_Tests["Tests"]:::core
        end
        subgraph "Rust Core SDK"
            direction TB
            Rust_Core["Core Library"]:::core
            Rust_Math["Math Utilities"]:::core
            Rust_Quote["Quote Engines"]:::core
            Rust_Types["Type Definitions"]:::core
        end
    end

    %% IDL & RPC Layer
    IDL["Anchor Program IDL & Client"]:::idl

    %% On-Chain Program
    subgraph "On-Chain Program Layer"
        direction TB
        Whirlpool["Whirlpool Program"]:::onchain
        subgraph "Modules"
            direction TB
            Instr["instructions/*"]:::onchain
            State["state/*"]:::onchain
            Manager["manager/*"]:::onchain
            OCMath["math/*"]:::onchain
            Util["util/*"]:::onchain
            Events["events.rs & errors.rs"]:::onchain
        end
    end

    %% Flow
    WebApp -->|"User Action: swap(), openPosition(), ..."| TS_Index
    CLI -->|"User Action"| TS_Index
    Bot -->|"User Action"| Rust_Index

    TS_Index -->|"buildInstruction()"| TS_PDA
    TS_Index -->|"parseAccounts()"| TS_GPA
    Rust_Index -->|"buildInstruction()"| Rust_PDA
    Rust_Index -->|"parseAccounts()"| Rust_GPA

    TS_PDA -->|"requestQuote()"| TS_Core
    TS_GPA -->|"requestQuote()"| TS_Core
    Rust_PDA -->|"requestQuote()"| Rust_Core
    Rust_GPA -->|"requestQuote()"| Rust_Core

    TS_Core -->|"quote = getSwapQuote(params)"| TS_Index
    Rust_Core -->|"quote = getSwapQuote(params)"| Rust_Index

    TS_Index -->|"RPC Request → Solana Network"| IDL
    Rust_Index -->|"RPC Request → Solana Network"| IDL

    IDL -->|"Transaction Instructions"| Whirlpool
    Whirlpool -->|"processTransaction"| Instr
    Instr -->|"update Accounts"| State
    Instr -->|"call Manager Logic"| Manager
    Instr -->|"use Math Routines"| OCMath
    Instr -->|"use Utilities"| Util
    Instr -->|"emit Logs"| Events

    %% Click Events
    click TS_Index "https://github.com/orca-so/whirlpools/blob/main/ts-sdk/client/src/index.ts"
    click TS_GPA "https://github.com/orca-so/whirlpools/tree/main/ts-sdk/client/src/gpa"
    click TS_PDA "https://github.com/orca-so/whirlpools/tree/main/ts-sdk/client/src/pda"
    click Rust_Index "https://github.com/orca-so/whirlpools/blob/main/rust-sdk/client/src/lib.rs"
    click Rust_GPA "https://github.com/orca-so/whirlpools/tree/main/rust-sdk/client/src/gpa"
    click Rust_PDA "https://github.com/orca-so/whirlpools/tree/main/rust-sdk/client/src/pda"
    click TS_Core "https://github.com/orca-so/whirlpools/blob/main/ts-sdk/core/src/lib.rs"
    click TS_Tests "https://github.com/orca-so/whirlpools/tree/main/ts-sdk/core/tests"
    click Rust_Core "https://github.com/orca-so/whirlpools/blob/main/rust-sdk/core/src/lib.rs"
    click Rust_Math "https://github.com/orca-so/whirlpools/tree/main/rust-sdk/core/src/math"
    click Rust_Quote "https://github.com/orca-so/whirlpools/tree/main/rust-sdk/core/src/quote"
    click Rust_Types "https://github.com/orca-so/whirlpools/tree/main/rust-sdk/core/src/types"
    click Whirlpool "https://github.com/orca-so/whirlpools/blob/main/programs/whirlpool/src/lib.rs"
    click Instr "https://github.com/orca-so/whirlpools/tree/main/programs/whirlpool/src/instructions"
    click State "https://github.com/orca-so/whirlpools/tree/main/programs/whirlpool/src/state"
    click Manager "https://github.com/orca-so/whirlpools/tree/main/programs/whirlpool/src/manager"
    click OCMath "https://github.com/orca-so/whirlpools/tree/main/programs/whirlpool/src/math"
    click Util "https://github.com/orca-so/whirlpools/tree/main/programs/whirlpool/src/util"

    %% Styles
    classDef app fill:#FDEBD0,stroke:#E67E22,color:#000;
    classDef clientSDK fill:#D4E6F1,stroke:#2E86C1,color:#000;
    classDef core fill:#D5F5E3,stroke:#27AE60,color:#000;
    classDef idl fill:#E8DAEF,stroke:#8E44AD,color:#000;
    classDef onchain fill:#FADBD8,stroke:#C0392B,color:#000;
```
