Surfpool SDK

Das Surfpool SDK startet eine vollständige Surfnet-Laufzeitumgebung innerhalb Ihres Testprozesses. Verwenden Sie es, wenn Sie einen lokalen Solana-kompatiblen RPC-Endpunkt, einen vorfinanzierten Zahler und direkte Zustandsmanipulation benötigen, ohne surfpool start als separaten Prozess zu starten.

Sowohl das Rust-Crate (surfpool-sdk) als auch die JS-Bindings (@solana/surfpool) kapseln dieselbe Laufzeitumgebung. Das JS-Paket liefert vorgefertigte native Binärdateien über napi-rs für macOS (Intel + Apple Silicon) und Linux x86-64.

Schnellstart

Installieren Sie das SDK, starten Sie ein Surfnet, rufen Sie den RPC-Endpunkt auf und stoppen Sie es anschließend. Parallele Tests teilen denselben Prozess sicher, da Ports dynamisch zugewiesen werden.

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

Was ist enthalten

Unterschiede zu surfpool start

Die CLI betreibt ein langlebiges Surfnet, mit dem Sie sich von externen Prozessen aus verbinden. Das SDK führt Surfnet innerhalb Ihres Tests aus, was bedeutet:

• Kein externes Port-Management — jedes Surfnet::start() bindet sich an einen freien Port, sodass Testsuiten parallel ausgeführt werden können, ohne --port-Flags.
• Synchrones Teardown — stop() kehrt zurück, wenn die Laufzeitumgebung ihre Ports tatsächlich freigegeben hat.
• Cheatcodes als typisierte Methoden — dieselbe Oberfläche, die von surfpool start über JSON-RPC bereitgestellt wird, ist als native Rust-Methoden und napi-rs-Bindings verfügbar.
• Direkte Ereignisbeobachtung — Laufzeitereignisse werden über einen In-Process-Kanal (Rust) oder eine Drain-Methode (JS) ohne WebSocket- Abonnement bereitgestellt.

Wann sollte das SDK verwendet werden?

Greifen Sie auf das SDK zurück, wenn:

• Sie Integrationstests für ein Anchor-Programm schreiben und nach einer Reihe von cheatcodierten Setups Aussagen über Token-Guthaben machen möchten.
• Sie parallele Test-Worker benötigen, die jeweils ein isoliertes Surfnet haben.
• Sie Mainnet-spezifische Konten forken möchten (remoteRpcUrl + streamAccount) innerhalb eines Tests.
• Sie deterministische Uhren benötigen, indem Sie die Laufzeitumgebung auf einen festen slot oder Zeitstempel setzen, bevor Sie Vesting-, Lockup- oder Ablauflogik testen.