JS API 参考文档

@solana/surfpool 包公开了一个类 Surfnet，以及调用其方法所需的类型定义。本页列出了所有导出的符号；如需了解使用说明，请参阅从概述开始的指南。

Kit 入口点

以下符号是 @solana/surfpool 的根导出项。@solana/surfpool/kit 子路径额外提供了 surfpool()、surfnetCheatcodes()、createSurfnetCheatcodesRpc()、DEFAULT_SURFNET_ENDPOINT、插件配置类型以及生成的作弊码线路类型——这些均记录在 Kit 插件页面，而非本表格中。

包导出

符号	类型	说明
`Surfnet`	类	运行中的 Surfnet 实例，包含作弊码方法
`SurfnetConfig`	类型	`Surfnet.startWithConfig` 的参数
`DeployOptions`	类型	`Surfnet.deploy` 的参数
`SetTokenAccountUpdate`	类型	`Surfnet.setTokenAccount` 的参数
`ResetAccountOptions`	类型	`Surfnet.resetAccount` 的参数
`StreamAccountOptions`	类型	`Surfnet.streamAccount` 的参数
`SolAccountFunding`	类型	传递给 `Surfnet.fundSolMany` 的数组元素
`SimnetEventValue`	类型	`Surfnet.drainEvents` 返回的元素
`KeypairInfo`	类型	由 `Surfnet.newKeypair` 返回
`ClockValue`	类型	`SimnetEventValue` 上的字段
`EpochInfoValue`	类型	由时间旅行辅助函数返回
`ByteArrayLike`	类型	`Uint8Array \| number[]` —— 灵活的字节输入

Surfnet 类

静态方法

class Surfnet {
  static start(): Surfnet;
  static startWithConfig(config: SurfnetConfig): Surfnet;
  static newKeypair(): KeypairInfo;
}

实例属性

class Surfnet {
  readonly rpcUrl: string; // http://127.0.0.1:<port>
  readonly wsUrl: string; // ws://127.0.0.1:<port>
  readonly payer: string; // base58 public key
  readonly payerSecretKey: Uint8Array; // 64-byte private key
  readonly instanceId: string;
}

生命周期

class Surfnet {
  stop(): void; // idempotent; safe to call from `finally` / test teardown
}

SOL 作弊码

class Surfnet {
  fundSol(address: string, lamports: number): void;
  fundSolMany(accounts: SolAccountFunding[]): void;
  setAccount(
    address: string,
    lamports: number,
    data: Uint8Array,
    owner: string
  ): void;
  resetAccount(address: string, options?: ResetAccountOptions): void;
}

Token 作弊码

class Surfnet {
  fundToken(
    owner: string,
    mint: string,
    amount: number,
    tokenProgram?: string
  ): void;
  fundTokenMany(
    owners: string[],
    mint: string,
    amount: number,
    tokenProgram?: string
  ): void;
  setTokenBalance(
    owner: string,
    mint: string,
    amount: number,
    tokenProgram?: string
  ): void;
  setTokenAccount(
    owner: string,
    mint: string,
    update: SetTokenAccountUpdate,
    tokenProgram?: string
  ): void;
  getAta(owner: string, mint: string, tokenProgram?: string): string;
}

时间旅行

class Surfnet {
  timeTravelToSlot(slot: number): EpochInfoValue;
  timeTravelToEpoch(epoch: number): EpochInfoValue;
  timeTravelToTimestamp(timestampMs: number): EpochInfoValue;
}

程序部署

class Surfnet {
  deployProgram(programName: string): string; // returns program id
  deploy(options: DeployOptions): string; // returns program id
}

流式传输与事件

class Surfnet {
  streamAccount(address: string, options?: StreamAccountOptions): void;
  drainEvents(): SimnetEventValue[];
}

配置类型

SurfnetConfig

interface SurfnetConfig {
  offline?: boolean; // default: true
  remoteRpcUrl?: string; // setting this implies offline=false
  blockProductionMode?: "manual" | "clock" | "transaction"; // default: "transaction"
  slotTimeMs?: number; // default: 1
  airdropSol?: number; // lamports; default: 10_000_000_000
  airdropAddresses?: string[];
  payerSecretKey?: ByteArrayLike;
  enableFeatures?: string[]; // feature IDs (base58 or kebab name)
  disableFeatures?: string[];
  allFeatures?: boolean;
}

DeployOptions

interface DeployOptions {
  programId: string; // base58 address
  soPath?: string; // mutually exclusive with soBytes
  soBytes?: ByteArrayLike;
  idlPath?: string; // optional Anchor IDL JSON
}

SetTokenAccountUpdate

interface SetTokenAccountUpdate {
  amount?: number;
  delegate?: string; // base58 pubkey
  clearDelegate?: boolean;
  state?: string; // e.g. "initialized", "frozen"
  delegatedAmount?: number;
  closeAuthority?: string;
  clearCloseAuthority?: boolean;
}

ResetAccountOptions

interface ResetAccountOptions {
  includeOwnedAccounts?: boolean;
}

StreamAccountOptions

interface StreamAccountOptions {
  includeOwnedAccounts?: boolean;
}

SolAccountFunding

interface SolAccountFunding {
  address: string;
  lamports: number;
}

KeypairInfo

interface KeypairInfo {
  publicKey: string; // base58
  secretKey: number[]; // 64 bytes
}

ByteArrayLike

type ByteArrayLike = Uint8Array | number[];

当某个方法接受 ByteArrayLike 时，您可以传入 Uint8Array 或普通数字数组。该包装器会将两者统一转换为原生绑定所需的格式。

事件类型

SimnetEventValue

一个包含 kind 判别字段及可选字段的扁平对象。请参阅事件了解变体目录。

interface SimnetEventValue {
  kind: string;
  message?: string;
  timestamp?: string;
  initialTransactionCount?: number;
  clock?: ClockValue;
  epochInfo?: EpochInfoValue;
  accountPubkey?: string;
  clockCommand?: string;
  slotIntervalMs?: number;
  transactionSignature?: string;
  logs?: string[];
  computeUnitsConsumed?: number;
  fee?: number;
  errorMessage?: string;
  tag?: string;
  profileKey?: string;
  profileSlot?: number;
  runbookId?: string;
  runbookErrors?: string[];
}

ClockValue

interface ClockValue {
  slot: number;
  epoch: number;
  leaderScheduleEpoch: number;
  unixTimestamp: number;
  epochStartTimestamp: number;
}

EpochInfoValue

interface EpochInfoValue {
  absoluteSlot: number;
  slotIndex: number;
  slotsInEpoch: number;
  epoch: number;
  blockHeight: number;
  transactionCount?: number;
}

错误

每个方法都会抛出一个标准的 Error，其消息中包含底层 Rust 的 SurfnetError。请检查 error.message 以区分不同的错误情况。

try {
  surfnet.deploy({ programId, soPath: "missing.so" });
} catch (err) {
  // err.message starts with "Cheatcode:" / "Startup:" / etc.
  console.error(err);
}

原生模块占用空间

该包依赖于以下平台特定的原生二进制文件，发布为 optionalDependencies：

Triple	Package
`aarch64-apple-darwin`	`@solana/surfpool-darwin-arm64`
`x86_64-apple-darwin`	`@solana/surfpool-darwin-x64`
`x86_64-unknown-linux-gnu`	`@solana/surfpool-linux-x64-gnu`

如果没有任何平台包能够在您的机器上安装，Surfnet.start() 将在首次调用时抛出明确的"未找到原生模块"错误。请参阅安装了解支持矩阵与故障排除说明。

Table of Contents