How solana-foundation/surfpool works
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: src/lib.rs Core · src/lib.rs SDK · src/lib.rs Types · main.rs CLI
Components 18
Core runtime
Local Solana-compatible execution, RPC, scenarios, and storage
- Core · Main Surfnet runtime, execution environment, RPC surfaces, scenarios, and storage integration
crates/core/src/lib.rs - Surfnet · SVM/LiteSVM-backed network execution and remote/locker integration
crates/core/src/surfnet/mod.rs - RPC · Solana-compatible RPC tiers plus Surfpool extensions and websocket support
crates/core/src/rpc/mod.rs - Scenarios · Protocol snapshots, IDLs, overrides, and scenario registry
crates/core/src/scenarios/mod.rs - Storage · Overlay and backend storage abstractions used by the runtime
crates/core/src/storage/mod.rs - Runloops · 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 · User-facing commands for starting, updating, scaffolding, and inspecting Surfpool
crates/cli/src/main.rs - Simnet · Network lifecycle and local simulation commands
crates/cli/src/cli/simnet/mod.rs - Scaffold · Project templates for Anchor, native, Pinocchio, Steel, and Typhoon workflows
crates/cli/src/scaffold/mod.rs - TUI · Interactive local control and inspection surface
crates/cli/src/tui/mod.rs - SDK · Rust programmatic cheatcodes and network helpers
crates/sdk/src/lib.rs - Node SDK · Node/TypeScript package exposing the Surfpool SDK surface
crates/sdk-node/src/lib.rs - MCP · Model Context Protocol tools for agentic control of Surfpool
crates/mcp/src/lib.rs - Studio · Dashboard/UI integration crate
crates/studio/src/lib.rs
Persistence
Database and storage backends
- DB · SQLite and Postgres persistence crate
crates/db/src/lib.rs
Shared types
Cross-crate constants and shared contracts
- Types · Shared constants, endpoints, features, scenarios, and token metadata
crates/types/src/lib.rs
Supporting tools
Benchmarks, examples, and test harnesses
- Bench · Transaction ingestion benchmarks
crates/bench/benches/transaction_ingestion.rs - Geyser example · Example plugin/integration harness for the core runtime
examples/hello-geyser/src/lib.rs
Connections 21
- 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