Configuring Erigon

Erigon 3.1 CLI Options

The Erigon 3 CLI has a wide range of flags that can be used to customize its behavior. Here's a breakdown of some of the flags, see Options for the full list:

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

• --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

Database and Caching

These flags control database performance and memory usage.

• --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: Limits the number of parallel database reads.

  • Default: 1408

• --database.verbosity value: Enables internal database logs.

  • Default: 2

• --batchSize value: Sets the batch size for the execution stage.

  • Default: 512M

• --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

Pruning and Snapshots

Flags for managing how old chain data is handled and stored.

• --prune.mode value: Selects a pruning preset (full, archive, minimal, blocks).

  • 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.experimental.include-commitment-history, --experimental.commitment-history: Enables faster eth_getProof for executed blocks.

  • Default: false

• --snap.keepblocks: Keeps ancient blocks in the database for debugging.

  • Default: false

• --snap.stop: Stops generating new snapshots.

  • Default: false

• --snap.state.stop: Stops generating new state files.

  • Default: false

• --snap.skip-state-snapshot-download: Skips state download and starts from genesis.

  • Default: false

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

Network and Peers

These flags manage network connectivity, peer discovery, and traffic control.

• --port value: The main network listening port.

  • Default: 30303

• --p2p.protocol value: The version of the eth P2P protocol.

  • Default: 68, 67

• --p2p.allowed-ports value: A comma-separated list of allowed ports for different P2P protocols.

  • Default: 30303, 30304, 30305, 30306, 30307

• --nat value: The NAT port mapping mechanism.

• --nodiscover: Disables peer discovery.

  • Default: false

• --v5disc: Enables the experimental RLPx V5 (Topic Discovery) mechanism.

  • Default: false

• --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.

• --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

• --rpc.batch.concurrency value: Limits the number of goroutines for batch requests.

  • Default: 2

• --rpc.streaming.disable: Disables JSON streaming for heavy endpoints.

  • 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.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.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.subscription.filters.maxlogs value: Maximum logs to store per subscription.

  • Default: 0

• --rpc.subscription.filters.maxheaders value: Maximum block headers to store per subscription.

  • Default: 0

• --rpc.subscription.filters.maxtxs value: Maximum transactions to store per subscription.

  • Default: 0

• --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

Logging and Profiling

Flags for controlling logging and performance profiling.

• --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: info

• --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.

  • 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.

• --clique.checkpoint value: The number of blocks after which to save the vote snapshot.

  • Default: 10

• --clique.snapshots value: The number of recent vote snapshots to keep in memory.

  • Default: 1024

• --clique.signatures value: The number of recent block signatures to keep in memory.

  • Default: 16384

• --clique.datadir value: The path to the clique database folder.

• --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

• --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

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

Flags for controlling the downloader component.

• --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.

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.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.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

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

Downloader

Flags for managing the Downloader for data synchronization.

• --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: 32mb

• --torrent.download.rate value: The download rate in bytes per second.

• --torrent.webseed.download.rate value: The download rate for webseeds.

• --torrent.verbosity value: Sets the verbosity level for BitTorrent logs.

  • Default: 1