Installation

The Surfpool SDK is published as two artifacts that wrap the same Rust runtime:

Rust

Add the crate as a dev-dependency. The SDK is async-first and expects a Tokio runtime, so include tokio with the full feature for tests.

[dev-dependencies]
surfpool-sdk = "1"
tokio = { version = "1", features = ["full"] }

The crate re-exports the Solana types you need most often, so a single use surfpool_sdk::{...} is usually enough:

use surfpool_sdk::{
    Keypair, Pubkey, RpcClient, Signer,        // re-exported Solana types
    Surfnet, SurfnetBuilder, SurfnetError,     // SDK entry points
    BlockProductionMode, SimnetEvent,          // re-exported surfpool types
};

If you need a type that isn't re-exported, depend on the underlying Solana crate directly — the SDK does not pin you to any specific version of solana-program or solana-client.

TypeScript / JavaScript

Install as a dev-dependency with your package manager of choice:

npm install --save-dev @solana/surfpool
# or
pnpm add -D @solana/surfpool
# or
yarn add --dev @solana/surfpool

The package exports a single Surfnet class plus supporting types:

import {
  Surfnet, // entry point
  type SurfnetConfig, // config for startWithConfig
  type DeployOptions, // explicit program deploy
  type SetTokenAccountUpdate,
  type ResetAccountOptions,
  type StreamAccountOptions,
  type SimnetEventValue, // event drained from drainEvents()
  type KeypairInfo, // shape returned by Surfnet.newKeypair()
  type EpochInfoValue,
  type ClockValue
} from "@solana/surfpool";

Supported Platforms

The JS package depends on platform-specific native modules that are installed automatically as optionalDependencies:

Requirements

• Node.js 18 or newer. The SDK uses Uint8Array, native fetch, and assert/strict from node:test.
• A writable temp directory. Each Surfnet instance allocates ports and may write transient data to the OS temp directory.

Verifying The Install

A one-line smoke test confirms the runtime starts and the RPC endpoint accepts requests.

use surfpool_sdk::{Signer, Surfnet};

#[tokio::test]
async fn surfpool_sdk_smoke() {
    let surfnet = Surfnet::start().await.expect("start surfnet");
    let balance = surfnet
        .rpc_client()
        .get_balance(&surfnet.payer().pubkey())
        .expect("get balance");
    assert!(balance > 0);
}

Troubleshooting