Riferimento API JS

Il pacchetto @solana/surfpool espone una classe, Surfnet, insieme ai tipi di supporto necessari per chiamare i suoi metodi in modo type-safe. Questa pagina elenca ogni simbolo esportato; per una guida narrativa all'utilizzo, consulta le guide a partire da Panoramica.

Esportazioni del pacchetto

Simbolo	Tipo	Note
`Surfnet`	class	Istanza Surfnet in esecuzione con metodi cheatcode
`SurfnetConfig`	type	Argomento di `Surfnet.startWithConfig`
`DeployOptions`	type	Argomento di `Surfnet.deploy`
`SetTokenAccountUpdate`	type	Argomento di `Surfnet.setTokenAccount`
`ResetAccountOptions`	type	Argomento di `Surfnet.resetAccount`
`StreamAccountOptions`	type	Argomento di `Surfnet.streamAccount`
`SolAccountFunding`	type	Elemento dell'array passato a `Surfnet.fundSolMany`
`SimnetEventValue`	type	Elemento restituito da `Surfnet.drainEvents`
`KeypairInfo`	type	Restituito da `Surfnet.newKeypair`
`ClockValue`	type	Campo su `SimnetEventValue`
`EpochInfoValue`	type	Restituito dagli helper di time-travel
`ByteArrayLike`	type	`Uint8Array \| number[]` — input byte flessibile

Classe Surfnet

Metodi statici

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

Proprietà dell'istanza

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

Ciclo di vita

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

Cheatcode 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;
}

Cheatcode 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;
}

Viaggio nel tempo

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

Deploy dei programmi

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

Streaming ed eventi

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

Tipi di configurazione

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[];

Dove un metodo accetta ByteArrayLike, è possibile passare un Uint8Array oppure un semplice array di numeri. Il wrapper normalizza entrambi nel formato atteso dal binding nativo.

Tipi di Evento

SimnetEventValue

Un oggetto flat con un discriminatore kind e campi opzionali. Consulta Events per il catalogo delle varianti.

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

Errori

Ogni metodo genera un Error standard il cui messaggio racchiude l'errore Rust SurfnetError sottostante. Ispeziona error.message per distinguere i casi.

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

Footprint del Modulo Nativo

Il pacchetto dipende da binari nativi specifici per piattaforma, pubblicati come optionalDependencies:

Triple	Pacchetto
`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`

Se nessuno dei pacchetti di piattaforma viene installato sul tuo computer, Surfnet.start() genera un errore alla prima chiamata con un messaggio chiaro "modulo nativo non trovato". Consulta Installazione per la matrice di supporto e la risoluzione dei problemi.

Indice dei contenuti