Node Operator EVM Configuration Guide

This guide covers every EVM-related configuration option available in app.toml, relevant CometBFT settings, command-line overrides, and production tuning recommendations for Lumera node operators.

Chain constants (not configurable — hardcoded in config/evm.go):

Automatic Config Migration (v1.20.0+)

Nodes upgrading from a pre-EVM binary (< v1.20.0) will have an app.toml that lacks the [evm], [evm.mempool], [json-rpc], [tls], and [lumera.*] sections. The Cosmos SDK only generates app.toml when the file does not exist, so these sections are never added automatically during a binary upgrade.

Starting with v1.20.0, lumerad includes a config migration helper (cmd/lumera/cmd/config_migrate.go) that runs on every startup:

1. Checks whether evm.evm-chain-id in the loaded config matches the Lumera constant (76857769).
2. If it does not match (absent section defaults to the upstream cosmos/evm value 262144, or 0 for entirely missing keys):
   • Reads all existing settings from the current app.toml via Viper.
   • Merges them with Lumera's EVM defaults (correct chain ID, JSON-RPC enabled, indexer enabled, rpc namespace for OpenRPC).
   • Regenerates app.toml with the full template, preserving all operator customizations.
3. Logs an INFO message when migration occurs.

No manual action is required. After upgrading the binary and restarting, the node will automatically add the missing EVM configuration sections with safe defaults. Operators can then customize settings as described below.

1. [evm] — Core EVM Module

Controls the x/vm EVM execution engine.

[evm]
# VM tracer for debug mode. Enables debug_traceTransaction, debug_traceBlockByNumber,
# debug_traceBlockByHash, debug_traceCall JSON-RPC methods when set.
# Values: "" (disabled), "json", "struct", "access_list", "markdown"
tracer = ""

# Gas wanted for each Ethereum tx in ante handler CheckTx mode.
# 0 = use the gas limit from the tx itself.
max-tx-gas-wanted = 0

# Enable SHA3 preimage recording in the EVM.
# Only useful for certain debugging/tracing scenarios.
cache-preimage = false

# EIP-155 chain ID. Must match the network's genesis chain ID.
# Do NOT change this on an existing chain.
evm-chain-id = 76857769

# Minimum priority fee (tip) for mempool acceptance, in wei.
# 0 = no minimum tip required beyond base fee.
min-tip = 0

# Address to bind the Geth-compatible metrics server.
geth-metrics-address = "127.0.0.1:8100"

Tuning notes

• tracer: Leave empty in production. Enable "json" temporarily for debugging specific transactions via debug_traceTransaction. The "struct" tracer is useful for programmatic analysis. Enabling any tracer adds overhead to every EVM call.
• max-tx-gas-wanted: Useful if you want to cap the gas that CheckTx considers for mempool admission. Generally leave at 0 unless you see mempool spam with inflated gas limits.
• min-tip: Increase this on validators that want to prioritize higher-fee transactions. Value is in wei (18-decimal alume), so 1000000000 = 1 gwei tip minimum.