ZEVM
ZEVM is a Zig Ethereum client with two runtime modes:
- Trusted mode: a writable local dev node with mining controls, transaction submission, and ZEVM dev methods.
- Light mode: a read-only, proof-backed, consensus-anchored client for execution reads.
Forking is trusted-mode configuration, not a separate runtime mode.
ZEVM is under active development. For version-specific behavior, check the ZEVM release notes and the reference pages in this docs site.
Current Public Contract
Section titled “Current Public Contract”For current scope, route to canonical sources instead of restated checklists:
- product/runtime and JSON-RPC contract boundaries: Canonical Specs
- startup/config precedence and operator contract: Configuration Overview
- deferred-surface promotion and boundary/graduation criteria: Specs And Process
The current contract remains source-first. Release artifact jobs may publish CLI binaries, C ABI libraries, and npm native packages, but byte-identical reproducible-build guarantees, signing/notarization, and installer UX are still out of scope. For release/build metadata routing, see Release Metadata And Behavior Deltas.
Choose Your Path
Section titled “Choose Your Path”| I want to… | Start here |
|---|---|
| Install from source and run ZEVM locally | Installation |
| Start a local trusted dev node | Run Trusted Mode |
| Start trusted mode against an upstream fork | Forked Dev Node |
| Run the proof-backed, consensus-anchored light client | Run Light Mode |
| Jump to authoritative contract source files | Canonical Specs |
| Follow docs-first update order and release/qualification policy | Specs And Process |
| Reproduce release metadata and operator provenance | Release Metadata Runbook |
| Check behavior changes by release | ZEVM Release Notes (GitHub) |
| Fix startup, configuration, or RPC issues | Troubleshooting |
Canonical Specs And Process
Section titled “Canonical Specs And Process”- contract-source index page: Canonical Specs
- process/policy page: Specs And Process
- active public contract sources:
docs/specs/prd.mdanddocs/specs/json-rpc-contract.md - contract-affecting changes are docs-first: update the canonical spec sources first, then land implementation/docs updates that match
- docs-first process contract:
docs/specs/docs-first-process.md - for release-specific behavior deltas, use ZEVM Release Notes
Learn The Runtime Model
Section titled “Learn The Runtime Model”- Runtime Modes
- Trusted Mode
- Light Mode
- State Fork And Snapshots
- Method Support By Mode
- Architecture And Upstream Ownership
Release Metadata And Behavior Deltas
Section titled “Release Metadata And Behavior Deltas”For exact release/build pins and baked defaults, use Release Metadata Runbook; use runtime zevm_lightSyncStatus as an audit signal only. For behavior deltas by release, use ZEVM Release Notes.
JSON-RPC And Configuration Reference
Section titled “JSON-RPC And Configuration Reference”Normative source ownership: