# drift-labs/drift-vaults architecture

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

- Interactive diagram: https://gitdiagram.com/drift-labs/drift-vaults
- Repository: https://github.com/drift-labs/drift-vaults

## Overview

##### Project Type and Purpose
- This is a blockchain-based DeFi program built with Solana + Anchor.
- Core on-chain logic lives in `programs/drift_vaults`, implementing “vaults” functionality (deposit, withdraw, profit share, rebase, insurance, etc.).
- Off-chain SDK & CLI in `ts/sdk` provide programmatic and CLI access to the on-chain program.
- Tests and CI/CD scripts automate local validator tests and devnet/mainnet deployments.

##### File Structure
- Top-level:
- `programs/drift_vaults`: Rust/Anchor smart contract
- `ts/sdk`: TypeScript SDK + CLI
- `tests`: end-to-end/integration tests (JS/TS, using a local validator or devnet)
- `deploy-scripts`, `build.sh`, GitHub Actions (`.github/workflows`): CI/CD & deployment
- Config: `Anchor.toml`, `Cargo.toml`/`rust-toolchain.toml`, TS configs, GitHub CI, Husky, ESLint, Prettier.
- Notice the “instructions” and “state” subdivisions under the Rust program—this is your business logic vs. account/model definitions.
- The CLI layer under `ts/sdk/cli/commands` maps 1:1 to on-chain instructions.

##### Key README Insights
- Anchor v0.29.0, Rust 1.70.0, Solana 1.16.27.
- Local development uses `anchor test` or the provided `test.sh`.
- Off-chain usage documented in `ts/sdk/README.md`.

##### Main Components & Interactions
a. On-chain Program (Rust/Anchor)
– Entrypoint: Anchor-generated IDL (`drift_vaults.json` in SDK/IDL)
– Modules: instructions (business logic), state (account schemas), CPIs (calls to other on-chain programs, e.g., Drift core, SPL Token).
– State accounts: Vault, VaultDepositor, InsuranceFundStake, WithdrawRequest, etc.
b. Off-chain SDK & CLI (TypeScript)
– `vaultClient.ts`: high-level client wrapping web3 calls using the IDL
– `cli/commands`: scripts to submit transactions
– Subscribers: polling for account changes
c. Solana Cluster
– Local Validator (for tests), Devnet/Mainnet (for deployments)
– Solana RPC node interface
d. CI/CD & Deployment
– GitHub Actions: runs lint, build, test, and optionally triggers `deploy-scripts/devnet-deploy.sh`
– `build.sh` / `deploy-scripts`: shell scripts to build and deploy the Anchor program.

##### Architectural Patterns & Design Principles
- Separation of concerns: business logic (instructions) vs. data definitions (state).
- CPI pattern: on-chain program invokes other programs for composability.
- SDK/CLI layering: IDL-driven client, command wrappers, subscriber utilities.
- Test harness: run local validator, fixture loading, bulk account loader for performance testing.

##### Essential Elements
- Clear component labels (e.g., “Drift Vaults Program”, “VaultClient”, “withdraw.ts CLI”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Layer
    Dev["Developer Terminal"]:::offchain
    Dev -->|"yarn build & test"| SDK

    %% Off-chain SDK & CLI
    subgraph "Off-chain SDK & CLI"
        direction TB
        SDK["VaultClient (ts/sdk/src/vaultClient.ts)"]:::offchain
        IDL["Anchor IDL (ts/sdk/src/idl/drift_vaults.json)"]:::offchain
        subgraph "SDK Core"
            direction TB
            Accounts["Account Wrappers (ts/sdk/src/accounts)"]:::offchain
            Subs["Subscribers (ts/sdk/src/accountSubscribers)"]:::offchain
            Types["Types (ts/sdk/src/types)"]:::offchain
            Parsers["Parsers (ts/sdk/src/parsers)"]:::offchain
            Math["Math Helpers (ts/sdk/src/math)"]:::offchain
            Consts["Addresses & Constants (ts/sdk/src/addresses.ts, ts/sdk/src/constants)"]:::offchain
        end
        subgraph "CLI Layer"
            direction TB
            CLIEntrypoint["CLI Entrypoint (ts/sdk/cli/cli.ts)"]:::offchain
            Commands["Commands (ts/sdk/cli/commands)"]:::offchain
            Utils["Utils & Wallet (ts/sdk/cli/utils.ts, ledgerWallet.ts)"]:::offchain
        end
    end

    SDK -->|uses IDL| IDL
    SDK -->|wraps web3 calls| RPC
    CLIEntrypoint -->|invokes| Commands
    Commands -->|use| SDK
    Utils -->|provides wallet| CLIEntrypoint
    Accounts -->|data types| SDK
    Subs -->|polls RPC| RPC

    %% Solana Network
    RPC["Solana RPC Node"]:::network
    RPC -->|"JSON-RPC"| Cluster

    %% On-chain Program
    subgraph "On-chain Program (Solana/Anchor)" 
        direction TB
        Program["Drift Vaults Program"]:::program
        Lib["Entrypoint lib.rs"]:::program
        Instr["Instructions"]:::program
        State["State Definitions"]:::program
        CPIs["Cross-Program Invocations"]:::program
        DriftCPI["Drift CPI"]:::program
        TokenCPI["Token CPI"]:::program
        AccountsOn["Vault, VaultDepositor, InsuranceFundStake..."]:::account
    end

    Cluster["Solana Cluster\n(Local/Devnet/Mainnet)"]:::network
    Cluster -->|deploy/tx| Program
    RPC -->|submitTransaction| Program
    Program -->|business logic| Instr
    Program -->|account schemas| State
    Instr -->|CPI calls| CPIs
    CPIs -->|↳| DriftCPI
    CPIs -->|↳| TokenCPI
    Program -->|stores data| AccountsOn

    %% CPI to external
    DriftCPI -->|CPI| DriftCore["Drift Core Program"]:::network
    TokenCPI -->|CPI| SPL["SPL Token Program"]:::network

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        GHActions["GitHub Actions"]:::cicd
        SolSetup["Solana Setup Action"]:::cicd
        BuildScript["build.sh"]:::cicd
        DeployScripts["Devnet Deploy\nbuild-devnet.sh & devnet-deploy.sh"]:::cicd
    end

    GHActions -->|runs lint, build, test| BuildScript
    GHActions -->|setup| SolSetup
    BuildScript -->|build Anchor| Program
    GHActions -->|trigger| DeployScripts
    DeployScripts -->|deploy Anchor| Cluster

    %% Click Events
    click Program "https://github.com/drift-labs/drift-vaults/tree/master/programs/drift_vaults"
    click Lib "https://github.com/drift-labs/drift-vaults/blob/master/programs/drift_vaults/src/lib.rs"
    click Instr "https://github.com/drift-labs/drift-vaults/tree/master/programs/drift_vaults/src/instructions"
    click State "https://github.com/drift-labs/drift-vaults/tree/master/programs/drift_vaults/src/state"
    click DriftCPI "https://github.com/drift-labs/drift-vaults/blob/master/programs/drift_vaults/src/drift_cpi.rs"
    click TokenCPI "https://github.com/drift-labs/drift-vaults/blob/master/programs/drift_vaults/src/token_cpi.rs"
    click SDK "https://github.com/drift-labs/drift-vaults/blob/master/ts/sdk/src/vaultClient.ts"
    click IDL "https://github.com/drift-labs/drift-vaults/blob/master/ts/sdk/src/idl/drift_vaults.json"
    click Accounts "https://github.com/drift-labs/drift-vaults/tree/master/ts/sdk/src/accounts"
    click Subs "https://github.com/drift-labs/drift-vaults/tree/master/ts/sdk/src/accountSubscribers"
    click CLIEntrypoint "https://github.com/drift-labs/drift-vaults/blob/master/ts/sdk/cli/cli.ts"
    click Commands "https://github.com/drift-labs/drift-vaults/tree/master/ts/sdk/cli/commands"
    click Utils "https://github.com/drift-labs/drift-vaults/blob/master/ts/sdk/cli/utils.ts"
    click Utils "https://github.com/drift-labs/drift-vaults/blob/master/ts/sdk/cli/ledgerWallet.ts"
    click Types "https://github.com/drift-labs/drift-vaults/tree/master/ts/sdk/src/types"
    click Parsers "https://github.com/drift-labs/drift-vaults/tree/master/ts/sdk/src/parsers"
    click Math "https://github.com/drift-labs/drift-vaults/tree/master/ts/sdk/src/math"
    click Consts "https://github.com/drift-labs/drift-vaults/blob/master/ts/sdk/src/addresses.ts"
    click Consts "https://github.com/drift-labs/drift-vaults/tree/master/ts/sdk/src/constants"
    click GHActions "https://github.com/drift-labs/drift-vaults/blob/master/.github/workflows/main.yml"
    click SolSetup "https://github.com/drift-labs/drift-vaults/tree/master/.github/actions/setup-solana"
    click BuildScript "https://github.com/drift-labs/drift-vaults/blob/master/build.sh"
    click DeployScripts "https://github.com/drift-labs/drift-vaults/blob/master/deploy-scripts/devnet-deploy.sh"

    %% Styles
    classDef offchain fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef program fill:#FFDDA0,stroke:#333,stroke-width:1px
    classDef account fill:#D0FFD6,stroke:#333,stroke-width:1px,shape:cylinder
    classDef network fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef cicd fill:#F0E0FF,stroke:#333,stroke-width:1px
```
