Referencia de la API de JS

El paquete @solana/surfpool expone una clase, Surfnet, junto con los tipos necesarios para llamar a sus métodos con seguridad de tipos. Esta página lista todos los símbolos exportados; para un uso más descriptivo, consulta las guías que comienzan con Descripción general.

Exportaciones del paquete

Símbolo	Tipo	Notas
`Surfnet`	clase	Instancia de Surfnet en ejecución con métodos de cheatcode
`SurfnetConfig`	tipo	Argumento de `Surfnet.startWithConfig`
`DeployOptions`	tipo	Argumento de `Surfnet.deploy`
`SetTokenAccountUpdate`	tipo	Argumento de `Surfnet.setTokenAccount`
`ResetAccountOptions`	tipo	Argumento de `Surfnet.resetAccount`
`StreamAccountOptions`	tipo	Argumento de `Surfnet.streamAccount`
`SolAccountFunding`	tipo	Elemento del array pasado a `Surfnet.fundSolMany`
`SimnetEventValue`	tipo	Elemento devuelto por `Surfnet.drainEvents`
`KeypairInfo`	tipo	Devuelto por `Surfnet.newKeypair`
`ClockValue`	tipo	Campo de `SimnetEventValue`
`EpochInfoValue`	tipo	Devuelto por los helpers de viaje en el tiempo
`ByteArrayLike`	tipo	`Uint8Array \| number[]` — entrada de bytes flexible

Clase Surfnet

Métodos estáticos

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

Propiedades de instancia

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 de vida

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

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

Viaje en el tiempo

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

Despliegue de programas

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

Streaming y eventos

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

Tipos de configuración

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

Cuando un método acepta ByteArrayLike, puedes pasar un Uint8Array o un arreglo de números simples. El wrapper normaliza ambos al formato que el binding nativo espera.

Tipos de Eventos

SimnetEventValue

Un objeto plano con un discriminador kind y campos opcionales. Consulta Events para el catálogo de 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;
}

Errores

Cada método lanza un Error estándar cuyo mensaje envuelve el SurfnetError de Rust subyacente. Inspecciona error.message para discriminar entre los casos.

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

Huella del Módulo Nativo

El paquete depende de binarios nativos específicos de la plataforma publicados como optionalDependencies:

Triple	Paquete
`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 ninguno de los paquetes de plataforma se instala en tu máquina, Surfnet.start() genera un error en la primera llamada con un mensaje claro de "módulo nativo no encontrado". Consulta Instalación para conocer la matriz de compatibilidad y la resolución de problemas.

Tabla de Contenidos