Surfpool SDK

Surfpool SDK는 테스트 프로세스 내부에서 전체 Surfnet 런타임을 시작합니다. 로컬 Solana 호환 RPC 엔드포인트, 사전 충전된 페이어, 그리고 surfpool start를 별도의 프로세스로 실행하지 않고도 직접 상태를 조작하고 싶을 때 사용하세요.

Rust 크레이트(surfpool-sdk)와 JS 바인딩(@solana/surfpool) 모두 동일한 런타임을 래핑합니다. JS 패키지는 napi-rs를 통해 macOS(Intel + Apple Silicon) 및 Linux x86-64용 사전 빌드된 네이티브 바이너리를 제공합니다.

빠른 시작

SDK를 설치하고, Surfnet을 시작한 후, RPC 엔드포인트에 접속하고, 종료하세요. 포트가 동적으로 할당되므로 병렬 테스트가 동일한 프로세스를 안전하게 공유합니다.

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

포함된 기능

surfpool start와의 차이점

CLI는 외부 프로세스에서 연결할 수 있는 장기 실행 Surfnet을 실행합니다. SDK는 Surfnet을 테스트 내부에서 실행하며, 이는 다음을 의미합니다:

• 외부 포트 관리 불필요 — 모든 Surfnet::start()는 사용 가능한 포트에 자동으로 바인딩되므로, 테스트 스위트를 --port 플래그 없이 병렬로 실행할 수 있습니다.
• 동기식 종료 — stop()는 런타임이 실제로 포트를 해제한 후에 반환됩니다.
• 타입이 지정된 메서드로 제공되는 치트코드 — surfpool start가 JSON-RPC를 통해 노출하는 동일한 인터페이스를 네이티브 Rust 메서드 및 napi-rs 바인딩으로 사용할 수 있습니다.
• 직접 이벤트 관찰 — 런타임 이벤트는 WebSocket 구독 없이 인프로세스 채널(Rust) 또는 drain 메서드(JS)를 통해 노출됩니다.

SDK를 사용해야 하는 경우

다음과 같은 경우 SDK를 사용하세요:

• Anchor 프로그램의 통합 테스트를 작성 중이며, 치트코드 설정 시퀀스 이후 토큰 잔액을 검증하고 싶을 때.
• 병렬 테스트 워커가 각각 독립된 Surfnet을 가져야 할 때.
• 테스트 내에서 remoteRpcUrl + streamAccount를 사용하여 메인넷의 특정 계정을 포크하고 싶을 때.
• 베스팅, 잠금, 만료 로직을 실행하기 전에 런타임을 특정 slot 또는 타임스탬프로 이동하여 결정론적 클록이 필요할 때.