Skip to main content
Version: v3.5

CLI Reference

The Erigon CLI has a wide range of flags that can be used to customize its behavior. There are 3 ways to configure Erigon, listed by priority:

tip

In order to see all the available options (flags) you must run the command:

./build/bin/erigon --help

Command line options​

Flags are passed directly to the erigon binary at startup. Each flag starts with --, followed by the flag name and, where applicable, a value separated by a space or =. For example, to start Erigon on the Holesky testnet with a custom data directory and the JSON-RPC API enabled on port 8545:

./build/bin/erigon --chain=holesky --datadir=/data/erigon --http --http.port=8545

Flags can be combined freely, providing a high degree of customization. Here's a breakdown of the most important flags:

General Options​

These flags cover the general behavior and configuration of the Erigon client.

  • --datadir value: Specifies the data directory for the databases.
    • Default: /home/usr/.local/share/erigon
  • --ethash.dagdir value: Sets the directory to store the ethash mining DAGs.
    • Default: /home/usr/.local/share/erigon-ethash
  • --config value: Sets Erigon flags using a YAML/TOML file.
  • --version, -v: Prints the version information.
  • --help, -h: Displays help information.
  • --chain value: Sets the name of the network to join.
    • Default: mainnet
  • --networkid value: Explicitly sets the network ID.
    • Default: 1
  • --identity value: Sets a custom node name.
  • --externalcl: Enables the external consensus layer.
    • Default: false, means that Caplin is enabled.
  • --override.osaka value: Manually specifies the Osaka fork time.
    • Default: 0
  • --override.amsterdam value: Manually specifies the Amsterdam fork time.
    • Default: 0
  • --vmdebug: Records information for VM and contract debugging.
    • Default: false
  • --gdbme: Restarts Erigon under gdb for debugging.
    • Default: false
  • --ethstats value: The reporting URL for an ethstats service.
  • --trusted-setup-file value: Absolute path to a trusted_setup.json file.
  • --persist.receipts, --experiment.persist.receipts.v2: Downloads historical receipts.
    • Default: true for minimal and full nodes, false for archive nodes
  • --keep.stored.chain.config: Avoids overriding the chain configuration already stored in the database.
    • Default: false

Development, testing, and block-production helpers​

These flags are mainly for dev networks, testing, or specialized block-production setups.

  • --allow-insecure-unlock: Accepted for go-ethereum CLI compatibility but currently has no effect — the flag is registered and settable, yet nothing in the codebase reads it and Erigon exposes no account-unlocking RPC.
    • Default: false
  • --dev-validator-seed value: Deterministic BLS key seed for the embedded dev validator. Read only in PoS dev mode, which is selected by --chain dev; on any other chain the flag does nothing.
    • Default: devnet
  • --dev-validator-count value: Number of validators for PoS dev mode (--chain dev).
    • Default: 64
  • --dev.slot-time value: Slot duration in seconds for PoS dev mode (--chain dev). Values below 2 are silently raised to 2.
    • Default: 6
  • --miner.gaslimit value: Target gas limit for mined blocks.
    • Default: unset — the target falls back to the chain configuration's default block gas limit, or 60000000 where the chain config does not set one. An explicit 0 is ignored rather than applied as a zero limit, so the flag only takes effect when set to a positive value.
  • --miner.extradata value: Block extra data set by the miner. Values longer than 32 bytes are silently truncated.
    • Default: the client version string
  • --experimental.bal: Generates block access lists.
    • Default: false
  • --experimental.always-generate-changesets: Overrides changeset generation logic.
    • Default: false, derived as the inverse of the BATCH_COMMITMENTS environment variable (itself true by default). Running with BATCH_COMMITMENTS=false therefore flips this default to true unless the flag is passed explicitly.
  • --chaos.monkey: Testing-only flag that enables spontaneous network, consensus, and other failures.
    • Default: false

Database and Caching​

These flags control database performance and memory usage. See Database for the on-disk layout.

  • --db.pagesize value: Sets the fixed page size for the database.
    • Default: 16KB
  • --db.size.limit value: Sets a runtime limit on the chaindata database size.
    • Default: 1TB
  • --db.writemap: Enables WRITE_MAP for fast database writes.
    • Default: true
  • --db.read.concurrency value: Ceiling on concurrent open database read transactions (the MDBX read-transaction semaphore); when it is full, extra readers wait for a slot by default, though some RPC paths (HTTP/WebSocket) fail fast with an overload response instead. Low values are fine for low read-concurrency nodes (for example, validators); raise it for nodes serving heavy parallel RPC.
    • Default: scales with the host as min(max(10, GOMAXPROCS * 64), 9000) — kept well above the CPU count because reads are I/O-bound, and capped below Go's roughly 10,000 OS-thread limit.
  • --database.verbosity value: Enables internal database logs.
    • Default: 2
  • --batchSize value: Sets the batch size for the execution stage.
    • Default: 512M
  • --etl.bufferSize value: Buffer size for ETL operations. Also settable through the ETL_OPTIMAL environment variable.
    • Default: 256MB
  • --bodies.cache value: Sets the size limit for the block bodies cache.
    • Default: 268435456
  • --state.cache value: Sets the amount of data to store in the StateCache.
    • Default: 0MB
  • --sync.parallel-state-flushing: Enables parallel state flushing.
    • Default: true
  • --erigondb.domain.steps-in-frozen-file value: Overrides the steps_in_frozen_file setting from erigondb.toml for the domain merge cap only (history and inverted-index merges are unaffected). Pass a positive integer to set an explicit cap, or Inf to leave the domain merge unbounded.
    • Default: unset (uses the value from erigondb.toml)
    • Use with care — an incorrect value may affect database structure.

Pruning and Snapshots​

Flags for managing how old chain data is handled and stored. See Snapshots Management for snapshot tooling and disk usage.

  • --prune.mode value: Selects a pruning preset (full, archive, minimal, blocks). See also Pruning Modes
    • Default: "full"
  • --prune.distance value: Keeps state history for the latest N blocks.
    • Default: 0
  • --prune.distance.blocks value: Keeps block history for the latest N blocks.
    • Default: 0
  • --prune.include-commitment-history, --prune.experimental.include-commitment-history, --experimental.commitment-history: Enables fast eth_getProof for executed blocks by storing commitment history. Requires +32 GB RAM. See eth_getProof.
    • Default: false
  • --snap.skip-state-snapshot-download: Skips state download and starts from genesis.
    • Default: false
  • --snap.keepblocks: Workaround/debug — keeps ancient blocks in the DB instead of moving them into snapshots (useful for debugging).
    • Default: false
  • --snap.stop: Workaround for snapshot-related bugs — stops producing new snapshot files (DB will grow as a result).
    • Default: false
  • --snap.state.stop: Workaround for state-related bugs — stops producing new state files (DB will grow as a result).
    • Default: false
  • --snap.p2p-manifest (New in v3.5) (experimental): Decentralized snapshot discovery — peers advertise their chain.toml manifest via ENR instead of the centralized preverified.toml. Opt-in; requires a compatible peer network.
    • Default: false
  • --snap.chaintoml-url value (New in v3.5): Fetch the preverified chain.toml directly from this URL instead of the default R2/GitHub CDN. Precedence: the ERIGON_REMOTE_PREVERIFIED environment variable (path to a local override file) wins over this URL and the default CDN; a local preverified.toml in the datadir also takes precedence — delete it to re-fetch from the URL.
    • Default: "" (uses the built-in CDN)
  • --snap.download.to.block, --shadow.fork.block value: Downloads snapshots only up to the given block number (exclusive). Intended for testing and shadow forks.
    • Default: 0 (disabled — downloads all available snapshots)

Transaction Pool (TxPool)​

Options for configuring the transaction pool.

  • --txpool.api.addr value: The TxPool API network address.
    • Default: Uses the value of --private.api.addr
  • --txpool.disable: Disables the internal transaction pool.
    • Default: false
  • --txpool.pricelimit value: Sets the minimum gas price for acceptance into the pool.
    • Default: 1
  • --txpool.pricebump value: Sets the price bump percentage to replace a transaction.
    • Default: 10
  • --txpool.blobpricebump value: Sets the price bump percentage for replacing a type-3 blob transaction.
    • Default: 100
  • --txpool.accountslots value: Sets the number of executable transaction slots per account.
    • Default: 16
  • --txpool.blobslots value: Sets the maximum number of blobs per account.
    • Default: 540
  • --txpool.totalblobpoollimit value: Sets the total limit on the number of all blobs in the pool.
    • Default: 5400
  • --txpool.globalslots value: Sets the maximum number of executable transaction slots for all accounts.
    • Default: 10000
  • --txpool.globalbasefeeslots value: Sets the maximum number of non-executable transactions with insufficient base fees.
    • Default: 30000
  • --txpool.globalqueue value: Sets the maximum number of non-executable transaction slots for all accounts.
    • Default: 30000
  • --txpool.trace.senders value: A comma-separated list of addresses whose transactions will be traced.
  • --txpool.commit.every value: Sets how often transactions are committed to storage.
    • Default: 15s
  • --txpool.gossip.disable: Disables P2P gossip of transactions.
    • Default: false
  • --txpool.queued.dormancy value: Evicts queued transactions from senders with no on-chain state changes for at least this duration (e.g. 3h, 2h30m).
    • Default: 3h0m0s
    • Set to 0 to disable dormancy-based eviction.

Network and Peers​

These flags manage network connectivity, peer discovery, and traffic control. See Default Ports for the full port map.

  • --port value: The main network listening port.
    • Default: 30303
  • --p2p.protocol value: The version of the eth P2P protocol.
    • Default: 69, 70, 71
  • --nat value: The NAT port mapping mechanism (See here for more details).
  • --nodiscover: Disables peer discovery.
    • Default: false
  • --discovery.v4, --discv4: Enables the Node Discovery Protocol v4 (Discv4) for managed ENRs and topic discovery.
    • Default: false (disabled by default since v3.4; discv5 is now the default discovery protocol)
  • --discovery.v5, --discv5, --v5disc: Enables the Node Discovery Protocol v5 (Discv5) for managed ENRs and topic discovery.
    • Default: true (enabled by default since v3.4)
  • --netrestrict value: Restricts network communication to specific IP networks.
  • --nodekey value: The P2P node key file.
  • --nodekeyhex value: The P2P node key as a hexadecimal string.
  • --discovery.dns value: Sets DNS discovery entry points.
  • --bootnodes value: Comma-separated enode URLs for P2P discovery bootstrap.
  • --staticpeers value: Comma-separated enode URLs to connect to.
  • --trustedpeers value: Comma-separated enode URLs for trusted peers.
  • --maxpeers value: The maximum number of network peers.
    • Default: 32

RPC & API​

Flags for configuring various RPC servers and their behavior. See Interacting with Erigon for the JSON-RPC API reference.

  • --private.api.addr value: The internal gRPC API address for Erigon's components.
    • Default: 127.0.0.1:9090
  • --private.api.ratelimit value: Limits the number of simultaneous internal API requests.
    • Default: 31872
  • --http: Enables the JSON-RPC HTTP server.
    • Default: true
  • --http.enabled: An alternative flag to enable the HTTP server.
    • Default: true
  • --graphql: Enables the GraphQL endpoint.
    • Default: false
  • --http.addr value: The HTTP-RPC server listening interface.
    • Default: localhost
  • --http.port value: The HTTP-RPC server listening port.
    • Default: 8545
  • --authrpc.addr value: The HTTP-RPC server listening interface for the Engine API.
    • Default: localhost
  • --authrpc.port value: The HTTP-RPC server listening port for the Engine API.
    • Default: 8551
  • --authrpc.jwtsecret value: The path to the JWT secret file for the consensus layer.
  • --http.compression: Enables compression over HTTP-RPC.
    • Default: true
  • --http.corsdomain value: A comma-separated list of domains for cross-origin requests.
  • --http.vhosts value: A comma-separated list of virtual hostnames.
    • Default: localhost
  • --authrpc.vhosts value: A comma-separated list of virtual hostnames for the Engine API.
    • Default: localhost
  • --http.api value: The APIs offered over the HTTP-RPC interface.
    • Default: eth,erigon,engine
  • --ws: Enables the WS-RPC server.
    • Default: false
  • --ws.port value: The WS-RPC server listening port.
    • Default: 8546
  • --ws.compression: Enables compression over WebSocket.
    • Default: true
  • --ws.max.connections value: Maximum number of concurrent WebSocket connections.
    • Default: 0 (unlimited)
  • --rpc.batch.concurrency value: Limits the number of goroutines for batch requests.
    • Default: 2
  • --rpc.max.concurrency value: Maximum number of concurrent HTTP RPC requests (HTTP admission control).
    • Default: 0 (inherits value from --db.read.concurrency)
    • Set to -1 to disable admission control (unlimited)
  • --rpc.streaming.disable: Disables JSON streaming for heavy endpoints.
    • Default: false
  • --state.stream.disable: Disables streaming of state changes from the core to the RPC daemon.
    • Default: false
  • --rpc.accessList value: Specifies a granular API allowlist.
  • --rpc.gascap value: Sets a cap on gas usage for eth_call/estimateGas.
    • Default: 50000000
  • --rpc.batch.limit value: Sets the maximum number of requests in a batch.
    • Default: 100
  • --rpc.blockrange.limit value: Sets the maximum block range for eth_getLogs and similar range queries.
    • Default: 1000
    • Applies to: eth_getLogs, erigon_getLogs
  • --rpc.logs.maxresults value: Sets the maximum number of log results returned per query.
    • Default: 20000
    • Applies to: eth_getLogs, erigon_getLogs, erigon_getLatestLogs
    • Set to 0 to remove the limit entirely (use with caution on large ranges).
    • Works in tandem with --rpc.blockrange.limit: both constraints apply independently — a query can be blocked by either limit.
  • --rpc.logs.querylimit value: Maximum number of alternative addresses or topics allowed per search position in the eth_getLogs filter criteria.
    • Default: 1000
    • Applies to: eth_getLogs
    • Set to 0 or a negative value for no limit.
  • --rpc.returndata.limit value: Sets the maximum return data size for eth_call.
    • Default: 100000
  • --rpc.allow-unprotected-txs: Allows unprotected transactions via RPC.
    • Default: false
  • --rpc.gethcompat: Enables Geth-compatible storage iteration order for debug_storageRangeAt (results sorted by keccak256 hash). Disabled by default for performance.
    • Default: false
  • --rpc.txfeecap value: Sets a cap on transaction fees in ether.
    • Default: 1
  • --rpc.slow value: Logs RPC requests slower than the specified threshold.
    • Default: 0s
  • --rpc.evmtimeout value: The maximum time to wait for an EVM call.
    • Default: 5m0s
  • --rpc.overlay.getlogstimeout value: The maximum time to wait for overlay_getLogs.
    • Default: 5m0s
  • --rpc.overlay.replayblocktimeout value: The maximum time to wait to replay a single block.
    • Default: 10s
  • --rpc.txsync.defaulttimeout value: The default timeout for eth_sendRawTransactionSync when the caller does not specify one.
    • Default: 25s
  • --rpc.txsync.maxtimeout value: The maximum timeout for eth_sendRawTransactionSync; larger requested timeouts are clamped to this value.
    • Default: 1m0s
  • --rpc.subscription.filters.maxlogs value: Maximum logs to store per subscription.
    • Default: 10000
  • --rpc.subscription.filters.maxheaders value: Maximum block headers to store per subscription.
    • Default: 10000
  • --rpc.subscription.filters.maxtxs value: Maximum transactions to store per subscription.
    • Default: 10000
  • --rpc.subscription.filters.maxaddresses value: Maximum addresses per subscription to filter logs by.
    • Default: 0
  • --rpc.subscription.filters.maxtopics value: Maximum topics per subscription to filter logs by.
    • Default: 0
  • --http.timeouts.read value: Maximum duration for reading a request.
    • Default: 30s
  • --http.timeouts.write value: Maximum duration before timing out a response write.
    • Default: 30m0s
  • --http.timeouts.idle value: Maximum idle time for a connection with keep-alives enabled.
    • Default: 2m0s
  • --authrpc.timeouts.read value: Maximum read duration for an Engine API request.
    • Default: 30s
  • --authrpc.timeouts.write value: Maximum write duration for an Engine API response.
    • Default: 30m0s
  • --authrpc.timeouts.idle value: Maximum idle time for an Engine API connection.
    • Default: 2m0s
  • --healthcheck: Enables gRPC health checks.
    • Default: false

MCP Server​

Flags for configuring the Model Context Protocol (MCP) server. The embedded MCP server is enabled by default on 127.0.0.1:8553. Pass --mcp.disable to turn it off.

  • --mcp.disable: Disables the embedded MCP server.
    • Default: false
  • --mcp.addr value: The MCP server listening address.
    • Default: 127.0.0.1
  • --mcp.port value: The MCP server listening port.
    • Default: 8553

Logging and Profiling​

Flags for controlling logging and performance profiling. See Logs for log files, levels, and rotation.

  • --log.json: Formats console logs with JSON.
    • Default: false
  • --log.console.json: Formats console logs with JSON.
    • Default: false
  • --log.dir.json: Formats file logs with JSON.
    • Default: false
  • --verbosity value: Sets the log level for console logs.
    • Default: info
  • --log.console.verbosity value: Sets the log level for console logs.
    • Default: info
  • --log.dir.disable: Disables disk logging.
    • Default: false
  • --log.dir.path value: The path to store user and error logs.
  • --log.dir.prefix value: The file name prefix for logs stored on disk.
  • --log.dir.verbosity value: Sets the log verbosity for disk logs.
    • Default: dbug
  • --log.delays: Enables block delay logging.
    • Default: false
  • --pprof: Enables the pprof HTTP server.
    • Default: false
  • --pprof.addr value: The pprof HTTP server listening interface.
    • Default: 127.0.0.1
  • --pprof.port value: The pprof HTTP server listening port.
    • Default: 6060
  • --pprof.cpuprofile value: Writes a CPU profile to a file.
  • --trace value: Writes an execution trace to a file.
  • --vmtrace value: Sets the provider tracer.
  • --vmtrace.jsonconfig value: Sets the tracer's configuration.
  • --metrics: Enables metrics collection and reporting. See Creating a Dashboard.
    • Default: false
  • --metrics.addr value: The stand-alone metrics HTTP server listening interface.
    • Default: 127.0.0.1
  • --metrics.port value: The metrics HTTP server listening port.
    • Default: 6061

Consensus and Forks​

Flags related to consensus mechanisms and network forks.

  • --fakepow: Disables proof-of-work verification.
    • Default: false
  • --gpo.blocks value: The number of recent blocks to check for gas prices.
    • Default: 20
  • --gpo.percentile value: The percentile of recent transaction gas prices to use for a suggested gas price.
    • Default: 60
  • --proposer.disable: Disables the PoS proposer.
    • Default: false
  • --builder.maxblobs value: Caps the number of blobs included in a locally built block.
    • Default: unset — the protocol maximum applies. Setting it to 0 excludes blob transactions from built blocks entirely.
  • --bor.heimdall value: The URL of the Heimdall service.
    • Default: http://localhost:1317
  • --bor.withoutheimdall: Runs without the Heimdall service.
    • Default: false
  • --bor.period: Overrides the bor block period.
    • Default: false
  • --bor.minblocksize: Ignores the bor block period and waits for blocksize transactions.
    • Default: false
  • --polygon.pos.ssf: Enables Polygon PoS Single Slot Finality.
    • Default: false
  • --polygon.pos.ssf.block value: Enables Polygon PoS Single Slot Finality from a specific block.
    • Default: 0
  • --polygon.wit-protocol: Enables the WIT protocol (wit/0) for stateless witness data exchange. Primarily useful on Bor (Polygon) chains — the witness buffer is only populated there — and must be set explicitly.
    • Default: false

Sentry​

Flags for configuring the Sentry component.

  • --sentry.api.addr value: A comma-separated list of Sentry addresses.
  • --sentry.log-peer-info: Logs detailed peer info when a peer connects or disconnects.
    • Default: false
  • --sentinel.addr value: The address for the sentinel component.
    • Default: localhost
  • --sentinel.port value: The port for the sentinel component.
    • Default: 7777
  • --sentinel.bootnodes value: Comma-separated enode URLs for P2P discovery bootstrap for the sentinel.
  • --sentinel.staticpeers value: Connects to comma-separated consensus static peers.

Downloader and Synchronization​

These flags control the block synchronization and data downloading process, including the BitTorrent protocol settings. See Downloader for how snapshot downloading works.

  • --downloader.api.addr value: The Downloader address.
  • --downloader.disable.ipv4: Disables IPv4 for the Downloader.
    • Default: false
  • --downloader.disable.ipv6: Disables IPv6 for the Downloader.
    • Default: false
  • --no-downloader: Disables the Downloader component.
    • Default: false
  • --downloader.verify: Verifies snapshots on startup.
    • Default: false
  • --sync.loop.throttle value: Sets the minimum time between sync loop starts.
  • --sync.loop.block.limit value: Sets the maximum number of blocks to process per loop iteration.
    • Default: 5000
  • --sync.loop.break.after value: Sets the last stage of the sync loop to run.
  • --bad.block value: Marks a block as bad and forces a reorg.
  • --webseed value: Comma-separated URLs for network support infrastructure.

BitTorrent Options​

  • --torrent.port value: The port to listen for the BitTorrent protocol.
    • Default: 42069
  • --torrent.maxpeers value: An unused parameter.
    • Default: 100
  • --torrent.conns.perfile value: The number of connections per file.
    • Default: 10
  • --torrent.trackers.disable: Disables conventional BitTorrent trackers.
    • Default: false
  • --torrent.upload.rate value: The upload rate in bytes per second.
    • Default: 16mb
  • --torrent.download.rate value: Sets the torrent download rate cap. Default: 512mb. Use a lower value on shared machines to avoid saturating the connection; use Inf to remove the limit.
  • --torrent.webseed.download.rate value: The download rate for webseeds. If not set, rate limit is shared with torrent.
  • --torrent.verbosity value: Sets the verbosity level for BitTorrent logs. 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail (must set --verbosity to equal or higher level)
    • Default: 1

Fork Choice Update (FCU)​

Flags for configuring Fork Choice Update behavior.

  • --fcu.timeout value: FCU timeout before switching to async processing (use 0 to disable).
    • Default: 1s
  • --fcu.background.prune: Enables background pruning after FCU.
    • Default: true
  • --fcu.background.commit: Enables background flush and commit after FCU.
    • Default: false

Execution​

Flags for configuring the parallel block execution engine.

All --exec.* flags are new in v3.5 — they expose, as CLI flags, execution toggles that on earlier releases were settable only via the EXEC3_* / NO_* environment variables (which still work).

  • --exec.workers value: Number of parallel block-execution workers (equivalent to the EXEC3_WORKERS env var). Overridden by --exec.serial.
    • Default: the number of CPU cores (inherited from the EXEC3_WORKERS default when the flag is not set).
    • Note: erigon --help describes this flag's default as "half the number of CPU cores". That value is not actually applied — when --exec.workers is omitted, Erigon uses EXEC3_WORKERS, which defaults to the full CPU-core count. The flag-help text is a known inconsistency in the binary.
  • --exec.serial: Force serial execution by clamping the parallel executor to a single worker. Wins over --exec.workers and EXEC3_WORKERS — use to disable parallelism for diagnostics or like-for-like baseline comparisons.
    • Default: false
  • --exec.no-prune: Disable all DB pruning: state-aggregator (Domain/InvertedIndex/forkable) plus stage-level pruning (Execution: ChangeSets3/BlockAccessList; TxLookup; WitnessProcessing; Snapshots: PruneAncientBlocks/canonical markers/retirement). Equivalent to NO_PRUNE=true. Diagnostic / perf-comparison use only.
    • Default: false
  • --exec.no-merge: Disable state-aggregator file merges for Domain / History / Inverted-Index. Equivalent to NO_MERGE=true. Diagnostic / perf-comparison use only.
    • Default: false
  • --exec.no-background-maintenance: Suppress background state-aggregator and E2 block-snapshot retirement goroutines so execution is not perturbed by housekeeping work. Equivalent to NO_BACKGROUND_E3_BUILD=true. Diagnostic / focused-performance-testing use only — NOT an operational setting.
    • Default: false
  • --exec.batched-io: Enable BAL-driven I/O optimisations — read-ahead pre-warming of the DB page cache (READ_AHEAD=true) and version-map pre-population from BAL hints (IGNORE_BAL=false). Disable for cold-read or non-BAL scheduling performance measurements.
    • Default: true
  • --exec.state-cache: Enable the executor's domain-shared read cache. Equivalent to USE_STATE_CACHE=true. Disable for cold-read performance measurements.
    • Default: true

Commitment-trie construction. The following flag changes how the commitment (state-root) trie is computed during execution. It defaults off and is intended for comparing root hashes against a sequential sync before enabling broadly.

  • --experimental.concurrent-commitment (experimental): Compute the commitment trie concurrently instead of sequentially. Also applies when rebuilding commitment from existing state.
    • Default: false

Caplin (Consensus Layer)​

Flags for configuring the Caplin consensus layer.

  • --caplin.discovery.addr value: The address for the Caplin DISCV5 protocol.
    • Default: 0.0.0.0
  • --caplin.discovery.port value: The port for the Caplin DISCV5 protocol.
    • Default: 4000
  • --caplin.discovery.tcpport value: The TCP port for the Caplin DISCV5 protocol.
    • Default: 4001
  • --caplin.checkpoint-sync-url value: The checkpoint sync endpoint.
  • --caplin.subscribe-all-topics: Subscribes to all gossip topics.
    • Default: false
  • --caplin.max-peer-count value: The maximum number of peers to connect to.
    • Default: 128
  • --caplin.enable-upnp: Enables NAT porting for Caplin.
    • Default: false
  • --caplin.local-discovery: Also attempts to find peers over private IPs. May cause issues with some hosts (for example, Hetzner).
    • Default: false
  • --caplin.nat value: NAT port mapping for Caplin P2P. Sets the external IP advertised in the discv5 ENR and libp2p multiaddrs while the socket binds to --caplin.discovery.addr. Required when running inside Docker or behind NAT. Accepted values: "" (none), "extip:1.2.3.4", "stun", "stun:<host>", "upnp", "pmp", "pmp:192.168.0.1".
    • Default: "" (no NAT mapping)
  • --caplin.max-inbound-traffic-per-peer value: The maximum inbound traffic per second per peer.
    • Default: 1MB
  • --caplin.max-outbound-traffic-per-peer value: The maximum outbound traffic per second per peer.
    • Default: 1MB
  • --caplin.adaptable-maximum-traffic-requirements: Makes the node adaptable to traffic based on the number of validators.
    • Default: true
  • --caplin.blocks-archive: Enables backfilling for blocks.
    • Default: false
  • --caplin.blobs-archive: Enables backfilling for blobs.
    • Default: false
  • --caplin.states-archive: Enables the archival node for historical states.
    • Default: false
  • --caplin.blobs-immediate-backfill: Tells Caplin to immediately backfill blobs.
    • Default: false
  • --caplin.blobs-no-pruning: Disables blob pruning.
    • Default: false
  • --caplin.columns-keep-slots value: Number of slots to retain PeerDAS data column sidecars. Increase for DA oracle or rollup nodes that need longer column history.
    • Default: 131072 (~18 days)
  • --caplin.checkpoint-sync.disable: Disables checkpoint sync.
    • Default: false
  • --caplin.snapgen: Enables snapshot generation.
    • Default: false
  • --caplin.mev-relay-url value: The MEV relay endpoint.
  • --caplin.validator-monitor: Enables Caplin validator monitoring metrics.
    • Default: false
  • --caplin.custom-config value: Sets a custom config for Caplin.
  • --caplin.custom-genesis value: Sets a custom genesis for Caplin.
  • --caplin.use-engine-api: Uses the Engine API for internal Caplin.
    • Default: false
  • --beacon.api.read.timeout value: HTTP read timeout for the Beacon API server, in seconds.
    • Default: 5
  • --beacon.api.write.timeout value: HTTP write timeout for the Beacon API server, in seconds.
    • Default: 31536000 (~1 year)
  • --beacon.api.idle.timeout value: HTTP idle (keep-alive) timeout for the Beacon API server, in seconds.
    • Default: 25

Shutter Network Encrypted Transactions​

Flags for configuring the Shutter Network encrypted transactions mempool.

  • --shutter: Enables the Shutter encrypted transactions mempool.
    • Default: false
  • --shutter.p2p.bootstrap.nodes value: Overrides the default P2P bootstrap nodes.
  • --shutter.p2p.listen.port value: Overrides the default P2P listen port.
    • Default: 0

Configuration file​

You can configure Erigon using a YAML or TOML configuration file by specifying its path with the --config flag.

tip

Note: flags specified in the configuration file can be overridden by directly setting them in the Erigon command line.

Both in YAML and TOML files boolean operators (false, true) and strings without spaces can be specified without quotes, while strings with spaces must be included in "" or '' quotes.

YAML​

Use the --config flag to point at the YAML configuration file.

./build/bin/erigon --config ./config.yaml --chain=holesky

Example of a YAML config file:

datadir : 'your datadir'
chain : "mainnet"
http : true
http.api : ["eth","debug","net"]

In this case the --chain flag in the command line will override the value in the YAML file and Erigon will run on the Holesky testnet.

TOML​

Use the --config flag to point at the TOML configuration file.

./build/bin/erigon --config ./config.toml

Example of a TOML config file:

datadir = 'your datadir'
chain = "mainnet"
http = true
"http.api" = ["eth","debug","net"]

Environment variables​

Erigon supports configuration through environment variables, primarily for experimental features and advanced settings.

tip

Erigon's own variables — everything below except the Docker ones, which do not take the ERIGON_ prefix — can be set with or without it. ERIGON_SNAPSHOT_MADV_RND and SNAPSHOT_MADV_RND both work. Prefer the prefixed form: Erigon logs a warning when it reads the bare name, and the prefix keeps these from colliding with unrelated variables in your environment. The examples below use it.

Core Environment Variables​

Database and Performance:

  • MDBX_LOCK_IN_RAM - Locks MDBX database in RAM for better performance
  • MDBX_DIRTY_SPACE_MB - Sets dirty space limit for MDBX database
  • SNAPSHOT_MADV_RND - Controls snapshot memory advice randomization (default: true)

Synchronization and Pruning:

  • NO_PRUNE - Disables pruning when set to true (flag equivalent: --exec.no-prune)
  • NO_MERGE - Disables merging operations (flag equivalent: --exec.no-merge)
  • PRUNE_TOTAL_DIFFICULTY - Controls total difficulty pruning (default: true)
  • MAX_REORG_DEPTH - Sets maximum reorganization depth (default: 96)

Execution and Processing:

  • EXEC3_PARALLEL - Enables parallel block execution (Block-STM). Default changed to true in v3.5 — parallel execution is now on by default. Set to false or use --exec.serial to revert to single-threaded execution.
  • EXEC3_WORKERS - Sets number of parallel execution workers (default: number of CPU cores)
  • STAGES_ONLY_BLOCKS - Limits stages to blocks only

Memory and Debugging Variables​

Memory Management:

  • NO_MEMSTAT - Disables memory statistics collection
  • SAVE_HEAP_PROFILE - Enables automatic heap profiling
  • HEAP_PROFILE_THRESHOLD - Memory usage percentage threshold for heap profiling (default: 35%)

Tracing and Debugging:

  • TRACE_ACCOUNTS - Comma-separated list of accounts to trace
  • TRACE_BLOCKS - Comma-separated list of block numbers to trace
  • TRACE_INSTRUCTIONS - Enables instruction-level tracing

Docker Environment Variables​

When running Erigon in Docker, you can configure user permissions and data directories:

  • DOCKER_UID - The UID of the Docker user
  • DOCKER_GID - The GID of the Docker user
  • XDG_DATA_HOME - The data directory mounted to containers

Usage Examples​

Basic Performance Tuning:

export ERIGON_MDBX_LOCK_IN_RAM=true
export ERIGON_SNAPSHOT_MADV_RND=false
./build/bin/erigon --datadir=/path/to/data

Memory Debugging:

export ERIGON_SAVE_HEAP_PROFILE=true
export ERIGON_HEAP_PROFILE_THRESHOLD=45
./build/bin/erigon --datadir=/path/to/data

Docker Deployment:

export DOCKER_UID=$(id -u)
export DOCKER_GID=$(id -g)
export XDG_DATA_HOME=/preferred/data/folder
make docker-compose
Last updated on