# meteoraag/damm-v2 architecture

> Architecture diagram of the GitHub repository meteoraag/damm-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/meteoraag/damm-v2
- Repository: https://github.com/meteoraag/damm-v2

## Overview

##### Project type and purpose
- This is a blockchain smart-contract project (an on-chain AMM program for Solana) with complementary off-chain clients and SDKs.
- Purpose: Implement a Constant-Product Automated Market Maker (AMM) with advanced features (dynamic fees, concentrated liquidity, customizable configs) using Anchor + Rust.

##### File structure
- Top-level:
- `.github/` – CI workflows & custom actions for Anchor/Solana setup
- `programs/cp-amm/` – on-chain Rust/Anchor program (all instruction handlers, state, math, tests)
- `rust-sdk/` – off-chain Rust SDK for interacting with the program
- `scripts/` – shell wrappers (CLI helpers)
- `tests/` – TypeScript/Node test suite, integration tests & bank-run utilities
- Config and manifest files: `Anchor.toml`, `Cargo.toml`, `package.json`, `tsconfig.json`

##### README for additional insights
- Describes key use cases & stakeholders (Admin, Keeper, Token team, Partner, Liquidity provider, Trading bot)
- Lists all on-chain “endpoints” (instructions) and state schema (config keys, pools, positions)
- Specifies tech stack: Anchor 0.31.0, Solana 2.1.0, Rust 1.85.0, TS tests

##### Capturing essential elements
- Separate user roles and their distinct flows (Admin vs LP vs Trader)
- Make PDAs explicit to illustrate how state is organized on-chain
- Detail the off-chain SDK/CLI/test harness to show the full dev/test lifecycle

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    subgraph "Users"
        direction TB
        Admin("Admin"):::external
        LiquidityProvider("Liquidity Provider"):::external
        Trader("Trader"):::external
        Keeper("Keeper"):::external
        TokenTeam("Token Team"):::external
    end

    %% Off-chain Clients
    subgraph "Off-chain Clients & SDKs"
        direction TB
        RustSDK("Rust SDK"):::offchain
        CLI("CLI Helpers & Shell Scripts"):::offchain
        TSTests("TS Test Harness & Integration Tests"):::offchain
    end

    %% Solana Cluster
    SolanaCluster("Solana Cluster\n(Devnet/Mainnet-beta)"):::cloud

    %% On-chain Program
    subgraph "On-chain Program (cp-amm)" 
        direction TB
        Instructions["Instruction Handlers"]:::onchain
        subgraph "instructions"
            direction TB
            AdminInstr("Admin"):::onchain
            InitPoolInstr("Initialize Pool"):::onchain
            PartnerInstr("Partner"):::onchain
            CoreInstr("Swap, Liquidity, Position, Reward"):::onchain
        end
        subgraph "state"
            direction TB
            StateCode("PDAs & Schemas"):::storage
            ConfigKey("ConfigKey Account"):::storage
            PoolAccount("PoolAccount PDA"):::storage
            PositionNFT("PositionNFT PDA"):::storage
            FeeVault("FeeVault Account"):::storage
            RewardVault("RewardVault Account"):::storage
        end
        subgraph "constants & params"
            direction TB
            ConstPDA("PDA Constants"):::onchain
            Constants("Constants"):::onchain
            Params("Parameter Definitions"):::onchain
        end
        subgraph "math"
            direction TB
            MathModules("Fee/Safe/Fixed-Point Math"):::onchain
        end
        PoolAction("Pool Action Access Control"):::onchain
        Utils("Utility Helpers"):::onchain
        Lib("lib.rs"):::onchain
        Macros("macros.rs"):::onchain
        Tests("On-chain Tests"):::onchain
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        CIWorkflows(".github/workflows/ci.yml"):::ci
        SetupActions(".github/actions/setup-*"):::ci
        Build("Anchor Build & BPF Compilation"):::ci
        Deploy("Deploy to Cluster"):::ci
        IntegrationTests("Run Integration Tests"):::ci
    end

    %% Flows
    Admin -->|uses| RustSDK
    LiquidityProvider -->|uses| RustSDK
    Trader -->|uses| RustSDK
    Keeper -->|uses| CLI
    TokenTeam -->|uses| CLI
    TSTests -->|executes| SolanaCluster

    RustSDK -->|sends txs| SolanaCluster
    CLI -->|sends txs| SolanaCluster
    TSTests -->|sends txs| SolanaCluster

    SolanaCluster -->|invokes| Lib
    Lib --> Instructions
    Instructions --> AdminInstr
    Instructions --> InitPoolInstr
    Instructions --> PartnerInstr
    Instructions --> CoreInstr

    Lib --> StateCode
    StateCode --> ConfigKey
    StateCode --> PoolAccount
    StateCode --> PositionNFT
    StateCode --> FeeVault
    StateCode --> RewardVault

    Lib --> ConstPDA
    Lib --> Constants
    Lib --> Params
    Lib --> MathModules
    Lib --> PoolAction
    Lib --> Utils
    Lib --> Macros
    Lib --> Tests

    FeeVault -->|flows fees| LiquidityProvider
    RewardVault -->|flows rewards| LiquidityProvider

    %% CI/CD flows
    CIWorkflows -.-> SetupActions
    SetupActions -.-> Build
    Build -.-> Deploy
    Deploy -.-> SolanaCluster
    Deploy -.-> TSTests
    TSTests -.-> IntegrationTests

    %% Click events
    click RustSDK "https://github.com/meteoraag/damm-v2/tree/main/rust-sdk/"
    click CLI "https://github.com/meteoraag/damm-v2/tree/main/scripts/"
    click TSTests "https://github.com/meteoraag/damm-v2/tree/main/tests/"
    click AdminInstr "https://github.com/meteoraag/damm-v2/tree/main/programs/cp-amm/src/instructions/admin/"
    click InitPoolInstr "https://github.com/meteoraag/damm-v2/tree/main/programs/cp-amm/src/instructions/initialize_pool/"
    click PartnerInstr "https://github.com/meteoraag/damm-v2/tree/main/programs/cp-amm/src/instructions/partner/"
    click CoreInstr "https://github.com/meteoraag/damm-v2/tree/main/programs/cp-amm/src/instructions/"
    click StateCode "https://github.com/meteoraag/damm-v2/tree/main/programs/cp-amm/src/state/"
    click ConstPDA "https://github.com/meteoraag/damm-v2/blob/main/programs/cp-amm/src/const_pda.rs"
    click Constants "https://github.com/meteoraag/damm-v2/blob/main/programs/cp-amm/src/constants.rs"
    click MathModules "https://github.com/meteoraag/damm-v2/tree/main/programs/cp-amm/src/math/"
    click Params "https://github.com/meteoraag/damm-v2/tree/main/programs/cp-amm/src/params/"
    click PoolAction "https://github.com/meteoraag/damm-v2/tree/main/programs/cp-amm/src/pool_action_access/"
    click Utils "https://github.com/meteoraag/damm-v2/tree/main/programs/cp-amm/src/utils/"
    click Lib "https://github.com/meteoraag/damm-v2/blob/main/programs/cp-amm/src/lib.rs"
    click Macros "https://github.com/meteoraag/damm-v2/blob/main/programs/cp-amm/src/macros.rs"
    click Tests "https://github.com/meteoraag/damm-v2/tree/main/programs/cp-amm/src/tests/"
    click CIWorkflows "https://github.com/meteoraag/damm-v2/blob/main/.github/workflows/ci.yml"
    click SetupActions "https://github.com/meteoraag/damm-v2/blob/main/.github/actions/setup-*/action.yml"

    %% Classes
    classDef external fill:#ffe0b2,stroke:#ff9800,color:#000
    classDef offchain fill:#bbdefb,stroke:#2196f3,color:#000
    classDef cloud fill:#c8e6c9,stroke:#4caf50,color:#000
    classDef onchain fill:#ffcdd2,stroke:#f44336,color:#000
    classDef storage fill:#e0e0e0,stroke:#9e9e9e,color:#000
    classDef ci fill:#f5f5f5,stroke:#607d8b,color:#000
```
