### SVM Action Configuration in HCL

Source: https://solana.com/docs/tools/surfpool/iac/svm/actions

Example configuration demonstrating the usage of various SVM actions within a setup block.

```hcl
action "setup" "svm::setup_surfnet" {
    // Set account balance
    set_account {
        public_key = signer.caller.public_key
        lamports = 999999999
    }

    // Set token balance
    set_token_account {
        public_key = signer.caller.public_key
        token = "usdc"
        amount = 1000000
    }

    // Clone a program
    clone_program_account {
        source_program_id = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
        destination_program_id = variable.my_program_id
    }

    // Set program authority
    set_program_authority {
        program_id = variable.my_program_id
        authority = signer.caller.public_key
    }

    // Deploy a program directly
    deploy_program {
        program_id = variable.my_program_id
        binary_path = "./target/deploy/my_program.so"
        idl_path = "./target/idl/my_program.json"
    }

    // Reset an account to re-fetch from upstream
    reset_account {
        public_key = variable.some_pubkey
    }

    // Stream account data from mainnet
    stream_account {
        public_key = variable.some_pubkey
        include_owned_accounts = true
    }
}
```

--------------------------------

### Install Surfpool via script

Source: https://solana.com/docs/tools/surfpool/toolchain/getting-started

Executes the installation script directly in the terminal.

```bash
curl -sL https://run.surfpool.run/ | bash
```

--------------------------------

### Surfnet::start

Source: https://solana.com/docs/tools/surfpool/sdk/rust-reference

Initializes and starts a new Surfnet instance.

```APIDOC
## pub async fn start() -> SurfnetResult<Self>

### Description
Starts a new Surfnet instance. This is the primary entry point for initializing the network environment.
```

--------------------------------

### Install Solana Kit Plugins

Source: https://solana.com/docs/tools/surfpool/sdk/installation

Install optional peer dependencies to use Surfpool as a Solana Kit plugin.

```bash
npm install --save-dev @solana/kit @solana/kit-plugin-rpc @solana/kit-plugin-signer
# or
pnpm add -D @solana/kit @solana/kit-plugin-rpc @solana/kit-plugin-signer
```

--------------------------------

### Install Surfpool SDK

Source: https://solana.com/docs/tools/surfpool/sdk/installation

Install the Surfpool package as a development dependency using npm, pnpm, or yarn.

```bash
npm install --save-dev @solana/surfpool
# or
pnpm add -D @solana/surfpool
# or
yarn add --dev @solana/surfpool
```

--------------------------------

### Compile Surfpool binary

Source: https://solana.com/docs/tools/surfpool/toolchain/getting-started

Builds the binary and installs it to ~/.cargo/bin/surfpool.

```bash
cargo surfpool-install
```

--------------------------------

### Start Surfpool with various configurations

Source: https://solana.com/docs/tools/surfpool/toolchain/cli

Commands to initialize the surfpool environment with different network, logging, and persistence settings.

```sh
surfpool start
```

```sh
surfpool start --network devnet
```

```sh
surfpool start --rpc-url https://api.mainnet-beta.solana.com
```

```sh
surfpool start --no-tui
```

```sh
surfpool start --offline
```

```sh
surfpool start --airdrop <PUBKEY> --airdrop <PUBKEY>
```

```sh
surfpool start --snapshot ./snapshot1.json --snapshot ./snapshot2.json
```

```sh
surfpool start --watch
```

```sh
surfpool start --db ./surfnet.sqlite --surfnet-id local-dev
```

--------------------------------

### Start Surfnet instance

Source: https://solana.com/docs/tools/surfpool/rpc/overview

Initializes a local Surfnet instance on http://localhost:8899 using the Surfpool CLI.

```bash
surfpool start
```

--------------------------------

### Install Surfpool Kit dependencies

Source: https://solana.com/docs/tools/surfpool/sdk/kit-plugin

Use these commands to install the necessary packages for the Surfpool Kit plugin via npm or pnpm.

```bash
npm install --save-dev @solana/kit @solana/kit-plugin-rpc @solana/kit-plugin-signer @solana/surfpool
# or
pnpm add -D @solana/kit @solana/kit-plugin-rpc @solana/kit-plugin-signer @solana/surfpool
```

--------------------------------

### Start MCP Server

Source: https://solana.com/docs/tools/surfpool/toolchain/cli

Initializes the Surfpool MCP server to enable AI tool integration.

```sh
surfpool mcp
```

--------------------------------

### Verify Surfpool SDK Installation

Source: https://solana.com/docs/tools/surfpool/sdk/installation

Smoke tests to confirm the runtime starts and the RPC endpoint accepts requests.

```rust
use surfpool_sdk::{Signer, Surfnet};

#[tokio::test]
async fn surfpool_sdk_smoke() {
    let surfnet = Surfnet::start().await.expect("start surfnet");
    let balance = surfnet
        .rpc_client()
        .get_balance(&surfnet.payer().pubkey())
        .expect("get balance");
    assert!(balance > 0);
}
```

```typescript
import { after, test } from "node:test";
import assert from "node:assert/strict";
import { Surfnet } from "@solana/surfpool";

const surfnet = Surfnet.start();
after(() => surfnet.stop());

test("surfpool sdk smoke", () => {
  assert.match(surfnet.rpcUrl, /^http:\/\/127\.0\.0\.1:\d+$/);
  assert.ok(surfnet.payer.length > 0);
});
```

--------------------------------

### Start a local Surfnet in tests

Source: https://solana.com/docs/tools/surfpool/sdk/overview

Initialize a local Surfnet runtime and verify RPC connectivity and payer availability.

```rust
use surfpool_sdk::{Signer, Surfnet};

#[tokio::test]
async fn starts_a_local_surfnet() {
    let surfnet = Surfnet::start().await.unwrap();

    let rpc = surfnet.rpc_client();
    let balance = rpc.get_balance(&surfnet.payer().pubkey()).unwrap();

    assert!(balance > 0);
    println!("rpc: {}", surfnet.rpc_url());
    println!("ws: {}", surfnet.ws_url());
}
```

```typescript
import { after, test } from "node:test";
import assert from "node:assert/strict";
import { Surfnet } from "@solana/surfpool";

const surfnet = Surfnet.start();

after(() => {
  surfnet.stop();
});

test("starts a local surfnet", () => {
  assert.match(surfnet.rpcUrl, /^http:\/\/127\.0\.0\.1:\d+$/);
  assert.match(surfnet.wsUrl, /^ws:\/\/127\.0\.0\.1:\d+$/);
  assert.ok(surfnet.payer);
});
```

--------------------------------

### surfpool mcp

Source: https://solana.com/docs/tools/surfpool/toolchain/cli

Starts the Surfpool MCP server for AI tool integration.

```APIDOC
## surfpool mcp

### Description
Starts the Surfpool MCP server for AI tool integration.

### Usage
`surfpool mcp`
```

--------------------------------

### Initialize Surfnet

Source: https://solana.com/docs/tools/surfpool/sdk/rust-reference

Constructors for starting a new Surfnet instance or creating a builder.

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

--------------------------------

### Configure SurfnetBuilder

Source: https://solana.com/docs/tools/surfpool/sdk/rust-reference

Setter methods for the builder, which support chaining and conclude with the start() method.

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

--------------------------------

### SurfnetBuilder

Source: https://solana.com/docs/tools/surfpool/sdk/rust-reference

A builder pattern implementation for configuring and starting a Surfnet instance.

```APIDOC
## SurfnetBuilder

### Description
Provides a fluent interface to configure the Surfnet instance before starting it. All setters return `Self` for method chaining.

### Methods
- **offline(bool)**: Sets the offline mode.
- **remote_rpc_url(String)**: Sets the remote RPC URL.
- **block_production_mode(BlockProductionMode)**: Configures block production behavior.
- **slot_time_ms(u64)**: Sets the slot time in milliseconds.
- **airdrop_addresses(Vec<Pubkey>)**: Sets addresses to receive an airdrop.
- **airdrop_sol(u64)**: Sets the amount of SOL to airdrop in lamports.
- **skip_blockhash_check(bool)**: Toggles blockhash verification.
- **payer(Keypair)**: Sets the payer keypair.
- **enable_feature(Pubkey)**: Enables a specific feature by ID.
- **disable_feature(Pubkey)**: Disables a specific feature by ID.
- **feature_config(SvmFeatureConfig)**: Sets the SVM feature configuration.
- **start() -> SurfnetResult<Surfnet>**: Consumes the builder and starts the Surfnet instance.
```

--------------------------------

### Using Cheatcodes for Test Setup

Source: https://solana.com/docs/tools/surfpool/sdk/kit-plugin

Demonstrates pausing the clock, time travel, setting arbitrary account state, and modifying token balances.

```ts
import { address, generateKeyPairSigner } from "@solana/kit";

// Deterministic clock.
const paused = await client.cheatcodes.pauseClock().send();
await client.cheatcodes
  .timeTravel({ absoluteSlot: paused.absoluteSlot + 1_000n })
  .send();
await client.cheatcodes.resumeClock().send();

// Arbitrary account state. `data` is hex-encoded.
const account = (await generateKeyPairSigner()).address;
const owner = (await generateKeyPairSigner()).address;
await client.cheatcodes
  .setAccount(account, { data: "aabbcc", lamports: 777_777, owner })
  .send();

// Token balances, without minting through the token program. The mint must
// already exist — create it, or clone it from mainnet with cloneProgramAccount.
const mint = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
await client.cheatcodes
  .setTokenAccount(owner, mint, { amount: 1_000_000n })
  .send();
```

--------------------------------

### Perform a basic GET request

Source: https://solana.com/docs/tools/surfpool/iac/std/http

Executes a simple GET request to a specified URL and captures the status code.

```hcl
action "example" "std::send_http_request" {
  url = "https://example.com"
}

output "status" {
  value = action.example.status_code
}
// > status: 200
```

--------------------------------

### Start a local Surfnet

Source: https://solana.com/docs/tools/surfpool/toolchain/cli

Initializes a local Surfnet instance. When executed within a Solana program directory, it can automatically generate and run deployment Runbooks.

```sh
surfpool start [OPTIONS]
```

--------------------------------

### HCL configuration for svm::send_token

Source: https://solana.com/docs/tools/surfpool/iac/svm/actions

Example configuration for sending tokens using the svm::send_token action in an HCL-based workflow.

```hcl
action "send_sol" "svm::send_token" {
    description = "Send some tokens"
    amount = 1000000
    signers = [signer.caller]
    recipient = "zbBjhHwuqyKMmz8ber5oUtJJ3ZV4B6ePmANfGyKzVGV"
    token = "3bv3j4GvMPjvvBX9QdoX27pVoWhDSXpwKZipFF1QiVr6"
    fund_recipient = true
}
```

--------------------------------

### Using Cheatcodes Without the Plugin

Source: https://solana.com/docs/tools/surfpool/sdk/kit-plugin

Provides examples for using cheatcodes as a standalone RPC or by adding them to an existing client.

```ts
import {
  createSurfnetCheatcodesRpc,
  surfnetCheatcodes
} from "@solana/surfpool/kit";

// Standalone RPC, no Kit client involved.
const cheatcodes = createSurfnetCheatcodesRpc("http://127.0.0.1:8899");
await cheatcodes.pauseClock().send();

// Add `client.cheatcodes` to a client you already composed.
const client = createClient().use(surfnetCheatcodes());
```

--------------------------------

### Jump to a specific epoch

Source: https://solana.com/docs/tools/surfpool/sdk/time-travel

Use the time_travel_to_epoch method to advance the runtime to the start of a target epoch.

```rust
let info = cheats.time_travel_to_epoch(420)?;
assert_eq!(info.epoch, 420);
```

```typescript
const info = surfnet.timeTravelToEpoch(420);
console.assert(info.epoch === 420);
```

--------------------------------

### Deploy Program from Files

Source: https://solana.com/docs/tools/surfpool/sdk/programs

Use explicit paths to deploy programs from keypair, shared object, and IDL files.

```rust
use surfpool_sdk::cheatcodes::builders::DeployProgram;
use surfpool_sdk::Surfnet;

let cheats = Surfnet::start().await?.cheatcodes();

// Derive the program ID from a keypair file.
let program_id = cheats.deploy(
    DeployProgram::from_keypair_path("fixtures/my_program-keypair.json")?
        .so_path("fixtures/my_program.so")
        .idl_path("fixtures/my_program.idl.json"),
)?;
```

```typescript
const surfnet = Surfnet.start();
const programId = "DemoProgram111111111111111111111111111111111";

surfnet.deploy({
  programId,
  soPath: "fixtures/my_program.so",
  idlPath: "fixtures/my_program.idl.json"
});

surfnet.stop();
```

--------------------------------

### HTTP GET Request with std::send_http_request

Source: https://solana.com/docs/tools/surfpool/iac/std/actions

Performs a GET request to an API endpoint and captures the response body and status code.

```hcl
action "api_call" "std::send_http_request" {
    description = "Fetch data from API"
    url = "https://api.example.com/data"
    method = "GET"
    headers = {
        "Authorization" = "Bearer ${variable.token}"
    }
}

output "response" {
    value = action.api_call.body
}

output "status" {
    value = action.api_call.status_code
}
```

--------------------------------

### Surfnet Static Methods

Source: https://solana.com/docs/tools/surfpool/sdk/js-reference

Methods for initializing the Surfnet instance and generating keypairs.

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

--------------------------------

### deploy_program

Source: https://solana.com/docs/tools/surfpool/iac/svm/actions

Deploys a program directly to the surfnet via account data write.

```APIDOC
## deploy_program

### Description
Deploys a program directly to the surfnet via account data write (not via transactions).

### Parameters
- **program_id** (string) - Required - The public key of the program being deployed
- **binary_path** (string) - Required - The location of the program's .so file
- **authority** (string) - Optional - The public key of the authority over the program after it is deployed
- **idl_path** (string) - Optional - The location of the program's IDL file
```

--------------------------------

### Define SurfnetBuilder struct

Source: https://solana.com/docs/tools/surfpool/sdk/rust-reference

The builder struct used to configure a Surfnet instance before starting.

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

--------------------------------

### Deploy Programs

Source: https://solana.com/docs/tools/surfpool/sdk/rust-reference

Methods for deploying programs to the test environment.

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

--------------------------------

### Compose Surfpool with program plugins

Source: https://solana.com/docs/tools/surfpool/sdk/kit-plugin

Demonstrates chaining the Surfpool plugin with the token program to execute instructions against an embedded Surfnet instance.

```ts
import { createClient, generateKeyPairSigner } from "@solana/kit";
import { tokenProgram } from "@solana-program/token";
import { surfpool } from "@solana/surfpool/kit";

const client = await createClient().use(surfpool()).use(tokenProgram());

const newMint = await generateKeyPairSigner();
await client.token.instructions
  .createMint({ decimals: 6, mintAuthority: client.payer.address, newMint })
  .sendTransaction();

await client.token.instructions
  .mintToATA({
    amount: 1_000_000n,
    decimals: 6,
    mint: newMint.address,
    mintAuthority: client.payer,
    owner: client.payer.address
  })
  .sendTransaction();
```

--------------------------------

### Perform an authenticated GET request

Source: https://solana.com/docs/tools/surfpool/iac/std/http

Includes an Authorization header using a variable for the bearer token.

```hcl
action "api_call" "std::send_http_request" {
    description = "Fetch data from API"
    url = "https://api.example.com/data"
    method = "GET"
    headers = {
        "Authorization" = "Bearer ${variable.token}"
    }
}

output "response" {
    value = action.api_call.response_body
}

output "status" {
    value = action.api_call.status_code
}
```

--------------------------------

### Program Deployment Methods

Source: https://solana.com/docs/tools/surfpool/sdk/js-reference

Methods for deploying programs to the local test environment.

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

--------------------------------

### Surfnet Class Initialization

Source: https://solana.com/docs/tools/surfpool/sdk/js-reference

Methods to initialize the Surfnet instance.

```APIDOC
## Surfnet.start()

### Description
Starts a new Surfnet instance.

## Surfnet.startWithConfig(config: SurfnetConfig)

### Description
Starts a new Surfnet instance with a specific configuration.

## Surfnet.newKeypair()

### Description
Generates a new keypair and returns the KeypairInfo.
```

--------------------------------

### Initialize Surfpool in Embedded Mode

Source: https://solana.com/docs/tools/surfpool/sdk/kit-plugin

Boot an in-process Surfnet by passing the plugin to the Kit client's use method.

```ts
import { createClient } from "@solana/kit";
import { surfpool } from "@solana/surfpool/kit";

const client = await createClient().use(surfpool());
```

--------------------------------

### Configure Surfpool plugin

Source: https://solana.com/docs/tools/surfpool/sdk/kit-plugin

Passes startup options to Surfnet and forwards additional configuration to the local Solana RPC plugin.

```ts
const client = await createClient().use(
  surfpool({
    surfnet: { offline: true }, // Surfnet startup config
    skipPreflight: true // forwarded to solanaLocalRpc()
  })
);
```

--------------------------------

### Writing Structured Accounts with Codecs

Source: https://solana.com/docs/tools/surfpool/sdk/kit-plugin

Shows how to use account encoders to write initialized account data directly to the network.

```ts
import {
  fetchMint,
  getMintEncoder,
  TOKEN_PROGRAM_ADDRESS
} from "@solana-program/token";
import {
  generateKeyPairSigner,
  getBase16Decoder,
  none,
  some
} from "@solana/kit";

const mint = (await generateKeyPairSigner()).address;

const data = getMintEncoder().encode({
  decimals: 6,
  freezeAuthority: none(),
  isInitialized: true,
  mintAuthority: some(client.payer.address),
  supply: 1_000_000_000n
});

await client.cheatcodes
  .setAccount(mint, {
    // getBase16Decoder() turns the encoded bytes into the hex `data` expects.
    data: getBase16Decoder().decode(data),
    lamports: 1_461_600, // rent-exempt minimum for an 82-byte mint
    owner: TOKEN_PROGRAM_ADDRESS
  })
  .send();

// Reads back as a normal mint through the program client.
const account = await fetchMint(client.rpc, mint);
account.data.decimals; // 6
account.data.supply; // 1_000_000_000n
```

--------------------------------

### DeployOptions Interface

Source: https://solana.com/docs/tools/surfpool/sdk/js-reference

Specifies options for deploying programs, requiring a program ID and either a file path or byte array for the program binary.

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

--------------------------------

### encode_base64

Source: https://solana.com/docs/tools/surfpool/iac/std/base64

Encodes a buffer, string, or addon as a base64 string. Strings starting with '0x' are treated as hex, while others are treated as raw UTF-8.

```APIDOC
## encode_base64

### Description
Encodes a buffer or string as a base64 string.

### Inputs
- **value** (buffer, string, addon) - The buffer or string to encode. Strings starting with '0x' are decoded as hex; otherwise, raw UTF-8 bytes are used.

### Output
- **value** (string) - The input, encoded as a base64 string

### Example
```hcl
output "encoded" {
    value = encode_base64("0x48656c6c6f20776f726c6421")
}
// > encoded: SGVsbG8gd29ybGQh
```
```

--------------------------------

### Deploying a program with svm::deploy_program

Source: https://solana.com/docs/tools/surfpool/iac/svm/actions

Deploys a Solana program to an SVM-compatible network using HCL configuration.

```hcl
action "deploy" "svm::deploy_program" {
    description = "Deploy hello world program"
    program = svm::get_program_from_anchor_project("hello_world")
    authority = signer.authority
    payer = signer.payer  # Optional, defaults to authority
}
```

--------------------------------

### Initialize Surfpool with Solana Kit

Source: https://solana.com/docs/tools/surfpool/sdk/kit-plugin

Use the surfpool plugin to automatically configure a Solana Kit client with a local network, pre-funded payer, and cheatcodes.

```ts
import { createClient } from "@solana/kit";
import { surfpool } from "@solana/surfpool/kit";

const client = await createClient().use(surfpool());

const slot = await client.rpc.getSlot().send();
await client.cheatcodes.timeTravel({ absoluteSlot: 1_000_000n }).send();
```

--------------------------------

### DeployProgram Builder

Source: https://solana.com/docs/tools/surfpool/sdk/rust-reference

Use this builder to deploy programs, supporting file paths or raw bytes.

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

--------------------------------

### Program Deployment

Source: https://solana.com/docs/tools/surfpool/sdk/js-reference

Methods for deploying programs to the local environment.

```APIDOC
## deployProgram(programName: string)

### Description
Deploys a program by name and returns the program ID.

## deploy(options: DeployOptions)

### Description
Deploys a program using provided options and returns the program ID.
```

--------------------------------

### Deploy Program from Raw Bytes

Source: https://solana.com/docs/tools/surfpool/sdk/programs

Deploy programs directly from memory buffers, bypassing the file system.

```rust
use surfpool_sdk::cheatcodes::builders::DeployProgram;
use surfpool_sdk::{Pubkey, Surfnet};

const PROGRAM_BYTES: &[u8] = include_bytes!("../fixtures/my_program.so");

let cheats = Surfnet::start().await?.cheatcodes();
let program_id: Pubkey = "DemoProgram111111111111111111111111111111111".parse()?;

cheats.deploy(
    DeployProgram::new(program_id).so_bytes(PROGRAM_BYTES.to_vec()),
)?;
```

```typescript
import { readFileSync } from "node:fs";

const surfnet = Surfnet.start();
const programBytes = readFileSync("fixtures/my_program.so");

surfnet.deploy({
  programId: "DemoProgramID11111111111111111111111111111",
  soBytes: programBytes
});

surfnet.stop();
```

--------------------------------

### Enable state management in txtx.yml

Source: https://solana.com/docs/tools/surfpool/iac/language

Configure the state location to allow Surfpool to track changes and prevent redundant runbook executions.

```yaml
runbooks:
  - name: Deploy Protocol
    location: ./deployment
    state:
      location: states
```

--------------------------------

### Add Rust dev-dependencies

Source: https://solana.com/docs/tools/surfpool/sdk/installation

Include the SDK and a Tokio runtime in your Cargo.toml file for testing.

```toml
[dev-dependencies]
surfpool-sdk = "1"
tokio = { version = "1", features = ["full"] }
```

--------------------------------

### Configure Surfnet with custom settings

Source: https://solana.com/docs/tools/surfpool/sdk/configuration

Use the builder pattern in Rust or the configuration object in TypeScript to define remote RPC URLs, block production modes, slot timing, and airdrop parameters.

```rust
use surfpool_sdk::{BlockProductionMode, Pubkey, Surfnet};

#[tokio::test]
async fn starts_with_custom_configuration() {
    let alice = Pubkey::new_unique();

    let surfnet = Surfnet::builder()
        .remote_rpc_url("https://api.mainnet-beta.solana.com")
        .block_production_mode(BlockProductionMode::Transaction)
        .slot_time_ms(10)
        .airdrop_addresses(vec![alice])
        .airdrop_sol(5_000_000_000)
        .skip_blockhash_check(true)
        .start()
        .await
        .unwrap();

    assert_eq!(
        surfnet.rpc_client().get_balance(&alice).unwrap(),
        5_000_000_000
    );
}
```

```typescript
import { Surfnet } from "@solana/surfpool";

const alice = Surfnet.newKeypair();

const surfnet = Surfnet.startWithConfig({
  remoteRpcUrl: "https://api.mainnet-beta.solana.com",
  blockProductionMode: "transaction",
  slotTimeMs: 10,
  airdropAddresses: [alice.publicKey],
  airdropSol: 5_000_000_000
});

try {
  console.log(surfnet.rpcUrl);
} finally {
  surfnet.stop();
}
```

--------------------------------

### svm::deploy_program

Source: https://solana.com/docs/tools/surfpool/iac/svm/actions

Deploys a Solana program to the specified SVM-compatible network.

```APIDOC
## svm::deploy_program

### Description
Deploys a Solana program to the specified SVM-compatible network.

### Parameters
- **description** (string) - Optional - A description of the deployment action
- **program** (object) - Required - The Solana program artifacts to deploy
- **payer** (string) - Optional - A reference to a signer for paying deployment costs
- **authority** (string) - Required - A reference to a signer for the program authority
- **commitment_level** (string) - Optional - The commitment level ('processed', 'confirmed', 'finalized')
- **auto_extend** (bool) - Optional - Whether to auto extend the program account (default: true)

### Outputs
- **signatures** (object) - The computed transaction signatures
- **program_id** (string) - The program ID of the deployed program
- **program_idl** (string) - The program IDL
```

--------------------------------

### Program Deployment

Source: https://solana.com/docs/tools/surfpool/sdk/rust-reference

Methods for deploying programs to the test environment.

```APIDOC
## deploy_program

### Description
Deploys a program by name.

### Signature
`pub fn deploy_program(&self, program_name: &str) -> SurfnetResult<Pubkey>`

## deploy

### Description
Deploys a program using a configuration builder.

### Signature
`pub fn deploy(&self, builder: DeployProgram) -> SurfnetResult<Pubkey>`
```

--------------------------------

### svm::create_token_account_instruction

Source: https://solana.com/docs/tools/surfpool/iac/svm/functions

Creates raw instruction bytes to create an associated token account.

```APIDOC
## svm::create_token_account_instruction

### Description
Creates raw instruction bytes to create an associated token account.

### Parameters
- **funding_address** (string) - Required - The address of the funding account
- **wallet_address** (string) - Required - The address of the wallet
- **token_mint_address** (string) - Optional - The address of the token mint
- **token_program_id** (string) - Optional - The address of the token program

### Example
```hcl
action "call" "svm::process_instructions" {
    signers = [signer.caller]

    instruction {
        raw_bytes = svm::create_token_account_instruction(
            signer.caller.address, // funding address
            signer.caller.address, // wallet address
            variable.token_mint, // token mint address
            variable.token_program // token program id
        )
    }
}
```
```

--------------------------------

### List Runbooks

Source: https://solana.com/docs/tools/surfpool/toolchain/cli

Displays all Runbooks defined in the workspace manifest.

```sh
surfpool ls [OPTIONS]
```

--------------------------------

### Define environment variables in txtx.yml

Source: https://solana.com/docs/tools/surfpool/iac/language

Use the environments key to define network-specific configurations that are accessible as global inputs within runbooks.

```yaml
---
name: protocol-deployment
runbooks:
  - name: Deploy Protocol
    description: This runbook deploys the protocol.
    location: ./deployment
environments:
  development:
    network_id: localnet
    rpc_api_url: http://localhost:8899
  devnet:
    network_id: devnet
    rpc_api_url: https://api.devnet.solana.com
  mainnet:
    network_id: mainnet
    rpc_api_url: https://api.mainnet-beta.solana.com
```

--------------------------------

### Test Lockup or Vesting Window with TypeScript

Source: https://solana.com/docs/tools/surfpool/sdk/time-travel

Demonstrates using Surfnet to simulate time progression for verifying account withdrawal behavior before and after a specific slot.

```ts
import { Surfnet } from "@solana/surfpool";

const surfnet = Surfnet.start();
const beneficiary = Surfnet.newKeypair();

// 1. Set up a vesting account that unlocks at slot 1,000,000.
surfnet.setAccount(/* ...lockup program state... */);

// 2. Verify withdrawal fails before unlock.
await assertWithdrawFails(surfnet.rpcUrl, beneficiary);

// 3. Travel past the unlock slot.
surfnet.timeTravelToSlot(1_000_001);

// 4. Verify withdrawal succeeds.
await assertWithdrawSucceeds(surfnet.rpcUrl, beneficiary);

surfnet.stop();
```

--------------------------------

### Navigate to Surfpool directory

Source: https://solana.com/docs/tools/surfpool/toolchain/getting-started

Changes the current working directory to the cloned repository.

```bash
cd surfpool
```

--------------------------------

### surfpool ls

Source: https://solana.com/docs/tools/surfpool/toolchain/cli

Lists all Runbooks declared in the workspace manifest.

```APIDOC
## surfpool ls

### Description
Lists all Runbooks declared in the workspace manifest.

### Usage
`surfpool ls [OPTIONS]`

### Options
- **--manifest-file-path** (path) - Optional - Path to the runbook manifest. Default: `./txtx.yml`
- **-m** (path) - Optional - Short alias for --manifest-file-path.
```

--------------------------------

### Deploy an Anchor workspace program

Source: https://solana.com/docs/tools/surfpool/sdk/programs

Uses auto-discovery to locate program artifacts in standard Anchor/Agave paths. Ensure the program is built before execution.

```rust
use surfpool_sdk::Surfnet;

let surfnet = Surfnet::start().await?;
let cheats = surfnet.cheatcodes();

let program_id = cheats.deploy_program("my_program")?;
println!("deployed at {program_id}");
```

```typescript
import { Surfnet } from "@solana/surfpool";

const surfnet = Surfnet.start();
try {
  const programId = surfnet.deployProgram("my_program");
  console.log("deployed at", programId);
} finally {
  surfnet.stop();
}
```

--------------------------------

### Create Token Account Instruction

Source: https://solana.com/docs/tools/surfpool/iac/svm/functions

Generates raw instruction bytes required to create an associated token account, typically used within a process_instructions action.

```hcl
action "call" "svm::process_instructions" {
    signers = [signer.caller]

    instruction {
        raw_bytes = svm::create_token_account_instruction(
            signer.caller.address, // funding address
            signer.caller.address, // wallet address
            variable.token_mint, // token mint address
            variable.token_program // token program id
        )
    }
}
```

--------------------------------

### Define a Program Deployment Action

Source: https://solana.com/docs/tools/surfpool/iac/language

Executes a program deployment using the svm::deploy_program action, referencing specific signers for authority and payment.

```hcl
action "deploy_hello_world" "svm::deploy_program" {
    description = "Deploy the hello_world program"
    program = svm::get_program_from_anchor_project("hello_world")
    authority = signer.authority
    payer = signer.payer
}
output "signature" {
  value = action.deploy_hello_world.signature
}
```

--------------------------------

### DeployProgram (Rust)

Source: https://solana.com/docs/tools/surfpool/sdk/programs

The DeployProgram builder allows for configuring program deployment parameters in Rust.

```APIDOC
## DeployProgram::new

### Signature
`(program_id: Pubkey) -> Self`

### Purpose
Build a deployment for a known program ID.

## DeployProgram::from_keypair_path

### Signature
`(path: impl AsRef<Path>) -> SurfnetResult<Self>`

### Purpose
Read a Solana keypair file; the public key becomes the program ID.

## .so_path

### Signature
`(path: impl Into<PathBuf>)`

### Purpose
Path to the compiled .so artifact on disk.

## .so_bytes

### Signature
`(bytes: Vec<u8>)`

### Purpose
Raw program bytes (mutually exclusive with so_path).

## .idl_path

### Signature
`(path: impl Into<PathBuf>)`

### Purpose
Optional Anchor IDL JSON to register after deployment.
```

--------------------------------

### Import Surfpool Types and Classes

Source: https://solana.com/docs/tools/surfpool/sdk/installation

Import the Surfnet class and supporting types from the @solana/surfpool package.

```ts
import {
  Surfnet, // entry point
  type SurfnetConfig, // config for startWithConfig
  type DeployOptions, // explicit program deploy
  type SetTokenAccountUpdate,
  type ResetAccountOptions,
  type StreamAccountOptions,
  type SimnetEventValue, // event drained from drainEvents()
  type KeypairInfo, // shape returned by Surfnet.newKeypair()
  type EpochInfoValue,
  type ClockValue
} from "@solana/surfpool";
```

--------------------------------

### Execute Runbooks with surfpool run

Source: https://solana.com/docs/tools/surfpool/toolchain/cli

Commands to execute runbooks defined in manifests or directly from .tx files.

```sh
surfpool run [OPTIONS] <RUNBOOK>
```

```sh
surfpool run deployment
```

```sh
surfpool run deployment --unsupervised --output-json .surfpool/runbook-outputs
```

```sh
surfpool run ./runbooks/deployment.tx
```

--------------------------------

### DeployOptions (JS)

Source: https://solana.com/docs/tools/surfpool/sdk/programs

The DeployOptions interface defines the configuration required for program deployment in JavaScript.

```APIDOC
## DeployOptions

### Properties
- **programId** (string) - Base58 address to deploy at
- **soPath** (string, optional) - Path to .so on disk
- **soBytes** (ByteArrayLike, optional) - Raw bytes in memory
- **idlPath** (string, optional) - Optional Anchor IDL JSON

### Note
soPath and soBytes are mutually exclusive — provide exactly one.
```

--------------------------------

### svm::process_instructions

Source: https://solana.com/docs/tools/surfpool/iac/svm/actions

Encodes instructions, adds them to a transaction, signs, and broadcasts the transaction.

```APIDOC
## svm::process_instructions

### Description
Encodes instructions, adds them to a transaction, and signs & broadcasts the transaction.

### Parameters
- **description** (string) - Optional - A description of the transaction
- **instruction** (map) - Required - The instructions to add to the transaction
- **signers** (array[string]) - Required - References to signer constructs
- **commitment_level** (string) - Optional - The commitment level
- **rpc_api_url** (string) - Required - The URL for API requests

### Outputs
- **signature** (string) - The transaction computed signature
```

--------------------------------

### surfpool completions

Source: https://solana.com/docs/tools/surfpool/toolchain/cli

Generates shell completion scripts for the CLI.

```APIDOC
## surfpool completions

### Description
Generates shell completion scripts.

### Usage
`surfpool completions <SHELL>`

### Arguments
- **SHELL** (enum) - Required - Shell to generate completions for. Supported values: `bash`, `elvish`, `fish`, `powershell`, `zsh`.
```

--------------------------------

### surfpool run

Source: https://solana.com/docs/tools/surfpool/toolchain/cli

Executes a Runbook, either by referencing a Runbook ID from a txtx.yml manifest or by providing a path to a .tx file.

```APIDOC
## surfpool run

### Description
Executes a Runbook. You can run a .tx file directly or reference a Runbook declared in a txtx.yml manifest.

### Usage
surfpool run [OPTIONS] <RUNBOOK>

### Arguments
- **RUNBOOK** (string) - Required - Runbook ID from txtx.yml, or path to a .tx file.

### Project Flags
- **--manifest-file-path** (path) - Optional - Path to the runbook manifest (default: ./txtx.yml).
- **--env** (string) - Optional - Environment from txtx.yml to use.

### Execution Mode Flags
- **--unsupervised** (boolean) - Optional - Execute without the supervisor UI.
- **--browser** (boolean) - Optional - Execute with supervision in the browser UI.
- **--terminal** (boolean) - Optional - Execute with supervision in the terminal console.

### Inputs & Outputs Flags
- **--output-json** (optional path) - Optional - Print or write Runbook outputs as JSON.
- **--output** (string) - Optional - Print one named output at the end of execution.
- **--input** (path[]) - Optional - Input file to use for batch processing.

### Execution Flags
- **--explain** (boolean) - Optional - Explain how the Runbook will execute.
- **--force** (boolean) - Optional - Ignore cached execution state.

### Supervisor UI Flags
- **--port** (integer) - Optional - Web UI port (default: 8488).
- **--ip** (string) - Optional - Web UI IP address (default: 127.0.0.1).

### Logging Flags
- **--log-level** (enum) - Optional - Runbook execution log level (trace, debug, info, warn, error).
- **--log-path** (path) - Optional - Directory for runbook execution logs (default: .surfpool/logs).
```

--------------------------------

### DeployProgram Builder

Source: https://solana.com/docs/tools/surfpool/sdk/rust-reference

The DeployProgram builder is used to deploy programs to the test environment.

```APIDOC
## DeployProgram

### Description
Constructs a cheatcode to deploy a program.

### Methods
- `new(program_id: Pubkey)`: Initializes the builder.
- `from_keypair_path(path: impl AsRef<Path>)`: Loads program from a keypair path.
- `so_path(path: impl Into<PathBuf>)`: Sets the path to the .so file.
- `so_bytes(bytes: Vec<u8>)`: Sets the .so file bytes directly.
- `idl_path(path: impl Into<PathBuf>)`: Sets the path to the IDL file.
```

--------------------------------

### DeployOptions TypeScript Interface

Source: https://solana.com/docs/tools/surfpool/sdk/programs

Defines the configuration object for program deployment in TypeScript. Ensure either soPath or soBytes is provided, as they are mutually exclusive.

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

interface DeployOptions {
  programId: string; // base58 address to deploy at
  soPath?: string; // path to .so on disk
  soBytes?: ByteArrayLike; // or raw bytes in memory
  idlPath?: string; // optional Anchor IDL JSON
}
```

--------------------------------

### Retrieve native program artifacts

Source: https://solana.com/docs/tools/surfpool/iac/svm/functions

Use this function to fetch deployment artifacts for non-Anchor programs by specifying the program name and optional paths.

```hcl
variable "contract" {
    value = svm::get_program_from_native_project("my_program")
}
output "idl" {
    value = variable.contract.idl
}
```

--------------------------------

### svm::get_program_from_native_project

Source: https://solana.com/docs/tools/surfpool/iac/svm/functions

Retrieves the program deployment artifacts for a non-Anchor program.

```APIDOC
## svm::get_program_from_native_project

### Description
Retrieves the program deployment artifacts for a non-Anchor program.

### Parameters
- **program_name** (string) - Required - The name of the program being deployed
- **keypair_path** (string) - Optional - The location of the program keypair file
- **idl_path** (string) - Optional - The location of the program IDL file
- **bin_path** (string) - Optional - The location of the program binary file
```

--------------------------------

### Invoke instructions with svm::process_instructions

Source: https://solana.com/docs/tools/surfpool/iac/svm/actions

Encodes instructions, adds them to a transaction, and signs & broadcasts the transaction.

```hcl
action "program_call" "svm::process_instructions" {
    description = "Invoke instructions"
    instruction {
        program_idl = variable.program.idl
        instruction_name = "initialize"
        instruction_args = [1]
        payer {
            public_key = signer.payer.public_key
        }
    }
    signers = [signer.caller]
}
```

--------------------------------

### Clone Surfpool repository

Source: https://solana.com/docs/tools/surfpool/toolchain/getting-started

Downloads the source code from the official GitHub repository.

```bash
git clone https://github.com/solana-foundation/surfpool.git
```

--------------------------------

### Fund SOL with Surfnet

Source: https://solana.com/docs/tools/surfpool/sdk/cheatcodes

Sets the lamport balance on any account, creating it if it does not exist. Supports funding multiple accounts in a single call.

```rust
use surfpool_sdk::{Pubkey, Surfnet};

let surfnet = Surfnet::start().await?;
let cheats = surfnet.cheatcodes();
let wallet = Pubkey::new_unique();

cheats.fund_sol(&wallet, 1_000_000_000)?;

// Fund several accounts in one call.
let bob = Pubkey::new_unique();
let carol = Pubkey::new_unique();
cheats.fund_sol_many(&[(&bob, 2_000_000_000), (&carol, 3_000_000_000)])?;
```

```typescript
import { Surfnet } from "@solana/surfpool";

const surfnet = Surfnet.start();
const wallet = Surfnet.newKeypair();

surfnet.fundSol(wallet.publicKey, 1_000_000_000);

const bob = Surfnet.newKeypair();
const carol = Surfnet.newKeypair();
surfnet.fundSolMany([
  { address: bob.publicKey, lamports: 2_000_000_000 },
  { address: carol.publicKey, lamports: 3_000_000_000 }
]);
```

--------------------------------

### Configure svm::web_wallet signer

Source: https://solana.com/docs/tools/surfpool/iac/svm/signers

Enables Runbook operators to sign transactions using a browser-based wallet.

```hcl
signer "alice" "svm::web_wallet" {
    expected_address = "zbBjhHwuqyKMmz8ber5oUtJJ3ZV4B6ePmANfGyKzVGV"
}
```

--------------------------------

### HTTP POST Request with std::send_http_request

Source: https://solana.com/docs/tools/surfpool/iac/std/actions

Performs a POST request to create a resource, including a JSON-formatted body.

```hcl
action "create_resource" "std::send_http_request" {
    description = "Create a new resource"
    url = "https://api.example.com/resources"
    method = "POST"
    headers = {
        "Content-Type" = "application/json"
    }
    body = {
        "name" = variable.name,
        "value" = variable.value
    }
}
```

--------------------------------

### Configure Surfpool in Attach Mode

Source: https://solana.com/docs/tools/surfpool/sdk/kit-plugin

Connects the client to an existing Surfpool instance by providing an rpcUrl. Ensure the client has a payer configured as this mode does not provide one automatically.

```ts
import { createKeyPairSignerFromBytes, createClient } from "@solana/kit";
import { payer } from "@solana/kit-plugin-signer";
import { surfpool } from "@solana/surfpool/kit";
import { readFile } from "node:fs/promises";

// Any funded signer works; this loads the local CLI keypair.
const keypairPath = `${process.env.HOME}/.config/solana/id.json`;
const myPayer = await createKeyPairSignerFromBytes(
  new Uint8Array(JSON.parse(await readFile(keypairPath, "utf8")))
);

const client = createClient()
  .use(payer(myPayer))
  .use(surfpool({ rpcUrl: "http://127.0.0.1:8899" }));
```

--------------------------------

### set_account

Source: https://solana.com/docs/tools/surfpool/iac/svm/actions

Sets account data directly on the surfnet. At least one field (lamports, data, owner, executable, or rent_epoch) must be provided unless account_path is used.

```APIDOC
## set_account

### Description
Sets account data directly on the surfnet.

### Parameters
#### Request Body
- **public_key** (string) - Required - The public key of the account to set
- **account_path** (string) - Optional - The path to a JSON file containing the account data to set. If provided, other fields are ignored
- **lamports** (integer) - Optional - The amount of lamports the account should be set to have
- **data** (bytes) - Optional - The data to set in the account
- **owner** (string) - Optional - The owner to set for the account
- **executable** (bool) - Optional - The executability state to set for the account
- **rent_epoch** (integer) - Optional - The epoch at which the account will be rent-exempt
```

--------------------------------

### Configure svm::secret_key signer

Source: https://solana.com/docs/tools/surfpool/iac/svm/signers

Use these configurations to sign transactions via secret key, mnemonic, or keypair file.

```hcl
signer "deployer" "svm::secret_key" {
    secret_key = input.secret_key
}
```

```hcl
signer "deployer" "svm::secret_key" {
    mnemonic = input.mnemonic
    derivation_path = "m/44'/501'/0'/0'"
}
```

```hcl
signer "deployer" "svm::secret_key" {
    keypair_json = "~/.config/solana/id.json"
}
```

--------------------------------

### Retrieve program artifacts with svm::get_program_from_anchor_project

Source: https://solana.com/docs/tools/surfpool/iac/svm/functions

Fetches deployment artifacts for a specified program within an Anchor project structure.

```hcl
variable "contract" {
    value = svm::get_program_from_anchor_project("my_program")
}
output "idl" {
    value = variable.contract.idl
}
```

--------------------------------

### add

Source: https://solana.com/docs/tools/surfpool/iac/std/operators

Returns the sum of two integer arguments.

```APIDOC
## add

### Description
Returns the sum of the left-hand-side integer argument and the right-hand-side integer argument.

### Inputs
- **lhs** (integer) - The first operand
- **rhs** (integer) - The second operand

### Output
- **value** (integer) - The result of the addition operation
```