# ellipsis-labs/phoenix-v1 architecture

> Architecture diagram of the GitHub repository ellipsis-labs/phoenix-v1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ellipsis-labs/phoenix-v1
- Repository: https://github.com/ellipsis-labs/phoenix-v1

## Overview

Step 1: Identify the project type and purpose
- This is a Solana on-chain decentralized limit orderbook (“Phoenix”) written in Rust.
- It exposes a program that clients invoke via Solana RPC calls to place/cancel orders, settle trades, emit events, and manage market state.

Step 2: Analyze the file structure
- Top-level build and config:
- Cargo.toml/Cargo.lock, Xargo.toml for cross-compilation
- Dockerfile, build.sh, test.sh for reproducible builds & tests
- .verified-build.json to compare on-chain deployment
- audits/ and SECURITY.md for formal review and bug bounty
- idl/: scripts (generateIdl.js, generateClient.js) plus JSON schema to produce TypeScript/JS clients
- src/: the core of the on-chain program
- lib.rs: entry point & CPI exports
- log.rs, status.rs: diagnostics & return codes
- program/: API surface
– instruction_builders/: off-chain helpers to craft instructions
– dispatch_market.rs: routes incoming instructions to processors
– processor/: handlers for each instruction (initialize, new_order, cancel, deposit, withdraw, fees, governance, etc.)
– validation/: preconditions & account loaders
– system_utils.rs & token_utils.rs: wrappers over Solana’s system and token programs
- state/: on-chain account layouts
– enums.rs, trader_state.rs, matching_engine_response.rs
– markets/: abstraction over FIFO order book implementations, event queues, wrappers
– order_schema/: packet formats for cross-program serialization
- quantities.rs, shank_structs.rs: numeric types & ABI structs
- tests/: Rust integration tests simulate RPC calls

Step 3: Examine the README for additional insights
- Confirms “on-chain orderbook that operates without a crank”
- References JS/TS client generation (idl folder) and GitBook docs
- Build & test workflows use build.sh and test.sh
- Program ID and verifiable build instructions hint at on-chain deployment

a. Main components
1. Off-chain client (TypeScript/JS) generated from idl/phoenix_v1.json
2. Solana RPC node (JSON-RPC endpoint)
3. On-chain program “Phoenix” (deployed via build.sh/Docker)
4. Solana runtime/system program (system_program)
5. SPL Token program (token_program)
6. On-chain accounts & data structures: Market account, Order book storage, Event queue, Trader state
b. Relationships/interactions
- Client → RPC: submit transactions with instructions built by instruction_builders
- RPC → Phoenix program entry point (lib.rs)
- Dispatcher → appropriate processor function in program/processor/…
- Processor calls validation loaders → loads/mutates state accounts
- Processor invokes token_utils for SPL token transfers, system_utils for lamports
- Processor updates in-memory structs (state/markets), serializes back to on-chain accounts
- Processor emits events via event_recorder → recorded in logs or on-chain event queue
- Solana runtime persists changes or rolls back on errors
c. Architectural patterns/design principles
- Modular separation: instruction builders, dispatch, validation, processing, state serialization
- Trait-based abstraction for different market implementations (state/markets/market_traits.rs)
- Single entry point and dispatcher to simplify instruction routing
- Strict validation layers before state mutation
d. Relevant technologies/frameworks
- Rust + Cargo/Xargo, Solana SDK
- Docker for repeatable builds, Solana Verify CLI
- Node.js / TypeScript for client generation (idl folder)
- SPL Token and System programs as external dependencies

- On-chain vs off-chain separation: Clients vs program vs runtime
- Instruction lifecycle: build → dispatch → validate → process → persist
- Account boundary: program’s own account data vs external programs (system, token)
- IDL generation as part of developer UX but not part of on-chain execution

Step 6: Diagramming guidelines
- Components:
- Client, RPC, “Phoenix” program, Solana runtime, external programs, storage accounts
- Client → RPC → Program → State → back to client (events/logs)
- Blue for off-chain elements, green for on-chain program, orange for external programs, gray for storage
- Dispatch, Validation, Processing, State Serialization, Event Recorder

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Off-chain Layer
    subgraph "Off-Chain Client" 
        direction TB
        Client["TypeScript/JS Client"]:::offchain
        IDL["phoenix_v1.json"]:::offchain
        GenIDL["generateIdl.js"]:::offchain
        GenClient["generateClient.js"]:::offchain
        PackageJSON["package.json"]:::offchain
    end

    %% RPC Layer
    RPC["Solana RPC Node"]:::external

    %% On-Chain Program
    subgraph "Phoenix Program" 
        direction TB
        Entry["lib.rs"]:::onchain
        Dispatch["dispatch_market.rs"]:::onchain
        Validation["Validation Layer"]:::onchain
        Processing["Processing Handlers"]:::onchain
        StateSerial["State Serialization"]:::onchain
        EventRec["Event Recorder"]:::onchain

        Dispatch --> Validation
        Validation --> Processing
        Processing --> StateSerial
        StateSerial --> EventRec
    end

    %% Processor Details
    subgraph "Processors" 
        direction TB
        Init["initialize.rs"]:::onchain
        NewOrder["new_order.rs"]:::onchain
        Cancel["cancel_multiple_orders.rs"]:::onchain
        Init --> NewOrder
        NewOrder --> Cancel
        Cancel --> Init
    end

    %% Validation Details
    subgraph "Validation" 
        direction TB
        Checkers["checkers/phoenix_checkers.rs"]:::onchain
        TokenCheck["checkers/token_checkers.rs"]:::onchain
        Loaders["loaders.rs"]:::onchain
    end

    %% External Programs
    subgraph "External Programs"
        direction TB
        SysProg["System Program"]:::external
        TokenProg["SPL Token Program"]:::external
    end

    %% Storage Accounts
    subgraph "On-Chain Accounts" 
        direction TB
        MarketAcc["Market Account"]:::storage
        OrderBook["Order Book Storage"]:::storage
        EventQueue["Event Queue"]:::storage
        TraderState["Trader State"]:::storage
    end

    %% Flows
    Client -->|"Transaction with Instructions"| RPC
    RPC -->|"invoke()"| Entry
    Entry -->|"routeInstruction()"| Dispatch
    Dispatch -->|"validatePreconditions"| Validation
    Validation -->|"executeHandler"| Processing
    Processing -->|"serializeState"| StateSerial
    StateSerial -->|"emitEvent"| EventRec
    Processing -->|"CPI"| TokenProg
    Processing -->|"CPI"| SysProg
    StateSerial --> MarketAcc
    StateSerial --> OrderBook
    EventRec --> EventQueue

    %% Click Events
    click IDL "https://github.com/ellipsis-labs/phoenix-v1/blob/master/idl/phoenix_v1.json"
    click GenIDL "https://github.com/ellipsis-labs/phoenix-v1/blob/master/idl/generateIdl.js"
    click GenClient "https://github.com/ellipsis-labs/phoenix-v1/blob/master/idl/generateClient.js"
    click PackageJSON "https://github.com/ellipsis-labs/phoenix-v1/blob/master/idl/package.json"
    click Entry "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/lib.rs"
    click Dispatch "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/dispatch_market.rs"
    click Validation "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/validation/mod.rs"
    click Checkers "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/validation/checkers/phoenix_checkers.rs"
    click TokenCheck "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/validation/checkers/token_checkers.rs"
    click Loaders "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/validation/loaders.rs"
    click Init "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/processor/initialize.rs"
    click NewOrder "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/processor/new_order.rs"
    click Cancel "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/processor/cancel_multiple_orders.rs"
    click SysProg "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/system_utils.rs"
    click TokenProg "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/token_utils.rs"
    click MarketAcc "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/state/markets/market_wrapper.rs"
    click OrderBook "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/state/markets/fifo.rs"
    click EventQueue "https://github.com/ellipsis-labs/phoenix-v1/blob/master/src/program/events.rs"

    %% Styles
    classDef offchain fill:#ddeeff,stroke:#0000ff
    classDef onchain fill:#ddffdd,stroke:#008000
    classDef external fill:#ffe4b5,stroke:#ff8c00
    classDef storage fill:#f0f0f0,stroke:#666666
```
