JSON-RPC Support
Tevm Node provides EIP-1193-compatible JSON-RPC support for integration with Ethereum libraries and tools.
EIP-1193 Provider
import { createTevmNode } from 'tevm'
import { requestEip1193 } from 'tevm/decorators'
const node = createTevmNode().extend(requestEip1193())
const blockNum = await node.request({ method: 'eth_blockNumber', params: [] })Supported Methods
For Tevm's runtime model and the mapping to ZEVM's native trusted/light-mode docs, see Runtime Model and ZEVM. Native ZEVM has its own mode-gated JSON-RPC Overview and Verified Light-Mode Reads contract; the index below is the Tevm source of truth.
Engine API methods are only registered when engineApi is enabled. tevm_*, hardhat_*, and ganache_* development-control aliases share implementations with matching anvil_* methods. tevm_contract and eth_sendUnsignedTransaction are registered compatibility stubs returning unsupported-method errors.
Tevm and ZEVM compatibility
Native Tevm methods:
tevm_calltevm_contracttevm_dumpStatetevm_getAccounttevm_lightSyncStatustevm_loadStatetevm_minetevm_minertevm_setAccountzevm_lightSyncStatus
Tevm aliases for development controls:
tevm_addBalancetevm_autoImpersonateAccounttevm_dealtevm_dealErc20tevm_dropAllTransactionstevm_dropTransactiontevm_enableTracestevm_getAutominetevm_getIntervalMiningtevm_impersonateAccounttevm_increaseTimetevm_metadatatevm_mineDetailedtevm_nodeInfotevm_removeBlockTimestampIntervaltevm_removePoolTransactionstevm_resettevm_reverttevm_setAutominetevm_setBalancetevm_setBlockGasLimittevm_setBlockTimestampIntervaltevm_setChainIdtevm_setCodetevm_setCoinbasetevm_setErc20Allowancetevm_setIntervalMiningtevm_setLoggingEnabledtevm_setMinGasPricetevm_setNextBlockBaseFeePerGastevm_setNextBlockTimestamptevm_setNoncetevm_setPrevRandaotevm_setRpcUrltevm_setStorageAttevm_setTimetevm_snapshottevm_stopImpersonatingAccount
Ethereum
eth_accountseth_blobBaseFeeeth_blobGasPriceeth_blockNumbereth_calleth_chainIdeth_coinbaseeth_createAccessListeth_estimateGaseth_feeHistoryeth_gasPriceeth_getBalanceeth_getBlockAccessListeth_getBlockByHasheth_getBlockByNumbereth_getBlockReceiptseth_getBlockTransactionCountByHasheth_getBlockTransactionCountByNumbereth_getCodeeth_getFilterChangeseth_getFilterLogseth_getLogseth_getProofeth_getStorageAteth_getStorageValueseth_getTransactionByBlockHashAndIndexeth_getTransactionByBlockNumberAndIndexeth_getTransactionByHasheth_getTransactionCounteth_getTransactionReceipteth_getUncleByBlockHashAndIndexeth_getUncleByBlockNumberAndIndexeth_getUncleCountByBlockHasheth_getUncleCountByBlockNumbereth_getWorketh_hashrateeth_maxPriorityFeePerGaseth_miningeth_newBlockFiltereth_newFiltereth_newPendingTransactionFiltereth_protocolVersioneth_sendRawTransactioneth_sendTransactioneth_sendUnsignedTransactioneth_signeth_signTransactioneth_simulateV1eth_simulateV2eth_submitHashrateeth_submitWorketh_subscribeeth_syncingeth_uninstallFiltereth_unsubscribe
Anvil
anvil_addBalanceanvil_autoImpersonateAccountanvil_dealanvil_dealErc20anvil_dropAllTransactionsanvil_dropTransactionanvil_dumpStateanvil_enableTracesanvil_getAutomineanvil_getIntervalMininganvil_impersonateAccountanvil_increaseTimeanvil_loadStateanvil_metadataanvil_mineanvil_mineDetailedanvil_nodeInfoanvil_removeBlockTimestampIntervalanvil_removePoolTransactionsanvil_resetanvil_revertanvil_setAutomineanvil_setBalanceanvil_setBlockGasLimitanvil_setBlockTimestampIntervalanvil_setChainIdanvil_setCodeanvil_setCoinbaseanvil_setErc20Allowanceanvil_setIntervalMininganvil_setLoggingEnabledanvil_setMinGasPriceanvil_setNextBlockBaseFeePerGasanvil_setNextBlockTimestampanvil_setNonceanvil_setPrevRandaoanvil_setRpcUrlanvil_setStorageAtanvil_setTimeanvil_snapshotanvil_stopImpersonatingAccount
Hardhat
hardhat_addBalancehardhat_autoImpersonateAccounthardhat_dealhardhat_dealErc20hardhat_dropAllTransactionshardhat_dropTransactionhardhat_dumpStatehardhat_enableTraceshardhat_getAutominehardhat_getIntervalMininghardhat_impersonateAccounthardhat_increaseTimehardhat_loadStatehardhat_metadatahardhat_minehardhat_mineDetailedhardhat_nodeInfohardhat_removeBlockTimestampIntervalhardhat_removePoolTransactionshardhat_resethardhat_reverthardhat_setAutominehardhat_setBalancehardhat_setBlockGasLimithardhat_setBlockTimestampIntervalhardhat_setChainIdhardhat_setCodehardhat_setCoinbasehardhat_setErc20Allowancehardhat_setIntervalMininghardhat_setLoggingEnabledhardhat_setMinGasPricehardhat_setNextBlockBaseFeePerGashardhat_setNextBlockTimestamphardhat_setNoncehardhat_setPrevRandaohardhat_setRpcUrlhardhat_setStorageAthardhat_setTimehardhat_snapshothardhat_stopImpersonatingAccount
Ganache
ganache_addBalanceganache_autoImpersonateAccountganache_dealganache_dealErc20ganache_dropAllTransactionsganache_dropTransactionganache_dumpStateganache_enableTracesganache_getAutomineganache_getIntervalMiningganache_impersonateAccountganache_increaseTimeganache_loadStateganache_metadataganache_mineganache_mineDetailedganache_nodeInfoganache_removeBlockTimestampIntervalganache_removePoolTransactionsganache_resetganache_revertganache_setAutomineganache_setBalanceganache_setBlockGasLimitganache_setBlockTimestampIntervalganache_setChainIdganache_setCodeganache_setCoinbaseganache_setErc20Allowanceganache_setIntervalMiningganache_setLoggingEnabledganache_setMinGasPriceganache_setNextBlockBaseFeePerGasganache_setNextBlockTimestampganache_setNonceganache_setPrevRandaoganache_setRpcUrlganache_setStorageAtganache_setTimeganache_snapshotganache_stopImpersonatingAccount
Debug
debug_dumpBlockdebug_getBadBlocksdebug_getModifiedAccountsByHashdebug_getModifiedAccountsByNumberdebug_getRawBlockdebug_getRawHeaderdebug_getRawReceiptsdebug_getRawTransactiondebug_intermediateRootsdebug_preimagedebug_storageRangeAtdebug_traceBlockdebug_traceBlockByHashdebug_traceBlockByNumberdebug_traceCalldebug_traceChaindebug_traceStatedebug_traceTransaction
EVM test-runner compatibility
evm_increaseTimeevm_mineevm_revertevm_setBlockGasLimitevm_setIntervalMiningevm_setNextBlockTimestampevm_snapshot
Engine API
engine_exchangeCapabilitiesengine_exchangeTransitionConfigurationV1engine_forkchoiceUpdatedV1engine_forkchoiceUpdatedV2engine_forkchoiceUpdatedV3engine_forkchoiceUpdatedV4engine_getBlobsV1engine_getBlobsV2engine_getBlobsV3engine_getClientVersionV1engine_getPayloadBodiesByHashV1engine_getPayloadBodiesByHashV2engine_getPayloadBodiesByRangeV1engine_getPayloadBodiesByRangeV2engine_getPayloadV1engine_getPayloadV2engine_getPayloadV3engine_getPayloadV4engine_getPayloadV5engine_getPayloadV6engine_newPayloadV1engine_newPayloadV2engine_newPayloadV3engine_newPayloadV4engine_newPayloadV5testing_buildBlockV1
Txpool, web3, net, rpc, and miner compatibility
miner_startminer_stopnet_listeningnet_peerCountnet_versionrpc_modulestxpool_contenttxpool_contentFromtxpool_inspecttxpool_statusweb3_clientVersionweb3_sha3
Client Integration
Viem
See Viem Documentation.
import { createTevmTransport } from 'tevm'
import { createPublicClient, custom } from 'viem'
import { requestEip1193 } from 'tevm/decorators'
const tevmTransport = createTevmTransport()
const client = createPublicClient({ chain: mainnet, transport: tevmTransport })Ethers
See Ethers Documentation.
import { createTevmNode } from 'tevm'
import { BrowserProvider } from 'ethers'
import { requestEip1193 } from 'tevm/decorators'
const node = createTevmNode().extend(requestEip1193())
const provider = new BrowserProvider(node)Error Handling
JSON-RPC errors follow the standard format and are fully typed. See JsonRpcError type:
interface JsonRpcError {
code: number
message: string
data?: unknown
}Common codes (see ErrorCodes):
-32700: Parse error (ParseError)-32600: Invalid request (InvalidRequest)-32601: Method not found (MethodNotFound)-32602: Invalid params (InvalidParams)-32603: Internal error (InternalError)-32000to-32099: Server error (ServerError)
See Error Handling Guide.
Best Practices
Wrap RPC calls in try-catch. Estimate gas before sending (ErrorCodes):
const gasEstimate = await node.request({ method: 'eth_estimateGas', params: [tx] })Wait for receipts (ethGetTransactionReceipt):
const txHash = await node.request({ method: 'eth_sendTransaction', params: [tx] })
const receipt = await node.request({ method: 'eth_getTransactionReceipt', params: [txHash] })Filter efficiently: set block ranges, use specific topics, clean up with eth_uninstallFilter.
See:
Related Topics
- Using with Viem
- Using with Ethers
- Managing State
- Receipts & Logs
- Ethereum JSON-RPC Specification
- EIP-1193
- Tevm API Documentation
Using Tevm Actions
High-level actions from tevm/actions (see actions docs):
import {
tevmCall,
tevmMine,
tevmGetAccount,
tevmSetAccount,
tevmDeal
} from 'tevm/actions'
import { createTevmNode } from 'tevm'
const node = createTevmNode()
const result = await tevmCall(node, {
to: '0x...',
data: '0x...',
value: 0n,
createTransaction: true
})
await tevmMine(node)
const account = await tevmGetAccount(node, { address: '0x...', blockTag: 'latest' })
await tevmSetAccount(node, {
address: '0x...',
balance: 100n,
nonce: 0n,
deployedBytecode: '0x...'
})
// Native ETH
await tevmDeal(node, {
account: '0x...',
amount: 1000000000000000000n // 1 ETH
})
// ERC20
await tevmDeal(node, {
erc20: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', // USDC mainnet
account: '0x...',
amount: 1000000n // 1 USDC (6 decimals)
})Type references:
Optimistic Updates with Receipt Manager
See Ethereum Receipts.
import { createTevmNode } from 'tevm'
import { tevmCall, tevmMine } from 'tevm/actions'
const node = createTevmNode()
const receiptsManager = await node.getReceiptsManager()
// Submit
const { txHash } = await tevmCall(node, {
method: 'eth_sendTransaction',
params: [tx],
createTransaction: true
})
const pendingReceipt = await receiptsManager.getReceiptByTxHash(txHash)
updateUI(pendingReceipt)
const realReceipt = await node.request({
method: 'eth_getTransactionReceipt',
params: [txHash]
})
if (receiptsAreDifferent(pendingReceipt, realReceipt)) {
await receiptsManager.removeReceipt(txHash)
updateUI(realReceipt)
}
// Rebase on new blocks
node.on('block', async (blockNumber) => {
const block = await node.request({
method: 'eth_getBlockByNumber',
params: [blockNumber, true]
})
const pendingTxs = await receiptsManager.getPendingTransactions()
for (const tx of pendingTxs) {
const result = await tevmCall(node, { ...tx, blockTag: 'pending' })
await receiptsManager.putReceipt(tx.hash, result)
}
await tevmMine(node)
})