Skip to content
ZEVM ZEVM

Light Mode

Light Mode

Section titled “Light Mode”

Light mode is ZEVM’s read-only, proof-backed, consensus-anchored runtime.

What Light Mode Owns

Section titled “What Light Mode Owns”

Light mode provides proof-backed, consensus-anchored reads and readiness reporting. It does not expose trusted-mode local-dev controls.

Phase-1 operator-facing startup inputs are network, consensusRpcUrl, and executionRpcUrl, plus optional checkpoint controls (checkpoint, checkpointDir, maxCheckpointAgeSeconds, strictCheckpointAge).

Supported light networks are a closed phase-1 set: mainnet, sepolia, and holesky. Any other network value is invalid startup input. Selected network constrains both runtime eth_chainId and pre-listener startup handshake root validation (GET /eth/v1/beacon/genesis); mismatch is startup failure before the HTTP listener opens.

For exact startup/config contract wording, see:

Supported Surface

Section titled “Supported Surface”

Light mode supports:

  • zevm_lightSyncStatus
  • eth_chainId
  • eth_blockNumber (readiness-gated)
  • proof-backed eth_getBalance, eth_getCode, eth_getStorageAt, eth_getTransactionCount
  • consensus-anchored selector semantics for latest, safe, and finalized

Not exposed in light mode:

  • trusted-mode zevm_* controls (except zevm_lightSyncStatus)
  • trusted compatibility aliases (anvil_*, hardhat_*, evm_*)
  • simulation, transaction submission, mining, and trusted canonical block/receipt/log query surfaces

Method-level support and exact alias handling are defined in:

Readiness Model

Section titled “Readiness Model”

zevm_lightSyncStatus is the readiness control point for light mode.

Operational guidance:

  • poll zevm_lightSyncStatus until ready = true and status = "synced" before treating proof-backed reads as serviceable
  • ready is non-monotonic: after ready = true, ZEVM can transition back to ready = false if status leaves synced or slot coherence no longer holds (finalizedSlot <= safeSlot <= optimisticSlot)
  • eth_chainId is available before readiness
  • while not ready, readiness-gated reads (including eth_blockNumber) are unavailable
  • if status remains error, verify network, consensusRpcUrl, executionRpcUrl, and checkpoint inputs, then restart
  • zevm_lightSyncStatus observability uses slot fields optimisticSlot, safeSlot, and finalizedSlot; while ready, expect finalizedSlot <= safeSlot <= optimisticSlot

Canonical readiness/proof contract:

Canonical error map for readiness-gated reads:

  • -32011: light mode is not ready (eth_blockNumber and proof-backed reads are gated)
  • -32014: proof verification failed at an otherwise supported selector
  • -32015: malformed data from upstream proof source

Selector Model

Section titled “Selector Model”

In light mode:

Tag or selectorMeaning
latestlatest verified optimistic execution head
safeconsensus-anchored safe head
finalizedconsensus-finalized head
earliestblock 0
numeric quantityblock 0 or retained verified-history block
pendingunsupported

Numeric selector acceptance is bounded to retained verified history plus genesis (0). For exact accepted-set and error behavior, see Retained-history numeric selector contract.

Checkpoint Selection (Startup)

Section titled “Checkpoint Selection (Startup)”

Startup checkpoint precedence:

  1. CLI checkpoint (--checkpoint), when provided
  2. Config checkpoint (mode.light.checkpoint), when set
  3. Persisted startup checkpoint input (checkpointDir/checkpoint)
  4. Baked default checkpoint for the selected network

Operational notes:

  • persisted checkpoint file lifecycle is operator-managed
  • baked defaults are release/build-specific and can rotate
  • checkpointSource in zevm_lightSyncStatus reports which startup source won precedence

Canonical startup/checkpoint contract:

For detailed internal semantics (checkpoint-age policy, persisted-checkpoint handling, and readiness transitions), see docs/specs/internal/light-mode-semantics.md.

Where To Go Next

Section titled “Where To Go Next”
Section titled “Related Pages”