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용 사전 빌드된 네이티브 바이너리를 제공하며, Solana Kit 플러그인 진입점도 노출합니다.

빠른 시작

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 또는 타임스탬프로 이동하여 결정론적 클록이 필요할 때.