Surfpool SDK

O SDK do Surfpool inicia um runtime Surfnet completo dentro do seu processo de teste. Use-o quando quiser um endpoint RPC local compatível com Solana, um pagador pré-financiado e manipulação direta de estado sem iniciar o surfpool start como um processo separado.

Tanto o crate Rust (surfpool-sdk) quanto as ligações JS (@solana/surfpool) encapsulam o mesmo runtime. O pacote JS inclui binários nativos pré-compilados via napi-rs para macOS (Intel + Apple Silicon) e Linux x86-64.

Início Rápido

Instale o SDK, inicie um Surfnet, acesse o endpoint RPC e, em seguida, encerre-o. Testes paralelos compartilham o mesmo processo com segurança, pois as portas são alocadas 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());
}

O Que Está Incluído

Como Se Diferencia do surfpool start

A CLI executa um Surfnet de longa duração ao qual você se conecta a partir de processos externos. O SDK executa o Surfnet dentro do seu teste, o que significa:

• Sem gerenciamento externo de portas — cada Surfnet::start() vincula-se a uma porta livre, permitindo que suítes de teste sejam executadas em paralelo sem flags --port.
• Encerramento síncrono — stop() retorna quando o runtime liberou efetivamente suas portas.
• Cheatcodes como métodos tipados — a mesma interface exposta via JSON-RPC pelo surfpool start está disponível como métodos nativos em Rust e bindings napi-rs.
• Observação direta de eventos — os eventos do runtime são expostos por meio de um canal em processo (Rust) ou de um método drain (JS), sem necessidade de assinatura via WebSocket.

Quando Usar o SDK

Utilize o SDK quando:

• Você está escrevendo testes de integração para um programa Anchor e deseja verificar saldos de tokens após uma sequência de configurações com cheatcodes.
• Você precisa que workers de teste paralelos tenham cada um uma Surfnet isolada.
• Você deseja fazer fork de contas da mainnet (remoteRpcUrl + streamAccount) dentro de um teste.
• Você precisa de clocks determinísticos, avançando o runtime para um slot ou timestamp fixo antes de testar lógicas de vesting, lockup ou expiração.