配置 | Solana

Surfnet::start()（Rust）和 Surfnet.start()（JS）以离线模式启动 Surfnet，使用交易模式区块生产，并为付款方预存 10 SOL。当你需要其他配置时——例如主网分叉的 Surfnet、更慢的时钟、确定性资金分配、指定的付款方 keypair——请使用构建器（Rust）或 startWithConfig（JS）。

默认值

如果你调用 start() 时不传任何参数，将得到以下配置：

设置	值
模式	离线（无上游 RPC）
区块生产	交易模式（每笔交易推进一个区块）
Slot 时间	1 毫秒
付款方	随机 keypair，预存 10 SOL（10,000,000,000 lamport）
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 setter	JS 字段	类型	默认值
离线模式	`offline(bool)`	`offline?: boolean`	`bool`	`true`
上游 RPC	`remote_rpc_url(impl Into<String>)`	`remoteRpcUrl?: string`	URL 字符串	无
区块生产	`block_production_mode(BlockProductionMode)`	`blockProductionMode?: string`	枚举 / `"manual" \| "clock" \| "transaction"`	`Transaction`
Slot 时间	`slot_time_ms(u64)`	`slotTimeMs?: number`	毫秒	`1`
空投地址	`airdrop_addresses(Vec<Pubkey>)`	`airdropAddresses?: string[]`	pubkey 列表	空
空投金额	`airdrop_sol(u64)`	`airdropSol?: number`	lamport	`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 获取，这也是 mainnet-fork 测试的工作方式。

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

使用高质量的上游 RPC

对于涉及大量 fork 账户的测试，请使用付费端点（Helius、Triton、QuickNode）。公共 mainnet-beta 有严格的速率限制，在并行测试负载下容易出现不稳定情况。

区块生产模式

模式	区块推进时机
`Transaction`（默认）	每笔交易后推进。最适合发送后立即断言的测试。
`Clock`	按 `slot_time_ms` 设定的固定间隔推进。最适合依赖多个 slot 经过而无需显式交易的测试。
`Manual`	仅在发送 `SimnetCommand::AdvanceClock` 时推进。最适合由测试驱动时钟的时间敏感型测试。

自定义付款方

默认情况下，付款方为一个新生成的 keypair。当测试需要已知地址时（例如预先构建引用付款方公钥的指令），请提供您自己的 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?;

跳过 Blockhash 检查

skip_blockhash_check(true)（仅限 Rust）禁用所有交易的 blockhash 验证。适用于提前签署交易或不关心过期问题的测试。

错误

配置错误的构建器在 start() 处失败。Rust SDK 返回 SurfnetError：

变体	触发时机
`PortAllocation(String)`	无法绑定到可用的 RPC 或 WebSocket 端口。
`Startup(String)`	运行时初始化失败（配置错误、远程 URL 无效等）。
`Runtime(String)`	运行时在就绪前于启动阶段崩溃。
`Aborted(String)`	启动被取消（例如，启动过程中收到关闭信号）。
`Cheatcode(String)`	构建器内部的作弊码调用失败。

JS SDK 会抛出一个 Error，其消息中封装了相同的底层变体。

Table of Contents