# igneous-labs/sanctum-router-sdk architecture

> Architecture diagram of the GitHub repository igneous-labs/sanctum-router-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/igneous-labs/sanctum-router-sdk
- Repository: https://github.com/igneous-labs/sanctum-router-sdk

## Overview

##### Project type and purpose
- This is a blockchain SDK repository for Solana, consisting of:
- An on-chain core program (Rust) that implements a “router” for staking operations across multiple protocols (Lido, Marinade, SPL Stake Pool, Reserve).
- An off-chain client SDK (TypeScript) for composing and submitting transactions to that on-chain program.
- A suite of integration tests and JSON fixtures to exercise the router against a local Solana validator.

##### File-structure analysis
- Top level:
- core/             – Rust library (`Cargo.toml`, `src/…`) containing the on-chain program logic: instructions, quote generators, PDA derivation, router modules for each protocol, trait definitions.
- ts/sdk/           – TypeScript SDK to interface with the on-chain program: PDA helpers, instruction builders, router interfaces, build scripts.
- ts/tests/         – Integration tests and scripts that spin up a local validator (via `docker-compose-local-validator.yml`), load JSON fixtures, and validate end-to-end behavior.
- test-fixtures/    – Sample Solana account data for each router and token mint to seed the local validator.
- Configuration: `.gitignore`, pre-commit, Docker compose for local validator, etc.

##### Key README insights
- Minimal README; core purpose described by directory names (“router‐sdk”) and successor to a previous similar SDK.
- Individual subdirectories contain their own READMEs with test instructions.

a. On-chain core program (Rust)
– Modules: `instructions/*`, `routers/*`, `quote/*`, `pda.rs`, `traits/*`
– Exposed program ID on Solana cluster
– Externally invokes (CPI) other Solana programs: Lido, Marinade, SPL Stake Pool, Reserve
b. Off-chain client SDK (TypeScript)
– PDA derivation, instruction construction, RPC client calls
– Postbuild and packaging scripts
c. Test harness
– Local Solana validator (Docker) loaded with JSON fixtures
– TypeScript tests driving the SDK against the program
d. External protocols on Solana
– Lido program, Marinade program, SPL Stake Pool program, Reserve program
e. Data flows
– Client → JSON RPC → On-chain program → CPI → External protocol → On-chain program → Client (via transaction confirmation)

##### Architectural patterns and principles
- Router pattern: single entrypoint dispatching to protocol-specific handlers
- PDA (Program Derived Address) abstraction: deterministic account addresses for program state
- Trait‐based design in Rust for uniform instruction/quote interfaces
- SDK/Program separation: clear boundary between on-chain logic and off-chain clients
- Use of JSON fixtures for reproducible local testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Off-chain SDK Layer
    subgraph "Off-chain Client SDK (TypeScript)"
        SDK["TS SDK"]:::code
    end

    %% Solana RPC
    RPC["Solana JSON RPC"]:::cloud

    %% On-chain Core Program
    subgraph "On-chain Core Program (Rust)"
        direction TB
        CoreLib["core/src/lib.rs"]:::code
        CargoToml["core/Cargo.toml"]:::code
        subgraph "Instructions Module"
            Instr["core/src/instructions/"]:::code
        end
        subgraph "Router Modules"
            LidoRouter["core/src/routers/lido/"]:::code
            MarinadeRouter["core/src/routers/marinade/"]:::code
            SPLRouter["core/src/routers/spl_stake_pool/"]:::code
            ReserveRouter["core/src/routers/reserve/"]:::code
        end
        subgraph "Quote Generators"
            Quote["core/src/quote/"]:::code
        end
        PDA["core/src/pda.rs"]:::code
        Traits["core/src/traits/"]:::code
    end

    %% On-chain Data Accounts
    PDAs["On-chain Data Accounts (PDAs)"]:::data

    %% External Protocols
    subgraph "External Protocol Programs"
        direction TB
        LIDO["Lido Program"]:::external
        MARINADE["Marinade Program"]:::external
        SPL["SPL Stake Pool Program"]:::external
        RESERVE["Reserve Program"]:::external
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        Validator["Local Solana Validator"]:::cloud
        Fixtures["JSON Test Fixtures"]:::data
        Tests["TS Integration Tests"]:::code
    end

    %% Flows
    SDK -->|"RPC Call"| RPC
    RPC -->|"Dispatch Transaction"| CoreLib
    CoreLib -->|uses| Instr
    CoreLib -->|uses| PDA
    CoreLib -->|uses| Traits
    CoreLib -->|dispatches| LidoRouter
    CoreLib -->|dispatches| MarinadeRouter
    CoreLib -->|dispatches| SPLRouter
    CoreLib -->|dispatches| ReserveRouter
    CoreLib -->|uses| Quote
    CoreLib -.->|CPI DepositStake| LIDO
    CoreLib -.->|CPI DepositStake| MARINADE
    CoreLib -.->|CPI DepositStake| SPL
    CoreLib -.->|CPI DepositStake| RESERVE
    CoreLib -->|updates| PDAs
    LIDO -.->|Callback| CoreLib
    MARINADE -.->|Callback| CoreLib
    SPL -.->|Callback| CoreLib
    RESERVE -.->|Callback| CoreLib
    CoreLib -->|"Tx Confirmation"| RPC
    RPC -->|"Response"| SDK

    Fixtures --> Validator
    Validator --> Tests
    Tests --> SDK

    %% Click Events
    click CoreLib "https://github.com/igneous-labs/sanctum-router-sdk/blob/master/core/src/lib.rs"
    click CargoToml "https://github.com/igneous-labs/sanctum-router-sdk/blob/master/core/Cargo.toml"
    click Instr "https://github.com/igneous-labs/sanctum-router-sdk/tree/master/core/src/instructions/"
    click LidoRouter "https://github.com/igneous-labs/sanctum-router-sdk/tree/master/core/src/routers/lido/"
    click MarinadeRouter "https://github.com/igneous-labs/sanctum-router-sdk/tree/master/core/src/routers/marinade/"
    click SPLRouter "https://github.com/igneous-labs/sanctum-router-sdk/tree/master/core/src/routers/spl_stake_pool/"
    click ReserveRouter "https://github.com/igneous-labs/sanctum-router-sdk/tree/master/core/src/routers/reserve/"
    click Quote "https://github.com/igneous-labs/sanctum-router-sdk/tree/master/core/src/quote/"
    click PDA "https://github.com/igneous-labs/sanctum-router-sdk/blob/master/core/src/pda.rs"
    click Traits "https://github.com/igneous-labs/sanctum-router-sdk/tree/master/core/src/traits/"
    click SDK "https://github.com/igneous-labs/sanctum-router-sdk/blob/master/ts/sdk/README.md"
    click Validator "https://github.com/igneous-labs/sanctum-router-sdk/blob/master/docker-compose-local-validator.yml"
    click Fixtures "https://github.com/igneous-labs/sanctum-router-sdk/tree/master/test-fixtures/"
    click Tests "https://github.com/igneous-labs/sanctum-router-sdk/tree/master/ts/tests/"

    %% Styles
    classDef code fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef data fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef cloud fill:#e0e0e0,stroke:#333,stroke-width:1px
    class code code
    class data data
    class external external
    class cloud cloud
```
