# raydium-io/raydium-amm architecture

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

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

## Overview

1. **Repository shape**
   This repo is a single Rust on-chain program crate under `program/`, not a multi-service application. The root `Cargo.toml` and `Cargo.lock` support building the Solana program, while `program/Xargo.toml` signals Solana BPF/SBF-oriented compilation.

2. **Primary runtime boundary**
   The deployed artifact is a Solana smart contract (`raydium-amm`) that runs inside the Solana validator runtime. The program ID differs by environment, with mainnet and devnet deployments called out in the README.

3. **External dependencies and ecosystem**
   The program depends on the Solana runtime, SPL Token / Associated Token Account / Token-2022 ecosystems, and OpenBook as the external centralized limit order book it integrates with. The AMM is not isolated liquidity logic; it also routes part of liquidity into OpenBook orders.

4. **Top-level request flow**
   Transaction flow is: an off-chain client builds an instruction, Solana invokes the program, `entrypoint.rs` hands control into the processor, and `processor.rs` executes the requested AMM operation against on-chain state. The program is effectively instruction-driven, with no persistent background jobs.

5. **Instruction parsing and dispatch**
   `instruction.rs` defines the program’s instruction schema and decodes incoming instruction data into concrete actions such as pool creation, deposit, withdraw, swap, and related pool/admin operations. This is the main interface boundary between clients and the on-chain logic.

6. **Core execution engine**
   `processor.rs` is the central orchestration layer. It interprets each instruction, validates accounts and state, applies AMM rules, and coordinates token transfers or OpenBook interactions. If you are drawing the architecture, this is the “business logic” center of the program.

7. **On-chain state model**
   `state.rs` contains the persistent account layouts used by the AMM, likely including pool metadata, vault references, LP token accounting, and OpenBook-related configuration. This module defines the data stored on chain and the structures the processor mutates.

8. **Pricing and amount calculations**
   `math.rs` isolates AMM formula logic and numeric helpers. This is where constant-product calculations, liquidity share arithmetic, slippage-related checks, and amount conversions are expected to live, separating deterministic math from account and CPI handling.

9. **Cross-program interactions**
   `invokers.rs` encapsulates CPI-style calls to other Solana programs, most importantly token movement and OpenBook-related actions. This boundary keeps external program invocations separated from core AMM state transitions.

10. **Operational support**
    `error.rs` defines program-specific error codes, and `log.rs` centralizes emitted logs for debugging and observability on chain. These do not change business behavior, but they are important for transaction diagnosis and monitoring.

11. **Feature/environment split**
    The README shows feature flags for `devnet` and `localnet`, which change program configuration such as cluster addresses and related pubkeys. Architecture-wise, the same codebase targets multiple Solana environments with different constants and deployment settings.

12. **Off-chain integration model**
    The README’s quickstart implies off-chain callers use `raydium-library` helpers to build instructions and sign transactions, then submit them via Solana RPC. So the full system boundary is: client app/library on one side, Solana AMM program on the other, with OpenBook and token programs as external on-chain dependencies.

Main entry points: [`program/src/processor.rs`](https://github.com/raydium-io/raydium-amm/blob/master/program/src/processor.rs) (Processor), [`program/src/lib.rs`](https://github.com/raydium-io/raydium-amm/blob/master/program/src/lib.rs) (Crate root), [`program/src/invokers.rs`](https://github.com/raydium-io/raydium-amm/blob/master/program/src/invokers.rs) (Invokers), [`program/src/entrypoint.rs`](https://github.com/raydium-io/raydium-amm/blob/master/program/src/entrypoint.rs) (Entrypoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onchain["On-chain program"]
  node_crate_root["Crate root<br/>Rust crate<br/>[lib.rs]"]
  node_entrypoint["Entrypoint<br/>SBF entry<br/>[entrypoint.rs]"]
  node_instruction["Instructions<br/>instruction schema<br/>[instruction.rs]"]
  node_processor["Processor<br/>execution engine<br/>[processor.rs]"]
  node_state[("State<br/>[state.rs]")]
  node_math["Math<br/>pricing logic<br/>[math.rs]"]
  node_invokers["Invokers<br/>CPI helpers<br/>[invokers.rs]"]
  node_error["Errors<br/>[error.rs]"]
  node_log["Logs<br/>observability<br/>[log.rs]"]
end

subgraph group_external["External ecosystem"]
  node_solana_runtime["Solana runtime<br/>validator runtime"]
  node_spl_token["SPL Token<br/>token program"]
  node_ata["ATA program<br/>account program"]
  node_token2022["Token-2022<br/>token program"]
  node_openbook["OpenBook<br/>orderbook program"]
  node_offchain_client(("Client<br/>off-chain caller"))
end

node_offchain_client -->|"build tx"| node_instruction
node_solana_runtime -->|"invoke"| node_entrypoint
node_entrypoint -->|"dispatch"| node_processor
node_instruction -->|"decode"| node_processor
node_crate_root -->|"exports"| node_entrypoint
node_crate_root -->|"exports"| node_instruction
node_crate_root -->|"exports"| node_processor
node_crate_root -->|"exports"| node_state
node_crate_root -->|"exports"| node_math
node_crate_root -->|"exports"| node_invokers
node_processor -->|"read/write"| node_state
node_processor -->|"compute"| node_math
node_processor -->|"cpi"| node_invokers
node_processor -->|"fail"| node_error
node_processor -->|"emit"| node_log
node_invokers -->|"cpi"| node_spl_token
node_invokers -->|"cpi"| node_ata
node_invokers -->|"cpi"| node_token2022
node_invokers -->|"cpi"| node_openbook
node_processor -->|"host APIs"| node_solana_runtime

click node_crate_root "https://github.com/raydium-io/raydium-amm/blob/master/program/src/lib.rs"
click node_entrypoint "https://github.com/raydium-io/raydium-amm/blob/master/program/src/entrypoint.rs"
click node_instruction "https://github.com/raydium-io/raydium-amm/blob/master/program/src/instruction.rs"
click node_processor "https://github.com/raydium-io/raydium-amm/blob/master/program/src/processor.rs"
click node_state "https://github.com/raydium-io/raydium-amm/blob/master/program/src/state.rs"
click node_math "https://github.com/raydium-io/raydium-amm/blob/master/program/src/math.rs"
click node_invokers "https://github.com/raydium-io/raydium-amm/blob/master/program/src/invokers.rs"
click node_error "https://github.com/raydium-io/raydium-amm/blob/master/program/src/error.rs"
click node_log "https://github.com/raydium-io/raydium-amm/blob/master/program/src/log.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_crate_root,node_entrypoint,node_instruction,node_processor,node_state,node_math,node_invokers,node_error,node_log toneBlue
class node_solana_runtime,node_spl_token,node_ata,node_token2022,node_openbook,node_offchain_client toneAmber
```

## Components

### On-chain program

Solana AMM program code and its local module boundaries.

- [Crate root](https://github.com/raydium-io/raydium-amm/blob/master/program/src/lib.rs): Rust crate · Library entry point that wires the program modules together. · `program/src/lib.rs`
- [Entrypoint](https://github.com/raydium-io/raydium-amm/blob/master/program/src/entrypoint.rs): SBF entry · Hands Solana runtime control into the program logic. · `program/src/entrypoint.rs`
- [Instructions](https://github.com/raydium-io/raydium-amm/blob/master/program/src/instruction.rs): instruction schema · Defines and decodes AMM instruction data. · `program/src/instruction.rs`
- [Processor](https://github.com/raydium-io/raydium-amm/blob/master/program/src/processor.rs): execution engine · Validates accounts, applies AMM rules, and orchestrates each instruction. · `program/src/processor.rs`
- [State](https://github.com/raydium-io/raydium-amm/blob/master/program/src/state.rs): account state · Persistent on-chain data layouts for pools, vaults, and related accounting. · `program/src/state.rs`
- [Math](https://github.com/raydium-io/raydium-amm/blob/master/program/src/math.rs): pricing logic · AMM formulas, amount conversions, and arithmetic helpers. · `program/src/math.rs`
- [Invokers](https://github.com/raydium-io/raydium-amm/blob/master/program/src/invokers.rs): CPI helpers · Cross-program invocation helpers for token movement and OpenBook actions. · `program/src/invokers.rs`
- [Errors](https://github.com/raydium-io/raydium-amm/blob/master/program/src/error.rs): program errors · Program-specific error codes and failure mapping. · `program/src/error.rs`
- [Logs](https://github.com/raydium-io/raydium-amm/blob/master/program/src/log.rs): observability · Centralized on-chain logging helpers. · `program/src/log.rs`

### External ecosystem

Runtime and other on-chain programs the AMM depends on.

- **Solana runtime**: validator runtime · Host runtime that executes the deployed program.
- **SPL Token**: token program · Token transfer and mint/burn program used by the AMM.
- **ATA program**: account program · Associated token account program used for token account handling.
- **Token-2022**: token program · Extended token program ecosystem supported by the AMM.
- **OpenBook**: orderbook program · External limit order book integrated by the AMM.
- **Client**: off-chain caller · Wallets, bots, or libraries that build and submit AMM transactions.

## Connections

- Client → Instructions: build tx · Off-chain callers assemble AMM instructions before submitting them.
- Solana runtime → Entrypoint: invoke · The validator runtime enters the program through the Solana entrypoint.
- Entrypoint → Processor: dispatch · Entrypoint hands control to the processor.
- Instructions → Processor: decode · Decoded instruction variants determine which processor path runs.
- Crate root → Entrypoint: exports · Crate root exposes the entrypoint module.
- Crate root → Instructions: exports · Crate root exposes instruction definitions.
- Crate root → Processor: exports · Crate root exposes the main execution engine.
- Crate root → State: exports · Crate root exposes account state types.
- Crate root → Math: exports · Crate root exposes arithmetic helpers.
- Crate root → Invokers: exports · Crate root exposes CPI helpers.
- Processor → State: read/write · Processor loads and mutates on-chain state accounts.
- Processor → Math: compute · Processor relies on AMM math for amounts and pricing.
- Processor → Invokers: cpi · Processor delegates external program calls to invokers.
- Processor → Errors: fail · Processor returns program-specific errors on validation or rule failures.
- Processor → Logs: emit · Processor emits structured logs for transaction diagnosis.
- Invokers → SPL Token: cpi · Token transfers and mint/burn operations go through SPL Token.
- Invokers → ATA program: cpi · Associated token account handling uses the ATA program.
- Invokers → Token-2022: cpi · Some token flows can target Token-2022 accounts and instructions.
- Invokers → OpenBook: cpi · Liquidity can be routed into OpenBook orders and settlement.
- Processor → Solana runtime: host APIs · Execution is constrained by Solana account and runtime semantics.