# marinade-finance/liquid-staking-program architecture

> Architecture diagram of the GitHub repository marinade-finance/liquid-staking-program, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marinade-finance/liquid-staking-program
- Repository: https://github.com/marinade-finance/liquid-staking-program

## Overview

##### Project type and purpose
- This is a Solana on-chain program (smart contract) built with the Anchor framework.
- It implements Marinade Finance’s liquid staking protocol, handling user deposits, stake delegation, a liquidity pool, delayed unstaking, validator management, and emergency operations.

##### File structure
- Top level:
- Anchor.toml, Cargo.toml: Anchor workspace and dependencies
- Docs/: backend design doc and reference images
- scripts/: deployment, upgrade and verification scripts
- programs/marinade-finance/: the core on-chain Rust program
- In programs/marinade-finance/src:
- instructions/: grouped by domain (admin, crank, delayed_unstake, liq_pool, management, user)
- events/: event definitions for each domain
- state/: account struct definitions (stake_system, validator_system, liq_pool, fee, list, delayed_unstake_ticket)
- calc.rs, checks.rs, error.rs: utility logic for math, validation, and error types

##### README for insights
- Project description: “Marinade-finance liquid staking program for the Solana blockchain.”
- Mentions Anchor v0.27 upgrade, audits, and links to detailed backend design.

##### Essential details
- Break out the on-chain program into its sub-modules: Admin, User, Crank, Liquidity Pool, Delayed Unstake, Management
- How each instruction group interacts with specific state accounts and CPIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Off-chain Layer
    subgraph "Off-chain Layer"
        direction TB
        UI["User UI/CLI"]:::offchain
        Crank["Crank Service"]:::offchain
        Scripts["Deployment & Upgrade Scripts"]:::offchain
        Docs["Backend Design Docs"]:::offchain
    end

    %% On-chain Anchor Program
    subgraph "Marinade Anchor Program" 
        direction TB
        Entry["Anchor Program Entry (lib.rs)"]:::onchain
        subgraph "Program Config & Manifest"
            AnchorToml["Anchor.toml"]:::config
            CargoRoot["Cargo.toml"]:::config
            CargoProg["Program Cargo.toml"]:::config
        end
        subgraph "Instruction Modules"
            Admin["Admin Instructions"]:::onchain
            CrankInstr["Crank Instructions"]:::onchain
            Delayed["Delayed Unstake Instructions"]:::onchain
            Liquidity["Liquidity Pool Instructions"]:::onchain
            Management["Management Instructions"]:::onchain
            UserInstr["User Instructions"]:::onchain
        end
        subgraph "State Account Definitions"
            StateMod["State mod.rs"]:::state
            DelayedState["delayed_unstake_ticket.rs"]:::state
            FeeState["fee.rs"]:::state
            PoolState["liq_pool.rs"]:::state
            ListState["list.rs"]:::state
            StakeState["stake_system.rs"]:::state
            ValState["validator_system.rs"]:::state
        end
        subgraph "Event Definitions"
            EventsMod["events mod.rs"]:::onchain
            AdminEvt["admin.rs"]:::onchain
            CrankEvt["crank.rs"]:::onchain
            DelayedEvt["delayed_unstake.rs"]:::onchain
            PoolEvt["liq_pool.rs"]:::onchain
            MgmtEvt["management.rs"]:::onchain
            UserEvt["user.rs"]:::onchain
        end
        subgraph "Utility Logic"
            Calc["calc.rs"]:::onchain
            Checks["checks.rs"]:::onchain
            Error["error.rs"]:::onchain
        end
    end

    %% Solana System Programs
    subgraph "Solana System Programs"
        direction TB
        StakeProg["Stake Program CPI"]:::system
        TokenProg["Token Program CPI"]:::system
        SysProg["System Program CPI"]:::system
    end

    %% State Accounts
    subgraph "On-chain State Accounts"
        direction TB
        ConfigAcct["Global Config & Fee Account"]:::state
        ValListAcct["Validator List & Stake System Account"]:::state
        LPAcct["Liquidity Pool Account & LP Mint"]:::state
        TicketAcct["Delayed Unstake Ticket Accounts"]:::state
    end

    %% Interactions
    UI -->|"send Txns"| RPC["Solana RPC & Validator Cluster"]:::offchain
    Crank -->|"invoke crank instrs"| RPC
    Scripts -->|"deploy/upgrade"| RPC
    RPC -->|"Anchor Instruction"| Entry
    Entry -->|"Admin handler"| Admin
    Entry -->|"Crank handler"| CrankInstr
    Entry -->|"DelayedUnstake handler"| Delayed
    Entry -->|"LiquidityPool handler"| Liquidity
    Entry -->|"Management handler"| Management
    Entry -->|"User handler"| UserInstr

    %% CPI interactions
    Admin -->|"CPI"| StakeProg
    UserInstr -->|"CPI delegate/deactivate"| StakeProg
    UserInstr -->|"CPI mint/burn"| TokenProg
    Liquidity -->|"CPI mint/burn"| TokenProg
    Management -->|"CPI system ops"| SysProg

    %% State updates & events
    Admin -->|"update"| ConfigAcct
    UserInstr -->|"update"| LPAcct
    UserInstr -->|"update"| ValListAcct
    Delayed -->|"create ticket"| TicketAcct
    CrankInstr -->|"rebalance"| ValListAcct
    Entry -->|"emit events"| EventsMod

    %% Docs link
    Docs -.-> UI

    %% Click Events
    click Entry "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/lib.rs"
    click AnchorToml "https://github.com/marinade-finance/liquid-staking-program/blob/main/Anchor.toml"
    click CargoRoot "https://github.com/marinade-finance/liquid-staking-program/blob/main/Cargo.toml"
    click CargoProg "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/Cargo.toml"
    click Admin "https://github.com/marinade-finance/liquid-staking-program/tree/main/programs/marinade-finance/src/instructions/admin/"
    click CrankInstr "https://github.com/marinade-finance/liquid-staking-program/tree/main/programs/marinade-finance/src/instructions/crank/"
    click Delayed "https://github.com/marinade-finance/liquid-staking-program/tree/main/programs/marinade-finance/src/instructions/delayed_unstake/"
    click Liquidity "https://github.com/marinade-finance/liquid-staking-program/tree/main/programs/marinade-finance/src/instructions/liq_pool/"
    click Management "https://github.com/marinade-finance/liquid-staking-program/tree/main/programs/marinade-finance/src/instructions/management/"
    click UserInstr "https://github.com/marinade-finance/liquid-staking-program/tree/main/programs/marinade-finance/src/instructions/user/"
    click StateMod "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/state/mod.rs"
    click DelayedState "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/state/delayed_unstake_ticket.rs"
    click FeeState "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/state/fee.rs"
    click PoolState "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/state/liq_pool.rs"
    click ListState "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/state/list.rs"
    click StakeState "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/state/stake_system.rs"
    click ValState "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/state/validator_system.rs"
    click EventsMod "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/events/mod.rs"
    click AdminEvt "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/events/admin.rs"
    click CrankEvt "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/events/crank.rs"
    click DelayedEvt "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/events/delayed_unstake.rs"
    click PoolEvt "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/events/liq_pool.rs"
    click MgmtEvt "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/events/management.rs"
    click UserEvt "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/events/user.rs"
    click Calc "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/calc.rs"
    click Checks "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/checks.rs"
    click Error "https://github.com/marinade-finance/liquid-staking-program/blob/main/programs/marinade-finance/src/error.rs"
    click Scripts "https://github.com/marinade-finance/liquid-staking-program/tree/main/scripts/"

    %% Styles
    classDef offchain fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef onchain fill:#90EE90,stroke:#333,stroke-width:1px
    classDef system fill:#FFA500,stroke:#333,stroke-width:1px
    classDef state fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef config fill:#DDA0DD,stroke:#333,stroke-width:1px
```
