# solana-foundation/surfpool architecture

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

- Interactive diagram: https://gitdiagram.com/solana-foundation/surfpool
- Repository: https://github.com/solana-foundation/surfpool

## Overview

##### What this repo is
Surfpool is a Rust workspace for running a local Solana-compatible network with mainnet-style state, plus a set of companion tools for scripting, indexing, scenarios, and agent access. The architecture centers on a core runtime, with multiple thin frontends and SDKs around it.

##### Core runtime is the center of the system
`crates/core` is the main engine. It contains the Solana VM integration (`surfnet`, `surfnet_lite_svm`, `svm`, `locker`, `remote`) and the RPC surface (`rpc/*`). This is the layer that actually hosts the local network, executes transactions, and exposes Solana-like APIs.

##### Solana-compatible service boundaries
The core RPC subsystem is split into specialized surfaces:
- `minimal`, `full`, and `bank_data` / `accounts_data` for different RPC capability levels
- `ws` for websocket subscriptions
- `admin` for management operations
- `jito` and `surfnet_cheatcodes` for Surfpool-specific extensions
- `accounts_scan` and `utils` for supporting RPC workflows
This indicates the network is not just a validator shim; it exposes multiple API tiers and custom operational endpoints.

##### Scenario and protocol modeling
`crates/core/src/scenarios` is a major architectural subsystem. It contains protocol-specific definitions for programs like Drift, Jupiter, Kamino, Meteora, Pyth, Raydium, Switchboard, and Whirlpool, each with IDLs and override files. The scenario registry suggests Surfpool can assemble curated chain-state snapshots and per-program overrides into reproducible test environments.

##### Storage and indexing layer
State persistence is abstracted in `crates/core/src/storage` and supported by `crates/db`. The storage layer includes:
- in-memory overlays and maps (`overlay`, `hash_map`, `fifo_map`)
- Diesel-based database adapters (`diesel_common`)
- concrete SQLite and Postgres backends
This shows a clear boundary between ephemeral runtime state and persisted/queryable state, which matters for the IDL-to-SQL and indexing features described in the README.

##### CLI as orchestration and developer UX
`crates/cli` is the primary entrypoint for users. It includes:
- `start`-style network operations under `cli/simnet`
- update/install commands
- scaffolding for protocol projects (`scaffold/*` with Anchor, native, Pinocchio, Steel, Typhoon templates)
- HTTP and TUI helpers for local control and inspection
The CLI does not implement the network itself; it orchestrates the core runtime, generates project wiring, and presents developer-facing workflows.

##### SDKs and cheatcodes are programmatic control surfaces
`crates/sdk` exposes reusable cheatcodes and builders such as deploy/reset/set/stream account operations and token-account helpers. This is a separate control plane for automation and testing, distinct from the CLI, and likely used by tests, scripts, and protocol toolchains.

##### MCP integration for agentic control
`crates/mcp` exposes Surfpool actions through MCP tools, currently focused on starting a Surfnet and setting token accounts. Architecturally, this is a thin adapter over the SDK/core capabilities that makes the local network controllable by AI assistants and other MCP clients.

##### Node/TypeScript distribution
`crates/sdk-node` packages a Node-facing SDK and includes release/smoke scripts plus a generated TypeScript surface in `surfpool-sdk/`. This is a language-boundary adapter around the Rust SDK/core functionality, intended for JS/TS workflows.

##### Shared data contracts
`crates/types` holds cross-cutting constants and domain data such as RPC endpoint metadata, feature flags, scenario definitions, and verified token lists. This crate reduces duplication across CLI, core, SDK, and tooling by centralizing shared schema-like information.

##### Operational and test harnesses
The repo also includes:
- `crates/bench` for transaction-ingestion benchmarks
- `crates/core/src/tests` and the `examples/hello-geyser` integration example
- GitHub Actions, Dockerfile, and install scripts for packaging/release
These are supporting layers around the main runtime, useful for verifying performance and shipping Surfpool as a binary or container.

##### Main runtime data flow
The primary flow is: CLI / SDK / MCP entrypoints configure a Surfnet instance → core initializes the SVM/LiteSVM-backed execution environment → scenarios and protocol overrides seed or modify account/program state → RPC/WebSocket services expose the network → storage/db layers persist or index selected data → tools like Studio or Node SDK consume the resulting APIs.

Main entry points: [`crates/core/src/lib.rs`](https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/lib.rs) (Core), [`crates/sdk/src/lib.rs`](https://github.com/solana-foundation/surfpool/blob/main/crates/sdk/src/lib.rs) (SDK), [`crates/types/src/lib.rs`](https://github.com/solana-foundation/surfpool/blob/main/crates/types/src/lib.rs) (Types), [`crates/cli/src/main.rs`](https://github.com/solana-foundation/surfpool/blob/main/crates/cli/src/main.rs) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Core runtime"]
  node_core["Core<br/>runtime engine<br/>[lib.rs]"]
  node_core_surfnet["Surfnet<br/>vm host<br/>[mod.rs]"]
  node_core_rpc["RPC<br/>api surface<br/>[mod.rs]"]
  node_core_scenarios["Scenarios<br/>state modeling<br/>[mod.rs]"]
  node_core_storage[("Storage<br/>state store<br/>[mod.rs]")]
  node_core_runloops(("Runloops<br/>orchestration<br/>[mod.rs]"))
end

subgraph group_clients["Access layers"]
  node_cli["CLI<br/>operator frontend<br/>[main.rs]"]
  node_cli_simnet["Simnet<br/>command module<br/>[mod.rs]"]
  node_cli_scaffold["Scaffold<br/>template generator<br/>[mod.rs]"]
  node_cli_tui(("TUI<br/>operator ui<br/>[mod.rs]"))
  node_sdk["SDK<br/>automation api<br/>[lib.rs]"]
  node_sdk_node["Node SDK<br/>js adapter<br/>[lib.rs]"]
  node_mcp["MCP<br/>agent bridge<br/>[lib.rs]"]
  node_studio["Studio<br/>ui package<br/>[lib.rs]"]
end

subgraph group_data["Persistence"]
  node_db[("DB<br/>database package<br/>[lib.rs]")]
end

subgraph group_shared["Shared types"]
  node_types["Types<br/>shared contracts<br/>[lib.rs]"]
end

subgraph group_support["Supporting tools"]
  node_bench(("Bench"))
  node_example_geyser(("Geyser example<br/>integration example<br/>[lib.rs]"))
end

node_cli -->|"starts"| node_core
node_cli -->|"uses"| node_types
node_cli_simnet -->|"configures"| node_core
node_cli_scaffold -->|"generates"| node_sdk
node_cli_tui -->|"inspects"| node_core
node_sdk -->|"drives"| node_core
node_sdk -->|"shares"| node_types
node_sdk_node -->|"wraps"| node_sdk
node_sdk_node -->|"targets"| node_core
node_mcp -->|"adapts"| node_sdk
node_mcp -->|"controls"| node_core
node_studio -->|"visualizes"| node_core
node_core -->|"hosts"| node_core_surfnet
node_core -->|"exposes"| node_core_rpc
node_core -->|"seeds"| node_core_scenarios
node_core -->|"persists"| node_core_storage
node_core -->|"orchestrates"| node_core_runloops
node_core_storage -->|"backed by"| node_db
node_db -->|"aligns"| node_types
node_bench -->|"measures"| node_core
node_example_geyser -->|"extends"| node_core

click node_core "https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/lib.rs"
click node_core_surfnet "https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/surfnet/mod.rs"
click node_core_rpc "https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/rpc/mod.rs"
click node_core_scenarios "https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/scenarios/mod.rs"
click node_core_storage "https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/storage/mod.rs"
click node_core_runloops "https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/runloops/mod.rs"
click node_cli "https://github.com/solana-foundation/surfpool/blob/main/crates/cli/src/main.rs"
click node_cli_simnet "https://github.com/solana-foundation/surfpool/blob/main/crates/cli/src/cli/simnet/mod.rs"
click node_cli_scaffold "https://github.com/solana-foundation/surfpool/blob/main/crates/cli/src/scaffold/mod.rs"
click node_cli_tui "https://github.com/solana-foundation/surfpool/blob/main/crates/cli/src/tui/mod.rs"
click node_sdk "https://github.com/solana-foundation/surfpool/blob/main/crates/sdk/src/lib.rs"
click node_sdk_node "https://github.com/solana-foundation/surfpool/blob/main/crates/sdk-node/src/lib.rs"
click node_mcp "https://github.com/solana-foundation/surfpool/blob/main/crates/mcp/src/lib.rs"
click node_studio "https://github.com/solana-foundation/surfpool/blob/main/crates/studio/src/lib.rs"
click node_db "https://github.com/solana-foundation/surfpool/blob/main/crates/db/src/lib.rs"
click node_types "https://github.com/solana-foundation/surfpool/blob/main/crates/types/src/lib.rs"
click node_bench "https://github.com/solana-foundation/surfpool/blob/main/crates/bench/benches/transaction_ingestion.rs"
click node_example_geyser "https://github.com/solana-foundation/surfpool/blob/main/examples/hello-geyser/src/lib.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_core,node_core_surfnet,node_core_rpc,node_core_scenarios,node_core_storage,node_core_runloops toneBlue
class node_cli,node_cli_simnet,node_cli_scaffold,node_cli_tui,node_sdk,node_sdk_node,node_mcp,node_studio toneAmber
class node_db toneMint
class node_types toneRose
class node_bench,node_example_geyser toneIndigo
```

## Components

### Core runtime

Local Solana-compatible execution, RPC, scenarios, and storage

- [Core](https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/lib.rs): runtime engine · Main Surfnet runtime, execution environment, RPC surfaces, scenarios, and storage integration · `crates/core/src/lib.rs`
- [Surfnet](https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/surfnet/mod.rs): vm host · SVM/LiteSVM-backed network execution and remote/locker integration · `crates/core/src/surfnet/mod.rs`
- [RPC](https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/rpc/mod.rs): api surface · Solana-compatible RPC tiers plus Surfpool extensions and websocket support · `crates/core/src/rpc/mod.rs`
- [Scenarios](https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/scenarios/mod.rs): state modeling · Protocol snapshots, IDLs, overrides, and scenario registry · `crates/core/src/scenarios/mod.rs`
- [Storage](https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/storage/mod.rs): state store · Overlay and backend storage abstractions used by the runtime · `crates/core/src/storage/mod.rs`
- [Runloops](https://github.com/solana-foundation/surfpool/blob/main/crates/core/src/runloops/mod.rs): orchestration · Runtime loops and coordination for serving the local network · `crates/core/src/runloops/mod.rs`

### Access layers

CLI, SDKs, MCP, and UI-facing adapters

- [CLI](https://github.com/solana-foundation/surfpool/blob/main/crates/cli/src/main.rs): operator frontend · User-facing commands for starting, updating, scaffolding, and inspecting Surfpool · `crates/cli/src/main.rs`
- [Simnet](https://github.com/solana-foundation/surfpool/blob/main/crates/cli/src/cli/simnet/mod.rs): command module · Network lifecycle and local simulation commands · `crates/cli/src/cli/simnet/mod.rs`
- [Scaffold](https://github.com/solana-foundation/surfpool/blob/main/crates/cli/src/scaffold/mod.rs): template generator · Project templates for Anchor, native, Pinocchio, Steel, and Typhoon workflows · `crates/cli/src/scaffold/mod.rs`
- [TUI](https://github.com/solana-foundation/surfpool/blob/main/crates/cli/src/tui/mod.rs): operator ui · Interactive local control and inspection surface · `crates/cli/src/tui/mod.rs`
- [SDK](https://github.com/solana-foundation/surfpool/blob/main/crates/sdk/src/lib.rs): automation api · Rust programmatic cheatcodes and network helpers · `crates/sdk/src/lib.rs`
- [Node SDK](https://github.com/solana-foundation/surfpool/blob/main/crates/sdk-node/src/lib.rs): js adapter · Node/TypeScript package exposing the Surfpool SDK surface · `crates/sdk-node/src/lib.rs`
- [MCP](https://github.com/solana-foundation/surfpool/blob/main/crates/mcp/src/lib.rs): agent bridge · Model Context Protocol tools for agentic control of Surfpool · `crates/mcp/src/lib.rs`
- [Studio](https://github.com/solana-foundation/surfpool/blob/main/crates/studio/src/lib.rs): ui package · Dashboard/UI integration crate · `crates/studio/src/lib.rs`

### Persistence

Database and storage backends

- [DB](https://github.com/solana-foundation/surfpool/blob/main/crates/db/src/lib.rs): database package · SQLite and Postgres persistence crate · `crates/db/src/lib.rs`

### Shared types

Cross-crate constants and shared contracts

- [Types](https://github.com/solana-foundation/surfpool/blob/main/crates/types/src/lib.rs): shared contracts · Shared constants, endpoints, features, scenarios, and token metadata · `crates/types/src/lib.rs`

### Supporting tools

Benchmarks, examples, and test harnesses

- [Bench](https://github.com/solana-foundation/surfpool/blob/main/crates/bench/benches/transaction_ingestion.rs): benchmark suite · Transaction ingestion benchmarks · `crates/bench/benches/transaction_ingestion.rs`
- [Geyser example](https://github.com/solana-foundation/surfpool/blob/main/examples/hello-geyser/src/lib.rs): integration example · Example plugin/integration harness for the core runtime · `examples/hello-geyser/src/lib.rs`

## Connections

- CLI → Core: starts · CLI orchestrates the runtime and local network lifecycle
- CLI → Types: uses · CLI reads shared feature and endpoint metadata
- Simnet → Core: configures · Simulation commands configure Surfnet instances
- Scaffold → SDK: generates · Scaffolds projects that consume the SDK and runtime APIs
- TUI → Core: inspects · TUI interacts with runtime state and control surfaces
- SDK → Core: drives · SDK issues cheatcodes and helper operations against Surfnet
- SDK → Types: shares · SDK uses shared types and metadata
- Node SDK → SDK: wraps · Node package exposes the Rust SDK surface
- Node SDK → Core: targets · JS/TS workflows ultimately control the core runtime
- MCP → SDK: adapts · MCP tools are thin adapters over SDK operations
- MCP → Core: controls · Agent tools start and modify Surfnet state
- Studio → Core: visualizes · Dashboard consumes runtime APIs and state
- Core → Surfnet: hosts · Core embeds the network execution subsystem
- Core → RPC: exposes · Core serves Solana-compatible and Surfpool-specific APIs
- Core → Scenarios: seeds · Core loads protocol scenarios and overrides into state
- Core → Storage: persists · Core delegates state storage and overlays
- Core → Runloops: orchestrates · Runloops coordinate serving and background execution
- Storage → DB: backed by · Storage uses the database crate for durable backends
- DB → Types: aligns · Database layer consumes shared schemas and metadata
- Bench → Core: measures · Benchmarks target transaction ingestion in the runtime
- Geyser example → Core: extends · Example demonstrates integration with the core runtime