Surfpool SDK

Le SDK Surfpool démarre un runtime Surfnet complet à l'intérieur de votre processus de test. Utilisez-le lorsque vous souhaitez un endpoint RPC local compatible Solana, un payeur pré-financé et une manipulation d'état directe sans lancer surfpool start comme processus séparé.

Le crate Rust (surfpool-sdk) et les bindings JS (@solana/surfpool) encapsulent le même runtime. Le package JS embarque des binaires natifs pré-compilés via napi-rs pour macOS (Intel + Apple Silicon) et Linux x86-64.

Démarrage rapide

Installez le SDK, démarrez un Surfnet, interrogez l'endpoint RPC, puis arrêtez-le. Les tests parallèles partagent le même processus en toute sécurité, car les ports sont alloués dynamiquement.

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

Ce qui est inclus

Différences avec surfpool start

La CLI exécute un Surfnet de longue durée auquel vous vous connectez depuis des processus externes. Le SDK exécute Surfnet à l'intérieur de votre test, ce qui signifie :

• Aucune gestion de port externe — chaque Surfnet::start() se lie à un port libre, ce qui permet aux suites de tests de s'exécuter en parallèle sans indicateurs --port.
• Démontage synchrone — stop() retourne une fois que le runtime a effectivement libéré ses ports.
• Cheatcodes comme méthodes typées — la même interface exposée via JSON-RPC par surfpool start est disponible en tant que méthodes Rust natives et liaisons napi-rs.
• Observation directe des événements — les événements du runtime sont exposés via un canal en cours de processus (Rust) ou une méthode de vidage (JS) sans abonnement WebSocket.

Quand utiliser le SDK

Utilisez le SDK lorsque :

• Vous écrivez des tests d'intégration pour un programme Anchor et souhaitez vérifier les soldes de tokens après une séquence de configurations cheatcodées.
• Vous avez besoin que des workers de test parallèles disposent chacun d'un Surfnet isolé.
• Vous souhaitez forker des comptes du mainnet (remoteRpcUrl + streamAccount) dans un test.
• Vous avez besoin d'horloges déterministes en faisant sauter le runtime vers un slot ou un horodatage fixe avant de tester une logique de vesting, de verrouillage ou d'expiration.