Surfpool SDK

The Surfpool SDK starts a full Surfnet runtime inside your test process. Use it when you want a local Solana-compatible RPC endpoint, a pre-funded payer, and direct state manipulation without launching surfpool start as a separate process.

Both the Rust crate (surfpool-sdk) and the JS bindings (@solana/surfpool) wrap the same runtime. The JS package ships pre-built native binaries through napi-rs for macOS (Intel + Apple Silicon) and Linux x86-64.

Quickstart

Install the SDK, start a Surfnet, hit the RPC endpoint, then stop it. Parallel tests share the same process safely because ports are allocated dynamically.

use surfpool_sdk::{Signer, Surfnet};

#[tokio::test]
async fn starts_a_local_surfnet() {
    let surfnet = Surfnet::start().await.unwrap();

    let rpc = surfnet.rpc_client();
    let balance = rpc.get_balance(&surfnet.payer().pubkey()).unwrap();

    assert!(balance > 0);
    println!("rpc: {}", surfnet.rpc_url());
    println!("ws: {}", surfnet.ws_url());
}

What's In The Box

How It Differs From surfpool start

The CLI runs a long-lived Surfnet you connect to from outside processes. The SDK runs Surfnet inside your test, which means:

• No external port management — every Surfnet::start() binds to a free port, so test suites can run in parallel without --port flags.
• Synchronous teardown — stop() returns when the runtime has actually released its ports.
• Cheatcodes as typed methods — the same surface exposed over JSON-RPC by surfpool start is available as native Rust methods and napi-rs bindings.
• Direct event observation — runtime events are exposed through an in-process channel (Rust) or a drain method (JS) without a WebSocket subscription.

When To Use The SDK

Reach for the SDK when:

• You're writing integration tests for an Anchor program and want to assert on token balances after a sequence of cheatcoded setups.
• You need parallel test workers to each have an isolated Surfnet.
• You want to mainnet-fork specific accounts (remoteRpcUrl + streamAccount) inside a test.
• You need deterministic clocks by jumping the runtime to a fixed slot or timestamp before exercising vesting, lockup, or expiry logic.