Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Runtime Model and ZEVM

Tevm and ZEVM share execution primitives but are different products with different public interfaces.

  • Tevm is a JavaScript-first in-memory node, viem transport, EIP-1193 provider, and package family.
  • ZEVM is the native Zig client with CLI/runtime docs for trusted mode and light mode.
  • Tevm docs should describe Tevm APIs first, then link to ZEVM for the native client contract.

Tevm Runtime Shapes

Local writable node

The default Tevm node is a writable local Ethereum execution environment. It supports local accounts, state mutation, transaction submission, mining controls, snapshots, traces, and the full JSON-RPC method set in the JSON-RPC Guide.

This is the Tevm equivalent of ZEVM's trusted-mode development-node docs, with Tevm's JavaScript APIs and broader compatibility namespaces.

Start here: Creating a Tevm Node · Mining Modes · Managing State · Local Testing Flow

Forked local node

Forking is configuration on top of the writable local node, not a separate runtime. Tevm fetches remote state lazily, caches it locally, and stores local writes in an overlay.

Start here: Forking and Reforking · Forking Mainnet · Managing State

This matches the boundary in ZEVM's State Fork and Snapshots docs: the fork source is a read source; local writes belong to the local overlay.

Optional light-client consensus service

Tevm can be configured with an injected consensus service for proof-aware reads. This is not the same as running the native ZEVM light-mode binary. In Tevm, the consensus service affects specific read paths and light-sync status inside a JavaScript node.

When consensus.mode is light-client, these RPC paths use consensus/readiness/proof hooks:

  • eth_chainId
  • eth_blockNumber
  • eth_getBalance
  • eth_getCode
  • eth_getStorageAt
  • eth_getTransactionCount
  • tevm_lightSyncStatus
  • zevm_lightSyncStatus

The rest of the Tevm node remains Tevm's JavaScript runtime surface unless the application restricts it. For the native ZEVM light-mode contract (startup checkpoints, selector rules, readiness gating, mode-unsupported error codes), see ZEVM's Light Mode and Verified Light-Mode Reads docs.

ZEVM Docs Cross-Reference

ZEVM has a strong docs split that Tevm mirrors through Tevm-specific guides rather than copying native CLI details directly.

ZEVM docs areaTevm version
InstallationGetting Started, Creating a Tevm Node, and package docs. Tevm installs from npm; native Zig build steps belong to ZEVM.
Run Trusted ModeCreating a Tevm Node, Local Testing Flow, Mining Modes.
Forked Dev NodeForking and Reforking, Forking Mainnet.
Run Light ModeTevm's injectable consensus service and tevm_lightSyncStatus/zevm_lightSyncStatus compatibility docs. Use ZEVM's page for the native CLI light client.
TroubleshootingSplit by surface: Bundler Troubleshooting, Forking and Reforking, JSON-RPC errors in JSON-RPC Guide.
Runtime ModesThis page. Tevm has local, forked local, and optional injected light-client consensus — not the same CLI mode selector as ZEVM.
Trusted ModeTevm's local writable node docs: Creating a Tevm Node, Mining Modes, Managing State, Account Management.
Light ModeTevm's light-client consensus notes on this page plus tevm_lightSyncStatus in JSON-RPC Guide. Use ZEVM docs for full native light-mode operation.
State Fork and SnapshotsForking and Reforking, Managing State, including checkpoint, dump/load, snapshot, and revert flows.
Method Support by ModeJSON-RPC Guide. Tevm documents every registered method and calls out compatibility stubs/aliases.
Architecture and Upstream OwnershipArchitecture Overview, VM and Submodules, and package references explaining which Tevm facades are backed by ZEVM packages.
Configuration ReferenceCreating a Tevm Node, Forking and Reforking, Mining Modes. Tevm config is JS options, not a ZEVM CLI JSON config.
JSON-RPC OverviewJSON-RPC Guide: EIP-1193 usage, error handling, exhaustive method index.
Core ReadsMethods Overview, JSON-RPC Guide, and viem-compatible read actions on createMemoryClient.
Managed Dev WalletAccount Management, Methods Overview, JSON-RPC Guide.
SimulationCall API, Methods Overview, eth_call/eth_estimateGas in JSON-RPC Guide.
Transactions and MiningMining Modes, Transaction Pool, tx methods in JSON-RPC Guide.
Blocks, Receipts, and LogsReceipts and Logs, Block reference, block/log methods in JSON-RPC Guide.
ZEVM ControlsControl methods in JSON-RPC Guide, Account Management, Managing State, Mining Modes.
Unsupported and DeferredTevm does not inherit ZEVM's unsupported list. Tevm supports many debug, filter, subscription, txpool, Engine API, Anvil, Hardhat, Ganache, and EVM compatibility methods ZEVM marks deferred. Source of truth: JSON-RPC Guide.

Compatibility Rules

Tevm's canonical custom namespace is tevm_*. ZEVM's canonical native namespace is zevm_*.

Tevm exposes only low-risk zevm_* aliases where semantics match. Today that means zevm_lightSyncStatus as an alias for tevm_lightSyncStatus. Other ZEVM-native control names should not be assumed to work in Tevm unless they appear in JSON-RPC Guide.

When writing Tevm docs:

  • Use tevm_* for Tevm-specific methods.
  • Mention zevm_lightSyncStatus only as a compatibility alias.
  • Link to ZEVM docs for native CLI mode selection, trusted/light mode operation, release metadata, and exact ZEVM JSON-RPC contracts.
  • Keep Tevm method support grounded in Tevm's registered handler map and JSON-RPC guide.

Next Steps

Creating a Tevm Node · Forking and Reforking · Managing State · JSON-RPC Guide · ZEVM Docs