Référence de l'API JS

Le package @solana/surfpool expose une classe, Surfnet, ainsi que les types nécessaires pour appeler ses méthodes de manière sûre. Cette page répertorie tous les symboles exportés ; pour une utilisation narrative, consultez les guides à partir de Vue d'ensemble.

Exports du package

Symbole	Type	Notes
`Surfnet`	classe	Instance Surfnet en cours d'exécution avec méthodes cheatcode
`SurfnetConfig`	type	Argument de `Surfnet.startWithConfig`
`DeployOptions`	type	Argument de `Surfnet.deploy`
`SetTokenAccountUpdate`	type	Argument de `Surfnet.setTokenAccount`
`ResetAccountOptions`	type	Argument de `Surfnet.resetAccount`
`StreamAccountOptions`	type	Argument de `Surfnet.streamAccount`
`SolAccountFunding`	type	Élément du tableau passé à `Surfnet.fundSolMany`
`SimnetEventValue`	type	Élément retourné par `Surfnet.drainEvents`
`KeypairInfo`	type	Retourné par `Surfnet.newKeypair`
`ClockValue`	type	Champ de `SimnetEventValue`
`EpochInfoValue`	type	Retourné par les assistants de voyage dans le temps
`ByteArrayLike`	type	`Uint8Array \| number[]` — entrée d'octets flexible

Classe Surfnet

Méthodes statiques

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

Propriétés de l'instance

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

Cycle de vie

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

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

Cheatcodes de tokens

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

Voyage dans le temps

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

Déploiement de programme

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

Streaming et événements

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

Types de configuration

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

Lorsqu'une méthode accepte ByteArrayLike, vous pouvez passer soit un Uint8Array, soit un tableau de nombres bruts. Le wrapper normalise les deux dans le format attendu par le binding natif.

Types d'événements

SimnetEventValue

Un objet plat avec un discriminateur kind et des champs optionnels. Voir Événements pour le catalogue des variantes.

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

Erreurs

Chaque méthode lève un Error standard dont le message encapsule l'erreur Rust SurfnetError sous-jacente. Inspectez error.message pour distinguer les différents cas.

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

Empreinte du module natif

Le package dépend de binaires natifs spécifiques à la plateforme, publiés sous la forme 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`

Si aucun des packages de plateforme ne s'installe sur votre machine, Surfnet.start() lève une exception au premier appel avec un message clair « module natif introuvable ». Consultez Installation pour la matrice de compatibilité et le dépannage.

Table des matières