How ellipsis-labs/phoenix-v1 works
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