Surfpool

https://docs.surfpool.run
Admin
Surfpool is a drop-in replacement for solana-test-validator that lets developers locally simulate...
Tokens:53,859
Snippets:361
Trust Score:6.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Surfpool Start Examples

Source: https://docs.surfpool.run/toolchain/cli

Common usage patterns for starting a local network with various configurations.

```bash
surfpool start
```

```bash
surfpool start --network mainnet --slot-time 200
```

```bash
surfpool start --ci
```

```bash
surfpool start -a MyPubkey123 --watch
```

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

### Admin - Start Time

Source: https://docs.surfpool.run/rpc/admin

Returns the system start time.

```APIDOC
## POST /rpc

### Description
Returns the system start time.

### Method
POST

### Endpoint
/rpc

### Request Body
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "startTime",
  "params": []
}
```

### Response
#### Success Response (200)
- **nanos** (integer) - Nanoseconds
- **secsSinceEpoch** (integer) - Seconds since Unix epoch
```

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

### Get System Start Time

Source: https://docs.surfpool.run/rpc/admin

Returns the system start time in nanoseconds and seconds since the Unix epoch.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "startTime",
  "params": []
}
```

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

### Start Surfpool MCP Server

Source: https://docs.surfpool.run/toolchain/cli

Start an MCP (Model Context Protocol) server for AI tool integration.

```bash
surfpool mcp
```

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

### Install Surfpool CLI

Source: https://docs.surfpool.run/llms.txt

Installs the Surfpool CLI using a curl script. This is the first step to setting up the local Solana node.

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

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

### Start a Surfpool Cloud Surfnet Instance

Source: https://docs.surfpool.run/toolchain/cli

Start a new Cloud Surfnet instance with specified options for workspace, name, description, RPC URL, block production mode, and transaction profiling.

```bash
surfpool cloud start [OPTIONS]
```

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

### Start a Surfnet

Source: https://docs.surfpool.run/toolchain/cli

Basic command to initialize a local simulation network.

```bash
surfpool start [OPTIONS]
```

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

### surfpool start

Source: https://docs.surfpool.run/toolchain/cli

Starts a local Surfnet (Solana simulation network). If run in a Solana program directory, Surfpool automatically generates Runbooks to deploy your programs.

```APIDOC
## surfpool start

### Description
Starts a local Surfnet. If run in a Solana program directory, Surfpool automatically generates Runbooks to deploy your programs.

### Method
CLI Command

### Endpoint
surfpool start [OPTIONS]

### Parameters
#### Network Options
- **--port** (`-p`) (number) - Simnet RPC port. Default: `8899`
- **--ws-port** (`-w`) (number) - Simnet WebSocket port. Default: `8900`
- **--host** (`-o`) (string) - Simnet host address. Default: `127.0.0.1`
- **--slot-time** (`-t`) (number) - Slot time in milliseconds. Default: `400`
- **--block-production-mode** (`-b`) (string) - Block production mode: `clock`, `transaction`, or `manual`. Default: `clock`
- **--rpc-url** (`-u`) (string) - Datasource RPC URL (conflicts with `--network`)
- **--network** (`-n`) (string) - Predefined network: `mainnet`, `devnet`, or `testnet` (conflicts with `--rpc-url`)
- **--offline** (boolean) - Start without remote RPC client. Default: `false`

#### Deployment Options
- **--manifest-file-path** (`-m`) (string) - Path to the manifest. Default: `./txtx.yml`
- **--no-deploy** (boolean) - Disable auto deployments. Default: `false`
- **--runbook** (`-r`) (string) - Runbook IDs to execute (repeatable). Default: `deployment`
- **--runbook-input** (`-i`) (string) - Inputs for runbooks (repeatable)
- **--yes** (`-y`) (boolean) - Skip prompts, assume "yes" for all. Default: `false`
- **--watch** (boolean) - Watch `target/deploy` and re-deploy when `.so` files change. Default: `false`
- **--snapshot** (string) - Path to JSON snapshot file(s) to preload accounts (repeatable)

#### Airdrop Options
- **--airdrop** (`-a`) (string) - Pubkeys to airdrop tokens to (repeatable)
- **--airdrop-amount** (`-q`) (number) - Amount of lamports to airdrop. Default: `10000000000000`
- **--airdrop-keypair-path** (`-k`) (string) - Keypair paths to airdrop (repeatable). Default: `~/.config/solana/id.json`

#### UI Options
- **--no-tui** (boolean) - Display logs instead of terminal UI dashboard. Default: `false`
- **--no-studio** (boolean) - Disable Studio. Default: `false`
- **--studio-port** (`-s`) (number) - Studio port. Default: `18488`

#### Logging & Profiling
- **--log-level** (`-l`) (string) - Log level: `trace`, `debug`, `info`, `warn`, `error`, `none`. Default: `info`
- **--log-path** (string) - Directory for simnet logs. Default: `.surfpool/logs`
- **--disable-instruction-profiling** (boolean) - Disable instruction profiling. Default: `false`
- **--max-profiles** (`-c`) (number) - Max transaction profiles held in memory. Default: `200`
- **--log-bytes-limit** (number) - Max bytes allowed in transaction logs (0 = unlimited)

#### Database Options
- **--db** (string) - Surfnet database URL for persistence (`:memory:`, `.sqlite` file, or postgres URL)
- **--surfnet-id** (string) - Unique ID for this surfnet instance (isolates database storage). Default: `default`

#### Plugin & Feature Options
- **--geyser-plugin-config** (`-g`) (string) - Geyser plugin config JSON files to load (repeatable)
- **--feature** (`-f`) (string) - Enable specific SVM features (repeatable)
- **--disable-feature** (string) - Disable specific SVM features (repeatable)
- **--features-all** (boolean) - Enable all SVM features (overrides mainnet defaults). Default: `false`

#### Compatibility & CI
- **--ci** (boolean) - CI mode: disables profiling, studio, tui; sets log level to none. Default: `false`
- **--daemon** (boolean) - Start as background process (Linux only). Default: `false`
- **--legacy-anchor-compatibility** (boolean) - Apply defaults for Anchor test suite compatibility. Default: `false`
- **--anchor-test-config-path** (string) - Path to `Test.toml` test suite files (repeatable)

### Request Example
```
surfpool start
```

### Response
(No specific response details provided for this command.)
```

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

### Start Surfnet Instance

Source: https://docs.surfpool.run/rpc/overview

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

```bash
surfpool start
```

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

### Start Surfpool Local Network

Source: https://docs.surfpool.run/llms.txt

Starts the Surfpool local network with a TUI dashboard. This command initiates the local Solana node for development and testing.

```bash
surfpool
```

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

### txtx Manifest Configuration with Environments

Source: https://docs.surfpool.run/iac/language

Example of a `txtx.yml` manifest file defining environments and their associated network configurations. This allows for easy management of different deployment settings.

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

```

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

### getBlocks

Source: https://docs.surfpool.run/rpc/network

Fetches a range of blocks based on start and end slots, with optional configuration.

```APIDOC
## GET /getBlocks

### Description
Returns the blocks for a given range of slots.

### Method
GET

### Endpoint
/getBlocks

### Parameters
#### Query Parameters
- **startSlot** (integer) - Required - The starting slot to query for blocks.
- **wrapper** (string) - Optional - Wrapper for end slot or context configuration.
- **config** (object) - Optional - Configuration object for the query.
  - **commitment** (string | string | string) - Optional - The commitment describes how finalized a block is at that point in time. Options are 'processed', 'confirmed', or 'finalized'.
  - **minContextSlot** (integer) - Optional - The minimum context slot for the context.

### Response
#### Success Response (200)
- **result** (array<integer>) - getBlocks - Returns blocks for a range of slots

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBlocks",
  "params": [
    123456789,
    0,
    {
      "commitment": "Processed",
      "minContextSlot": 123456789
    }
  ]
}
```

### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    123456789,
    123456790,
    123456791
  ]
}
```
```

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

### Run a Surfpool Runbook (Supervised Mode)

Source: https://docs.surfpool.run/toolchain/cli

Execute a runbook in supervised mode, which starts a web server for manual interaction with execution steps. Use this for validation and runtime data input.

```bash
surfpool run my-runbook
```

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

### Configure svm::secret_key signer

Source: https://docs.surfpool.run/iac/svm/signers

Examples for configuring the secret_key signer using different authentication methods.

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

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

### Get Epoch Schedule

Source: https://docs.surfpool.run/rpc/network

Retrieves the current epoch schedule configuration.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getEpochSchedule",
  "params": []
}
```

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

### Get Inflation Governor Settings

Source: https://docs.surfpool.run/rpc/network

Retrieves the current inflation governor configuration settings.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getInflationGovernor",
  "params": [
    {
      "commitment": "Processed"
    }
  ]
}
```

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

### Get Balance

Source: https://docs.surfpool.run/rpc/accounts

Fetch the balance for a given public key. Configuration options include commitment level and minimum context slot.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBalance",
  "params": [
    "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri",
    {
      "commitment": "Processed",
      "minContextSlot": 123456789
    }
  ]
}
```

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

### Get Epoch Information

Source: https://docs.surfpool.run/rpc/network

Returns current epoch details including slot index and transaction counts.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getEpochInfo",
  "params": [
    {
      "commitment": "Processed",
      "minContextSlot": 123456789
    }
  ]
}
```

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

### Get Recent Performance Samples

Source: https://docs.surfpool.run/rpc/network

Retrieves recent performance samples for the network. Accepts an optional limit for the number of samples to return.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getRecentPerformanceSamples",
  "params": [
    0
  ]
}
```

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

### Get Account Info

Source: https://docs.surfpool.run/rpc/accounts

Retrieve detailed information about a specific account using its public key. Supports configuration for commitment level, data slicing, and encoding.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getAccountInfo",
  "params": [
    "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri",
    {
      "commitment": "Processed",
      "dataSlice": {
        "length": 0,
        "offset": 0
      },
      "encoding": "binary",
      "minContextSlot": 123456789
    }
  ]
}
```

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

### Get Multiple Accounts Info

Source: https://docs.surfpool.run/rpc/accounts

Efficiently retrieve information for multiple accounts in a single API call. Accepts an array of public keys and configuration options.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getMultipleAccounts",
  "params": [
    [
      "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri"
    ],
    {
      "commitment": "Processed",
      "dataSlice": {
        "length": 0,
        "offset": 0
      },
      "encoding": "binary",
      "minContextSlot": 123456789
    }
  ]
}
```

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

### Build Surfpool from Source

Source: https://docs.surfpool.run/toolchain/getting-started

Clones the repository, navigates to the directory, and compiles the binary using Cargo.

```bash
git clone https://github.com/txtx/surfpool.git
```

```bash
cd surfpool
```

```bash
cargo surfpool-install
```

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

### Get Active IDL for a Program

Source: https://docs.surfpool.run/rpc/cheatcodes

Use this method to retrieve the Interface Description Language (IDL) for a specific program ID at a given slot. If the slot is omitted, the latest available IDL will be returned.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "surfnet_getActiveIdl",
  "params": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    123456789
  ]
}
```

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

### Get Cluster Nodes RPC

Source: https://docs.surfpool.run/rpc/node

Returns information about the cluster nodes. Use this to get details about each node's connectivity and features.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getClusterNodes",
  "params": []
}
```

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

### Send HTTP GET Request

Source: https://docs.surfpool.run/iac/std/actions

Use this action to fetch data from a specified URL using the GET method. It includes optional headers for authentication or other purposes. The response body and status code can be accessed as outputs.

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

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

### Get Genesis Hash

Source: https://docs.surfpool.run/rpc/network

Retrieves the genesis hash of the cluster.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getGenesisHash",
  "params": []
}
```

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

### deploy_program

Source: https://docs.surfpool.run/iac/svm/actions

Deploys a program directly to the surfnet.

```APIDOC
## deploy_program

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

### Parameters
#### Request Body
- **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
```

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

### Get Block Height

Source: https://docs.surfpool.run/rpc/network

Returns the current block height of the network.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBlockHeight",
  "params": [
    {
      "commitment": "Processed",
      "minContextSlot": 123456789
    }
  ]
}
```

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

### Get Slot Leaders

Source: https://docs.surfpool.run/rpc/network

Retrieves the leaders for a specified range of slots.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getSlotLeaders",
  "params": [
    123456789,
    0
  ]
}
```

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

### Process Solana Instructions

Source: https://docs.surfpool.run/iac/svm/actions

Use `svm::process_instructions` to encode, sign, and broadcast instructions. Requires program IDL, instruction details, signers, and RPC URL.

```action
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]
}
```

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

### Execute a Runbook

Source: https://docs.surfpool.run/toolchain/cli

Command to run a specific deployment runbook or .tx file.

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

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

### Get Slot Leader

Source: https://docs.surfpool.run/rpc/network

Retrieves the identity of the leader for the current slot.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getSlotLeader",
  "params": [
    {
      "commitment": "Processed",
      "minContextSlot": 123456789
    }
  ]
}
```

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

### Create Token Account Instruction

Source: https://docs.surfpool.run/iac/svm/functions

Generates raw instruction bytes to create an associated token account.

```APIDOC
## create_token_account_instruction

### Description
`svm::create_token_account_instruction` creates raw instruction bytes to create an associated token account.

### Inputs
Name| Required| Type| Description
---|---|---|---
`funding_address`| required| string| The address of the funding account
`wallet_address`| required| string| The address of the wallet
`token_mint_address`| optional| string| The address of the token mint
`token_program_id`| optional| string| The address of the token program

### Request Example
```
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
        )
    }
}
```
```

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

### Configure SVM Surfnet Environment

Source: https://docs.surfpool.run/iac/svm/actions

Defines the setup_surfnet action to initialize accounts, tokens, and program states within the SVM environment.

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

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

### Get Highest Snapshot Slot

Source: https://docs.surfpool.run/rpc/network

Returns the highest full and incremental snapshot slots.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getHighestSnapshotSlot",
  "params": []
}
```

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

### Get Current Slot

Source: https://docs.surfpool.run/rpc/network

Returns the current slot number with optional commitment configuration.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getSlot",
  "params": [
    {
      "commitment": "Processed",
      "minContextSlot": 123456789
    }
  ]
}
```

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

### Basic txtx DSL Structure

Source: https://docs.surfpool.run/iac/language

Illustrates the fundamental structure of a txtx Runbook file, including variable, action, and output blocks. Use this as a template for defining deployment resources and their interactions.

```txtx
variable "query_path" {
  description = "An input that can be edited in the web UI!"
  value = "details"
  editable = true
}

action "http_query" "std::send_http_request" {
  description = "This action will make a GET request to the specified URL!"
  url = "https://example.com/${variable.my_var.query_path}"
}

output "status_code" {
  description = "This output will be displayed in the Outputs section of the web UI!"
  value = action.http_query.status_code
}
```

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

### Define an action and output

Source: https://docs.surfpool.run/iac/language

Actions perform specific tasks like deploying programs, and outputs display results after execution.

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

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

### Get Current Inflation Rate

Source: https://docs.surfpool.run/rpc/network

Retrieves the current network inflation rate statistics.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getInflationRate",
  "params": []
}
```

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

### Referencing Command Outputs in txtx

Source: https://docs.surfpool.run/iac/language

Demonstrates how to reference outputs from other commands within a txtx Runbook. This is crucial for establishing dependencies and chaining operations.

```txtx
variable "my_var" {
  description = variable.another_var.value // references the `value` output of a `variable` named `another_var`
  value = action.my_action.data // references the `data` output of an `action` named `my_action`
}
```

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

### List Surfpool Runbooks

Source: https://docs.surfpool.run/toolchain/cli

List all runbooks declared in the manifest file in the current directory. The default manifest path is './txtx.yml'.

```bash
surfpool ls [OPTIONS]
```

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

### getBlocksWithLimit

Source: https://docs.surfpool.run/rpc/network

Retrieves a specified number of blocks within a given range, starting from a specific slot.

```APIDOC
## GET /getBlocksWithLimit

### Description
Returns the blocks for a given range of slots with a limit.

### Method
GET

### Endpoint
/getBlocksWithLimit

### Parameters
#### Query Parameters
- **startSlot** (integer) - Required - The starting slot to query for blocks.
- **limit** (integer) - Required - The maximum number of blocks to return.
- **config** (object) - Optional - Configuration object for the query.
  - **commitment** (string | string | string) - Optional - The commitment describes how finalized a block is at that point in time. Options are 'processed', 'confirmed', or 'finalized'.
  - **minContextSlot** (integer) - Optional - The minimum context slot for the context.

### Response
#### Success Response (200)
- **result** (array<integer>) - getBlocksWithLimit - Returns blocks with limit

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBlocksWithLimit",
  "params": [
    123456789,
    0,
    {
      "commitment": "Processed",
      "minContextSlot": 123456789
    }
  ]
}
```

### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    123456789,
    123456790
  ]
}
```
```

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

### Using Functions and Arithmetic in txtx

Source: https://docs.surfpool.run/iac/language

Shows how to utilize built-in functions and arithmetic operations within txtx for calculations and data manipulation. This includes referencing other command outputs within function calls.

```txtx
variable "one" {
  value = 1
}
variable "two" {
  value = 2
}
variable "addem_up" {
  value = variable.one + variable.two
}
output "add_some_more" {
  value = add_uint(variable.addem_up + variable.one, variable.two)
}
```

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

### Create Token Account Instruction

Source: https://docs.surfpool.run/iac/svm/functions

Generates raw instruction bytes for creating an associated token account within a call 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
        )
    }
}
```

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

### Get Cluster Version

Source: https://docs.surfpool.run/rpc/network

Fetches the version information of the Solana cluster. This method takes no parameters.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getVersion",
  "params": []
}
```

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

### Surfpool CLI Commands

Source: https://docs.surfpool.run/llms.txt

Provides basic commands for interacting with the Surfpool CLI. Use 'surfpool --help' to see all available options.

```bash
surfpool start
```

```bash
surfpool --help
```

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

### Login to Surfpool Cloud

Source: https://docs.surfpool.run/toolchain/cli

Authenticate with the Txtx Cloud platform to manage cloud resources.

```bash
surfpool cloud login
```

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

### Get First Available Block

Source: https://docs.surfpool.run/rpc/network

Query for the earliest available block in the chain. This method does not require any parameters.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getFirstAvailableBlock",
  "params": []
}
```

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

### Load New Plugin

Source: https://docs.surfpool.run/rpc/admin

Dynamically loads a new plugin into the runtime from a specified configuration file.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "loadPlugin",
  "params": [
    "<some-configfile>"
  ]
}
```

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

### Get Cluster Identity RPC

Source: https://docs.surfpool.run/rpc/node

Retrieves the unique identity of the cluster. This can be used for identification and verification purposes.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getIdentity",
  "params": []
}
```

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

### Deploy Solana Program

Source: https://docs.surfpool.run/iac/svm/actions

Use `svm::deploy_program` to deploy a Solana program. Specify program artifacts, authority, and optionally a payer and commitment level.

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

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

### Run a Surfpool Runbook (Unsupervised Mode)

Source: https://docs.surfpool.run/toolchain/cli

Execute a runbook in unsupervised mode for automatic step execution. This is the default mode for deploying programs to Surfnet.

```bash
surfpool run my-runbook -u
```

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

### Get Recent Prioritization Fees

Source: https://docs.surfpool.run/rpc/network

Retrieves recent prioritization fees for a provided array of account public keys.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getRecentPrioritizationFees",
  "params": [
    []
  ]
}
```

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

### Network API - getMinimumBalanceForRentExemption

Source: https://docs.surfpool.run/rpc/network

Returns the minimum balance required for rent exemption.

```APIDOC
## POST /rpc

### Description
Returns the minimum balance required for rent exemption.

### Method
POST

### Endpoint
/rpc

### Parameters
#### Request Body
- **method** (string) - Required - The name of the method to call.
- **params** (array) - Required - An array of parameters for the method.
  - **0** (integer) - Required - The account data length in bytes.
  - **1** (object) - Optional - The commitment describes how finalized a block is at that point in time. Options are 'processed', 'confirmed', or 'finalized'.
    - **commitment** (string) - Optional - The commitment describes how finalized a block is at that point in time. Options are 'processed', 'confirmed', or 'finalized'

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getMinimumBalanceForRentExemption",
  "params": [
    0,
    {
      "commitment": "Processed"
    }
  ]
}
```

### Response
#### Success Response (200)
- **result** (integer) - getMinimumBalanceForRentExemption - Returns minimum balance for rent exemption

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 123456789
}
```
```

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

### Get Latest Blockhash

Source: https://docs.surfpool.run/rpc/network

Retrieve the most recent blockhash. Configuration options include commitment and minimum context slot.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getLatestBlockhash",
  "params": [
    {
      "commitment": "Processed",
      "minContextSlot": 123456789
    }
  ]
}
```

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

### Admin - Load Plugin

Source: https://docs.surfpool.run/rpc/admin

Dynamically loads a new plugin into the runtime from a configuration file.

```APIDOC
## POST /rpc

### Description
Dynamically loads a new plugin into the runtime from a configuration file.

### Method
POST

### Endpoint
/rpc

### Parameters
#### Request Body
- **configFile** (string) - Required - The path to the configuration file for the new plugin.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "loadPlugin",
  "params": [
    "<some-configfile>"
  ]
}
```

### Response
#### Success Response (200)
- **configFile** (string) -
```

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

### Get Minimum Ledger Slot

Source: https://docs.surfpool.run/rpc/network

Returns the minimum slot number available in the ledger. This method does not require any parameters.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "minimumLedgerSlot",
  "params": []
}
```

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

### Get Maximum Retransmit Slot

Source: https://docs.surfpool.run/rpc/network

Returns the maximum slot number that is currently being retransmitted. This method does not require any parameters.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getMaxRetransmitSlot",
  "params": []
}
```

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

### SVM Deploy Program

Source: https://docs.surfpool.run/iac/svm/actions

Deploys a Solana program to an SVM-compatible network.

```APIDOC
## POST /svm/deploy_program

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

### Method
POST

### Endpoint
`/svm/deploy_program`

### Parameters
#### Request Body
- **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)

### Request Example
```json
{
  "description": "Deploy hello world program",
  "program": "svm::get_program_from_anchor_project(\"hello_world\")",
  "authority": "signer.authority",
  "payer": "signer.payer"
}
```

### Response
#### Success Response (200)
- **signatures** (object) - The computed transaction signatures
- **program_id** (string) - The program ID of the deployed program
- **program_idl** (string) - The program IDL

#### Response Example
```json
{
  "signatures": {},
  "program_id": "<program_id>",
  "program_idl": "<program_idl>"
}
```
```

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

### Get Surfnet network information

Source: https://docs.surfpool.run/rpc/cheatcodes

Retrieves general Surfnet network information, including runbook execution statuses.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "surfnet_getSurfnetInfo",
  "params": []
}
```

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

### Enabling State Management in txtx Manifest

Source: https://docs.surfpool.run/iac/language

Configuration snippet for enabling state management in a `txtx.yml` manifest. This allows Surfpool to track changes and prevent unnecessary re-executions of Runbooks.

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

```

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

### Get Associated Token Account

Source: https://docs.surfpool.run/iac/svm/functions

Computes the associated token account address for a given wallet and token mint.

```hcl
variable "token_account" {
    value = svm::get_associated_token_account(signer.caller.address, "So11111111111111111111111111111111111111112")
}
```

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

### surfnet_setSupply

Source: https://docs.surfpool.run/rpc/cheatcodes

Configures the network supply information including total, circulating, and non-circulating amounts.

```APIDOC
## POST /surfnet_setSupply

### Description
Configures the network supply information including total, circulating, and non-circulating amounts.

### Method
POST

### Endpoint
/surfnet_setSupply

### Parameters
#### Request Body
- **update** (object) - Required - The supply data to update. Contains new values for total, circulating, and non-circulating SOL amounts.
  - **circulating** (integer) - Required - The new circulating supply of SOL in lamports (total supply minus non-circulating).
  - **nonCirculating** (integer) - Required - The new non-circulating supply of SOL in lamports (locked in non-circulating accounts).
  - **nonCirculatingAccounts** (array) - Required - The new list of non-circulating account addresses that hold locked SOL.
  - **total** (integer) - Required - The new total supply of SOL in lamports across the entire network.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "surfnet_setSupply",
  "params": [
    {
      "circulating": 0,
      "nonCirculating": 0,
      "nonCirculatingAccounts": [],
      "total": 0
    }
  ]
}
```

### Response
#### Success Response (200)
- **context** (object) - Context information.
  - **apiVersion** (string) - The API version.
  - **slot** (integer) - The current slot.
- **value** (null) - This method does not return a value upon success.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "context": {
      "apiVersion": "string",
      "slot": 0
    },
    "value": null
  }
}
```
```

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

### Get RPC Server Address

Source: https://docs.surfpool.run/rpc/admin

Returns the IP address and port of the RPC server. Useful for establishing connections.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "rpcAddress",
  "params": []
}
```

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

### Configure svm::web_wallet signer

Source: https://docs.surfpool.run/iac/svm/signers

Configures a signer that prompts the operator to connect a browser-based wallet.

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

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

### Get Maximum Shred Insert Slot

Source: https://docs.surfpool.run/rpc/network

Returns the maximum slot number where shreds can be inserted. This method does not require any parameters.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getMaxShredInsertSlot",
  "params": []
}
```

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

### Get Minimum Balance for Rent Exemption

Source: https://docs.surfpool.run/rpc/network

Queries the minimum balance required for an account to be rent-exempt based on data length.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getMinimumBalanceForRentExemption",
  "params": [
    0,
    {
      "commitment": "Processed"
    }
  ]
}
```

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

### Update network supply with surfnet_setSupply

Source: https://docs.surfpool.run/rpc/cheatcodes

Configures total, circulating, and non-circulating SOL supply amounts in lamports.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "surfnet_setSupply",
  "params": [
    {
      "circulating": 0,
      "nonCirculating": 0,
      "nonCirculatingAccounts": [],
      "total": 0
    }
  ]
}
```

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

### POST getVersion

Source: https://docs.surfpool.run/rpc/network

Returns the version of the cluster software.

```APIDOC
## POST getVersion

### Description
Returns the version of the cluster.

### Request Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getVersion",
  "params": []
}

### Response
#### Success Response (200)
- **feature-set** (integer) - The feature set version.
- **solana-core** (string) - The solana-core version string.
```

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

### Get Block Commitment

Source: https://docs.surfpool.run/rpc/accounts

Fetch commitment levels for a specified block (slot). This method is useful for understanding the finality of a block.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBlockCommitment",
  "params": [
    0
  ]
}
```

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

### List Loaded Plugins

Source: https://docs.surfpool.run/rpc/admin

Returns a list of all currently loaded plugin names. Useful for auditing.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "listPlugins",
  "params": []
}
```

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

### Get Transaction Count

Source: https://docs.surfpool.run/rpc/network

Retrieves the current transaction count for the cluster. Requires a configuration object with commitment and minimum context slot.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTransactionCount",
  "params": [
    {
      "commitment": "Processed",
      "minContextSlot": 123456789
    }
  ]
}
```

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

### surfpool run

Source: https://docs.surfpool.run/toolchain/cli

Executes a Runbook. Can run a `.tx` file directly or reference a runbook declared in a `txtx.yml` manifest.

```APIDOC
## surfpool run

### Description
Executes a Runbook. Can run a `.tx` file directly or reference a runbook declared in a `txtx.yml` manifest.

### Method
CLI Command

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

### Parameters
#### Arguments
- **RUNBOOK** (string) - Name of the runbook as indexed in `txtx.yml`, or path to a `.tx` file

#### Execution Mode
These flags are mutually exclusive. If none is specified, `--browser` is the default.
- **--unsupervised** (`-u`) (boolean) - Execute without supervision
- **--browser** (`-b`) (boolean) - Execute with browser UI supervision (default)
- **--terminal** (`-t`) (boolean) - Execute with terminal supervision (coming soon)

### Request Example
```
surfpool run my_runbook
```

### Response
(No specific response details provided for this command.)
```

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

### Get Block Time by Slot

Source: https://docs.surfpool.run/rpc/network

Fetch the block time for a given slot. This method is useful for determining when a specific block was processed.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBlockTime",
  "params": [
    123456789
  ]
}
```

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

### Register a network scenario

Source: https://docs.surfpool.run/rpc/cheatcodes

Registers a scenario with account overrides for testing different network states.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "surfnet_registerScenario",
  "params": [
    {
      "id": "<some-id>",
      "name": "<some-name>",
      "description": "<some-description>",
      "overrides": [
        {
          "id": "<some-id>",
          "templateId": "<some-templateid>",
          "values": {},
          "scenarioRelativeSlot": 123456789,
          "label": "<some-label>",
          "enabled": true,
          "fetchBeforeUse": true,
          "account": {
            "pubkey": "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri"
          }
        }
      ],
      "tags": [
        "<some-tags>"
      ]
    },
    123456789
  ]
}
```

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

### Get Token Supply

Source: https://docs.surfpool.run/rpc/accounts

Retrieve the total supply of a token by providing its mint address. Supports specifying commitment level for the query.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenSupply",
  "params": [
    "<some-mint>",
    {
      "commitment": "Processed"
    }
  ]
}
```

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

### Get Leader Schedule

Source: https://docs.surfpool.run/rpc/network

Retrieves the leader schedule for a given slot or configuration. Supports filtering by validator identity and specifying commitment level.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getLeaderSchedule",
  "params": [
    0,
    {
      "commitment": {
        "commitment": "Processed"
      },
      "identity": "<some-identity>"
    }
  ]
}
```

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

### Declare SVM Addon in Runbook

Source: https://docs.surfpool.run/iac/svm/overview

Configure the SVM addon by specifying the network ID and RPC API URL within the Runbook.

```hcl
addon "svm" {
  network_id = "devnet"
  rpc_api_url = "https://api.devnet.solana.com"
}
```
Tokens:
Raw