---
title: JS API Reference
description:
  Complete public API for the @solana/surfpool package — Surfnet class, config
  types, deploy options, and event shape.
---

The `@solana/surfpool` package exposes one class, `Surfnet`, plus the supporting
types you need to call its methods type-safely. This page lists every exported
symbol; for narrative usage, see the guides starting with
[Overview](/docs/tools/surfpool/sdk/overview).

<Callout type="info" title="Kit entry point">
  The symbols below are the root `@solana/surfpool` exports. The
  `@solana/surfpool/kit` subpath adds `surfpool()`, `surfnetCheatcodes()`,
  `createSurfnetCheatcodesRpc()`, `DEFAULT_SURFNET_ENDPOINT`, the plugin config
  types, and the generated cheatcode wire types — all documented on [Kit
  Plugin](/docs/tools/surfpool/sdk/kit-plugin) rather than in this table.
</Callout>

## Package Exports

| Symbol                  | Kind  | Notes                                                |
| ----------------------- | ----- | ---------------------------------------------------- |
| `Surfnet`               | class | Running Surfnet instance with cheatcode methods      |
| `SurfnetConfig`         | type  | Argument to `Surfnet.startWithConfig`                |
| `DeployOptions`         | type  | Argument to `Surfnet.deploy`                         |
| `SetTokenAccountUpdate` | type  | Argument to `Surfnet.setTokenAccount`                |
| `ResetAccountOptions`   | type  | Argument to `Surfnet.resetAccount`                   |
| `StreamAccountOptions`  | type  | Argument to `Surfnet.streamAccount`                  |
| `SolAccountFunding`     | type  | Element of the array passed to `Surfnet.fundSolMany` |
| `SimnetEventValue`      | type  | Element returned by `Surfnet.drainEvents`            |
| `KeypairInfo`           | type  | Returned by `Surfnet.newKeypair`                     |
| `ClockValue`            | type  | Field on `SimnetEventValue`                          |
| `EpochInfoValue`        | type  | Returned by time-travel helpers                      |
| `ByteArrayLike`         | type  | `Uint8Array \| number[]` — flexible byte input       |

## Surfnet Class

### Static Methods

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

### Instance Properties

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

### Lifecycle

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

### SOL Cheatcodes

```ts
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 Cheatcodes

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

### Time Travel

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

### Program Deployment

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

### Streaming & Events

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

## Config Types

### SurfnetConfig

```ts
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

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

### SetTokenAccountUpdate

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

### ResetAccountOptions

```ts
interface ResetAccountOptions {
  includeOwnedAccounts?: boolean;
}
```

### StreamAccountOptions

```ts
interface StreamAccountOptions {
  includeOwnedAccounts?: boolean;
}
```

### SolAccountFunding

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

### KeypairInfo

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

### ByteArrayLike

```ts
type ByteArrayLike = Uint8Array | number[];
```

Where a method accepts `ByteArrayLike`, you can pass either a `Uint8Array` or a
plain number array. The wrapper normalizes both into the format the native
binding expects.

## Event Types

### SimnetEventValue

A flat object with a `kind` discriminator and optional fields. See
[Events](/docs/tools/surfpool/sdk/events) for the variant catalog.

```ts
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

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

### EpochInfoValue

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

## Errors

Every method throws a standard `Error` whose message wraps the underlying Rust
`SurfnetError`. Inspect `error.message` to discriminate between cases.

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

## Native Module Footprint

The package depends on platform-specific native binaries published as
`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` |

If none of the platform packages installs on your machine, `Surfnet.start()`
throws at first call with a clear "native module not found" error. See
[Installation](/docs/tools/surfpool/sdk/installation) for the support matrix and
troubleshooting.