# the3rdweblabs/magiclob architecture

> Architecture diagram of the GitHub repository the3rdweblabs/magiclob, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/the3rdweblabs/magiclob
- Repository: https://github.com/the3rdweblabs/magiclob

## Overview

magiCLOB is a Solana central-limit order book with Magicblock Ephemeral Rollup sessions, an integration SDK, and a web trading demo. The principal workflow initializes a market and funds trader custody on Solana, delegates the book and trader to an ER, routes orders through matching, then settles and undelegates. The README also documents staking, governance, flash loans, and an indexer-backed market-data path, which are represented as distinct capabilities. Some app and SDK implementation details were not sampled; edges for those branches use documented relationships rather than inferred calls.

Main entry points: [`contracts/programs/magiclob/src/lib.rs`](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/lib.rs) (Anchor Program), [`contracts/programs/magiclob/src/engine/matcher.rs`](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/engine/matcher.rs) (Matching Engine), [`sdk/src/sdk.ts`](https://github.com/the3rdweblabs/magiclob/blob/main/sdk/src/sdk.ts) (SDK Facade), [`contracts/programs/magiclob/src/instructions/delegate_trader_session.rs`](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/delegate_trader_session.rs) (ER Delegation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_demo["Trading Demo"]
  node_magicbook["MagicBook UI<br/>[page.tsx]"]
  node_tradingui["Trading Components"]
  node_marketdata["Market Data<br/>[indexer.ts]"]
  node_dataapi["Data API"]
end

subgraph group_integration["Integrator SDK"]
  node_sdk["SDK Facade<br/>[sdk.ts]"]
  node_router["Base ER Router<br/>[client.ts]"]
  node_sdkinstructions["Instruction Builders"]
  node_accountreaders["Account Readers"]
  node_codec["Account Codec<br/>[codec.ts]"]
  node_pda["PDA Derivation<br/>[pda.ts]"]
end

subgraph group_program["Solana Program"]
  node_program["Anchor Program<br/>[lib.rs]"]
  node_marketinit["Market Setup"]
  node_custody["Vault Custody<br/>[deposit.rs]"]
  node_delegation["ER Delegation"]
  node_settlement["Settlement"]
  node_marketstate[("Market State<br/>[market.rs]")]
  node_bookstate[("Order Book State<br/>[order_book.rs]")]
  node_traderstate[("Trader State<br/>[trader.rs]")]
  node_otherfeatures["Finance Governance"]
  node_orderentry["Order Entry"]
end

subgraph group_engine["Execution Engine"]
  node_matcher["Matching Engine<br/>[matcher.rs]"]
  node_ordertypes["Order Types<br/>[order_types.rs]"]
  node_fees["Fee Router<br/>[fees.rs]"]
end

node_trader(("Trader"))
node_solana(("Solana Network"))
node_ephemeral{{"Ephemeral Rollup"}}

node_trader -->|"trades through"| node_magicbook
node_magicbook -.->|"uses"| node_tradingui
node_tradingui -.->|"submits orders"| node_sdk
node_magicbook -.->|"reads market data"| node_marketdata
node_marketdata -.->|"serves streams"| node_dataapi
node_tradingui -.->|"requests data"| node_dataapi
node_sdk -->|"routes transactions"| node_router
node_sdk -.->|"builds instructions"| node_sdkinstructions
node_sdk -.->|"reads accounts"| node_accountreaders
node_accountreaders -->|"decodes accounts"| node_codec
node_sdkinstructions -->|"derives addresses"| node_pda
node_router -->|"sends base transactions"| node_solana
node_router -->|"sends session transactions"| node_ephemeral
node_solana -->|"executes program"| node_program
node_program -->|"dispatches setup"| node_marketinit
node_program -->|"dispatches deposits"| node_custody
node_program -->|"dispatches delegation"| node_delegation
node_program -->|"dispatches orders"| node_orderentry
node_program -->|"dispatches settlement"| node_settlement
node_marketinit -->|"initializes"| node_marketstate
node_custody -->|"moves SPL tokens"| node_solana
node_delegation -->|"delegates session"| node_ephemeral
node_delegation -->|"delegates book"| node_bookstate
node_delegation -->|"delegates trader"| node_traderstate
node_orderentry -->|"matches orders"| node_matcher
node_matcher -->|"reads and updates"| node_bookstate
node_matcher -->|"settles fills"| node_traderstate
node_matcher -->|"uses order types"| node_ordertypes
node_matcher -->|"calculates fees"| node_fees
node_settlement -->|"commits and undelegates"| node_solana
node_program -->|"dispatches finance actions"| node_otherfeatures
node_marketdata -.->|"watches fills"| node_bookstate

click node_magicbook "https://github.com/the3rdweblabs/magiclob/blob/main/app/src/app/magicbook/page.tsx"
click node_tradingui "https://github.com/the3rdweblabs/magiclob/tree/main/app/src/components/orderbook"
click node_marketdata "https://github.com/the3rdweblabs/magiclob/blob/main/app/src/server/indexer.ts"
click node_dataapi "https://github.com/the3rdweblabs/magiclob/tree/main/app/src/app/api"
click node_sdk "https://github.com/the3rdweblabs/magiclob/blob/main/sdk/src/sdk.ts"
click node_router "https://github.com/the3rdweblabs/magiclob/blob/main/sdk/src/client.ts"
click node_sdkinstructions "https://github.com/the3rdweblabs/magiclob/tree/main/sdk/src/instructions"
click node_accountreaders "https://github.com/the3rdweblabs/magiclob/tree/main/sdk/src/accounts"
click node_codec "https://github.com/the3rdweblabs/magiclob/blob/main/sdk/src/codec.ts"
click node_pda "https://github.com/the3rdweblabs/magiclob/blob/main/sdk/src/pda.ts"
click node_program "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/lib.rs"
click node_marketinit "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/initialize_market.rs"
click node_custody "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/deposit.rs"
click node_delegation "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/delegate_trader_session.rs"
click node_settlement "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/settle_and_undelegate.rs"
click node_marketstate "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/state/market.rs"
click node_bookstate "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/state/order_book.rs"
click node_traderstate "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/state/trader.rs"
click node_otherfeatures "https://github.com/the3rdweblabs/magiclob/tree/main/contracts/programs/magiclob/src/instructions"
click node_orderentry "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/place_limit_order.rs"
click node_matcher "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/engine/matcher.rs"
click node_ordertypes "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/engine/order_types.rs"
click node_fees "https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/fees.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_magicbook,node_tradingui,node_marketdata,node_dataapi toneBlue
class node_sdk,node_router,node_sdkinstructions,node_accountreaders,node_codec,node_pda toneAmber
class node_program,node_marketinit,node_custody,node_delegation,node_settlement,node_marketstate,node_bookstate,node_traderstate,node_otherfeatures,node_orderentry toneMint
class node_matcher,node_ordertypes,node_fees toneRose
class node_trader,node_solana,node_ephemeral toneIndigo
```

## Components

### Trading Demo

- [MagicBook UI](https://github.com/the3rdweblabs/magiclob/blob/main/app/src/app/magicbook/page.tsx): `app/src/app/magicbook/page.tsx`
- [Trading Components](https://github.com/the3rdweblabs/magiclob/tree/main/app/src/components/orderbook): `app/src/components/orderbook`
- [Market Data](https://github.com/the3rdweblabs/magiclob/blob/main/app/src/server/indexer.ts): `app/src/server/indexer.ts`
- [Data API](https://github.com/the3rdweblabs/magiclob/tree/main/app/src/app/api): `app/src/app/api`

### Integrator SDK

- [SDK Facade](https://github.com/the3rdweblabs/magiclob/blob/main/sdk/src/sdk.ts): `sdk/src/sdk.ts`
- [Base ER Router](https://github.com/the3rdweblabs/magiclob/blob/main/sdk/src/client.ts): `sdk/src/client.ts`
- [Instruction Builders](https://github.com/the3rdweblabs/magiclob/tree/main/sdk/src/instructions): `sdk/src/instructions`
- [Account Readers](https://github.com/the3rdweblabs/magiclob/tree/main/sdk/src/accounts): `sdk/src/accounts`
- [Account Codec](https://github.com/the3rdweblabs/magiclob/blob/main/sdk/src/codec.ts): `sdk/src/codec.ts`
- [PDA Derivation](https://github.com/the3rdweblabs/magiclob/blob/main/sdk/src/pda.ts): `sdk/src/pda.ts`

### Solana Program

- [Anchor Program](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/lib.rs): `contracts/programs/magiclob/src/lib.rs`
- [Market Setup](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/initialize_market.rs): `contracts/programs/magiclob/src/instructions/initialize_market.rs`
- [Vault Custody](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/deposit.rs): `contracts/programs/magiclob/src/instructions/deposit.rs`
- [ER Delegation](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/delegate_trader_session.rs): `contracts/programs/magiclob/src/instructions/delegate_trader_session.rs`
- [Settlement](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/settle_and_undelegate.rs): `contracts/programs/magiclob/src/instructions/settle_and_undelegate.rs`
- [Market State](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/state/market.rs): `contracts/programs/magiclob/src/state/market.rs`
- [Order Book State](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/state/order_book.rs): `contracts/programs/magiclob/src/state/order_book.rs`
- [Trader State](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/state/trader.rs): `contracts/programs/magiclob/src/state/trader.rs`
- [Finance Governance](https://github.com/the3rdweblabs/magiclob/tree/main/contracts/programs/magiclob/src/instructions): `contracts/programs/magiclob/src/instructions`
- [Order Entry](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/instructions/place_limit_order.rs): `contracts/programs/magiclob/src/instructions/place_limit_order.rs`

### Execution Engine

- [Matching Engine](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/engine/matcher.rs): `contracts/programs/magiclob/src/engine/matcher.rs`
- [Order Types](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/engine/order_types.rs): `contracts/programs/magiclob/src/engine/order_types.rs`
- [Fee Router](https://github.com/the3rdweblabs/magiclob/blob/main/contracts/programs/magiclob/src/fees.rs): `contracts/programs/magiclob/src/fees.rs`

### Other components

- **Trader**
- **Solana Network**
- **Ephemeral Rollup**

## Connections

- Trader → MagicBook UI: trades through (evidence: `README.md`)
- MagicBook UI → Trading Components: uses
- Trading Components → SDK Facade: submits orders
- MagicBook UI → Market Data: reads market data (evidence: `README.md`)
- Market Data → Data API: serves streams (evidence: `README.md`)
- Trading Components → Data API: requests data
- SDK Facade → Base ER Router: routes transactions (evidence: `README.md`)
- SDK Facade → Instruction Builders: builds instructions
- SDK Facade → Account Readers: reads accounts
- Account Readers → Account Codec: decodes accounts (evidence: `sdk/src/accounts/market.ts`)
- Instruction Builders → PDA Derivation: derives addresses (evidence: `sdk/src/instructions/delegateSession.ts`)
- Base ER Router → Solana Network: sends base transactions (evidence: `sdk/src/client.ts`)
- Base ER Router → Ephemeral Rollup: sends session transactions (evidence: `README.md`)
- Solana Network → Anchor Program: executes program (evidence: `README.md`)
- Anchor Program → Market Setup: dispatches setup (evidence: `contracts/programs/magiclob/src/lib.rs`)
- Anchor Program → Vault Custody: dispatches deposits (evidence: `contracts/programs/magiclob/src/lib.rs`)
- Anchor Program → ER Delegation: dispatches delegation (evidence: `contracts/programs/magiclob/src/lib.rs`)
- Anchor Program → Order Entry: dispatches orders (evidence: `contracts/programs/magiclob/src/lib.rs`)
- Anchor Program → Settlement: dispatches settlement (evidence: `contracts/programs/magiclob/src/lib.rs`)
- Market Setup → Market State: initializes (evidence: `README.md`)
- Vault Custody → Solana Network: moves SPL tokens (evidence: `README.md`)
- ER Delegation → Ephemeral Rollup: delegates session (evidence: `contracts/programs/magiclob/src/instructions/delegate_trader_session.rs`)
- ER Delegation → Order Book State: delegates book (evidence: `contracts/programs/magiclob/src/instructions/delegate_trader_session.rs`)
- ER Delegation → Trader State: delegates trader (evidence: `contracts/programs/magiclob/src/instructions/delegate_trader_session.rs`)
- Order Entry → Matching Engine: matches orders (evidence: `README.md`)
- Matching Engine → Order Book State: reads and updates (evidence: `contracts/programs/magiclob/src/engine/matcher.rs`)
- Matching Engine → Trader State: settles fills (evidence: `contracts/programs/magiclob/src/engine/matcher.rs`)
- Matching Engine → Order Types: uses order types (evidence: `contracts/programs/magiclob/src/engine/matcher.rs`)
- Matching Engine → Fee Router: calculates fees (evidence: `contracts/programs/magiclob/src/engine/matcher.rs`)
- Settlement → Solana Network: commits and undelegates (evidence: `README.md`)
- Anchor Program → Finance Governance: dispatches finance actions (evidence: `contracts/programs/magiclob/src/lib.rs`)
- Market Data → Order Book State: watches fills (evidence: `README.md`)
