# igneous-labs/s architecture

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

- Interactive diagram: https://gitdiagram.com/igneous-labs/s
- Repository: https://github.com/igneous-labs/s

## Overview

##### Main Components
- Off-Chain Client/CLI & Tooling:
- The CLI client (found under the “cli” directory) that is used by the authorities to manage the pool.
- Supporting utilities and test fixtures that help simulate transactions and perform integration tests.
- Libraries and Shared Code:
- A vast set of libraries under “libs” that encapsulate business logic, account resolvers, instruction sets, account serialization, and calculation modules (like pricing logic and value calculations).
- These libraries are used both in the on-chain programs and by the CLI tools.
- On-Chain Programs:
- S Controller Program: Handles pool operations such as liquidity management, administrative changes, and authority-based commands.
- Pricing Programs: Contains flat-fee and no-fee pricing logic to compute the swaps and fee distributions.
- SOL Value Calculator Programs: Multiple variants (including generic, lido, marinade, wSOL, etc.) that execute the logic for converting between token representations.
- IDL and Generated Artifacts:
- “idl” and “generated” directories provide JSON interfaces and generated Rust interfaces for program instructions, ensuring consistency between the on-chain programs and off-chain clients.
- Deployment and Configuration:
- Configuration files (such as Cargo.toml, pre-commit, and the Solana toolchain files) ensure reproducible builds, while keys directories indicate the cryptographic keys used to sign transactions and deploy the programs.
- External Systems:
- Although not traditional “external” services, the project’s interaction with the Solana blockchain (and tools like solana-cargo-build-sbf and solana-verify) should be clearly noted.

##### Relationships and Interactions
- The CLI client (*.rs files in the “cli” folder) sends “commands” to the on-chain programs. This communication happens via transactions executed on the Solana blockchain.
- The on-chain programs use the libraries (from “libs”) for common logic such as account handling, fee computations, and program-specific instruction processing.
- The IDL and generated interfaces serve as a contract between the off-chain (e.g., CLI) and on-chain code, ensuring that the instructions, errors, and data definitions match.
- Testing utilities (in “test-fixtures” and “test-utils”) simulate interactions, validate program logic, and ensure robustness.
- Build and deployment pipelines (using Dockerfiles in cli and solana toolchain definitions) ensure that the programs are compiled with the correct Rust and Solana environment.

##### Architectural Patterns and Design Principles
- Modularity: The separation into “cli,” “libs,” “programs,” and “generated” shows a strong modular structure, facilitating independent development and testing.
- IDL-first Approach: This design principle ensures the system’s external contracts (instructions/data types) are well defined and versioned.
- Microservices-like On-chain Components: Though all on-chain programs run on the same blockchain, the clear separation into S Controller, Pricing, and SOL Value Calculators represents a microservices abstraction.
- Reproducible Builds: Ensuring consistent builds across environments (as seen with explicit Solana versioning and Cargo configurations) is also an important design consideration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-Chain Client/CLI & Tooling
    subgraph "Off-Chain Client/CLI & Tooling"
        CLI["\"CLI Client\""]:::cli
        CLI_Tools["\"Test Utilities\""]:::cli
    end

    %% IDL & Generated Interfaces
    subgraph "IDL & Generated Interfaces"
        IDL["\"IDL Files & Generated Interfaces\""]:::idl
    end

    %% On-Chain Programs
    subgraph "On-Chain Programs"
        %% S Controller Program
        subgraph "S Controller Program"
            S_Controller["\"S Controller Program\""]:::program
        end

        %% Pricing Programs
        subgraph "Pricing Programs"
            Pricing_Flat["\"Flat Fee Pricing\""]:::program
            Pricing_NoFee["\"No Fee Pricing\""]:::program
        end

        %% SOL Value Calculators
        subgraph "SOL Value Calculators"
            Calc_Generic["\"Generic Pool Calculator\""]:::program
            Calc_Lido["\"Lido Calculator\""]:::program
            Calc_Marinade["\"Marinade Calculator\""]:::program
            Calc_wSOL["\"wSOL Calculator\""]:::program
        end
    end

    %% Shared Libraries & Business Logic
    subgraph "Shared Libraries & Business Logic"
        LIBS["\"Shared Libraries\""]:::libs
    end

    %% Deployment and Configuration
    subgraph "Deployment and Configuration"
        DEPLOY["\"Keys & Configurations\""]:::deploy
    end

    %% Interactions and Data Flow
    %% CLI sends commands to on-chain programs
    CLI -->|"sends_commands"| S_Controller
    CLI -->|"sends_commands"| Pricing_Flat
    CLI -->|"sends_commands"| Calc_Generic

    %% CLI interacts with IDL interfaces
    CLI <==>|"IDL_contract"| IDL

    %% On-chain programs interact with IDL interfaces
    S_Controller <==>|"IDL_contract"| IDL
    Pricing_Flat <==>|"IDL_contract"| IDL
    Pricing_NoFee <==>|"IDL_contract"| IDL
    Calc_Generic <==>|"IDL_contract"| IDL
    Calc_Lido <==>|"IDL_contract"| IDL
    Calc_Marinade <==>|"IDL_contract"| IDL
    Calc_wSOL <==>|"IDL_contract"| IDL

    %% On-chain programs depend on shared libraries
    S_Controller -->|"uses_library"| LIBS
    Pricing_Flat -->|"uses_library"| LIBS
    Pricing_NoFee -->|"uses_library"| LIBS
    Calc_Generic -->|"uses_library"| LIBS
    Calc_Lido -->|"uses_library"| LIBS
    Calc_Marinade -->|"uses_library"| LIBS
    Calc_wSOL -->|"uses_library"| LIBS

    %% Deployment/Configuration supports build and keys for both CLI and On-chain Programs
    DEPLOY -->|"build_config"| CLI
    DEPLOY -->|"build_config"| S_Controller
    DEPLOY -->|"build_config"| Pricing_Flat
    DEPLOY -->|"build_config"| Pricing_NoFee
    DEPLOY -->|"build_config"| Calc_Generic
    DEPLOY -->|"build_config"| Calc_Lido
    DEPLOY -->|"build_config"| Calc_Marinade
    DEPLOY -->|"build_config"| Calc_wSOL

    %% Click Events for Off-Chain Client/CLI & Tooling
    click CLI "https://github.com/igneous-labs/s/tree/master/cli"
    click CLI_Tools "https://github.com/igneous-labs/s/tree/master/cli/cli-test-utils"
    %% Additional CLI related components
    %% (Assuming these subdirectories are part of the CLI layer)
    click CLI "https://github.com/igneous-labs/s/tree/master/cli/generic-pool-calculator"
    click CLI "https://github.com/igneous-labs/s/tree/master/cli/pricing-programs"
    click CLI "https://github.com/igneous-labs/s/tree/master/cli/s-controller"
    click CLI "https://github.com/igneous-labs/s/tree/master/cli/s-cli-utils"

    %% Click Events for Shared Libraries
    click LIBS "https://github.com/igneous-labs/s/tree/master/libs"
    click LIBS "https://github.com/igneous-labs/s/tree/master/libs/pricing-programs"
    click LIBS "https://github.com/igneous-labs/s/tree/master/libs/s-controller-lib"
    click LIBS "https://github.com/igneous-labs/s/tree/master/libs/s-jup-interface"
    click LIBS "https://github.com/igneous-labs/s/tree/master/libs/sanctum-s-common"
    click LIBS "https://github.com/igneous-labs/s/tree/master/libs/sol-value-calculator-programs"

    %% Click Events for On-Chain Programs – S Controller
    click S_Controller "https://github.com/igneous-labs/s/tree/master/programs/s-controller"
    %% Assuming tests are associated with the S Controller Program
    click S_Controller "https://github.com/igneous-labs/s/tree/master/programs/s-controller/tests"

    %% Click Events for On-Chain Programs – Pricing Programs
    click Pricing_Flat "https://github.com/igneous-labs/s/tree/master/programs/pricing-programs/flat-fee"
    click Pricing_NoFee "https://github.com/igneous-labs/s/tree/master/programs/pricing-programs/no-fee-pricing-program"

    %% Click Events for On-Chain Programs – SOL Value Calculators
    click Calc_Generic "https://github.com/igneous-labs/s/tree/master/programs/sol-value-calculator-programs"
    click Calc_Lido "https://github.com/igneous-labs/s/tree/master/programs/sol-value-calculator-programs/lido-calculator"
    click Calc_Marinade "https://github.com/igneous-labs/s/tree/master/programs/sol-value-calculator-programs/marinade-calculator"
    click Calc_wSOL "https://github.com/igneous-labs/s/tree/master/programs/sol-value-calculator-programs/wsol-calculator"

    %% Click Events for IDL & Generated Interfaces
    click IDL "https://github.com/igneous-labs/s/tree/master/idl"
    click IDL "https://github.com/igneous-labs/s/tree/master/generated"

    %% Click Events for Deployment and Configuration
    click DEPLOY "https://github.com/igneous-labs/s/tree/master/keys"
    click DEPLOY "https://github.com/igneous-labs/s/blob/master/Cargo.toml"
    click DEPLOY "https://github.com/igneous-labs/s/blob/master/.pre-commit-config.yaml"
    click DEPLOY "https://github.com/igneous-labs/s/blob/master/rust-toolchain.toml"
    click DEPLOY "https://github.com/igneous-labs/s/tree/master/test-fixtures"
    click DEPLOY "https://github.com/igneous-labs/s/blob/master/install-precommit.sh"

    %% Styles
    classDef cli fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef idl fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef program fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef libs fill:#A3E4D7,stroke:#17A589,stroke-width:2px;
    classDef deploy fill:#F5B7B1,stroke:#CB4335,stroke-width:2px;
```
