1---
2title: Surfpool
3description: A drop-in replacement for solana-test-validator with sub-second startup, automatic mainnet state cloning, transaction profiling, and a built-in web UI.
4---
5 
6# Surfpool Reference
7 
8## What is Surfpool
9 
10Surfpool is a drop-in replacement for `solana-test-validator` built on [LiteSVM](https://github.com/LiteSVM/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).
11 
12Key differences from `solana-test-validator`:
13- **Instant startup** — no genesis ledger to bootstrap; the SVM runs in-process.
14- **Mainnet state on demand** — accounts are lazily fetched from a remote RPC and cached locally. No need to pre-clone accounts.
15- **Cheatcodes** — 22 `surfnet_*` RPC methods to manipulate time, accounts, programs, and scenarios without restarting.
16- **Transaction profiling** — compute-unit estimation with before/after account snapshots.
17- **Scenario system** — override protocol state (Pyth, Jupiter, Raydium, etc.) to simulate market conditions.
18- **Infrastructure as Code** — define deployment runbooks in `txtx.yml` and auto-execute on start.
19- **MCP server** — expose surfnet operations as tool calls for AI agents.
20 
21## Installation
22 
23```bash
24curl -sL https://run.surfpool.run/ | bash
25```
26 
27Or install from source with Cargo:
28 
29```bash
30cargo surfpool-install
31```
32 
33Verify installation:
34 
35```bash
36surfpool --version
37```
38 
39## Agent Usage (NO_DNA)
40 
41When running surfpool commands as an agent, always prefix with `NO_DNA=1`. This disables TUI, interactive prompts, and enables verbose structured output:
42 
43```bash
44NO_DNA=1 surfpool start
45NO_DNA=1 surfpool start --watch
46NO_DNA=1 surfpool run deployment --unsupervised --output-json ./outputs/
47```
48 
49See [no-dna.org](https://no-dna.org) for the full standard.
50 
51## Quick Start
52 
53### Anchor Project
54 
55Start surfpool in the root of an Anchor workspace. It detects `txtx.yml` (or generates one) and deploys programs automatically:
56 
57```bash
58cd my-anchor-project
59surfpool start
60```
61 
62Use `--watch` to auto-redeploy when `.so` files change in `target/deploy/`:
63 
64```bash
65surfpool start --watch
66```
67 
68For Anchor test suites, enable compatibility mode:
69 
70```bash
71surfpool start --legacy-anchor-compatibility
72```
73 
74### Mainnet State Cloning
75 
76Fork mainnet state with zero config — accounts are fetched lazily when accessed:
77 
78```bash
79surfpool start --network mainnet
80```
81 
82Use a custom RPC for better rate limits:
83 
84```bash
85surfpool start --rpc-url https://my-rpc-provider.com
86```
87 
88Run fully offline (no remote fetching):
89 
90```bash
91surfpool start --offline
92```
93 
94### CI Mode
95 
96Start with CI-optimized defaults (no TUI, no Studio, no profiling, no logs):
97 
98```bash
99surfpool start --ci
100```
101 
102Run as a background daemon (Linux only):
103 
104```bash
105surfpool start --ci --daemon
106```
107 
108## When to Use Surfpool
109 
110| Criterion | surfpool | solana-test-validator | litesvm / bankrun |
111|---|---|---|---|
112| Startup time | Sub-second | 10-30 seconds | Sub-second |
113| Architecture | In-process SVM (LiteSVM) | Full validator runtime | In-process SVM |
114| RPC server | Full JSON-RPC on port 8899 | Full JSON-RPC on port 8899 | No RPC server (bankrun has limited BanksClient) |
115| WebSocket support | Yes (port 8900) | Yes | No |
116| Mainnet state | Lazy clone on first access | Manual `--clone` per account | Manual account setup |
117| Account manipulation | 22 cheatcode RPC methods | None (restart + `--account` files) | Direct `set_account()` in-process |
118| Time control | `surfnet_timeTravel`, `pauseClock`, `resumeClock` | `--slots-per-epoch`, warp via CLI | `warp_to_slot()` in-process |
119| Transaction profiling | Built-in CU profiling with snapshots | None | None |
120| Program hot-reload | `--watch` flag | Restart required | Restart required |
121| Web UI | Studio (port 18488) | None | None |
122| Protocol scenarios | 8 built-in protocols | None | None |
123| MCP server | Built-in (`surfpool mcp`) | None | None |
124| Geyser plugins | Supported | Supported | Not supported |
125| CI mode | `--ci` flag | Manual config | Native (no server needed) |
126| Infrastructure as Code | txtx.yml runbooks | None | None |
127| Offline mode | `--offline` flag | Always offline | Always offline |
128| Persistent state | `--db` flag (SQLite) | Ledger directory | None |
129 
130**Use surfpool** for local development, integration testing, mainnet forking, and CI pipelines that need an RPC endpoint.
131 
132**Use litesvm/bankrun** for unit-level program tests that run in-process without an RPC server.
133 
134**Use solana-test-validator** only when specific validator runtime behavior is required that surfpool does not yet replicate (vote processing, leader schedule, etc.).
135 
136### Decision Tree
137 
138- **Unit test exercising a single instruction in isolation?** Use litesvm (Rust) or bankrun (JS/Python).
139- **Need a full JSON-RPC endpoint?** Use surfpool.
140- **Need mainnet account state (tokens, programs, oracles)?** Use surfpool (lazy cloning).
141- **Need to manipulate time, accounts, or protocol state at runtime?** Use surfpool (cheatcodes).
142- **Local dev environment with hot-reload?** Use surfpool (`--watch`).
143- **CI pipeline needing RPC?** Use `surfpool start --ci`.
144- **DeFi scenario simulation?** Use surfpool (scenario system).
145- **Full validator fidelity?** Use solana-test-validator.
146 
147### Summary Table
148 
149| Use Case | Recommended Tool |
150|---|---|
151| Unit testing a single instruction | litesvm / bankrun |
152| Integration testing with RPC | surfpool |
153| Local development with hot-reload | surfpool |
154| Mainnet fork testing | surfpool |
155| CI pipeline (needs RPC) | surfpool (`--ci`) |
156| CI pipeline (in-process only) | litesvm / bankrun |
157| DeFi scenario simulation | surfpool |
158| AI agent-assisted development | surfpool (MCP server) |
159| Full validator fidelity testing | solana-test-validator |
160 
161## Migration from solana-test-validator
162 
163Replace:
164 
165```bash
166solana-test-validator \
167  --clone TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
168  --clone <account-1> \
169  --clone <account-2> \
170  --url https://api.mainnet-beta.solana.com \
171  --reset
172```
173 
174With:
175 
176```bash
177surfpool start
178```
179 
180Accounts are cloned lazily — no need to specify them upfront.
181 
182Replace account file loading:
183 
184```bash
185solana-test-validator --account <pubkey> ./account.json
186```
187 
188With snapshot loading:
189 
190```bash
191surfpool start --snapshot ./accounts.json
192```
193 
194Or use cheatcodes at runtime:
195 
196```bash
197curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
198  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_setAccount","params":["<pubkey>",{"lamports":1000000000}]}'
199```
200 
201### From litesvm/bankrun (adding RPC layer)
202 
203If in-process tests need to be promoted to integration tests with an RPC endpoint, start surfpool alongside:
204 
205```bash
206surfpool start --ci
207```
208 
209Then point the test client to `http://127.0.0.1:8899` instead of using the in-process bank.
210 
211## CLI Reference
212 
213### `surfpool start`
214 
215Start a local Solana network (surfnet). Alias: `surfpool simnet`.
216 
217#### Network Configuration
218 
219| Flag | Short | Default | Env Var | Description |
220|---|---|---|---|---|
221| `--port` | `-p` | `8899` | — | RPC port |
222| `--ws-port` | `-w` | `8900` | — | WebSocket port |
223| `--host` | `-o` | `127.0.0.1` | `SURFPOOL_NETWORK_HOST` | Bind address |
224| `--rpc-url` | `-u` | — | `SURFPOOL_DATASOURCE_RPC_URL` | Custom datasource RPC URL (conflicts with `--network`) |
225| `--network` | `-n` | — | — | Predefined network: `mainnet`, `devnet`, `testnet` (conflicts with `--rpc-url`) |
226| `--offline` | — | `false` | — | Start without a remote RPC client |
227 
228#### Block Production
229 
230| Flag | Short | Default | Description |
231|---|---|---|---|
232| `--slot-time` | `-t` | `400` | Slot time in milliseconds |
233| `--block-production-mode` | `-b` | `clock` | Block production mode: `clock`, `transaction`, `manual` |
234 
235Modes:
236- `clock` — advance slots at a fixed interval (default, `400ms`)
237- `transaction` — advance a slot only when a transaction is received
238- `manual` — slots only advance via explicit RPC calls
239 
240#### Airdrops
241 
242| Flag | Short | Default | Description |
243|---|---|---|---|
244| `--airdrop` | `-a` | — | Pubkey(s) to airdrop SOL to on start. Repeatable. |
245| `--airdrop-amount` | `-q` | `10000000000000` | Amount of lamports to airdrop (default ~10,000 SOL) |
246| `--airdrop-keypair-path` | `-k` | `~/.config/solana/id.json` | Keypair file(s) to airdrop to. Repeatable. |
247 
248#### Deployment & Runbooks
249 
250| Flag | Short | Default | Description |
251|---|---|---|---|
252| `--manifest-file-path` | `-m` | `./txtx.yml` | Path to the runbook manifest |
253| `--runbook` | `-r` | `deployment` | Runbook ID(s) to execute. Repeatable. |
254| `--runbook-input` | `-i` | — | JSON input file(s) for runbooks. Repeatable. |
255| `--no-deploy` | — | `false` | Disable auto deployment |
256| `--yes` | `-y` | `false` | Skip runbook generation prompts |
257| `--watch` | — | `false` | Auto re-execute deployment on `.so` file changes in `target/deploy/` |
258 
259#### Anchor Compatibility
260 
261| Flag | Short | Default | Description |
262|---|---|---|---|
263| `--legacy-anchor-compatibility` | — | `false` | Apply Anchor test suite defaults |
264| `--anchor-test-config-path` | — | — | Path(s) to `Test.toml` files. Repeatable. |
265 
266#### Studio
267 
268| Flag | Short | Default | Description |
269|---|---|---|---|
270| `--studio-port` | `-s` | `18488` | Studio web UI port |
271| `--no-studio` | — | `false` | Disable Studio |
272 
273#### Profiling & Logging
274 
275| Flag | Short | Default | Description |
276|---|---|---|---|
277| `--disable-instruction-profiling` | — | `false` | Disable instruction profiling |
278| `--max-profiles` | `-c` | `200` | Max transaction profiles to hold in memory |
279| `--log-level` | `-l` | `info` | Log level: `trace`, `debug`, `info`, `warn`, `error`, `none` |
280| `--log-path` | — | `.surfpool/logs` | Log file directory |
281| `--log-bytes-limit` | — | `10000` | Max bytes in transaction logs (0 = unlimited) |
282 
283#### SVM Features
284 
285| Flag | Short | Default | Description |
286|---|---|---|---|
287| `--feature` | `-f` | — | Enable specific SVM features. Repeatable. |
288| `--disable-feature` | — | — | Disable specific SVM features. Repeatable. |
289| `--features-all` | — | `false` | Enable all SVM features (override mainnet defaults) |
290 
291By default, surfpool uses mainnet feature flags.
292 
293#### Plugins & Subgraphs
294 
295| Flag | Short | Default | Description |
296|---|---|---|---|
297| `--geyser-plugin-config` | `-g` | — | Geyser plugin config file(s). Repeatable. |
298| `--subgraph-db` | `-d` | `:memory:` | Subgraph database URL (SQLite or Postgres) |
299 
300#### Persistence & Snapshots
301 
302| Flag | Short | Default | Description |
303|---|---|---|---|
304| `--db` | — | — | Surfnet database URL for persistent state (`:memory:` or `*.sqlite`) |
305| `--surfnet-id` | — | `default` | Unique ID to isolate database storage across instances |
306| `--snapshot` | — | — | JSON snapshot file(s) to preload accounts from. Repeatable. |
307 
308#### Telemetry
309 
310| Flag | Short | Default | Env Var | Description |
311|---|---|---|---|---|
312| `--metrics-enabled` | — | `false` | `SURFPOOL_METRICS_ENABLED` | Enable Prometheus metrics |
313| `--metrics-addr` | — | `0.0.0.0:9000` | `SURFPOOL_METRICS_ADDR` | Prometheus endpoint address |
314 
315#### Process Control
316 
317| Flag | Short | Default | Description |
318|---|---|---|---|
319| `--no-tui` | — | `false` | Stream logs instead of terminal UI |
320| `--daemon` | — | `false` | Run as background process (Linux only) |
321| `--ci` | — | `false` | CI mode (sets `--no-tui`, `--no-studio`, `--disable-instruction-profiling`, `--log-level none`) |
322| `--skip-signature-verification` | — | `false` | Skip signature verification for all transactions |
323 
324### `surfpool run`
325 
326Execute a runbook from the manifest.
327 
328| Flag | Short | Default | Description |
329|---|---|---|---|
330| `--manifest-file-path` | `-m` | `./txtx.yml` | Path to the manifest |
331| `--unsupervised` | `-u` | `false` | Execute without interactive supervision |
332| `--browser` | `-b` | `false` | Supervise via browser UI |
333| `--terminal` | `-t` | `false` | Supervise via terminal (coming soon) |
334| `--output-json` | — | — | Output results as JSON. Optional directory path. |
335| `--output` | — | — | Pick a specific output to stdout |
336| `--explain` | — | `false` | Explain execution plan without running |
337| `--env` | — | — | Environment from txtx.yml |
338| `--input` | — | — | Input file(s) for batch processing. Repeatable. |
339| `--force` | `-f` | `false` | Execute even if cached state shows already executed |
340| `--log-level` | `-l` | `info` | Log level |
341| `--log-path` | — | `.surfpool/logs` | Log directory |
342 
343Positional argument: `<runbook>` — runbook name or `.tx` file path.
344 
345```bash
346# Execute interactively in browser
347surfpool run deployment
348 
349# Execute without supervision, output JSON
350surfpool run deployment --unsupervised --output-json ./outputs/
351 
352# Force re-execution
353surfpool run deployment --unsupervised --force
354```
355 
356### `surfpool ls`
357 
358List runbooks in the current directory.
359 
360| Flag | Short | Default | Description |
361|---|---|---|---|
362| `--manifest-file-path` | `-m` | `./txtx.yml` | Path to the manifest |
363 
364### `surfpool mcp`
365 
366Start the MCP (Model Context Protocol) server for AI agent integrations. No additional flags.
367 
368```bash
369surfpool mcp
370```
371 
372### `surfpool completions`
373 
374Generate shell completion scripts. Alias: `surfpool completion`.
375 
376Positional argument: `<shell>` — `bash`, `zsh`, `fish`, `elvish`, `powershell`.
377 
378```bash
379surfpool completions zsh
380```
381 
382### Environment Variables
383 
384| Variable | Description | Used By |
385|---|---|---|
386| `NO_DNA` | Non-human operator signal — disables TUI, prompts; enables verbose/structured output | All commands |
387| `SURFPOOL_DATASOURCE_RPC_URL` | Default datasource RPC URL | `--rpc-url` |
388| `SURFPOOL_NETWORK_HOST` | Override bind host | `--host` |
389| `SURFPOOL_METRICS_ENABLED` | Enable Prometheus metrics | `--metrics-enabled` |
390| `SURFPOOL_METRICS_ADDR` | Prometheus endpoint address | `--metrics-addr` |
391 
392## Infrastructure as Code
393 
394Surfpool uses `txtx.yml` manifests and runbooks to define deployment workflows.
395 
396### Manifest Structure
397 
398Place a `txtx.yml` at the project root:
399 
400```yaml
401name: my-project
402runbooks:
403  - name: deployment
404    description: Deploy programs to localnet
405    file: ./runbooks/deployment.tx
406```
407 
408### Auto-Deploy with Watch
409 
410Combine `--watch` with runbooks to auto-redeploy on `.so` file changes:
411 
412```bash
413surfpool start --watch --runbook deployment
414```
415 
416### Runbook Inputs
417 
418Pass inputs to runbooks for parameterized deployments:
419 
420```bash
421surfpool start --runbook-input params.json
422```
423 
424## MCP Integration
425 
426Surfpool includes a built-in MCP (Model Context Protocol) server for AI agent integrations. The server communicates over stdio using the MCP protocol.
427 
428### Configuration
429 
430The MCP server uses stdio transport. Add the server entry to your tool's MCP config file:
431 
432| Tool | Config file |
433|---|---|
434| Claude Code | `.claude/settings.json` (project) or `~/.claude/settings.json` (global) |
435| Claude Desktop | `claude_desktop_config.json` |
436| Cursor | `.cursor/mcp.json` |
437| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
438| VS Code / Copilot | `.vscode/mcp.json` |
439| Codex | `codex.json` or MCP config via CLI |
440 
441**Standard MCP config** (Claude Code, Claude Desktop, Cursor, Windsurf):
442 
443```json
444{
445  "mcpServers": {
446    "surfpool": {
447      "command": "surfpool",
448      "args": ["mcp"]
449    }
450  }
451}
452```
453 
454**VS Code / Copilot** (uses `servers` instead of `mcpServers`):
455 
456```json
457{
458  "servers": {
459    "surfpool": {
460      "command": "surfpool",
461      "args": ["mcp"]
462    }
463  }
464}
465```
466 
467For any other MCP-compatible tool, use the stdio transport with command `surfpool` and args `["mcp"]`.
468 
469### Available MCP Tools
470 
471| Tool | Description |
472|---|---|
473| `start_surfnet` | Start a local Solana network. Default returns a shell command; `run_as_subprocess: true` starts in background. |
474| `set_token_accounts` | Set SOL/SPL token balances for accounts on a running surfnet |
475| `start_surfnet_with_token_accounts` | Start network + fund accounts in one call (background process) |
476| `call_surfnet_rpc` | Call any RPC method (standard Solana or `surfnet_*` cheatcodes) on a running surfnet |
477| `create_scenario` | Create a protocol state scenario. Read `override_templates` resource first. |
478| `get_override_templates` | List available override templates |
479 
480### MCP Resources
481 
482| Resource URI | Description |
483|---|---|
484| `str:///rpc_endpoints` | List of all available RPC endpoints |
485| `str:///override_templates` | All available scenario override templates |
486 
487### Agent Workflow via MCP
488 
4891. **Start surfnet:** Call `start_surfnet` or `start_surfnet_with_token_accounts`
4902. **Set up state:** Use `set_token_accounts` to fund accounts, or `call_surfnet_rpc` with cheatcodes
4913. **Create scenarios:** Read `override_templates`, then call `create_scenario`
4924. **Execute transactions:** Use `call_surfnet_rpc` with `sendTransaction` or `simulateTransaction`
4935. **Inspect results:** Use `call_surfnet_rpc` with `surfnet_getTransactionProfile` or `surfnet_exportSnapshot`
494 
495## Cheatcodes Overview
496 
497Surfpool exposes 22 `surfnet_*` JSON-RPC methods on the same port as the standard Solana RPC:
498 
499### Account Manipulation
500- `surfnet_setAccount` — set lamports, data, owner, executable flag on any account
501- `surfnet_setTokenAccount` — set SPL token account balances, delegates, state
502- `surfnet_resetAccount` — restore an account to its initial state
503- `surfnet_streamAccount` — mark an account for automatic remote fetching and caching
504- `surfnet_getStreamedAccounts` — list all streamed accounts
505 
506### Program Management
507- `surfnet_cloneProgramAccount` — copy a program from one address to another
508- `surfnet_setProgramAuthority` — change a program's upgrade authority
509- `surfnet_writeProgram` — deploy program data in chunks (bypasses TX size limits)
510- `surfnet_registerIdl` — register an IDL for a program in memory
511- `surfnet_getActiveIdl` — retrieve the registered IDL for a program
512 
513### Time Control
514- `surfnet_timeTravel` — jump to an absolute timestamp, slot, or epoch
515- `surfnet_pauseClock` — freeze slot advancement
516- `surfnet_resumeClock` — resume slot advancement
517 
518### Transaction Profiling
519- `surfnet_profileTransaction` — simulate a transaction and return CU estimates with account snapshots
520- `surfnet_getTransactionProfile` — retrieve a stored profile by signature or UUID
521- `surfnet_getProfileResultsByTag` — retrieve all profiles for a given tag
522 
523### Network State
524- `surfnet_setSupply` — configure what `getSupply` returns
525- `surfnet_resetNetwork` — reset the entire network to initial state
526- `surfnet_getLocalSignatures` — get recent transaction signatures with logs
527- `surfnet_getSurfnetInfo` — get network info including runbook execution history
528- `surfnet_exportSnapshot` — export all account state as a JSON snapshot
529 
530### Scenarios
531- `surfnet_registerScenario` — register a set of account overrides on a timeline
532 
533See [cheatcodes.md](cheatcodes.md) for full parameter schemas and JSON-RPC examples.
534 
535## Scenarios Overview
536 
537The scenario system allows overriding protocol account state to simulate market conditions, liquidation events, and oracle price movements without deploying mock contracts.
538 
539### Supported Protocols
540 
541| Protocol | Version | Account Types | Templates |
542|---|---|---|---|
543| Pyth | v2 | PriceUpdateV2 | SOL/USD, BTC/USD, ETH/USD, ETH/BTC |
544| Jupiter | v6 | TokenLedger | Token ledger override |
545| Raydium | CLMM v3 | PoolState | SOL/USDC, BTC/USDC, ETH/USDC |
546| Switchboard | on-demand | SwitchboardQuote | Quote override |
547| Meteora | DLMM v1 | LbPair | SOL/USDC, USDT/SOL |
548| Kamino | v1 | Reserve, Obligation | Reserve state, reserve config, obligation health |
549| Drift | v2 | PerpMarket, SpotMarket, User, State | Perp market, spot market, user state, global state |
550| Whirlpool | v0.7.0 | Whirlpool | SOL/USDC, SOL/USDT, mSOL/SOL, ORCA/USDC |
551 
552Protocol templates and scenario coverage are summarized in this section.
553 
554## Common Agent Workflows
555 
556> **Note:** All commands below should be prefixed with `NO_DNA=1` when run by an agent.
557 
558### 1. Start a Local Network and Deploy a Program
559 
560```bash
561NO_DNA=1 surfpool start --watch
562```
563 
564Surfpool 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`.
565 
566### 2. Set Up Token Accounts for Testing
567 
568```bash
569curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
570  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_setTokenAccount","params":["<OWNER>","<MINT>",{"amount":"1000000000"}]}'
571```
572 
573### 3. Test Time-Sensitive Logic
574 
575```bash
576# Pause
577curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
578  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_pauseClock","params":[]}'
579 
580# Time travel to a future epoch
581curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
582  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_timeTravel","params":[{"absoluteEpoch":100}]}'
583 
584# Resume
585curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
586  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_resumeClock","params":[]}'
587```
588 
589### 4. Profile Transaction Compute Units
590 
591```bash
592curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
593  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_profileTransaction","params":["<BASE64_TX>"]}'
594```
595 
596### 5. Export and Restore State
597 
598```bash
599# Export snapshot
600curl -X POST http://127.0.0.1:8899 -H "Content-Type: application/json" \
601  -d '{"jsonrpc":"2.0","id":1,"method":"surfnet_exportSnapshot","params":[]}'
602 
603# Load on next start
604NO_DNA=1 surfpool start --snapshot ./snapshot.json
605```
606