---
title: Rust API Reference
description:
  Complete public API for the surfpool-sdk crate — Surfnet, builder, cheatcodes,
  builders, errors, and re-exports.
---

The `surfpool-sdk` crate exposes a small surface centered on the `Surfnet`
struct. This page lists every public item; for narrative usage, see the guides
starting with [Overview](/docs/tools/surfpool/sdk/overview).

## Crate Root Exports

| Item                  | Kind       | Notes                                                          |
| --------------------- | ---------- | -------------------------------------------------------------- |
| `Surfnet`             | struct     | Running Surfnet instance — RPC/WS endpoints, payer, cheatcodes |
| `SurfnetBuilder`      | struct     | Fluent builder used by `Surfnet::builder()`                    |
| `Cheatcodes<'_>`      | struct     | Borrowed cheatcode helper returned by `Surfnet::cheatcodes()`  |
| `SurfnetError`        | enum       | All error variants the SDK returns                             |
| `SurfnetResult<T>`    | type alias | `Result<T, SurfnetError>`                                      |
| `Keypair`             | re-export  | `solana_keypair::Keypair`                                      |
| `Pubkey`              | re-export  | `solana_pubkey::Pubkey`                                        |
| `Signer`              | re-export  | `solana_signer::Signer`                                        |
| `RpcClient`           | re-export  | `solana_rpc_client::rpc_client::RpcClient`                     |
| `BlockProductionMode` | re-export  | `surfpool_types::BlockProductionMode`                          |
| `SimnetCommand`       | re-export  | `surfpool_types::SimnetCommand`                                |
| `SimnetEvent`         | re-export  | `surfpool_types::SimnetEvent`                                  |
| `SvmFeatureConfig`    | re-export  | `surfpool_types::SvmFeatureConfig`                             |

## Surfnet

```rust
pub struct Surfnet { /* private */ }
```

### Constructors

```rust
impl Surfnet {
    pub async fn start() -> SurfnetResult<Self>;
    pub fn builder() -> SurfnetBuilder;
}
```

### Accessors

```rust
impl Surfnet {
    pub fn rpc_url(&self) -> &str;
    pub fn ws_url(&self) -> &str;
    pub fn payer(&self) -> &Keypair;
    pub fn instance_id(&self) -> &str;
    pub fn rpc_client(&self) -> RpcClient;
    pub fn cheatcodes(&self) -> Cheatcodes<'_>;
    pub fn events(&self) -> &crossbeam_channel::Receiver<SimnetEvent>;
    pub fn send_command(&self, cmd: SimnetCommand) -> SurfnetResult<()>;
}
```

### Lifecycle

```rust
impl Surfnet {
    pub fn stop(&mut self) -> SurfnetResult<()>;
}

impl Drop for Surfnet { /* calls stop() if not already stopped */ }
```

`stop` blocks for up to five seconds waiting for the runtime to release its
ports. Failure during `Drop` is silent; failure during an explicit `stop`
returns a `SurfnetError::Runtime`.

## SurfnetBuilder

```rust
pub struct SurfnetBuilder { /* private */ }
```

Every setter returns `Self`, so calls can be chained. The terminal call is
`start().await`.

```rust
impl SurfnetBuilder {
    pub fn offline(self, offline: bool) -> Self;
    pub fn remote_rpc_url(self, url: impl Into<String>) -> Self;
    pub fn block_production_mode(self, mode: BlockProductionMode) -> Self;
    pub fn slot_time_ms(self, ms: u64) -> Self;
    pub fn airdrop_addresses(self, addrs: Vec<Pubkey>) -> Self;
    pub fn airdrop_sol(self, lamports: u64) -> Self;
    pub fn skip_blockhash_check(self, skip: bool) -> Self;
    pub fn payer(self, payer: Keypair) -> Self;
    pub fn enable_feature(self, feature_id: Pubkey) -> Self;
    pub fn disable_feature(self, feature_id: Pubkey) -> Self;
    pub fn feature_config(self, config: SvmFeatureConfig) -> Self;
    pub async fn start(self) -> SurfnetResult<Surfnet>;
}
```

## Cheatcodes

```rust
pub struct Cheatcodes<'a> { /* private */ }
```

### SOL Funding

```rust
impl<'a> Cheatcodes<'a> {
    pub fn fund_sol(&self, address: &Pubkey, lamports: u64) -> SurfnetResult<()>;
    pub fn fund_sol_many(&self, accounts: &[(&Pubkey, u64)]) -> SurfnetResult<()>;
}
```

### Token Funding

```rust
impl<'a> Cheatcodes<'a> {
    pub fn fund_token(
        &self,
        owner: &Pubkey,
        mint: &Pubkey,
        amount: u64,
        token_program: Option<&Pubkey>,
    ) -> SurfnetResult<()>;

    pub fn fund_token_many(
        &self,
        owners: &[&Pubkey],
        mint: &Pubkey,
        amount: u64,
        token_program: Option<&Pubkey>,
    ) -> SurfnetResult<()>;

    pub fn set_token_balance(
        &self,
        owner: &Pubkey,
        mint: &Pubkey,
        amount: u64,
        token_program: Option<&Pubkey>,
    ) -> SurfnetResult<()>;

    pub fn get_ata(
        &self,
        owner: &Pubkey,
        mint: &Pubkey,
        token_program: Option<&Pubkey>,
    ) -> Pubkey;
}
```

### Account Mutation

```rust
impl<'a> Cheatcodes<'a> {
    pub fn set_account(
        &self,
        address: &Pubkey,
        lamports: u64,
        data: &[u8],
        owner: &Pubkey,
    ) -> SurfnetResult<()>;

    pub fn execute<B: CheatcodeBuilder>(&self, builder: B) -> SurfnetResult<()>;
}
```

### Time Travel

```rust
impl<'a> Cheatcodes<'a> {
    pub fn time_travel_to_slot(&self, slot: u64) -> SurfnetResult<EpochInfo>;
    pub fn time_travel_to_epoch(&self, epoch: u64) -> SurfnetResult<EpochInfo>;
    pub fn time_travel_to_timestamp(&self, timestamp_ms: u64) -> SurfnetResult<EpochInfo>;
}
```

### Program Deployment

```rust
impl<'a> Cheatcodes<'a> {
    pub fn deploy_program(&self, program_name: &str) -> SurfnetResult<Pubkey>;
    pub fn deploy(&self, builder: DeployProgram) -> SurfnetResult<Pubkey>;
}
```

## CheatcodeBuilder Trait

```rust
pub trait CheatcodeBuilder {
    const METHOD: &'static str;
    fn build(self) -> serde_json::Value;
}
```

Implement this for custom JSON-RPC cheatcodes not yet wrapped by a typed
builder.

## Builders

All builders live in `surfpool_sdk::cheatcodes::builders`.

### SetAccount

```rust
pub struct SetAccount { /* private */ }

impl SetAccount {
    pub fn new(address: Pubkey) -> Self;
    pub fn lamports(self, lamports: u64) -> Self;
    pub fn data(self, data: Vec<u8>) -> Self;
    pub fn owner(self, owner: Pubkey) -> Self;
    pub fn rent_epoch(self, epoch: u64) -> Self;
    pub fn executable(self, executable: bool) -> Self;
}
```

### SetTokenAccount

```rust
pub struct SetTokenAccount { /* private */ }

impl SetTokenAccount {
    pub fn new(owner: Pubkey, mint: Pubkey) -> Self;
    pub fn amount(self, amount: u64) -> Self;
    pub fn delegate(self, delegate: Pubkey) -> Self;
    pub fn clear_delegate(self) -> Self;
    pub fn state(self, state: impl Into<String>) -> Self;
    pub fn delegated_amount(self, amount: u64) -> Self;
    pub fn close_authority(self, authority: Pubkey) -> Self;
    pub fn clear_close_authority(self) -> Self;
    pub fn token_program(self, program: Pubkey) -> Self;
}
```

### ResetAccount

```rust
pub struct ResetAccount { /* private */ }

impl ResetAccount {
    pub fn new(address: Pubkey) -> Self;
    pub fn include_owned_accounts(self, include: bool) -> Self;
}
```

### StreamAccount

```rust
pub struct StreamAccount { /* private */ }

impl StreamAccount {
    pub fn new(address: Pubkey) -> Self;
    pub fn include_owned_accounts(self, include: bool) -> Self;
}
```

### DeployProgram

```rust
pub struct DeployProgram { /* private */ }

impl DeployProgram {
    pub fn new(program_id: Pubkey) -> Self;
    pub fn from_keypair_path(path: impl AsRef<Path>) -> SurfnetResult<Self>;
    pub fn so_path(self, path: impl Into<PathBuf>) -> Self;
    pub fn so_bytes(self, bytes: Vec<u8>) -> Self;
    pub fn idl_path(self, path: impl Into<PathBuf>) -> Self;
}
```

## SurfnetError

```rust
#[derive(Debug)]
pub enum SurfnetError {
    PortAllocation(String),
    Startup(String),
    Runtime(String),
    Cheatcode(String),
    Aborted(String),
}
```

| Variant          | Cause                                                  |
| ---------------- | ------------------------------------------------------ |
| `PortAllocation` | Could not bind to a free port for RPC or WebSocket.    |
| `Startup`        | The runtime failed to initialize.                      |
| `Runtime`        | The runtime thread panicked or exited unexpectedly.    |
| `Cheatcode`      | A cheatcode JSON-RPC call returned an error.           |
| `Aborted`        | The runtime was shut down or cancelled during startup. |

The crate implements `std::error::Error` and `Display` on `SurfnetError`, so it
works with `?` and `anyhow` out of the box.