# raydium-io/raydium-sdk-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/raydium-io/raydium-sdk-v2
- Repository: https://github.com/raydium-io/raydium-sdk-v2

## Overview

##### Project Type and Purpose
- This is a TypeScript/Node.js SDK library (“@raydium-io/raydium-sdk-v2”) for interacting with the Raydium decentralized finance protocols on Solana.
- It exposes programmatic methods to initialize a Raydium client, fetch on-chain data (pools, farms, markets), build and sign transactions, and parse token/account information.

##### File Structure Analysis
- Top-level config: .babelrc, tsconfig.json, jest.config.ts, package.json, etc.
- src/
- api/: HTTP wrapper around Raydium REST endpoints (api.ts, url.ts, type.ts).
- common/: low-level utilities (big numbers, dates, PDAs, logging, error handling, txTool for assembling transactions).
- marshmallow/: binary data layout/serialization support.
- module/: high-level domain constructs (amount, currency, fraction, formatter, token).
- solana/: thin wrapper types around solana/web3 types.
- raydium/: core Raydium protocol modules, each under subfolders (account, clmm, cpmm, farm, ido, launchpad, liquidity, marketV2, serum, token, tradeV2, utils1216).
- test/: SDK integration/local tests (init.ts).

##### README Insights
- Describes SDK initialization (Raydium.load), optional wallet adaptor, token account parsing.
- Lists available API methods (getTokenList, fetchPoolById, fetchFarmInfoById).
- Demonstrates dependency on Solana RPC, token-program accounts, @solana/wallet-adapter for signing.

##### Diagramming the Architecture
a. Main Components
1. SDK Core
- Raydium.load() bootstrap
- Raydium client object
2. API Layer
- src/api – HTTP client calling Raydium REST services
3. Common Utilities
- src/common – helpers for BigNumber, PDA derivation, logging, txTool
4. Serialization Layer
- src/marshmallow – BufferLayout definitions
5. Domain Modules
- src/module – domain primitives (currency, amount, fraction)
6. Protocol Modules
- src/raydium/* – on-chain instruction builders & parsers for each Raydium program
7. Solana Interaction
- src/solana – wrapper types
- solana/web3.js RPC connection & wallet adapter for signing
8. External Systems
- Solana JSON-RPC node
- @solana/wallet-adapter (browser or Node keypair)
- Raydium on-chain programs & Serum DEX

b. Relationships and Interactions
- The application imports Raydium.load() → Core initializes with a RPC Connection + Signer → populates token maps (via API Layer + Common Utils) → user invokes protocol modules (e.g., clmm.swap, farm.stake) → uses marshmallow to serialize account layouts → common txTool assembles transactions → Solana Interaction sends signed txs to JSON-RPC → on-chain Raydium/Serum programs process them.
- API Layer fetches off-chain metadata (pools, tokens) and feeds Domain Modules.
- Common Utilities are shared by Core, API, Domain, and Protocol modules.

c. Architectural Patterns & Principles
- Layered modular design:
- Presentation → SDK Core/API
- Domain → module/*, common/*
- Infrastructure → solana/*, marshmallow/*
- Persistence (on-chain) → protocol modules under raydium/*
- Separation of concerns: HTTP vs on-chain, serialization vs business logic.
- Extensibility: each Raydium subprotocol is a standalone folder.

d. Key Technologies
- TypeScript, Node.js, Yarn
- solana/web3.js, @solana/wallet-adapter
- BufferLayout for binary serialization (marshmallow)
- Axios or fetch (within src/api)
- Jest for tests

##### Detailed Guidance
- Data transformations: raw on-chain account bytes → marshmallow layouts → typed JS objects.
- Optional paths (e.g., wallet adapter vs direct Keypair).
- Versioning/config: package.json, tsconfig—denote build/test pipeline if desired.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        style ES fill:#ccffcc,stroke:#006600,stroke-width:2px
        REST_API["Raydium REST API"]:::external
        JSON_RPC["Solana JSON-RPC Node"]:::external
        WALLET["@solana/wallet-adapter"]:::external
        ONCHAIN["Raydium & Serum On-chain Programs"]:::external
    end

    %% SDK Components
    subgraph "SDK Internal Layers"
        style SI fill:#e6f2ff,stroke:#004080,stroke-width:2px

        subgraph "SDK Core"
            style SC fill:#cce0ff,stroke:#004080
            CoreIndex["src/index.ts"]:::core
            RaydiumTS["src/raydium/raydium.ts"]:::core
            ModuleBase["src/raydium/moduleBase.ts"]:::core
        end

        subgraph "API Layer"
            style AL fill:#cce0ff,stroke:#004080
            APIIndex["src/api/index.ts"]:::api
            APIClient["src/api/api.ts"]:::api
            APIURL["src/api/url.ts"]:::api
            APIType["src/api/type.ts"]:::api
            APIUtils["src/api/utils.ts"]:::api
        end

        subgraph "Common Utilities"
            style CU fill:#cce0ff,stroke:#004080
            CommonIndex["src/common/index.ts"]:::common
            BN["src/common/bignumber.ts"]:::common
            PDA["src/common/pda.ts"]:::common
            Logger["src/common/logger.ts"]:::common

            subgraph "txTool"
                style TT fill:#e6f2ff,stroke:#004080
                TxTool["src/common/txTool/txTool.ts"]:::common
                Lookup["src/common/txTool/lookupTable.ts"]:::common
                TxUtils["src/common/txTool/txUtils.ts"]:::common
            end
        end

        subgraph "Serialization (marshmallow)"
            style ML fill:#cce0ff,stroke:#004080
            MarshIndex["src/marshmallow/index.ts"]:::serial
            BufferLayout["src/marshmallow/buffer-layout.ts"]:::serial
        end

        subgraph "Domain Modules"
            style DM fill:#cce0ff,stroke:#004080
            ModIndex["src/module/index.ts"]:::domain
            Amount["src/module/amount.ts"]:::domain
            Currency["src/module/currency.ts"]:::domain
            Fraction["src/module/fraction.ts"]:::domain
            Formatter["src/module/formatter.ts"]:::domain
            TokenMod["src/module/token.ts"]:::domain
        end

        subgraph "Protocol Modules"
            style PM fill:#ffe6cc,stroke:#994d00
            AccountMod["account/"]:::protocol
            ClmmMod["clmm/"]:::protocol
            CpmmMod["cpmm/"]:::protocol
            FarmMod["farm/"]:::protocol
            IDOMod["ido/"]:::protocol
            LaunchpadMod["launchpad/"]:::protocol
            LiquidityMod["liquidity/"]:::protocol
            MarketV2Mod["marketV2/"]:::protocol
            SerumMod["serum/"]:::protocol
            TokenPM["token/"]:::protocol
            TradeV2Mod["tradeV2/"]:::protocol
            Utils1216["utils1216/"]:::protocol
            RaydiumIndex["src/raydium/index.ts"]:::protocol
        end

        subgraph "Solana Interaction"
            style SI2 fill:#cce0ff,stroke:#004080
            SolIndex["src/solana/index.ts"]:::sol
            SolType["src/solana/type.ts"]:::sol
        end

        subgraph "Tests"
            style TS fill:#e6f2ff,stroke:#004080
            InitTest["test/init.ts"]:::test
        end
    end

    %% Relationships
    CoreIndex -->|boots with| SolIndex
    CoreIndex -->|loads modules| RaydiumTS
    CoreIndex -->|uses| APIIndex
    CoreIndex -->|uses| CommonIndex
    CoreIndex -->|uses| ModIndex
    CoreIndex -->|uses| MarshIndex
    CoreIndex -->|loads| RaydiumIndex

    APIIndex -->|calls| REST_API
    APIClient -->|uses URL/types/utils| APIURL
    APIIndex -->|uses| APIClient
    APIIndex -->|feeds| ModIndex

    CommonIndex -->|provides| BN
    CommonIndex -->|provides| PDA
    CommonIndex -->|provides| Logger
    CommonIndex -->|provides| TxTool

    ModIndex -->|defines| Amount
    ModIndex -->|defines| Currency
    ModIndex -->|defines| Fraction
    ModIndex -->|defines| Formatter
    ModIndex -->|defines| TokenMod

    MarshIndex -->|serializes| ProtocolModules

    RaydiumIndex -->|aggregates| AccountMod
    RaydiumIndex -->|aggregates| ClmmMod
    RaydiumIndex -->|aggregates| CpmmMod
    RaydiumIndex -->|aggregates| FarmMod
    RaydiumIndex -->|aggregates| IDOMod
    RaydiumIndex -->|aggregates| LaunchpadMod
    RaydiumIndex -->|aggregates| LiquidityMod
    RaydiumIndex -->|aggregates| MarketV2Mod
    RaydiumIndex -->|aggregates| SerumMod
    RaydiumIndex -->|aggregates| TokenPM
    RaydiumIndex -->|aggregates| TradeV2Mod
    RaydiumIndex -->|aggregates| Utils1216

    AccountMod -->|builds txs| TxTool
    ClmmMod -->|builds txs| TxTool
    CpmmMod -->|builds txs| TxTool
    FarmMod -->|builds txs| TxTool
    IDOMod -->|builds txs| TxTool
    LaunchpadMod -->|builds txs| TxTool
    LiquidityMod -->|builds txs| TxTool
    MarketV2Mod -->|builds txs| TxTool
    SerumMod -->|builds txs| TxTool
    TokenPM -->|builds txs| TxTool
    TradeV2Mod -->|builds txs| TxTool
    Utils1216 -->|builds txs| TxTool

    TxTool -->|sends signed| JSON_RPC
    SolIndex -->|connects to| JSON_RPC
    SolIndex -->|uses| WALLET
    WALLET -->|signs tx| TxTool
    JSON_RPC -->|executes| ONCHAIN

    InitTest -->|tests| CoreIndex

    %% Click events
    click CoreIndex "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/index.ts"
    click RaydiumTS "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/raydium/raydium.ts"
    click ModuleBase "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/raydium/moduleBase.ts"
    click APIIndex "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/api/index.ts"
    click APIClient "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/api/api.ts"
    click APIURL "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/api/url.ts"
    click APIType "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/api/type.ts"
    click APIUtils "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/api/utils.ts"
    click CommonIndex "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/common/index.ts"
    click BN "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/common/bignumber.ts"
    click PDA "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/common/pda.ts"
    click Logger "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/common/logger.ts"
    click TxTool "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/common/txTool/txTool.ts"
    click Lookup "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/common/txTool/lookupTable.ts"
    click TxUtils "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/common/txTool/txUtils.ts"
    click MarshIndex "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/marshmallow/index.ts"
    click BufferLayout "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/marshmallow/buffer-layout.ts"
    click ModIndex "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/module/index.ts"
    click Amount "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/module/amount.ts"
    click Currency "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/module/currency.ts"
    click Fraction "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/module/fraction.ts"
    click Formatter "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/module/formatter.ts"
    click TokenMod "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/module/token.ts"
    click AccountMod "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/account/"
    click ClmmMod "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/clmm/"
    click CpmmMod "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/cpmm/"
    click FarmMod "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/farm/"
    click IDOMod "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/ido/"
    click LaunchpadMod "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/launchpad/"
    click LiquidityMod "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/liquidity/"
    click MarketV2Mod "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/marketV2/"
    click SerumMod "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/serum/"
    click TokenPM "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/token/"
    click TradeV2Mod "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/tradeV2/"
    click Utils1216 "https://github.com/raydium-io/raydium-sdk-v2/tree/master/src/raydium/utils1216/"
    click RaydiumIndex "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/raydium/index.ts"
    click SolIndex "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/solana/index.ts"
    click SolType "https://github.com/raydium-io/raydium-sdk-v2/blob/master/src/solana/type.ts"
    click InitTest "https://github.com/raydium-io/raydium-sdk-v2/blob/master/test/init.ts"

    %% Classes
    classDef external fill:#ccffcc,stroke:#006600,stroke-width:1px
    classDef core fill:#cce0ff,stroke:#003366
    classDef api fill:#cce0ff,stroke:#003366
    classDef common fill:#cce0ff,stroke:#003366
    classDef serial fill:#cce0ff,stroke:#003366
    classDef domain fill:#cce0ff,stroke:#003366
    classDef protocol fill:#ffe6cc,stroke:#994d00
    classDef sol fill:#cce0ff,stroke:#003366
    classDef test fill:#e6f2ff,stroke:#003366
```
