Philosophy

This module is an un-opinionated representation of the Ethereum execution APIs — every JSON-RPC eth_* method as a tree-shakable primitive function. Methods come in three shapes:

• Readable<T> for state queries (eth_getBalance, eth_getBlockByHash, …) — consumed by a reader resolver.
• Writable<T> for state mutations (eth_sendRawTransaction) — consumed by a writer resolver.
• Signable<T> for wallet operations (eth_signTransaction, eth_sign, eth_sendTransaction) — consumed by a signer resolver.

This package is also the canonical home of the JSON-RPC Ethereum schemas — block / receipt / generic-transaction / variant-signed-transaction. Primitive schemas (AddressSchema, BytesSchema, UintSchema, …) live in @ethernauta/core; per-EIP transaction wire schemas (Transaction1559SignedSchema, AccessListSchema, Transaction4844UnsignedSchema, …) live in @ethernauta/eip/<n> and are imported from there.

Modules

• abi [NPM]
• chain [NPM]
• cli [NPM]
• core [NPM]
• crypto [NPM]
• eip [NPM]
• ens [NPM]
• erc [NPM]
• eth [NPM]
• react [NPM]
• transaction [NPM]
• transport [NPM]
• utils [NPM]
• wallet

API

Every method is curried — method(args)(resolver({ chain_id, …ctx })) — and is one of the four resolver shapes exported by @ethernauta/transport.

Client methods — Readable<T>

import {
  eth_accounts,
  eth_blockNumber,
  eth_chainId,
  eth_coinbase,
  eth_syncing,
} from "@ethernauta/eth"

const chainId = await eth_chainId()(reader({ chain_id }))
const head = await eth_blockNumber()(reader({ chain_id }))

Block methods — Readable<T>

import {
  eth_getBlockByHash,
  eth_getBlockByNumber,
  eth_getBlockReceipts,
  eth_getBlockTransactionCountByHash,
  eth_getBlockTransactionCountByNumber,
  eth_getUncleCountByBlockHash,
  eth_getUncleCountByBlockNumber,
} from "@ethernauta/eth"

const block = await eth_getBlockByHash([
  "0x31386e6cfba70bb4d8a95404bdb740572b758a15c62e51ee912071a7b5be9e26",
  false,
])(reader({ chain_id }))

Transaction methods — Readable<T>

import {
  eth_getTransactionByBlockHashAndIndex,
  eth_getTransactionByBlockNumberAndIndex,
  eth_getTransactionByHash,
  eth_getTransactionReceipt,
} from "@ethernauta/eth"

const receipt = await eth_getTransactionReceipt([hash])(reader({ chain_id }))

State methods — Readable<T>

import {
  eth_getBalance,
  eth_getCode,
  eth_getProof,
  eth_getStorageAt,
  eth_getTransactionCount,
} from "@ethernauta/eth"

const balance = await eth_getBalance([address, "latest"])(reader({ chain_id }))

Execute methods — Readable<T>

import {
  eth_call,
  eth_createAccessList,
  eth_estimateGas,
} from "@ethernauta/eth"

Fee market — Readable<T>

import {
  eth_feeHistory,
  eth_gasPrice,
  eth_maxPriorityFeePerGas,
} from "@ethernauta/eth"

Filters — Readable<T> + Writable<T>

import {
  eth_getContractEvents,
  eth_getFilterChanges,
  eth_getFilterLogs,
  eth_getLogs,
  eth_newBlockFilter,
  eth_newFilter,
  eth_newPendingTransactionFilter,
  eth_uninstallFilter,
} from "@ethernauta/eth"

Subscriptions

import {
  eth_subscribeLogs,
  eth_subscribeNewHeads,
  eth_subscribeNewPendingTransactions,
} from "@ethernauta/eth"

Subscription methods consume a websocket transport (see websocket() in @ethernauta/transport) and resolve with an Unsubscribe function.

Signing — Signable<T>

import { eth_sign, eth_signTransaction } from "@ethernauta/eth"
import { number_to_hex } from "@ethernauta/utils"
import { signer, writer, SEPOLIA_CHAIN_ID } from "./resolvers"

// `eth_signTransaction` returns the raw signed payload —
// path 2: dapp broadcasts via `eth_sendRawTransaction`.
const signed_transaction = await eth_signTransaction([
  {
    to: "0x636c0fcd6da2207abfa80427b556695a4ad0af94",
    value: number_to_hex(1),
  },
])(signer({ chain_id: SEPOLIA_CHAIN_ID }))

Submitting — Writable<T> + Signable<T>

import { eth_sendRawTransaction, eth_sendTransaction } from "@ethernauta/eth"

// Path 2 — dapp pre-signs and broadcasts
const hash = await eth_sendRawTransaction([signed_transaction])(
  writer({ chain_id: SEPOLIA_CHAIN_ID }),
)

// Path 1 — wallet signs and broadcasts in one step
const hash2 = await eth_sendTransaction([{
  to: "0x…",
  value: number_to_hex(1),
}])(signer({ chain_id: SEPOLIA_CHAIN_ID }))

Reacting to transaction states

import { eth_getTransactionReceipt } from "@ethernauta/eth"
import { hex_to_number } from "@ethernauta/utils"

// Single-hash UI tracking — inline ~10-line poll. The wallet
// owns batched-call tracking via EIP-5792 (wallet_getCallsStatus);
// for a typed multi-tx tracker (subscription + persistence) see
// `@ethernauta/transaction`.
const interval_id = setInterval(async () => {
  const receipt = await eth_getTransactionReceipt([hash])(reader({ chain_id }))
  if (!receipt || !receipt.status) return
  const status = hex_to_number(receipt.status) === 1 ? "mined" : "reverted"
  clearInterval(interval_id)
}, 2000)

Schemas + RLP helpers

import {
  ReceiptInfoSchema,
  RECEIPT_STATUS,
  is_post_byzantium,
  EthSignTransactionParametersSchema,
  // block / transaction / withdrawal / filter schemas …
} from "@ethernauta/eth"

import { encode_rlp, type RLPInput } from "@ethernauta/eth"

The lib subtree exposes the post-Byzantium receipt helper (is_post_byzantium, RECEIPT_STATUS, ReceiptStatusSchema, PostByzantiumReceiptSchema) plus the typed RLP encoder used by transaction-builders. EthSignTransactionParametersSchema is the parameter shape consumed by both eth_signTransaction (path 2) and the wallet's eth_sendTransaction handler.

Gas + 1559 fee math

The gas subtree concentrates the L1-mainnet fee primitives previously housed in a separate @ethernauta/gas package (now retired). Composing these helpers on top of eth_feeHistory / eth_maxPriorityFeePerGas / eth_estimateGas is path 2 territory — no wallet involved.

import {
  estimate_1559_fees,        // base-fee math + priority fee + buffer
  estimate_priority_fee,     // priority-fee suggestion from eth_feeHistory
  buffer_gas_limit,          // multiply estimateGas result by a safety factor
  type Fees1559,
} from "@ethernauta/eth"

L2-specific fee math lives in the matching rollup package:

• OP-Stack — estimate_op_fees in @ethernauta/op.
• Arbitrum — estimate_arbitrum_fees in @ethernauta/arbitrum.
• zkSync Era — gas surface in @ethernauta/zksync.