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' })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 { mainnet } from 'tevm/common'
import { createPublicClient } from 'viem'
const tevmTransport = createTevmTransport()
const client = createPublicClient({ chain: mainnet, transport: tevmTransport })Ethers
See Ethers Documentation.
import { createMemoryClient } from 'tevm'
import { BrowserProvider } from 'ethers'
const client = createMemoryClient()
const provider = new BrowserProvider(client)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 action functions are exported by tevm. Handler factories and parameter/result types are exported by tevm/actions.
import {
createMemoryClient,
tevmCall,
tevmMine,
tevmGetAccount,
tevmSetAccount,
} from 'tevm'
const client = createMemoryClient()
const address = '0x1111111111111111111111111111111111111111'
const result = await tevmCall(client, {
to: address,
value: 0n,
})
await tevmMine(client, { blockCount: 1 })
const account = await tevmGetAccount(client, {
address,
blockTag: 'latest',
})
await tevmSetAccount(client, {
address,
balance: 100n,
nonce: 0n,
deployedBytecode: '0x',
})Type references:
Tevm calls are simulations unless they create a transaction. Use addToMempool: true and mine for a receipt, or configure { miningConfig: { type: 'auto' } }.