Surfpool SDK

El SDK de Surfpool inicia un entorno de ejecución Surfnet completo dentro de tu proceso de prueba. Úsalo cuando necesites un endpoint RPC local compatible con Solana, un pagador con fondos y manipulación directa del estado sin lanzar surfpool start como un proceso separado.

Tanto el crate de Rust (surfpool-sdk) como los bindings de JS (@solana/surfpool) envuelven el mismo entorno de ejecución. El paquete de JS incluye binarios nativos precompilados a través de napi-rs para macOS (Intel + Apple Silicon) y Linux x86-64.

Inicio rápido

Instala el SDK, inicia una Surfnet, accede al endpoint RPC y luego detenla. Las pruebas paralelas comparten el mismo proceso de forma segura porque los puertos se asignan dinámicamente.

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

Qué incluye

En qué se diferencia de surfpool start

La CLI ejecuta una Surfnet de larga duración a la que te conectas desde procesos externos. El SDK ejecutía Surfnet dentro de tu prueba, lo que significa:

• Sin gestión externa de puertos — cada Surfnet::start() se enlaza a un puerto libre, por lo que los conjuntos de pruebas pueden ejecutarse en paralelo sin flags --port.
• Desmontaje sincrónico — stop() retorna cuando el runtime ha liberado efectivamente sus puertos.
• Cheatcodes como métodos tipados — la misma interfaz expuesta sobre JSON-RPC por surfpool start está disponible como métodos nativos de Rust y bindings de napi-rs.
• Observación directa de eventos — los eventos del runtime se exponen a través de un canal en proceso (Rust) o un método drain (JS) sin necesidad de suscripción por WebSocket.

Cuándo Usar el SDK

Recurre al SDK cuando:

• Estás escribiendo pruebas de integración para un programa de Anchor y quieres verificar saldos de tokens tras una secuencia de configuraciones con cheatcodes.
• Necesitas que los workers de pruebas en paralelo tengan cada uno una Surfnet aislada.
• Quieres hacer fork de cuentas específicas de mainnet (remoteRpcUrl + streamAccount) dentro de una prueba.
• Necesitas relojes deterministas saltando el runtime a un slot o marca de tiempo fijos antes de ejercer lógica de vesting, bloqueo o expiración.