Onchain.RPC (onchain v0.7.0)

Ethereum JSON-RPC wrapper using cartouche's RPC client.

Provides a curated API for common Ethereum RPC methods with consistent error tuples and option handling. All functions accept :rpc_url, :timeout, and :block options. Single RPC calls also accept an opt-in :retry policy. Omit :retry to preserve the underlying Cartouche.RPC.send_rpc/3 single-attempt behavior. Pass retry: [max_retries: 2, backoff_ms: 100] to retry RPC/network errors before returning the final normalized error.

Telemetry

Every single-call RPC (do_rpc/3, all named wrappers, and call/3) plus batch/2 is wrapped in :telemetry.span/3 under the event prefix [:onchain, :rpc, :request] — emitting :start, :stop, and :exception events. Start metadata is %{method: method}; stop metadata is %{method: method, status: :ok} on success or %{method: method, status: :error, error: reason} on a returned error tuple (method is "batch" for batch/2). Attach a handler to measure latency or count failures per method.

Error Format

Address validation: {:error, {:invalid_address, input}}
Data validation: {:error, {:invalid_data, input}}
Block validation: {:error, {:invalid_block, input}}
Tx hash validation: {:error, {:invalid_tx_hash, input}} (must be 32 bytes)
RPC/network errors: {:error, {:rpc_error, map}}

For RPC errors, the map always has at least a :message key. JSON-RPC error responses from the node include :code; network/transport errors are wrapped with inspect/1 as the message.

Revert errors (`code: 3`)

When eth_call reverts, the node returns a JSON-RPC error with code: 3. The inner map is widened with extra fields populated by cartouche (see Cartouche.RPC.rpc_error/0) plus :data mirrored by Onchain (enriched internally by the Onchain.RPC.Helpers module):

:revert — the raw revert-data binary (present on code: 3 when the node returned a data field; absent if the node omitted it). Use this for selector inspection or pass to ABI libraries that accept binaries.
:data — the same payload as a lowercase 0x-prefixed hex string. Mirrored from :revert whenever the latter is set so callers can pipe it straight into Onchain.ABI.decode_error/2 (which expects 0x hex, not raw bytes).
:error_abi — the matching custom-error signature String.t() from the :errors opt (e.g. "InsufficientBalance(uint256,uint256)"). Only present when the caller passed errors: AND the revert payload's selector matches one of those signatures (or a Solidity 0.8.x Panic variant — those decode to a human-readable string like "arithmetic error: overflow or underflow").
:error_params — the decoded argument list for :error_abi (e.g. [1_000, 500] for InsufficientBalance(1000, 500)). Empty list [] for nullary errors. Same population rule as :error_abi.

Pattern matches:

# Revert without :errors opt — decode out-of-band via the hex :data mirror
{:error, {:rpc_error, %{code: 3, data: hex_data}}} = result
{:ok, %{error: signature, args: args}} =
  Onchain.ABI.decode_error(hex_data, ["InsufficientBalance(uint256,uint256)"])

# Revert with matching :errors opt — already decoded inline
{:error,
 {:rpc_error,
  %{code: 3, error_abi: "InsufficientBalance(uint256,uint256)", error_params: [1000, 500]}}} =
  result

Existing {:error, {:rpc_error, %{code:, message:}}} matches still work — the revert fields are additive on the inner map.

Functions

Function	Purpose
`eth_call/3`	Read-only contract call → raw hex response
`eth_call!/3`	Same, raises on error
`eth_send_raw_transaction/2`	Broadcast signed tx → tx hash
`eth_send_raw_transaction!/2`	Same, raises on error
`get_balance/2`	Account ETH balance in wei
`get_balance!/2`	Same, raises on error
`block_number/1`	Current block height
`block_number!/1`	Same, raises on error
`syncing/1`	Node sync status (`false` or sync-status map)
`syncing!/1`	Same, raises on error
`get_block_by_number/2`	Fetch block by number or tag → atom-keyed decoded map (same conventions as `get_transaction_by_hash`)
`get_block_by_number!/2`	Same, raises on error
`chain_id/1`	Network chain ID
`chain_id!/1`	Same, raises on error
`eth_get_logs/2`	Fetch event logs by filter
`eth_get_logs!/2`	Same, raises on error
`get_transaction_receipt/2`	Transaction receipt by hash
`get_transaction_receipt!/2`	Same, raises on error
`get_transaction_count/2`	Account nonce (tx count)
`get_transaction_count!/2`	Same, raises on error
`eth_get_code/2`	Contract bytecode (or "0x" for EOAs)
`eth_get_code!/2`	Same, raises on error
`get_transaction_by_hash/2`	Full transaction details by hash
`get_transaction_by_hash!/2`	Same, raises on error
`call/3`	Generic JSON-RPC passthrough — any method, raw result
`call!/3`	Same, raises on error
`batch/2`	Generic JSON-RPC array batch — one HTTP round-trip for many raw calls
`fee_history/2`	EIP-1559 fee history (`eth_feeHistory`) → `Cartouche.FeeHistory.t()`
`fee_history!/2`	Same, raises on error
`get_proof/3`	Account + storage Merkle proofs (`eth_getProof`)
`get_proof!/3`	Same, raises on error

API Functions

Function	Arity	Description	Param Kinds
`get_proof!`	3	Fetch Merkle proof for an account and storage slots. Raises on error.	`address: value`, `storage_keys: value`, `opts: value`
`get_proof`	3	Fetch Merkle proof for an account and storage slots (eth_getProof).	`address: value`, `storage_keys: value`, `opts: value`
`fee_history!`	2	Fetch fee history. Raises on error.	`block_count: value`, `opts: value`
`fee_history`	2	Fetch base-fee history and per-block priority-fee percentiles (eth_feeHistory).	`block_count: value`, `opts: value`
`batch`	2	Generic JSON-RPC array batch — invoke many methods in one HTTP request.	`requests: value`, `opts: value`
`call!`	3	Generic JSON-RPC passthrough. Raises on error.	`method: value`, `params: value`, `opts: value`
`call`	3	Generic JSON-RPC passthrough — invoke any method not covered by a named wrapper.	`method: value`, `params: value`, `opts: value`
`eth_get_logs!`	2	Fetch event logs matching a filter. Raises on error.	`filter: value`, `opts: value`
`eth_get_logs`	2	Fetch event logs matching a filter (eth_getLogs).	`filter: value`, `opts: value`
`get_transaction_by_hash!`	2	Get full transaction details by hash. Raises on error.	`tx_hash: value`, `opts: value`
`get_transaction_by_hash`	2	Get full transaction details by hash (eth_getTransactionByHash).	`tx_hash: value`, `opts: value`
`eth_get_code!`	2	Fetch contract bytecode at an address. Raises on error.	`address: value`, `opts: value`
`eth_get_code`	2	Fetch contract bytecode at an address (eth_getCode).	`address: value`, `opts: value`
`get_transaction_count!`	2	Get the transaction count (nonce) of an address. Raises on error.	`address: value`, `opts: value`
`get_transaction_count`	2	Get the transaction count (nonce) of an address.	`address: value`, `opts: value`
`get_transaction_receipt!`	2	Get a transaction receipt by hash. Raises on error.	`tx_hash: value`, `opts: value`
`get_transaction_receipt`	2	Get a transaction receipt by hash (eth_getTransactionReceipt).	`tx_hash: value`, `opts: value`
`chain_id!`	1	Get the network chain ID. Raises on error.	`opts: value`
`chain_id`	1	Get the network chain ID.	`opts: value`
`get_block_by_number!`	2	Fetch a block by number or tag. Raises on error.	`block_id: value`, `opts: value`
`get_block_by_number`	2	Fetch a block by number or tag (eth_getBlockByNumber).	`block_id: value`, `opts: value`
`syncing!`	1	Get the node's sync status. Raises on error.	`opts: value`
`syncing`	1	Get the node's sync status (eth_syncing).	`opts: value`
`block_number!`	1	Get the current block height. Raises on error.	`opts: value`
`block_number`	1	Get the current block height.	`opts: value`
`get_balance!`	2	Get the ETH balance of an address in wei. Raises on error.	`address: value`, `opts: value`
`get_balance`	2	Get the ETH balance of an address in wei.	`address: value`, `opts: value`
`eth_send_raw_transaction!`	2	Broadcast a signed transaction. Raises on error.	`data: value`, `opts: value`
`eth_send_raw_transaction`	2	Broadcast a signed transaction.	`data: value`, `opts: value`
`eth_call!`	3	Execute a read-only contract call. Raises on error.	`address: value`, `data: value`, `opts: value`
`eth_call`	3	Execute a read-only contract call (eth_call).	`address: value`, `data: value`, `opts: value`

Summary

Functions

batch(requests, opts \\ [])

Invoke many raw JSON-RPC calls in one HTTP request.

block_number(opts \\ [])

Get the current block height.

block_number!(opts \\ [])

Get the current block height. Raises on error.

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

Generic JSON-RPC passthrough — invoke any method not covered by a named wrapper.

call!(method, params, opts \\ [])

Generic JSON-RPC passthrough. Raises on error.

chain_id(opts \\ [])

Get the network chain ID.

chain_id!(opts \\ [])

Get the network chain ID. Raises on error.

eth_call(address, data, opts \\ [])

Execute a read-only contract call (eth_call).

eth_call!(address, data, opts \\ [])

Execute a read-only contract call. Raises on error.

eth_get_code(address, opts \\ [])

Fetch contract bytecode at an address (eth_getCode).

eth_get_code!(address, opts \\ [])

Fetch contract bytecode at an address. Raises on error.

eth_get_logs(filter, opts \\ [])

Fetch event logs matching a filter (eth_getLogs).

eth_get_logs!(filter, opts \\ [])

Fetch event logs matching a filter. Raises on error.

eth_send_raw_transaction(data, opts \\ [])

Broadcast a signed transaction.

eth_send_raw_transaction!(data, opts \\ [])

Broadcast a signed transaction. Raises on error.

fee_history(block_count, opts \\ [])

Fetch base-fee history and per-block priority-fee percentiles (eth_feeHistory).

fee_history!(block_count, opts \\ [])

Fetch fee history. Raises on error.

get_balance(address, opts \\ [])

Get the ETH balance of an address in wei.

get_balance!(address, opts \\ [])

Get the ETH balance of an address in wei. Raises on error.

get_block_by_number(block_id, opts \\ [])

Fetch a block by number or tag (eth_getBlockByNumber).

get_block_by_number!(block_id, opts \\ [])

Fetch a block by number or tag. Raises on error.

get_proof(address, storage_keys, opts \\ [])

Fetch Merkle proof for an account and storage slots (eth_getProof).

get_proof!(address, storage_keys, opts \\ [])

Fetch Merkle proof for an account and storage slots. Raises on error.

get_transaction_by_hash(tx_hash, opts \\ [])

Get full transaction details by hash (eth_getTransactionByHash).

get_transaction_by_hash!(tx_hash, opts \\ [])

Get full transaction details by hash. Raises on error.

get_transaction_count(address, opts \\ [])

Get the transaction count (nonce) of an address.

get_transaction_count!(address, opts \\ [])

Get the transaction count (nonce) of an address. Raises on error.

get_transaction_receipt(tx_hash, opts \\ [])

Get a transaction receipt by hash (eth_getTransactionReceipt).

get_transaction_receipt!(tx_hash, opts \\ [])

Get a transaction receipt by hash. Raises on error.

syncing(opts \\ [])

Get the node's sync status (eth_syncing).

syncing!(opts \\ [])

Get the node's sync status. Raises on error.

Functions

batch(requests, opts \\ [])

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

Invoke many raw JSON-RPC calls in one HTTP request.

Each request is a {method, params} tuple. Results are returned in request order even when the node returns the JSON-RPC response array out of order.

block_number(opts \\ [])

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

Get the current block height.

Parameters

opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Current block number ({:ok, non_neg_integer} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, non_neg_integer} | {:error, term}",
    description: "Current block number"
  }
}

block_number!(opts \\ [])

@spec block_number!(keyword()) :: non_neg_integer()

Get the current block height. Raises on error.

Parameters

opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Current block number (non_neg_integer)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    }
  },
  returns: %{type: :non_neg_integer, description: "Current block number"}
}

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

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

Generic JSON-RPC passthrough — invoke any method not covered by a named wrapper.

Parameters

method - JSON-RPC method name, e.g. "eth_getStorageAt", "debug_traceTransaction", "trace_call", "eth_feeHistory" (value)
params - List of params for the method, in the order the JSON-RPC spec requires (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Raw decoded JSON result (no further decoding — caller knows what they asked for) or wrapped error tuple ({:ok, term} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    params: %{
      description: "List of params for the method, in the order the JSON-RPC spec requires",
      kind: :value
    },
    method: %{
      description: "JSON-RPC method name, e.g. \"eth_getStorageAt\", \"debug_traceTransaction\", \"trace_call\", \"eth_feeHistory\"",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, term} | {:error, term}",
    description: "Raw decoded JSON result (no further decoding — caller knows what they asked for) or wrapped error tuple"
  }
}

call!(method, params, opts \\ [])

@spec call!(String.t(), [term()], keyword()) :: term()

Generic JSON-RPC passthrough. Raises on error.

Parameters

method - JSON-RPC method name (value)
params - List of params for the method (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Raw decoded JSON result (term)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    params: %{description: "List of params for the method", kind: :value},
    method: %{description: "JSON-RPC method name", kind: :value}
  },
  returns: %{type: :term, description: "Raw decoded JSON result"}
}

chain_id(opts \\ [])

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

Get the network chain ID.

Parameters

opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Chain ID (1 = mainnet, 11155111 = sepolia, etc.) ({:ok, non_neg_integer} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, non_neg_integer} | {:error, term}",
    description: "Chain ID (1 = mainnet, 11155111 = sepolia, etc.)"
  }
}

chain_id!(opts \\ [])

@spec chain_id!(keyword()) :: non_neg_integer()

Get the network chain ID. Raises on error.

Parameters

opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Chain ID integer (non_neg_integer)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    }
  },
  returns: %{type: :non_neg_integer, description: "Chain ID integer"}
}

eth_call(address, data, opts \\ [])

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

Execute a read-only contract call (eth_call).

Options

:rpc_url — node URL (overrides Application.get_env(:cartouche, :ethereum_node))
:timeout — request timeout in ms (default 30_000)
:block — block number / tag / 0x hex (default "latest")
:errors — list of Solidity custom-error signatures, e.g. ["InsufficientBalance(uint256,uint256)", "Unauthorized()"]. When the call reverts with matching revert data, the error map carries decoded :error_abi + :error_params alongside the raw :revert binary and its hex mirror :data.

Revert handling

On code: 3 reverts the inner map widens — see the module's "Error Format" section. Quick pattern-match shape:

case Onchain.RPC.eth_call(token, calldata, errors: ["InsufficientBalance(uint256,uint256)"]) do
  {:ok, hex_result} ->
    # Decode hex_result with Onchain.ABI.decode_response/2
    :ok

  {:error, {:rpc_error, %{code: 3, error_abi: "InsufficientBalance(uint256,uint256)", error_params: [requested, available]}}} ->
    {:insufficient, requested, available}

  {:error, {:rpc_error, %{code: 3, data: hex_data}}} ->
    # Custom error not in :errors list (or :errors omitted) — fall back
    # to the hex-mirrored revert payload and decode out-of-band.
    # `Onchain.ABI.decode_error/2` expects 0x hex, which is exactly :data.
    Onchain.ABI.decode_error(hex_data, ["MyError(uint256)"])

  {:error, {:rpc_error, %{message: msg}}} ->
    {:rpc, msg}
end

eth_call!(address, data, opts \\ [])

@spec eth_call!(String.t() | binary(), String.t(), keyword()) :: String.t()

Execute a read-only contract call. Raises on error.

Parameters

address - Contract address as 0x hex string or 20-byte binary (value)
data - 0x-prefixed hex-encoded calldata (value)
opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Raw 0x-prefixed hex response (string)

# descripex:contract
%{
  params: %{
    data: %{description: "0x-prefixed hex-encoded calldata", kind: :value},
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    address: %{
      description: "Contract address as 0x hex string or 20-byte binary",
      kind: :value
    }
  },
  returns: %{type: :string, description: "Raw 0x-prefixed hex response"}
}

eth_get_code(address, opts \\ [])

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

Fetch contract bytecode at an address (eth_getCode).

Parameters

address - Account address as 0x hex string or 20-byte binary (value)
opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

0x-prefixed bytecode hex string, or "0x" for EOA addresses ({:ok, hex_string} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    address: %{
      description: "Account address as 0x hex string or 20-byte binary",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, hex_string} | {:error, term}",
    description: "0x-prefixed bytecode hex string, or \"0x\" for EOA addresses",
    example: "\"0x\" for EOAs, \"0x6080604052...\" for contracts"
  }
}

eth_get_code!(address, opts \\ [])

@spec eth_get_code!(
  String.t() | binary(),
  keyword()
) :: String.t()

Fetch contract bytecode at an address. Raises on error.

Parameters

address - Account address as 0x hex string or 20-byte binary (value)
opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

0x-prefixed bytecode hex string (string)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    address: %{
      description: "Account address as 0x hex string or 20-byte binary",
      kind: :value
    }
  },
  returns: %{type: :string, description: "0x-prefixed bytecode hex string"}
}

eth_get_logs(filter, opts \\ [])

@spec eth_get_logs(
  map(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Fetch event logs matching a filter (eth_getLogs).

Parameters

filter - Filter map. Atom keys: :address (hex string), :topics (list), :from_block (integer or tag), :to_block (integer or tag), :block_hash (32-byte hex). Canonical JSON-RPC camelCase string keys ("fromBlock", "toBlock", "address", "topics", "blockHash") are accepted as aliases. If both an atom key and its camelCase alias are present, the atom key wins (the alias value is silently dropped). :block_hash is mutually exclusive with :from_block / :to_block per EIP-1474. Unknown keys return {:error, {:invalid_filter_key, key}}. (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

List of log maps with keys: address, topics, data, block_number, transaction_hash, log_index, transaction_index, removed. Errors: {:invalid_filter_key, key} for unknown filter keys; {:invalid_filter, {field, value}} for bad values; {:invalid_filter, {:block_hash_mutually_exclusive, present}} when :block_hash is combined with :from_block / :to_block. ({:ok, [log_map]} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    filter: %{
      description: "Filter map. Atom keys: :address (hex string), :topics (list), :from_block (integer or tag), :to_block (integer or tag), :block_hash (32-byte hex). Canonical JSON-RPC camelCase string keys (\"fromBlock\", \"toBlock\", \"address\", \"topics\", \"blockHash\") are accepted as aliases. If both an atom key and its camelCase alias are present, the atom key wins (the alias value is silently dropped). :block_hash is mutually exclusive with :from_block / :to_block per EIP-1474. Unknown keys return {:error, {:invalid_filter_key, key}}.",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, [log_map]} | {:error, term}",
    description: "List of log maps with keys: address, topics, data, block_number, transaction_hash, log_index, transaction_index, removed. Errors: {:invalid_filter_key, key} for unknown filter keys; {:invalid_filter, {field, value}} for bad values; {:invalid_filter, {:block_hash_mutually_exclusive, present}} when :block_hash is combined with :from_block / :to_block."
  }
}

eth_get_logs!(filter, opts \\ [])

@spec eth_get_logs!(
  map(),
  keyword()
) :: [map()]

Fetch event logs matching a filter. Raises on error.

Parameters

filter - Filter map (see eth_get_logs/2) (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

List of parsed log maps ([log_map])

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    filter: %{description: "Filter map (see eth_get_logs/2)", kind: :value}
  },
  returns: %{type: "[log_map]", description: "List of parsed log maps"}
}

eth_send_raw_transaction(data, opts \\ [])

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

Broadcast a signed transaction.

Parameters

data - 0x-prefixed hex-encoded signed transaction (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Transaction hash as 0x hex string ({:ok, tx_hash} | {:error, term})

# descripex:contract
%{
  params: %{
    data: %{
      description: "0x-prefixed hex-encoded signed transaction",
      kind: :value
    },
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, tx_hash} | {:error, term}",
    description: "Transaction hash as 0x hex string",
    example: "0xabc123..."
  }
}

eth_send_raw_transaction!(data, opts \\ [])

@spec eth_send_raw_transaction!(
  String.t(),
  keyword()
) :: String.t()

Broadcast a signed transaction. Raises on error.

Parameters

data - 0x-prefixed hex-encoded signed transaction (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Transaction hash as 0x hex string (string)

# descripex:contract
%{
  params: %{
    data: %{
      description: "0x-prefixed hex-encoded signed transaction",
      kind: :value
    },
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    }
  },
  returns: %{type: :string, description: "Transaction hash as 0x hex string"}
}

fee_history(block_count, opts \\ [])

@spec fee_history(
  pos_integer(),
  keyword()
) :: {:ok, Cartouche.FeeHistory.t()} | {:error, term()}

Fetch base-fee history and per-block priority-fee percentiles (eth_feeHistory).

Parameters

block_count - Number of recent blocks to query, 1..1024 (EIP-1474 cap) (value)
opts - Options: :newest_block (default "latest"), :reward_percentiles (default [50] — list of ints 0..100, monotonically non-decreasing), :rpc_url, :timeout (default: [], value)

Returns

Deserialized fee history struct: oldest_block, base_fee_per_gas (block_count + 1 entries), gas_used_ratio, reward (block_count rows × length(reward_percentiles) cols) ({:ok, Cartouche.FeeHistory.t()} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :newest_block (default \"latest\"), :reward_percentiles (default [50] — list of ints 0..100, monotonically non-decreasing), :rpc_url, :timeout",
      kind: :value
    },
    block_count: %{
      description: "Number of recent blocks to query, 1..1024 (EIP-1474 cap)",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, Cartouche.FeeHistory.t()} | {:error, term}",
    description: "Deserialized fee history struct: oldest_block, base_fee_per_gas (block_count + 1 entries), gas_used_ratio, reward (block_count rows × length(reward_percentiles) cols)"
  }
}

fee_history!(block_count, opts \\ [])

@spec fee_history!(
  pos_integer(),
  keyword()
) :: Cartouche.FeeHistory.t()

Fetch fee history. Raises on error.

Parameters

block_count - Number of recent blocks to query, 1..1024 (value)
opts - Options: :newest_block, :reward_percentiles, :rpc_url, :timeout (default: [], value)

Returns

Deserialized fee history struct (Cartouche.FeeHistory.t())

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :newest_block, :reward_percentiles, :rpc_url, :timeout",
      kind: :value
    },
    block_count: %{
      description: "Number of recent blocks to query, 1..1024",
      kind: :value
    }
  },
  returns: %{
    type: "Cartouche.FeeHistory.t()",
    description: "Deserialized fee history struct"
  }
}

get_balance(address, opts \\ [])

@spec get_balance(
  String.t() | binary(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, term()}

Get the ETH balance of an address in wei.

Parameters

address - Account address as 0x hex string or 20-byte binary (value)
opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Balance in wei ({:ok, non_neg_integer} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    address: %{
      description: "Account address as 0x hex string or 20-byte binary",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, non_neg_integer} | {:error, term}",
    description: "Balance in wei"
  }
}

get_balance!(address, opts \\ [])

@spec get_balance!(
  String.t() | binary(),
  keyword()
) :: non_neg_integer()

Get the ETH balance of an address in wei. Raises on error.

Parameters

address - Account address as 0x hex string or 20-byte binary (value)
opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Balance in wei (non_neg_integer)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    address: %{
      description: "Account address as 0x hex string or 20-byte binary",
      kind: :value
    }
  },
  returns: %{type: :non_neg_integer, description: "Balance in wei"}
}

get_block_by_number(block_id, opts \\ [])

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

Fetch a block by number or tag (eth_getBlockByNumber).

Parameters

block_id - Block number (integer) or tag string ("latest", "finalized", "pending", "earliest", "safe", or "0x..." hex) (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Decoded block map (atom keys): quantities as integers, miner checksummed, blooms/hashes/roots/extra_data as 0x hex; transactions are tx hashes or decoded maps if full txs requested ({:ok, map | nil} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    block_id: %{
      description: "Block number (integer) or tag string (\"latest\", \"finalized\", \"pending\", \"earliest\", \"safe\", or \"0x...\" hex)",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, map | nil} | {:error, term}",
    description: "Decoded block map (atom keys): quantities as integers, miner checksummed, blooms/hashes/roots/extra_data as 0x hex; transactions are tx hashes or decoded maps if full txs requested",
    example: "%{number: 20_000_000, timestamp: 1_717_281_407, hash: \"0x...\", transactions: [\"0x...\", ...]}"
  }
}

get_block_by_number!(block_id, opts \\ [])

@spec get_block_by_number!(
  integer() | String.t(),
  keyword()
) :: map() | nil

Fetch a block by number or tag. Raises on error.

Parameters

block_id - Block number (integer) or tag string (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Decoded atom-keyed block map (map | nil)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    block_id: %{
      description: "Block number (integer) or tag string",
      kind: :value
    }
  },
  returns: %{type: "map | nil", description: "Decoded atom-keyed block map"}
}

get_proof(address, storage_keys, opts \\ [])

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

Fetch Merkle proof for an account and storage slots (eth_getProof).

Parameters

address - Account address as 0x hex string or 20-byte binary (value)
storage_keys - List of 0x-prefixed 32-byte hex storage slot keys (may be empty for account-only proofs) (value)
opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Atom-keyed proof map: address (checksummed), balance (integer wei), nonce (integer), code_hash (0x hex), storage_hash (0x hex), account_proof ([0x hex]), storage_proof ([%{key, value, proof}]) ({:ok, map} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    address: %{
      description: "Account address as 0x hex string or 20-byte binary",
      kind: :value
    },
    storage_keys: %{
      description: "List of 0x-prefixed 32-byte hex storage slot keys (may be empty for account-only proofs)",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, map} | {:error, term}",
    description: "Atom-keyed proof map: address (checksummed), balance (integer wei), nonce (integer), code_hash (0x hex), storage_hash (0x hex), account_proof ([0x hex]), storage_proof ([%{key, value, proof}])"
  }
}

get_proof!(address, storage_keys, opts \\ [])

@spec get_proof!(String.t() | binary(), [String.t()], keyword()) :: map()

Fetch Merkle proof for an account and storage slots. Raises on error.

Parameters

address - Account address as 0x hex string or 20-byte binary (value)
storage_keys - List of 0x-prefixed 32-byte hex storage slot keys (may be empty for account-only proofs) (value)
opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Atom-keyed proof map (see get_proof/3) (map)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    address: %{
      description: "Account address as 0x hex string or 20-byte binary",
      kind: :value
    },
    storage_keys: %{
      description: "List of 0x-prefixed 32-byte hex storage slot keys (may be empty for account-only proofs)",
      kind: :value
    }
  },
  returns: %{type: "map", description: "Atom-keyed proof map (see get_proof/3)"}
}

get_transaction_by_hash(tx_hash, opts \\ [])

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

Get full transaction details by hash (eth_getTransactionByHash).

Parameters

tx_hash - 0x-prefixed hex transaction hash (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Parsed transaction map, or nil if the transaction is unknown ({:ok, map | nil} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    tx_hash: %{description: "0x-prefixed hex transaction hash", kind: :value}
  },
  returns: %{
    type: "{:ok, map | nil} | {:error, term}",
    description: "Parsed transaction map, or nil if the transaction is unknown"
  }
}

get_transaction_by_hash!(tx_hash, opts \\ [])

@spec get_transaction_by_hash!(
  String.t(),
  keyword()
) :: map() | nil

Get full transaction details by hash. Raises on error.

Parameters

tx_hash - 0x-prefixed hex transaction hash (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Parsed transaction map or nil (map | nil)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    tx_hash: %{description: "0x-prefixed hex transaction hash", kind: :value}
  },
  returns: %{type: "map | nil", description: "Parsed transaction map or nil"}
}

get_transaction_count(address, opts \\ [])

@spec get_transaction_count(
  String.t() | binary(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, term()}

Get the transaction count (nonce) of an address.

Parameters

address - Account address as 0x hex string or 20-byte binary (value)
opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Transaction count (nonce) ({:ok, non_neg_integer} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    address: %{
      description: "Account address as 0x hex string or 20-byte binary",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, non_neg_integer} | {:error, term}",
    description: "Transaction count (nonce)"
  }
}

get_transaction_count!(address, opts \\ [])

@spec get_transaction_count!(
  String.t() | binary(),
  keyword()
) :: non_neg_integer()

Get the transaction count (nonce) of an address. Raises on error.

Parameters

address - Account address as 0x hex string or 20-byte binary (value)
opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Transaction count (nonce) (non_neg_integer)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    address: %{
      description: "Account address as 0x hex string or 20-byte binary",
      kind: :value
    }
  },
  returns: %{type: :non_neg_integer, description: "Transaction count (nonce)"}
}

get_transaction_receipt(tx_hash, opts \\ [])

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

Get a transaction receipt by hash (eth_getTransactionReceipt).

Parameters

tx_hash - 0x-prefixed hex transaction hash (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Parsed receipt map, or nil if the transaction is pending/unknown ({:ok, map | nil} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    tx_hash: %{description: "0x-prefixed hex transaction hash", kind: :value}
  },
  returns: %{
    type: "{:ok, map | nil} | {:error, term}",
    description: "Parsed receipt map, or nil if the transaction is pending/unknown"
  }
}

get_transaction_receipt!(tx_hash, opts \\ [])

@spec get_transaction_receipt!(
  String.t(),
  keyword()
) :: map() | nil

Get a transaction receipt by hash. Raises on error.

Parameters

tx_hash - 0x-prefixed hex transaction hash (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Parsed receipt map or nil (map | nil)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    tx_hash: %{description: "0x-prefixed hex transaction hash", kind: :value}
  },
  returns: %{type: "map | nil", description: "Parsed receipt map or nil"}
}

syncing(opts \\ [])

@spec syncing(keyword()) :: {:ok, false | map()} | {:error, term()}

Get the node's sync status (eth_syncing).

Parameters

opts - Options: :rpc_url, :timeout (default: [], value)

Returns

false when the node is fully synced; otherwise a raw sync-status map with hex-encoded fields (startingBlock, currentBlock, highestBlock, sometimes snap-sync fields). Field shape varies by client — caller decodes. ({:ok, false | map} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, false | map} | {:error, term}",
    description: "`false` when the node is fully synced; otherwise a raw sync-status map with hex-encoded fields (`startingBlock`, `currentBlock`, `highestBlock`, sometimes snap-sync fields). Field shape varies by client — caller decodes."
  }
}

syncing!(opts \\ [])

@spec syncing!(keyword()) :: false | map()

Get the node's sync status. Raises on error.

Parameters

opts - Options: :rpc_url, :timeout (default: [], value)

Returns

false when synced, sync-status map otherwise (false | map)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    }
  },
  returns: %{
    type: "false | map",
    description: "`false` when synced, sync-status map otherwise"
  }
}

Onchain.RPC (onchain v0.7.0)

Telemetry

Error Format

Revert errors (code: 3)

Functions

API Functions

Summary

Functions

Functions

batch(requests, opts \\ [])

block_number(opts \\ [])

Parameters

Returns

block_number!(opts \\ [])

Parameters

Returns

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

Parameters

Returns

call!(method, params, opts \\ [])

Parameters

Returns

chain_id(opts \\ [])

Parameters

Returns

chain_id!(opts \\ [])

Parameters

Returns

eth_call(address, data, opts \\ [])

Options

Revert handling

eth_call!(address, data, opts \\ [])

Parameters

Returns

eth_get_code(address, opts \\ [])

Parameters

Returns

eth_get_code!(address, opts \\ [])

Parameters

Returns

eth_get_logs(filter, opts \\ [])

Parameters

Returns

eth_get_logs!(filter, opts \\ [])

Parameters

Returns

eth_send_raw_transaction(data, opts \\ [])

Parameters

Returns

eth_send_raw_transaction!(data, opts \\ [])

Parameters

Returns

fee_history(block_count, opts \\ [])

Parameters

Returns

fee_history!(block_count, opts \\ [])

Parameters

Returns

get_balance(address, opts \\ [])

Parameters

Returns

get_balance!(address, opts \\ [])

Parameters

Returns

get_block_by_number(block_id, opts \\ [])

Parameters

Returns

get_block_by_number!(block_id, opts \\ [])

Parameters

Returns

get_proof(address, storage_keys, opts \\ [])

Parameters

Returns

get_proof!(address, storage_keys, opts \\ [])

Parameters

Returns

get_transaction_by_hash(tx_hash, opts \\ [])

Parameters

Returns

get_transaction_by_hash!(tx_hash, opts \\ [])

Revert errors (`code: 3`)