Surfpool SDK

L'SDK Surfpool avvia un runtime Surfnet completo all'interno del processo di test. Usalo quando hai bisogno di un endpoint RPC locale compatibile con Solana, un pagante pre-finanziato e la manipolazione diretta dello stato senza avviare surfpool start come processo separato.

Sia il crate Rust (surfpool-sdk) che i binding JS (@solana/surfpool) condividono lo stesso runtime. Il pacchetto JS include binari nativi precompilati tramite napi-rs per macOS (Intel + Apple Silicon) e Linux x86-64.

Avvio Rapido

Installa l'SDK, avvia un Surfnet, chiama l'endpoint RPC, poi fermalo. I test paralleli condividono lo stesso processo in modo sicuro perché le porte vengono allocate dinamicamente.

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

Cosa È Incluso

Differenze Rispetto a surfpool start

La CLI esegue un Surfnet a lunga durata a cui ci si connette da processi esterni. L'SDK esegue Surfnet all'interno del tuo test, il che significa:

• Nessuna gestione esterna delle porte — ogni Surfnet::start() si associa a una porta libera, quindi le suite di test possono essere eseguite in parallelo senza flag --port.
• Teardown sincrono — stop() ritorna solo quando il runtime ha effettivamente rilasciato le sue porte.
• Cheatcode come metodi tipizzati — la stessa interfaccia esposta tramite JSON-RPC da surfpool start è disponibile come metodi Rust nativi e binding napi-rs.
• Osservazione diretta degli eventi — gli eventi del runtime sono esposti tramite un canale in-process (Rust) o un metodo drain (JS) senza una sottoscrizione WebSocket.

Quando Usare l'SDK

Ricorri all'SDK quando:

• Stai scrivendo test di integrazione per un programma Anchor e vuoi verificare i saldi dei token dopo una sequenza di setup con cheatcode.
• Hai bisogno che worker di test paralleli abbiano ciascuno una Surfnet isolata.
• Vuoi eseguire il fork di account specifici della mainnet (remoteRpcUrl + streamAccount) all'interno di un test.
• Hai bisogno di clock deterministici portando il runtime a uno slot o timestamp fisso prima di testare logiche di vesting, lockup o scadenza.