Surfpool SDK

Surfpool SDK 在您的测试进程内启动完整的 Surfnet 运行时。当您需要本地 Solana 兼容 RPC 端点、预充值付款方以及直接状态操作，而无需将 surfpool start 作为独立进程启动时，请使用它。

Rust crate（surfpool-sdk）和 JS 绑定（@solana/surfpool）均封装了相同的运行时。JS 包通过 napi-rs 为 macOS（Intel + Apple Silicon）和 Linux x86-64 提供预构建的原生二进制文件。

快速入门

安装 SDK，启动 Surfnet，访问 RPC 端点，然后停止它。由于端口是动态分配的，并行测试可以安全地共享同一进程。

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());
}

功能概览

与 surfpool start 的区别

CLI 运行一个长期存在的 Surfnet，供外部进程连接。而 SDK 则在您的测试内部运行 Surfnet，这意味着：

• 无需外部端口管理 — 每个 Surfnet::start() 都会绑定到一个空闲端口，因此测试套件可以并行运行，无需使用 --port 标志。
• 同步销毁 — stop() 在运行时实际释放其端口后才会返回。
• 作为类型化方法的作弊码 — surfpool start 通过 JSON-RPC 暴露的相同接口，以原生 Rust 方法和 napi-rs 绑定的形式提供。
• 直接事件观察 — 运行时事件通过进程内通道（Rust）或 drain 方法（JS）暴露，无需 WebSocket 订阅。

何时使用 SDK

在以下情况下使用 SDK：

• 您正在为 Anchor 程序编写集成测试，并希望在一系列作弊码设置后断言代币余额。
• 您需要并行测试工作线程，每个都拥有独立的 Surfnet。
• 您希望在测试中主网分叉特定账户（remoteRpcUrl + streamAccount）。
• 您需要确定性时钟，通过在执行归属、锁定或到期逻辑之前，将运行时跳转到固定 slot 或时间戳。