구성 | Solana

Surfnet::start() (Rust)와 Surfnet.start() (JS)는 트랜잭션 모드 블록 생성과 10 SOL이 미리 충전된 페이어로 오프라인 Surfnet을 시작합니다. 메인넷 포크된 Surfnet, 느린 클록, 결정론적 자금 지원, 특정 페이어 keypair 등이 필요한 경우 빌더 (Rust) 또는 startWithConfig (JS)를 사용하세요.

기본값

start()를 인수 없이 호출하면 다음과 같은 설정이 적용됩니다:

설정	값
모드	오프라인 (업스트림 RPC 없음)
블록 생성	트랜잭션 (각 tx마다 블록 진행)
Slot 시간	1 ms
페이어	10 SOL (10,000,000,000 lamports)이 충전된 랜덤 keypair
RPC URL	`http://127.0.0.1:<random>`
WS URL	`ws://127.0.0.1:<random>`
피처 구성	기본 메인넷 피처 세트

커스텀 구성

use surfpool_sdk::{BlockProductionMode, Pubkey, Surfnet};

#[tokio::test]
async fn starts_with_custom_configuration() {
    let alice = Pubkey::new_unique();

    let surfnet = Surfnet::builder()
        .remote_rpc_url("https://api.mainnet-beta.solana.com")
        .block_production_mode(BlockProductionMode::Transaction)
        .slot_time_ms(10)
        .airdrop_addresses(vec![alice])
        .airdrop_sol(5_000_000_000)
        .skip_blockhash_check(true)
        .start()
        .await
        .unwrap();

    assert_eq!(
        surfnet.rpc_client().get_balance(&alice).unwrap(),
        5_000_000_000
    );
}

빌더 레퍼런스

Rust 빌더와 JS 구성 객체는 camelCase / snake_case 명명 방식으로 동일한 논리적 옵션을 제공합니다.

옵션	Rust 세터	JS 필드	타입	기본값
오프라인 모드	`offline(bool)`	`offline?: boolean`	`bool`	`true`
업스트림 RPC	`remote_rpc_url(impl Into<String>)`	`remoteRpcUrl?: string`	URL 문자열	없음
블록 생성	`block_production_mode(BlockProductionMode)`	`blockProductionMode?: string`	enum / `"manual" \| "clock" \| "transaction"`	`Transaction`
Slot 시간	`slot_time_ms(u64)`	`slotTimeMs?: number`	밀리초	`1`
에어드롭 주소	`airdrop_addresses(Vec<Pubkey>)`	`airdropAddresses?: string[]`	pubkey 목록	없음
에어드롭 수량	`airdrop_sol(u64)`	`airdropSol?: number`	lamports	`10_000_000_000`
블록해시 건너뛰기	`skip_blockhash_check(bool)`	n/a	`bool`	`false`
커스텀 페이어	`payer(Keypair)`	`payerSecretKey?: Uint8Array \| number[]`	Keypair / 바이트	자동 생성
피처 활성화	`enable_feature(Pubkey)`	`enableFeatures?: string[]`	피처 ID	없음
피처 비활성화	`disable_feature(Pubkey)`	`disableFeatures?: string[]`	피처 ID	없음
전체 피처	n/a	`allFeatures?: boolean`	`bool`	`false`
피처 구성	`feature_config(SvmFeatureConfig)`	n/a	전체 구성	기본 메인넷

원격 RPC 폴백

remoteRpcUrl (또는 Rust에서는 remote_rpc_url)를 설정하면 Surfnet이 오프라인 모드에서 벗어납니다. 로컬에 없는 계정은 업스트림 RPC에서 필요 시 가져오며, 이것이 메인넷 포크 테스트의 작동 방식입니다.

let surfnet = Surfnet::builder()
    .remote_rpc_url("https://api.mainnet-beta.solana.com")
    .start()
    .await?;

고품질 업스트림 RPC 사용

포크된 계정을 많이 사용하는 테스트에는 유료 엔드포인트(Helius, Triton, QuickNode)를 사용하세요. 공개 mainnet-beta는 요청 횟수 제한이 심하여 병렬 테스트 환경에서 불안정하게 동작할 수 있습니다.

블록 생성 모드

모드	블록 진행 시점
`Transaction` (기본값)	모든 트랜잭션 이후. 트랜잭션을 전송하고 즉시 검증하는 테스트에 적합합니다.
`Clock`	`slot_time_ms`로 설정한 고정 간격마다. 명시적인 트랜잭션 없이 여러 slot이 경과하는 테스트에 적합합니다.
`Manual`	`SimnetCommand::AdvanceClock`가 전송될 때만. 테스트가 클럭을 직접 제어하는 시간 민감형 테스트에 적합합니다.

커스텀 페이어

기본적으로 페이어는 새로 생성된 keypair입니다. 테스트에서 알려진 주소가 필요한 경우, 예를 들어 페이어의 공개 키를 참조하는 명령을 미리 구성할 때 직접 제공할 수 있습니다.

use surfpool_sdk::{Keypair, Signer, Surfnet};

let payer = Keypair::new();
let surfnet = Surfnet::builder().payer(payer.insecure_clone()).start().await?;

assert_eq!(surfnet.payer().pubkey(), payer.pubkey());

피처 게이트

ID로 개별 SVM 피처 게이트를 토글하거나, allFeatures: true (JS 전용 — Rust 빌더는 전체 세트에 feature_config를 사용)로 알려진 모든 피처를 활성화할 수 있습니다.

use surfpool_sdk::{Pubkey, Surfnet};

let feature_id: Pubkey = "9bn2vTJUsUcnpiZWbu2woSKtTGW3ErZC9ERv88SDqQjK"
    .parse()
    .unwrap();

let surfnet = Surfnet::builder()
    .enable_feature(feature_id)
    .start()
    .await?;

블록해시 검사 건너뛰기

skip_blockhash_check(true) (Rust 전용)는 모든 트랜잭션에 대한 블록해시 유효성 검사를 비활성화합니다. 제출 전 미리 트랜잭션에 서명하거나 만료 여부를 신경 쓰지 않는 테스트에 유용합니다.

오류

잘못 구성된 빌더는 start()에서 실패합니다. Rust SDK는 SurfnetError를 반환합니다:

변형	발생 시점
`PortAllocation(String)`	사용 가능한 RPC 또는 WebSocket 포트에 바인딩할 수 없는 경우.
`Startup(String)`	런타임 초기화 실패 (잘못된 구성, 잘못된 원격 URL 등).
`Runtime(String)`	준비 상태가 되기 전 시작 중에 런타임이 충돌한 경우.
`Aborted(String)`	시작이 취소된 경우 (예: 부팅 중 종료 신호).
`Cheatcode(String)`	빌더 내부의 치트코드 호출이 실패한 경우.

JS SDK는 동일한 기본 변형을 메시지로 래핑하는 Error를 발생시킵니다.

목차