Surfpool Reference

What is Surfpool

Surfpool is a drop-in replacement for solana-test-validator built on LiteSVM. It provides a local Solana network (called a "surfnet") with sub-second startup, automatic mainnet state cloning, transaction profiling, and a built-in web UI (Studio).

Key differences from solana-test-validator:

• Instant startup — no genesis ledger to bootstrap; the SVM runs in-process.
• Mainnet state on demand — accounts are lazily fetched from a remote RPC and cached locally. No need to pre-clone accounts.
• Cheatcodes — 22 surfnet_* RPC methods to manipulate time, accounts, programs, and scenarios without restarting.
• Transaction profiling — compute-unit estimation with before/after account snapshots.
• Scenario system — override protocol state (Pyth, Jupiter, Raydium, etc.) to simulate market conditions.
• Infrastructure as Code — define deployment runbooks in txtx.yml and auto-execute on start.
• MCP server — expose surfnet operations as tool calls for AI agents.

Installation

curl -sL https://run.surfpool.run/ | bash

Or install from source with Cargo:

cargo surfpool-install

Verify installation:

surfpool --version

Agent Usage (NO_DNA)

When running surfpool commands as an agent, always prefix with NO_DNA=1. This disables TUI, interactive prompts, and enables verbose structured output:

NO_DNA=1 surfpool start
NO_DNA=1 surfpool start --watch
NO_DNA=1 surfpool run deployment --unsupervised --output-json ./outputs/

See no-dna.org for the full standard.

Quick Start

Anchor Project

Start surfpool in the root of an Anchor workspace. It detects txtx.yml (or generates one) and deploys programs automatically:

cd my-anchor-project
surfpool start

Use --watch to auto-redeploy when .so files change in target/deploy/:

surfpool start --watch

For Anchor test suites, enable compatibility mode:

surfpool start --legacy-anchor-compatibility

Mainnet State Cloning

Fork mainnet state with zero config — accounts are fetched lazily when accessed:

surfpool start --network mainnet

Use a custom RPC for better rate limits:

surfpool start --rpc-url https://my-rpc-provider.com

Run fully offline (no remote fetching):

surfpool start --offline

CI Mode

Start with CI-optimized defaults (no TUI, no Studio, no profiling, no logs):

surfpool start --ci

Run as a background daemon (Linux only):

surfpool start --ci --daemon

When to Use Surfpool

Use surfpool for local development, integration testing, mainnet forking, and CI pipelines that need an RPC endpoint.

Use litesvm/bankrun for unit-level program tests that run in-process without an RPC server.

Use solana-test-validator only when specific validator runtime behavior is required that surfpool does not yet replicate (vote processing, leader schedule, etc.).

Decision Tree

• Unit test exercising a single instruction in isolation? Use litesvm (Rust) or bankrun (JS/Python).
• Need a full JSON-RPC endpoint? Use surfpool.
• Need mainnet account state (tokens, programs, oracles)? Use surfpool (lazy cloning).
• Need to manipulate time, accounts, or protocol state at runtime? Use surfpool (cheatcodes).
• Local dev environment with hot-reload? Use surfpool (--watch).
• CI pipeline needing RPC? Use surfpool start --ci.
• DeFi scenario simulation? Use surfpool (scenario system).
• Full validator fidelity? Use solana-test-validator.

Summary Table

Migration from solana-test-validator

Replace:

solana-test-validator \
  --clone TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
  --clone <account-1> \
  --clone <account-2> \
  --url https://api.mainnet-beta.solana.com \
  --reset

With:

surfpool start

Accounts are cloned lazily — no need to specify them upfront.

Replace account file loading:

solana-test-validator --account <pubkey> ./account.json

With snapshot loading:

surfpool start --snapshot ./accounts.json

Or use cheatcodes at runtime:

curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_setAccount","params":["<pubkey>",{"lamports":1000000000}]}'

From litesvm/bankrun (adding RPC layer)

If in-process tests need to be promoted to integration tests with an RPC endpoint, start surfpool alongside:

surfpool start --ci

Then point the test client to http://127.0.0.1:8899 instead of using the in-process bank.

CLI Reference

surfpool start

Start a local Solana network (surfnet). Alias: surfpool simnet.

#### Network Configuration

#### Block Production

Modes:

• clock — advance slots at a fixed interval (default, 400ms)
• transaction — advance a slot only when a transaction is received
• manual — slots only advance via explicit RPC calls

#### Airdrops

#### Deployment & Runbooks

#### Anchor Compatibility

#### Studio

#### Profiling & Logging

#### SVM Features

By default, surfpool uses mainnet feature flags.

#### Plugins & Subgraphs

#### Persistence & Snapshots

#### Telemetry

#### Process Control

surfpool run

Execute a runbook from the manifest.

Positional argument: <runbook> — runbook name or .tx file path.

# Execute interactively in browser
surfpool run deployment

# Execute without supervision, output JSON
surfpool run deployment --unsupervised --output-json ./outputs/

# Force re-execution
surfpool run deployment --unsupervised --force

surfpool ls

List runbooks in the current directory.

surfpool mcp

Start the MCP (Model Context Protocol) server for AI agent integrations. No additional flags.

surfpool mcp

surfpool completions

Generate shell completion scripts. Alias: surfpool completion.

Positional argument: <shell> — bash, zsh, fish, elvish, powershell.

surfpool completions zsh

Environment Variables

Infrastructure as Code

Surfpool uses txtx.yml manifests and runbooks to define deployment workflows.

Manifest Structure

Place a txtx.yml at the project root:

name: my-project
runbooks:
  - name: deployment
    description: Deploy programs to localnet
    file: ./runbooks/deployment.tx

Auto-Deploy with Watch

Combine --watch with runbooks to auto-redeploy on .so file changes:

surfpool start --watch --runbook deployment

Runbook Inputs

Pass inputs to runbooks for parameterized deployments:

surfpool start --runbook-input params.json

MCP Integration

Surfpool includes a built-in MCP (Model Context Protocol) server for AI agent integrations. The server communicates over stdio using the MCP protocol.

Configuration

The MCP server uses stdio transport. Add the server entry to your tool's MCP config file:

Standard MCP config (Claude Code, Claude Desktop, Cursor, Windsurf):

{
  "mcpServers": {
    "surfpool": {
      "command": "surfpool",
      "args": ["mcp"]
    }
  }
}

VS Code / Copilot (uses servers instead of mcpServers):

{
  "servers": {
    "surfpool": {
      "command": "surfpool",
      "args": ["mcp"]
    }
  }
}

For any other MCP-compatible tool, use the stdio transport with command surfpool and args ["mcp"].

Available MCP Tools

MCP Resources

Agent Workflow via MCP

1. Start surfnet: Call start_surfnet or start_surfnet_with_token_accounts
2. Set up state: Use set_token_accounts to fund accounts, or call_surfnet_rpc with cheatcodes
3. Create scenarios: Read override_templates, then call create_scenario
4. Execute transactions: Use call_surfnet_rpc with sendTransaction or simulateTransaction
5. Inspect results: Use call_surfnet_rpc with surfnet_getTransactionProfile or surfnet_exportSnapshot

Cheatcodes Overview

Surfpool exposes 22 surfnet_* JSON-RPC methods on the same port as the standard Solana RPC:

Account Manipulation

• surfnet_setAccount — set lamports, data, owner, executable flag on any account
• surfnet_setTokenAccount — set SPL token account balances, delegates, state
• surfnet_resetAccount — restore an account to its initial state
• surfnet_streamAccount — mark an account for automatic remote fetching and caching
• surfnet_getStreamedAccounts — list all streamed accounts

Program Management

• surfnet_cloneProgramAccount — copy a program from one address to another
• surfnet_setProgramAuthority — change a program's upgrade authority
• surfnet_writeProgram — deploy program data in chunks (bypasses TX size limits)
• surfnet_registerIdl — register an IDL for a program in memory
• surfnet_getActiveIdl — retrieve the registered IDL for a program

Time Control

• surfnet_timeTravel — jump to an absolute timestamp, slot, or epoch
• surfnet_pauseClock — freeze slot advancement
• surfnet_resumeClock — resume slot advancement

Transaction Profiling

• surfnet_profileTransaction — simulate a transaction and return CU estimates with account snapshots
• surfnet_getTransactionProfile — retrieve a stored profile by signature or UUID
• surfnet_getProfileResultsByTag — retrieve all profiles for a given tag

Network State

• surfnet_setSupply — configure what getSupply returns
• surfnet_resetNetwork — reset the entire network to initial state
• surfnet_getLocalSignatures — get recent transaction signatures with logs
• surfnet_getSurfnetInfo — get network info including runbook execution history
• surfnet_exportSnapshot — export all account state as a JSON snapshot

Scenarios

• surfnet_registerScenario — register a set of account overrides on a timeline

See cheatcodes.md for full parameter schemas and JSON-RPC examples.

Scenarios Overview

The scenario system allows overriding protocol account state to simulate market conditions, liquidation events, and oracle price movements without deploying mock contracts.

Supported Protocols

Protocol templates and scenario coverage are summarized in this section.

Common Agent Workflows

Note: All commands below should be prefixed with NO_DNA=1 when run by an agent.

1. Start a Local Network and Deploy a Program

NO_DNA=1 surfpool start --watch

Surfpool detects txtx.yml, generates a deployment runbook if needed, deploys programs, and airdrops SOL to the default keypair. The RPC is available at http://127.0.0.1:8899.

2. Set Up Token Accounts for Testing

curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_setTokenAccount","params":["<OWNER>","<MINT>",{"amount":"1000000000"}]}'

3. Test Time-Sensitive Logic

# Pause
curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_pauseClock","params":[]}'

# Time travel to a future epoch
curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_timeTravel","params":[{"absoluteEpoch":100}]}'

# Resume
curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_resumeClock","params":[]}'

4. Profile Transaction Compute Units

curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_profileTransaction","params":["<BASE64_TX>"]}'

5. Export and Restore State

# Export snapshot
curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_exportSnapshot","params":[]}'

# Load on next start
NO_DNA=1 surfpool start --snapshot ./snapshot.json