Trusted-Mode Configuration

Trusted mode is the default runtime. It provides local execution and local mutation with optional fork backing.

Normative sources: docs/specs/prd.md and docs/specs/json-rpc-contract.md.

This page is an operational summary. For product-contract disputes, follow those normative sources.

Runtime Defaults

Field	Default
`chainId`	`31337` (`0x7a69`)
managed accounts	10 deterministic dev accounts
`coinbaseIndex`	`0`
`initialBalance`	`10000000000000000000000` wei
`gasPrice`	`2000000000`
`baseFee`	`1000000000`
`blobBaseFee`	`1`
`maxPriorityFeePerGas`	`1000000000`
`blockGasLimit`	`30000000`
mining mode	`auto`

CLI And Config Field Map

CLI flag	Config field	Type	Default
`--chain-id`	`mode.trusted.chainId`	`u64`	`31337`
`--coinbase-index`	`mode.trusted.coinbaseIndex`	integer `0..9`	`0`
`--initial-balance`	`mode.trusted.initialBalance`	decimal wei string	`10000000000000000000000`
`--gas-price`	`mode.trusted.gasPrice`	decimal wei string	`2000000000`
`--base-fee`	`mode.trusted.baseFee`	decimal wei string	`1000000000`
`--blob-base-fee`	`mode.trusted.blobBaseFee`	decimal wei string	`1`
`--max-priority-fee-per-gas`	`mode.trusted.maxPriorityFeePerGas`	decimal wei string	`1000000000`
`--block-gas-limit`	`mode.trusted.blockGasLimit`	`u64`	`30000000`
`--mining`	`mode.trusted.mining.type`	`auto`, `manual`, `interval`	`auto`
`--block-time`	`mode.trusted.mining.blockTime`	seconds (`u64`)	none
`--fork-url`	`mode.trusted.fork.url`	execution RPC URL	none
`--fork-block-number`	`mode.trusted.fork.blockNumber`	`u64`	none (when omitted with `--fork-url`, follow upstream head)
`--genesis`	`mode.trusted.genesis`	genesis JSON path	none
`--chain-rlp`	`mode.trusted.chainRlp`	concatenated RLP block stream path	none

Fork block-number representation bridge: startup CLI/config values are decimal u64, while JSON-RPC zevm_reset uses QuantityHex for forkConfig.blockNumber (example: 22000000 -> "0x14fb180").

Mining Shapes

mode.trusted.mining accepts:

{ "type": "auto" }

{ "type": "manual" }

{ "type": "interval", "blockTime": 12 }

Fork Shapes

mode.trusted.fork accepts:

null

{ "url": "https://rpc.example" }

{ "url": "https://rpc.example", "blockNumber": 22000000 }

When fork.url is set and fork.blockNumber is omitted, ZEVM follows the upstream head by default.

Genesis Allocation

mode.trusted.genesis accepts a path to a genesis JSON file:

{ "genesis": "/path/to/genesis.json" }

ZEVM reads the file at startup and imports the top-level alloc object. Account entries support balance or legacy wei, and optional nonce, code, and storage fields. Supplying a genesis file replaces default dev-account pre-funding; the deterministic managed accounts still exist for signing and eth_accounts.

Chain RLP Import

mode.trusted.chainRlp accepts a path to a concatenated RLP block stream:

{ "chainRlp": "/path/to/chain.rlp" }

ZEVM imports the stream after genesis initialization as query-only block history and advances the canonical head to the last imported block. Imported block bodies retain raw transaction envelopes for block transaction arrays and transaction-by-block/index lookups.

chainRlp does not execute imported transactions, validate post-state roots, materialize account/storage state, or populate receipt/log indexes in phase 1. State-backed reads, eth_call, eth_estimateGas, receipts, and logs continue to use the local runtime state created from genesis plus subsequent local transactions. The startup log emits chain_rlp_query_only_imported with state_materialized=false, receipts_indexed=false, and logs_indexed=false whenever this path is used.

Engine API Listener

Trusted mode can expose a second plain-HTTP Engine API listener with top-level engineRpc or CLI --engine-host / --engine-port:

{ "engineRpc": { "host": "127.0.0.1", "port": 8551 } }

The implemented Engine surface covers capability exchange, transition configuration exchange, and forkchoice updates that validate referenced hashes against ZEVM’s local block history. It does not make ZEVM a full consensus-client-facing execution engine yet; payload execution, payload building, payload-body methods, and blob/body retrieval remain outside the phase-1 surface and return method-not-found when called.

Validation Rules

--block-time is required when --mining interval
--block-time is invalid for auto and manual
--fork-block-number is invalid without --fork-url
--fork-url without --fork-block-number is valid and follows upstream head
--genesis is trusted-mode only and must point to a readable genesis file
--chain-rlp is trusted-mode only, query-only in phase 1, and the stream must link to the configured genesis/imported parent chain
--engine-host, --engine-port, and top-level engineRpc are trusted-mode only
trusted-only flags are invalid in light mode
coinbaseIndex must be within 0..9

Example: Trusted Mode With Interval Mining And Fork

{
  "rpc": { "host": "127.0.0.1", "port": 8545 },
  "mode": {
    "trusted": {
      "chainId": 31337,
      "coinbaseIndex": 0,
      "initialBalance": "10000000000000000000000",
      "gasPrice": "2000000000",
      "baseFee": "1000000000",
      "blobBaseFee": "1",
      "maxPriorityFeePerGas": "1000000000",
      "blockGasLimit": 30000000,
      "mining": { "type": "interval", "blockTime": 12 },
      "fork": { "url": "https://rpc.example", "blockNumber": 22000000 },
      "genesis": "./genesis.json",
      "chainRlp": "./chain.rlp"
    }
  }
}

Example: CLI Startup

zevm \
  --mode trusted \
  --chain-id 31337 \
  --mining interval \
  --block-time 12 \
  --fork-url https://rpc.example \
  --fork-block-number 22000000 \
  --genesis ./genesis.json \
  --chain-rlp ./chain.rlp

Trusted-Mode Configuration

Trusted-Mode Configuration

Runtime Defaults

CLI And Config Field Map

Mining Shapes

Fork Shapes

Genesis Allocation

Chain RLP Import

Engine API Listener

Validation Rules

Example: Trusted Mode With Interval Mining And Fork

Example: CLI Startup

Related Pages