Search documentation of Cartouche

# Cartouche.Solana.RPC (Cartouche v0.1.3)

Copy Markdown View Source

JSON-RPC client for Solana.

Provides typed functions for Solana RPC methods with automatic Base58 encoding of pubkeys, commitment level options, and response deserialization.

## Configuration

    config :cartouche,
      solana_node: "https://api.mainnet-beta.solana.com"

## Examples

    {:ok, balance} = Cartouche.Solana.RPC.get_balance(pubkey)
    {:ok, slot} = Cartouche.Solana.RPC.get_slot()
    {:ok, %{blockhash: bh}} = Cartouche.Solana.RPC.get_latest_blockhash()

## Summary

### Functions

get_account_info(pubkey, opts \\ [])

Get account info for a pubkey. Returns `nil` if the account doesn't exist.

get_balance(pubkey, opts \\ [])

Get the SOL balance (in lamports) for an account.

get_block_height(opts \\ [])

Get the current block height.

get_health(opts \\ [])

Check node health. Returns `:ok` if healthy, `{:error, ...}` if unhealthy.

get_latest_blockhash(opts \\ [])

Get the latest blockhash and its last valid block height.

get_minimum_balance_for_rent_exemption(data_length, opts \\ [])

Get the minimum balance for rent exemption for a given data size.

get_multiple_accounts(pubkeys, opts \\ [])

Get account info for multiple pubkeys (max 100).

get_recent_prioritization_fees(addresses \\ [], opts \\ [])

Get recent prioritization fees. Pass account addresses to see fees for transactions locking those accounts.

get_signature_statuses(signatures, opts \\ [])

Get the statuses of transaction signatures (max 256).

get_slot(opts \\ [])

Get the current slot.

get_token_account_balance(pubkey, opts \\ [])

Get the token balance for an SPL Token account.

get_token_accounts_by_owner(owner, filter, opts \\ [])

Get all token accounts owned by a wallet.

get_transaction(signature, opts \\ [])

Get a transaction by its signature.

get_version(opts \\ [])

Get the node version.

request_airdrop(pubkey, lamports, opts \\ [])

Request an airdrop of SOL (devnet/testnet only).

send_and_confirm(transaction, opts \\ [])

Send a transaction and poll for confirmation.

send_rpc(method, params, opts \\ [])

Send a raw JSON-RPC request to the Solana node.

send_transaction(transaction, opts \\ [])

Send a signed transaction to the network.

simulate_transaction(transaction, opts \\ [])

Simulate a transaction without submitting it.

## Functions

# get_account_info(pubkey, opts \\ [])

    @spec get_account_info(
      <<_::256>>,
      keyword()
    ) :: {:ok, map() | nil} | {:error, term()}

Get account info for a pubkey. Returns `nil` if the account doesn't exist.

## Options

- `:commitment` - `:processed`, `:confirmed`, or `:finalized`
- `:encoding` - `:base64` (default), `:base58`, `:"base64+zstd"`, `:json_parsed`

# get_balance(pubkey, opts \\ [])

    @spec get_balance(
      <<_::256>>,
      keyword()
    ) :: {:ok, non_neg_integer()} | {:error, term()}

Get the SOL balance (in lamports) for an account.

## Options

- `:commitment` - `:processed`, `:confirmed`, or `:finalized`

# get_block_height(opts \\ [])

    @spec get_block_height(keyword()) :: {:ok, non_neg_integer()} | {:error, term()}

Get the current block height.

# get_health(opts \\ [])

    @spec get_health(keyword()) :: :ok | {:error, term()}

Check node health. Returns `:ok` if healthy, `{:error, ...}` if unhealthy.

# get_latest_blockhash(opts \\ [])

    @spec get_latest_blockhash(keyword()) ::
      {:ok, %{blockhash: binary(), last_valid_block_height: non_neg_integer()}}
      | {:error, term()}

Get the latest blockhash and its last valid block height.

# get_minimum_balance_for_rent_exemption(data_length, opts \\ [])

    @spec get_minimum_balance_for_rent_exemption(
      non_neg_integer(),
      keyword()
    ) :: {:ok, non_neg_integer()} | {:error, term()}

Get the minimum balance for rent exemption for a given data size.

# get_multiple_accounts(pubkeys, opts \\ [])

    @spec get_multiple_accounts(
      [<<_::256>>],
      keyword()
    ) :: {:ok, [map() | nil]} | {:error, term()}

Get account info for multiple pubkeys (max 100).

## Options

- `:commitment`, `:encoding` - same as `get_account_info/2`

# get_recent_prioritization_fees(addresses \\ [], opts \\ [])

    @spec get_recent_prioritization_fees(
      [<<_::256>>],
      keyword()
    ) ::
      {:ok, [%{slot: non_neg_integer(), prioritization_fee: non_neg_integer()}]}
      | {:error, term()}

Get recent prioritization fees. Pass account addresses to see fees for transactions locking those accounts.

# get_signature_statuses(signatures, opts \\ [])

    @spec get_signature_statuses(
      [String.t()],
      keyword()
    ) :: {:ok, [map() | nil]} | {:error, term()}

Get the statuses of transaction signatures (max 256).

## Options

- `:search_transaction_history` - Search beyond recent status cache (default: false)

# get_slot(opts \\ [])

    @spec get_slot(keyword()) :: {:ok, non_neg_integer()} | {:error, term()}

Get the current slot.

# get_token_account_balance(pubkey, opts \\ [])

    @spec get_token_account_balance(
      <<_::256>>,
      keyword()
    ) ::
      {:ok,
       %{
         amount: non_neg_integer(),
         decimals: non_neg_integer(),
         ui_amount_string: String.t()
       }}
      | {:error, term()}

Get the token balance for an SPL Token account.

Returns the raw integer amount, decimal precision, and `ui_amount_string` (a human-readable formatted string provided by the RPC node, e.g. `"1.5"` for 1500000 with 6 decimals).

# get_token_accounts_by_owner(owner, filter, opts \\ [])

    @spec get_token_accounts_by_owner(<<_::256>>, keyword(), keyword()) ::
      {:ok, [%{pubkey: String.t(), account: map()}]} | {:error, term()}

Get all token accounts owned by a wallet.

Requires exactly one filter: `:mint` (specific token) or `:program_id` (all tokens under a program).

Uses `jsonParsed` encoding by default for structured token account data.

## Examples

    get_token_accounts_by_owner(wallet, mint: usdc_mint)
    get_token_accounts_by_owner(wallet, program_id: Programs.token_program())

# get_transaction(signature, opts \\ [])

    @spec get_transaction(
      String.t(),
      keyword()
    ) :: {:ok, map() | nil} | {:error, term()}

Get a transaction by its signature.

Returns `nil` if the transaction is not found.

## Options

- `:commitment` - `:confirmed` or `:finalized` (`:processed` is NOT supported)
- `:encoding` - `:json` (default), `:json_parsed`, `:base64`, `:base58`

# get_version(opts \\ [])

    @spec get_version(keyword()) ::
      {:ok, %{solana_core: String.t(), feature_set: non_neg_integer()}}
      | {:error, term()}

Get the node version.

# request_airdrop(pubkey, lamports, opts \\ [])

    @spec request_airdrop(<<_::256>>, non_neg_integer(), keyword()) ::
      {:ok, String.t()} | {:error, term()}

Request an airdrop of SOL (devnet/testnet only).

Returns the airdrop transaction signature.

# send_and_confirm(transaction, opts \\ [])

    @spec send_and_confirm(
      Cartouche.Solana.Transaction.t() | binary(),
      keyword()
    ) :: {:ok, String.t()} | {:error, term()}

Send a transaction and poll for confirmation.

## Options

- `:commitment` - Confirmation level to wait for (default: `:confirmed`)
- `:timeout` - Max time to wait in ms (default: 30_000)
- `:poll_interval` - Poll interval in ms (default: 500)
- All options from `send_transaction/2`

# send_rpc(method, params, opts \\ [])

    @spec send_rpc(String.t(), list(), keyword()) :: {:ok, term()} | {:error, term()}

Send a raw JSON-RPC request to the Solana node.

Options:

- `:solana_node` - Override the node URL
- `:timeout` - Request timeout in ms (default: 30000)
- `:id` - JSON-RPC request ID (default: auto-generated)

## Examples

    Cartouche.Solana.RPC.send_rpc("getSlot", [])
    {:ok, 123456789}

# send_transaction(transaction, opts \\ [])

    @spec send_transaction(
      binary() | Cartouche.Solana.Transaction.t(),
      keyword()
    ) :: {:ok, String.t()} | {:error, term()}

Send a signed transaction to the network.

Accepts a `Cartouche.Solana.Transaction` struct or raw serialized bytes.

## Options

- `:encoding` - `:base64` (default) or `:base58`
- `:skip_preflight` - Skip preflight checks (default: false)
- `:preflight_commitment` - Commitment for preflight simulation
- `:max_retries` - Max retries before giving up

Returns the transaction signature (Base58 string).

# simulate_transaction(transaction, opts \\ [])

    @spec simulate_transaction(
      binary() | Cartouche.Solana.Transaction.t(),
      keyword()
    ) :: {:ok, map()} | {:error, term()}

Simulate a transaction without submitting it.

Returns simulation result including logs, compute units consumed, and errors.