# turbos-finance/turbos-clmm-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/turbos-finance/turbos-clmm-sdk
- Repository: https://github.com/turbos-finance/turbos-clmm-sdk

## Overview

##### Project Type and Purpose
- This is a TypeScript SDK (open-source library) that provides a high-level facade for interacting with a Sui-based concentrated-liquidity AMM (CLMM).
- Its main goal is to expose modules like contract, trade, pool, nft, account, and math so that dApp developers can easily query on-chain data and build/execute transactions.

##### File Structure
- Top–level config for linting, formatting, CI/CD (.github, .husky, tsconfig.json, vitest.config.ts, tsup.config.ts).
- Source code under src/:
- src/constants: network & magic numbers
- src/lib: module implementations (account.ts, contract.ts, trade.ts, pool.ts, nft.ts, math.ts, etc.)
- src/utils: helper functions (bit-math, quote calculations, Sui-kit wrappers)
- src/sdk.ts: entry point, constructs TurbosSdk class exposing each module
- src/index.ts: package export aggregator
- Tests under test/ validate each module.

##### Extract Architecture Clues from README
- README shows instantiation patterns: TurbosSdk takes a Network enum or a JsonRpcProvider.
- Exposes methods: sdk.contract.getConfig(), sdk.trade.swap(), etc.
- Relies on @mysten/sui’s JsonRpcProvider to talk to testnet/mainnet.

##### Main Components & Their Relationships
a. Developer Application
- Imports TurbosSdk, passes network/provider, calls high-level methods.
b. TurbosSdk (Facade Layer)
- Holds references to all modules (contract, trade, pool, nft, account, math).
- Normalizes input parameters and delegates calls.
c. Modules (Business Logic Layer)
- Each module (in src/lib) contains functions that build RPC queries or transactions, call utils, use constants.
d. Utils & Constants (Helper Layer)
- Pure functions for bit math, fee/reward quotes, object validation.
- Centralized magic-numbers and network configurations.
e. Sui JsonRpcProvider (Infrastructure Layer)
- Underlying RPC client from @mysten/sui that sends JSON-RPC requests to the blockchain.
f. Sui Blockchain Nodes
- Remote testnet/mainnet nodes which process requests and return data or transaction confirmations.

##### Architectural Patterns & Principles
- Facade Pattern: TurbosSdk exposes a simplified interface over many modules.
- Layered Architecture: separation between SDK entrypoint, modules, utilities, and external provider.
- Single-Responsibility: each module focuses on one domain (trade, pool, etc.).
- Dependency Injection: provider can be passed in by consumer.

##### Key Details to Capture
- Facade entrypoint (src/sdk.ts) and how it wires modules.
- Each module’s reliance on provider and utils.
- Flow of data: high-level method call → module logic → provider RPC → blockchain → back.
- Configurable network/provider at SDK instantiation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Layer
    DeveloperApp["Developer dApp"]:::consumer
    DeveloperApp -->|"import TurbosSdk"| SDKExport

    %% SDK Export Aggregator
    SDKExport["src/index.ts\n(SDK Export Aggregator)"]:::sdk
    click SDKExport "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/index.ts"
    SDKExport -->|"exports TurbosSdk"| TurbosSdk

    %% Facade Layer
    subgraph "TurbosSdk Facade" 
        direction TB
        TurbosSdk["TurbosSdk\n(src/sdk.ts)"]:::sdk
        click TurbosSdk "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/sdk.ts"
        subgraph Modules
            direction TB
            AccountModule["Account Module\n(src/lib/account.ts)"]:::module
            click AccountModule "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/lib/account.ts"
            ContractModule["Contract Module\n(src/lib/contract.ts)"]:::module
            click ContractModule "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/lib/contract.ts"
            TradeModule["Trade Module\n(src/lib/trade.ts)"]:::module
            click TradeModule "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/lib/trade.ts"
            PoolModule["Pool Module\n(src/lib/pool.ts)"]:::module
            click PoolModule "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/lib/pool.ts"
            NFTModule["NFT Module\n(src/lib/nft.ts)"]:::module
            click NFTModule "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/lib/nft.ts"
            MathModule["Math Module\n(src/lib/math.ts)"]:::module
            click MathModule "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/lib/math.ts"
            BaseHelpers["Shared Base Helpers\n(src/lib/base.ts)"]:::module
            click BaseHelpers "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/lib/base.ts"
            ModuleIndex["Module Index\n(src/lib/index.ts)"]:::module
            click ModuleIndex "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/lib/index.ts"
        end
        TurbosSdk -->|"constructs modules"| AccountModule
        TurbosSdk -->|"constructs modules"| ContractModule
        TurbosSdk -->|"constructs modules"| TradeModule
        TurbosSdk -->|"constructs modules"| PoolModule
        TurbosSdk -->|"constructs modules"| NFTModule
        TurbosSdk -->|"constructs modules"| MathModule
        TurbosSdk -->|"uses base"| BaseHelpers
        TurbosSdk -->|"uses index"| ModuleIndex
    end

    %% Utils & Constants Layer
    subgraph "Utils & Constants" 
        direction TB
        ConstantsDir["Constants Directory\n(src/constants)"]:::helper
        click ConstantsDir "https://github.com/turbos-finance/turbos-clmm-sdk/tree/main/src/constants"
        MagicNumbers["Magic Numbers\n(src/constants/magic-numbers.ts)"]:::helper
        click MagicNumbers "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/constants/magic-numbers.ts"
        NetworkConfig["Network Config\n(src/constants/network.ts)"]:::helper
        click NetworkConfig "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/constants/network.ts"
        ConstantsIndex["Constants Entry\n(src/constants/index.ts)"]:::helper
        click ConstantsIndex "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/constants/index.ts"
        UtilsDir["Utils Directory\n(src/utils)"]:::helper
        click UtilsDir "https://github.com/turbos-finance/turbos-clmm-sdk/tree/main/src/utils"
        BitMath["Bit Math Helpers\n(src/utils/bit-math.ts)"]:::helper
        click BitMath "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/utils/bit-math.ts"
        FeesQuote["Fee Quote Calc\n(src/utils/collect-fees-quote.ts)"]:::helper
        click FeesQuote "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/utils/collect-fees-quote.ts"
        RewardsQuote["Rewards Quote Calc\n(src/utils/collect-rewards-quote.ts)"]:::helper
        click RewardsQuote "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/utils/collect-rewards-quote.ts"
        DeprecatedRewards["Deprecated Rewards\n(src/utils/deprecated-pool-rewards.ts)"]:::helper
        click DeprecatedRewards "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/utils/deprecated-pool-rewards.ts"
        ObjectValidation["Object Validation\n(src/utils/validate-object-response.ts)"]:::helper
        click ObjectValidation "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/utils/validate-object-response.ts"
        NullIDChecker["Null-ID Checker\n(src/utils/is-null-object-id.ts)"]:::helper
        click NullIDChecker "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/utils/is-null-object-id.ts"
        SuiKit["Sui-kit RPC Wrappers\n(src/utils/sui-kit.ts)"]:::helper
        click SuiKit "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/src/utils/sui-kit.ts"
    end

    %% Infrastructure Layer
    JsonProvider["JsonRpcProvider\n(@mysten/sui)"]:::infra
    SuiNetwork["Sui Network\n(testnet/mainnet)"]:::infra

    %% Test Layer
    subgraph "Tests (Validation)" 
        direction TB
        ModuleTests["Module Unit Tests\n(test/*.test.ts)"]:::test
        click ModuleTests "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/test/*.test.ts"
        SDKHelper["Helper SDK Creator\n(test/helper/create-sdk.ts)"]:::test
        click SDKHelper "https://github.com/turbos-finance/turbos-clmm-sdk/blob/main/test/helper/create-sdk.ts"
    end

    %% Relationships
    AccountModule -->|uses| UtilsDir
    ContractModule -->|uses| UtilsDir
    TradeModule -->|uses| UtilsDir
    PoolModule -->|uses| UtilsDir
    NFTModule -->|uses| UtilsDir
    MathModule -->|uses| UtilsDir
    BaseHelpers -->|uses| UtilsDir

    AccountModule -->|uses| ConstantsDir
    ContractModule -->|uses| ConstantsDir
    TradeModule -->|uses| ConstantsDir
    PoolModule -->|uses| ConstantsDir
    NFTModule -->|uses| ConstantsDir
    MathModule -->|uses| ConstantsDir

    subgraph RPC_Flow
        TurbosSdk -->|"module call"| JsonProvider
        JsonProvider -->|"RPC request/response"| SuiNetwork
        SuiNetwork -->|"data/tx result"| JsonProvider
        JsonProvider -->|"returns data"| TurbosSdk
    end

    DeveloperApp -->|"runs tests"| ModuleTests
    ModuleTests -->|"utilizes"| SDKHelper

    %% Styles
    classDef consumer fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef sdk fill:#87CEEB,stroke:#333,stroke-width:1px;
    classDef module fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef helper fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef infra fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef test fill:#DDA0DD,stroke:#333,stroke-width:1px;
```
