Runtime Modes
Runtime Modes
Section titled “Runtime Modes”ZEVM has exactly two runtime modes:
Normative sources:
docs/specs/prd.mdanddocs/specs/json-rpc-contract.md.
trusted: writable local development nodelight: proof-backed, consensus-anchored read-only runtime
Forking is configuration inside trusted mode, not a third mode.
Startup Selection
Section titled “Startup Selection”Mode is selected from startup inputs in this order:
- explicit CLI selector:
--mode trustedor--mode light - otherwise, the config mode branch (
mode.trustedormode.light) - otherwise, the trusted-mode default
Light-mode operator-facing startup inputs are network, consensusRpcUrl, and executionRpcUrl, with optional checkpoint controls (checkpoint, checkpointDir, maxCheckpointAgeSeconds, strictCheckpointAge).
If operators want persisted checkpoint-source behavior, they must manage checkpointDir/checkpoint themselves; ZEVM does not auto-populate it.
Proof-source internals are not user-configurable in the public contract.
Phase 1 Sequencing Note
Section titled “Phase 1 Sequencing Note”Phase 1 names the current public runtime/RPC scope in this docs set. GA posture here is source-build contract only (not packaged distribution channels). Within that scope, delivery remains trusted-first:
- trusted mode carries the primary local dev-node surface (writes, simulation, mining, snapshots, and fork overlay controls)
- light mode currently exposes readiness-gated proof-backed reads plus
zevm_lightSyncStatus - deferred or unsupported light-mode methods are tracked in Unsupported And Deferred
- deferred-surface promotion and phase-1 boundary/graduation criteria are canonicalized in Specs And Process
Mode Boundary
Section titled “Mode Boundary”| Surface | Trusted mode | Light mode |
|---|---|---|
Core reads (eth_chainId, eth_blockNumber, account/code/storage/nonce reads) | yes | yes (limited to eth_chainId, eth_blockNumber, and proof-backed account/code/storage/nonce reads) |
Simulation (eth_call, eth_estimateGas) | yes | no (-32010; both are trusted-only in phase 1, and eth_call remains a deferred light-mode proof-backed target) |
| Transaction submission and mining | yes | no |
Canonical block, receipt, and log queries (including eth_getLogs) | yes | no |
ZEVM trusted controls (zevm_* except zevm_lightSyncStatus) | yes | no |
Trusted compatibility aliases (anvil_*, selected hardhat_*, selected evm_*) | yes | no |
Light readiness/status (zevm_lightSyncStatus) | no | yes |
Methods unavailable in the active mode fail with -32010.
Compatibility alias acceptance is closed-world: accepted aliases are exactly those listed in the Accepted aliases columns on ZEVM Controls, Submission Methods, Mining And Txpool Methods, Time And Block-Environment Methods, and Fork-Source Methods.
Selector Semantics
Section titled “Selector Semantics”| Tag or selector | Trusted mode | Light mode |
|---|---|---|
latest | current local head | latest verified optimistic execution head |
pending | alias of latest | unsupported |
safe | alias of latest | consensus-anchored safe head |
finalized | alias of latest | consensus-finalized head |
earliest | block 0 | block 0 |
| numeric quantity | exact local block number | block 0, or an exact block inside the retained verified-history window |
Trusted-mode pending, safe, and finalized are compatibility aliases only.
In light mode:
eth_chainIdis always callableready = truecan be reached only afterstatustransitions tosyncedand ZEVM has accepted verified optimistic (latest), safe (safe), and finalized (finalized) heads- while
ready = true, verified-head ordering must hold:finalized <= safe <= latest - if
statusleavessyncedor slot coherence no longer holds (finalizedSlot <= safeSlot <= optimisticSlot), ZEVM setsready = falsein the same transition before serving the next readiness-gated RPC call - while
ready = false, proof-backed reads fail with-32011 - while
ready = false,eth_blockNumberalso fails with-32011 - once ready,
eth_blockNumberreturns thelatestlight-mode head number - numeric selectors are bounded to block
0and retained verified-history blocks - numeric selectors outside that retained window fail with
-32602
Where To Go Next
Section titled “Where To Go Next”- Quickstart: Run Trusted Mode
- Quickstart: Forked Dev Node
- Reference: Canonical Specs And Docs-First Process
- Reference: JSON-RPC Overview
- Reference: Core Reads
- Reference: Verified Light-Mode Reads
- Reference: Unsupported And Deferred
- Reference: Configuration Overview