Surfpool SDK

Surfpool SDKは、テストプロセス内でフルSurfnetランタイムを起動します。ローカルのSolana互換RPCエンドポイント、事前に資金が付与されたペイヤー、そしてsurfpool startを別プロセスとして起動せずに直接状態を操作したい場合に使用します。

Rustクレートの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 フラグなしでテストスイートを並列実行できます。
• 同期的なteardown — stop() は、ランタイムが実際にポートを解放した時点で返ります。
• 型付きメソッドとしてのCheatcode — surfpool start によってJSON-RPC上に公開されているのと同じインターフェースが、ネイティブRustメソッドおよびnapi-rsバインディングとして利用できます。
• 直接的なイベント観測 — ランタイムイベントは、WebSocketサブスクリプションを使わずに、インプロセスチャネル（Rust）またはdrainメソッド（JS）を通じて公開されます。

SDKを使うべきタイミング

以下の場合にSDKの使用を検討してください：

• Anchor プログラムのインテグレーションテストを記述しており、一連のCheatcode設定後にトークン残高をアサートしたい場合。
• 並列テストワーカーそれぞれに独立したSurfnetを持たせたい場合。
• テスト内で remoteRpcUrl + streamAccount を使ってメインネットの特定アカウントをフォークしたい場合。
• ベスティング、ロックアップ、または有効期限ロジックを検証する前に、ランタイムを固定の slot またはタイムスタンプに移動させることで決定論的なクロックを実現したい場合。