Onchain

Ethereum library with RPC, ABI encoding/decoding and transaction signing. The former hieroglyph and cartouche libraries ship here; since 0.16.0 their ABI.* and Cartouche.* modules are Onchain.ABI.* and Onchain.* (see the CHANGELOG migration section). ABI, transaction and EIP-712 codecs use the core alloy Rust NIF. Cryptography uses the existing Keccak and secp256k1 NIF dependencies.

Package Family

EVM simulation and the JavaScript bridge remain separate optional packages.

Installation

def deps do
  [
    {:onchain, "~> 0.16"},
    # Add if you need Aave:
    {:onchain_aave, "~> 0.1"},
    # Add if you need EVM simulation / Solidity parsing:
    {:onchain_evm, "~> 0.1"},
    # Add if you need JS bridge (solc-js, Uniswap SDK, etc.):
    {:onchain_js, "~> 0.1"},
    # Add if you need Tempo chain (0x76 transactions, TIP-20 tokens):
    {:onchain_tempo, "~> 0.1"}
  ]
end

Requires an Ethereum JSON-RPC endpoint. Configure via:

# config/config.exs
config :cartouche, :ethereum_node, "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"

Or pass rpc_url: url or ethereum_node: url per call to either RPC module (:rpc_url takes precedence). Without either option or the application default, requests return {:error, {:missing_option, :ethereum_node}}.

Single calls and JSON-RPC array batches now share Onchain.RPC's transport. Configure transport defaults with config :cartouche, Onchain.RPC, [...], then config :cartouche, :req_options, [...]; per-call req_options: [...] takes highest precedence. Migrate former batch settings under :onchain, Onchain.RPC and :onchain, :req_options to these :cartouche keys for RPC. The :onchain settings still apply to the CCIP-Read HTTP gateway.

Opt into transport retries with retry: [max_retries: 2, backoff_ms: 100] on raw, typed, or batch calls. JSON-RPC errors are final; decoding does not resend a request. Each call emits one [:onchain, :rpc, :request] telemetry span, including all retry attempts, with the existing method, status, and error metadata. All RPC calls go through Onchain.RPC and return the same tagged node refusals.

Node compatibility

Onchain is built to run against any mainstream Ethereum JSON-RPC endpoint — Alchemy, Infura, QuickNode, a self-hosted Geth/reth/Erigon, pruned or archive. That portability is a deliberate constraint, not an accident: the maintainers develop against a full archive node, and anything that only works there is treated as a bug.

Everything in Onchain.RPC, Onchain.ERC20, Onchain.ERC721, Onchain.ERC1155, Onchain.Contract, Onchain.Block, Onchain.Multicall and Onchain.ENS uses standard methods and needs no special endpoint. These surfaces depend on what your provider serves:

Each of those error terms is classified on the shared Onchain.RPC transport path so a codegen'd wrapper, a hand-written wrapper, call/3 and batch/2 apply the same rules to the same wire response. Note that a provider may not send the same wire response in both modes — Alchemy reports pruned history as -32001 to a single call but as a generic -32000 "Internal error" inside an array batch, so a batched capability probe can come back unclassified. Unrecognized JSON-RPC codes still arrive as {:error, {:rpc_error, map}}. See Onchain.RPC's moduledoc § "Node-capability refusals" for the pinned message shapes and for the finding that -32001 is not uniquely pruned history (Alchemy answers it for some unimplemented methods too).

Onchain.RPC.base_fee/1 returns the next block's fee from eth_feeHistory, which Alchemy and Infura mainnet serve; it does not call eth_baseFee or read the pending header. Onchain.RPC.blob_base_fee/1 still wraps eth_blobBaseFee. The probe, the hosted refusals, and why fee history won are in docs/base-fee-portability.md.

If you hit a method that works on your node but not on a common hosted provider, that's a portability bug worth reporting.

Quick Start

# Read an ERC-20 token balance (USDC on mainnet)
usdc = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
{:ok, balance} = Onchain.ERC20.balance_of(usdc, "0xYourAddress")

# Resolve an ENS name (UTS-46/ENSIP-15 normalized before namehash)
{:ok, address} = Onchain.ENS.resolve("vitalik.eth")

# Multi-coin / wildcard / CCIP-Read resolution: walks parent labels for a
# wildcard resolver (ENSIP-10) and follows EIP-3668 OffchainLookup reverts.
{:ok, eth_bytes} = Onchain.ENS.address("vitalik.eth", 60)
{:ok, op_bytes} = Onchain.ENS.address("name.eth", Onchain.ENS.evm_coin_type(10))

# Generic contract call (encode -> eth_call -> decode)
{:ok, [name]} = Onchain.Contract.call(usdc, "name()", [], "(string)")

# All functions have bang variants that raise on error
balance = Onchain.ERC20.balance_of!(usdc, "0xYourAddress")

# EIP-1559 fee suggestion: fetch history, compute base/priority/max in one go.
# `:reward_percentiles` is required — non-empty, monotonically non-decreasing list of integers in 0..100.
{:ok, history} = Onchain.RPC.fee_history(20, reward_percentiles: [50])
{:ok, {base_fee, max_priority, max_fee}} = Onchain.Fees.suggest_fees(history)

# Gas-limit estimation (eth_estimateGas) over a tx-params map
{:ok, gas} = Onchain.RPC.eth_estimate_gas(%{from: from, to: token, data: calldata})

# send_transaction auto-estimates the gas limit (with 1.25x headroom) when :gas_limit
# is omitted — so stale hardcoded limits can't OOG-revert. Pass :gas_limit to opt out.
{:ok, tx_hash} =
  Onchain.ERC20.transfer(token, recipient, amount,
    private_key: key, nonce: nonce, chain_id: 1, rpc_url: url
  )

# Decode a Solidity 0.8.4+ custom-error revert against a list of candidate signatures
{:ok, %{error: "OwnableUnauthorizedAccount", args: [_addr]}} =
  Onchain.ABI.decode_hex_error(
    "0x118cdaa7000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045",
    ["OwnableUnauthorizedAccount(address)"]
  )

# After an eth_call that reverts with a custom error, use :data from the rpc_error map:
# {:error, {:rpc_error, %{data: revert_hex}}} -> Onchain.ABI.decode_hex_error(revert_hex, [...])

Modules

Core

Chain Intelligence

DeFi

Account Abstraction (ERC-4337)

Most read functions (Onchain.RPC, Onchain.ERC20/ERC721/ERC1155, Onchain.Block, Onchain.DEX.Router.amount_out_v2, …) expose a function!/1 bang variant that raises on error instead of returning {:error, reason}. Newer composite modules (Onchain.MEV, Onchain.AA, Onchain.ERC7730, Onchain.DEX.Router.route/quote_pool) return tagged tuples only — no bang variant.

Real-time Subscriptions

Stream new blocks, pending transactions, and event logs via WebSocket:

# Connect to a WebSocket endpoint
{:ok, sub} = Onchain.Subscription.connect("wss://eth-mainnet.g.alchemy.com/v2/KEY")

# Subscribe to new block headers
{:ok, sub_id} = Onchain.Subscription.subscribe(sub, :new_heads)

# Events arrive as messages to the calling process
receive do
  {:subscription, {:new_heads, ^sub_id, head}} ->
    IO.inspect(head.number, label: "new block")
end

# Or provide a custom handler
{:ok, sub} = Onchain.Subscription.connect("wss://...",
  handler: fn {:new_heads, _id, head} -> Logger.info("Block #{head.number}") end
)

# Subscribe to filtered event logs
{:ok, _} = Onchain.Subscription.subscribe(sub, {:logs, %{
  address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  topics: [Onchain.Transfer.transfer_topics()]
}})

# Clean up
Onchain.Subscription.unsubscribe(sub, sub_id)
Onchain.Subscription.close(sub)

Requires a WebSocket-capable endpoint (wss:// or ws://), separate from the HTTP RPC URL.

Discovery

All modules use descripex for self-describing APIs:

Onchain.describe()                  # List of all annotated modules (one summary per module)
Onchain.describe(:hex)              # Function summary list for a module
Onchain.describe(:hex, :decode)     # Function detail map (params, errors, returns)

Testing

mix test.json --quiet                          # Unit tests (no RPC needed)
mix test.json --quiet --include integration    # Integration tests (requires RPC)

Differential tests compare Onchain.RPC against independently decoded raw JSON-RPC on the same node (opt-in, requires mainnet RPC):

export ONCHAIN_DIFFERENTIAL_TESTS=1
export ETHEREUM_API_URL="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
mix test.json --quiet --include differential test/onchain/differential

Integration tests require an Ethereum RPC endpoint:

export ETHEREUM_API_URL="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"

WebSocket subscription tests require a WebSocket endpoint:

export ETHEREUM_WS_URL="wss://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"

Sepolia write tests additionally require ETH_SEPOLIA_RPC_URL and SIGNER_PRIVATE_KEY.

License

MIT