Node Configuration

To configure your node, you will need to do the following:

1. Configure op-node to point to the correct L1, op-geth, and L2 network.
2. Initialize op-geth with the correct network parameters.
3. Configure op-geth to properly communicate with the Rollup Node.
4. Optionally, configure Legacy Geth.

Configuring op-geth

We'll start with op-geth's configuration because it is more complex. As mentioned before, op-geth is a minimal fork of go-ethereum. As a result, it stores its state in a database that requires initialization. Initialization is done one of two ways, depending on which network you're deploying:

1. With a Genesis File: This is for OP Sepolia, and other testnets or deployments that are not migrated from a legacy network. In this case, you'll download the genesis file (opens in a new tab) and initialize the data directory via geth init.
2. With a Data Directory: This is used for networks that are migrated from a legacy network. This currently only includes OP Mainnet. In this case, you'll download a preconfigured data directory and extract it. No further initialization is necessary in this case, because the data directory contains the network's genesis information.

Regardless of how op-geth is initialized, you'll need to ensure that you have sufficient disk space available to store the network's data. As of this writing, the mainnet data directory is ~1TB for a full node and ~4TB for an archival node.

Instructions for each initialization method are below. If you're spinning up an OP Mainnet, use the Initialization via Data Directory path. If you're spinning up an OP Sepolia node, use the Initialization via Genesis File path.

Initialization via Genesis File

op-geth uses JSON files to encode a network's genesis information. Unlike OP Mainnet, the genesis for OP Sepolia is not currently included in the op-geth binary. For networks that are initialized in this way, you'll receive a URL to the genesis JSON. You'll need to download the genesis JSON, then run the following command to initialize the data directory:

#!/bin/sh
FILE=/$DATADIR/genesis.json
OP_GETH_GENESIS_URL=https://networks.optimism.io/op-sepolia/genesis.json
 
if [ ! -s $FILE ]; then
  apk add curl
  curl $OP_GETH_GENESIS_URL -o $FILE
  geth init --datadir /db $FILE
else
  echo "Genesis file already exists. Skipping initialization."
fi

Initialization via Data Directory

To initialize op-geth with a preconfigured data directory, simply download and extract the data directory to a place of your choosing. The data directory is exported as a tar file. An example command to do this is below:

curl -o <path to data directory> -sL <URL to data directory>
tar -xvf <path to data directory>

Configuration

Once op-geth is initialized, it can be configured via CLI flags. op-geth accepts all the standard go-ethereum flags (opens in a new tab) as well as a few extra flags that are specific to Optimism. These flags are:

• --rollup.historicalrpc: Enables the historical RPC endpoint. This endpoint is used to fetch historical execution data from Legacy Geth. This flag is only necessary for upgraded networks.
• --rollup.sequencerhttp: HTTP endpoint of the sequencer. op-geth will route eth_sendRawTransaction calls to this URL. Bedrock does not currently have a public mempool, so this is required if you want your node to support transaction submission. Consult the documentation for the network you are participating in to get the correct URL.
• --rollup.disabletxpoolgossip: Disables transaction pool gossiping. While not required, it's useful to set this to true since transaction pool gossip is currently unsupported.

To communicate with op-node and enable the Engine API, you'll also need to generate a JWT secret file and enable Geth's authenticated RPC endpoint.

To generate the JWT secret, run the following:

openssl rand -hex 32 > jwt.txt

Then, specify the following flags:

• --authrpc.addr: Sets the address op-geth's authenticated RPC should listen on.
• --authrpc.port: Sets the port op-geth's authenticated RPC should listen on. The default value is 8551.
• --authrpc.jwtsecret: Sets the path to a JWT secret file you generated above.

Optional op-geth Configuration

You may also want to specify the following flags based on your configuration:

• --authrpc.vhosts: Whitelists which hosts (as defined in the Host header) are allowed to access the authenticated RPC endpoint. This is useful if you're running op-geth on containerized infrastructure. The default value is localhost.
• --http.vhosts: Whitelists which hosts (as defined in the Host header) are allowed to access the unauthenticated RPC endpoint. This is useful if you're running op-geth on containerized infrastructure. The default value is localhost.
• --http, --http.addr, and --http.port: Enables the unauthenticated RPC endpoint, configures its address, and configures its port. You'll almost certainly want to specify these, since they will enable Geth's JSON-RPC endpoint.
• --ws, --ws.addr, and --ws.port: Enables the WebSocket API.
• --verbosity: Configures Geth's log level. This is a number between 0 and 5, with 5 being the most verbose. Defaults to 3.

Working Base Configuration

A valid command that runs op-geth and enables RPC over HTTP and WebSockets looks like:

geth \
  --ws \
  --ws.port=8546 \
  --ws.addr=localhost \
  --ws.origins="*" \
  --http \
  --http.port=8545 \
  --http.addr=localhost \
  --http.vhosts="*" \
  --http.corsdomain="*" \
  --authrpc.addr=localhost \
  --authrpc.jwtsecret=/var/secrets/jwt.txt \
  --authrpc.port=8551 \
  --authrpc.vhosts="*" \
  --datadir=/data \
  --verbosity=3 \
  --rollup.disabletxpoolgossip=true \
  --rollup.sequencerhttp=https://mainnet-sequencer.optimism.io/ \
  --op-network=op-mainnet

Consult Geth's documentation (opens in a new tab) for more information on customizing op-geth's behavior.

Configuring op-node

op-node is a standalone, statically linked binary. It stores no state, and requires no initialization. It consumes configuration parameters either via the command line or environment variables. For some networks, the Rollup Node also requires a configuration file (called rollup.json or the "rollup config") that configures network-specific genesis parameters. For official networks like OP Sepolia and OP Mainnet, the genesis config is hardcoded in the op-node software and can be specified via a --network flag.

Following the Ecotone upgrade node operators must set an L1 beacon value to retrieve blobs from a Beacon node.

Working Base Configuration

A minimal valid configuration that runs op-node looks like:

op-node --l1=<ethereum mainnet RPC url> \
        --l2=<op-geth authenticated RPC url> \
        --network=op-mainnet \
        --rpc.addr=127.0.0.1 \
        --rpc.port=9545 \
        --l2.jwt-secret=<path to JWT secret> \
        --l1.beacon=<http endpoint address of L1 Beacon-node>

You can manually specify a path to a rollup config with the --rollup.config flag. This is used for testnets or internal deployments that are not migrated from a legacy network.

Each of the above flags can also be defined via an environment variable. Run op-node --help to see a list of all available flags and environment variables.

Configuring Peer-to-Peer Networking

Unlike the previous system, the op-node participates in a peer-to-peer network. This network is used to distribute blocks that have not been submitted to L1 yet. The op-node will automatically discover and connect to peers using a hardcoded set of bootnodes. You can also manually specify peers to connect to via the --p2p.static flag.

For best results, run op-node with a static IP address that is accessible from the public Internet. For Kubernetes deployments, this can be achieved by configuring a dedicated Ingress with an external IP, and using the --p2p.advertise.ip flag to specify the IP address of the load balancer when advertising IP addresses to peers.

The default port for the peer-to-peer network is 9003. You will need to open this port on your firewall to receive unsubmitted blocks. For your node to be discoverable, this port must be accessible via both TCP and UDP protocols.

Legacy Geth

If you are running a node for an upgraded network like OP Mainnet (but not OP Sepolia), you will also need to run Legacy Geth in order to serve historical execution traces. Fundamentally, Legacy Geth is our old l2geth binary running against a preconfigured data directory. To configure Legacy Geth, follow the instructions above for using a preconfigured data directory, then execute the following command:

USING_OVM=true \
  ETH1_SYNC_SERVICE_ENABLE=false \
  RPC_API=eth,rollup,net,web3,debug \
  RPC_ADDR=0.0.0.0 \
  RPC_CORS_DOMAIN=* \
  RPC_ENABLE=true \
  RPC_PORT=8545 \
  RPC_VHOSTS=* \
  geth --datadir <path to data directory>

This command is the minimum required to run Legacy Geth and expose a functioning RPC endpoint. As before, l2geth takes all standard go-ethereum flags so you can customize the configuration as needed.

As mentioned above, don't forget to specify --rollup.historicalrpc on op-geth to properly route requests for historical execution to Legacy Geth.

Since Legacy Geth is read-only, it is safe to run multiple Legacy Geth nodes behind a load balancer.

Historical Execution vs. Historical Data Routing

Only requests for historical execution will be routed to Legacy Geth. Everything else will be served by op-geth directly. The term historical execution refers to RPC methods that need to execute transactions prior to bedrock (not just read data from the database):

• eth_call
• eth_estimateGas
• debug_traceBlockByNumber
• debug_traceBlockByHash
• debug_traceCall
• debug_traceTransaction

If you do not need these RPC methods for historical data, then you do not need to run Legacy Geth at all.

Command line options

You can configure your node using command line options (a.k.a. flags). There are also has sub-commands, which can be used to invoke functionality such as the console or blockchain import/export.

The command line help listing is reproduced below for your convenience.

op-node

op-node implements most rollup-specific functionality as Consensus-Layer, similar to a L1 beacon-node. The following options are from the --help in v1.5.1 (opens in a new tab).

GLOBAL OPTIONS

conductor.enabled

Enable the conductor service. The default value is false.

conductor.rpc

Conductor service rpc endpoint. The default value is http://127.0.0.1:8547.

conductor.rpc-timeout value

Conductor service rpc timeout. The default value is 1s.

heartbeat.enabled

Enables or disables heartbeating. The default value is false.

heartbeat.moniker

Sets a moniker for this node.

heartbeat.url

Sets the URL to heartbeat to. The default value is "https://heartbeat.optimism.io".

l1

Address of L1 User JSON-RPC endpoint to use (eth namespace required). The default value is "http://127.0.0.1:8545".

l1.beacon

Address of L1 Beacon-node HTTP endpoint to use.

l1.beacon.fetch-all-sidecars

If true, all sidecars are fetched and filtered locally. Workaround for buggy Beacon nodes. The default value is false.

l1.beacon.ignore

When false, halts op-node startup if the healthcheck to the Beacon-node endpoint fails. The default value is false.

l1.epoch-poll-interval

Poll interval for retrieving new L1 epoch updates such as safe and finalized block changes. Disabled if 0 or negative. The default value is 6m24s.

l1.http-poll-interval

Polling interval for latest-block subscription when using an HTTP RPC provider. Ignored for other types of RPC endpoints. The default value is 12s.

l1.max-concurrency

Maximum number of concurrent RPC requests to make to the L1 RPC provider. The default value is 10.

l1.rpc-max-batch-size

Maximum number of RPC requests to bundle, e.g., during L1 blocks receipt fetching. The L1 RPC rate limit counts this as N items, but allows it to burst at once. The default value is 20.

l1.rpc-rate-limit

Optional self-imposed global rate-limit on L1 RPC requests, specified in requests / second. Disabled if set to 0. The default value is 0.

l1.rpckind

The kind of RPC provider, used to inform optimal transactions receipts fetching, and thus reduce costs. Valid options: alchemy, quicknode, infura, parity, nethermind, debug_geth, erigon, basic, any, standard. The default value is standard.

l1.runtime-config-reload-interval

Poll interval for reloading the runtime config, useful when config events are not being picked up. Disabled if 0 or negative. The default value is 10m0s.

l1.trustrpc

Trust the L1 RPC, sync faster at risk of malicious/buggy RPC providing bad or inconsistent L1 data. The default value is false.

l2

Address of L2 Engine JSON-RPC endpoints to use (engine and eth namespace required).

l2.jwt-secret

Path to JWT secret key. Keys are 32 bytes, hex encoded in a file. A new key will be generated if left empty.

log.color

Color the log output if in terminal mode. The default value is false.

log.format

Format the log output. Supported formats: 'text', 'terminal', 'logfmt', 'json', 'json-pretty'. The default value is text.

log.level

The lowest log level that will be output. The default value is info.

metrics.addr

Metrics listening address. The default value is "0.0.0.0".

metrics.enabled

Enable the metrics server. The default value is false.

metrics.port

Metrics listening port. The default value is 7300.

network

Predefined network selection. Available networks: oplabs-devnet-0-sepolia-dev-0, op-labs-chaosnet-0-goerli-dev-0, zora-mainnet, base-sepolia, pgn-sepolia, zora-sepolia, base-devnet-0-sepolia-dev-0, base-goerli, base-devnet-0-goerli-dev-0, conduit-devnet-0-goerli-dev-0, base-mainnet, pgn-mainnet, op-sepolia, lyra-mainnet, mode-mainnet, op-mainnet, op-goerli, op-labs-devnet-0-goerli-dev-0, orderly-mainnet.

override.canyon

Manually specify the Canyon fork timestamp, overriding the bundled setting. The default value is 0.

override.delta

Manually specify the Delta fork timestamp, overriding the bundled setting. The default value is 0.

override.ecotone

Manually specify the ecotone fork timestamp, overriding the bundled setting. The default value is 0.

p2p.advertise.ip

The IP address to advertise in Discv5, put into the ENR of the node. This may also be a hostname/domain name to resolve to an IP.

p2p.advertise.tcp

The TCP port to advertise in Discv5, put into the ENR of the node. Set to p2p.listen.tcp value if 0. The default value is 0.

p2p.advertise.udp

The UDP port to advertise in Discv5 as a fallback if not determined by Discv5, put into the ENR of the node. Set to p2p.listen.udp value if 0. The default value is 0.

p2p.ban.duration

The duration that peers are banned for. The default value is 1h0m0s.

p2p.ban.peers

Enables peer banning. The default value is true.

p2p.ban.threshold

The minimum score below which peers are disconnected and banned. The default value is -100.

p2p.bootnodes

Comma-separated base64-format ENR list. Bootnodes to start discovering other node records from.

p2p.disable

Completely disable the P2P stack. The default value is false.

p2p.discovery.path

Enables persistent storage of discovered ENRs in a database to recover from a restart without bootstrapping the discovery process again. Set to 'memory' to never persist the peerstore. The default value is opnode_discovery_db.

p2p.listen.ip

Specifies the IP to bind LibP2P and Discv5 to. The default value is 0.0.0.0.

p2p.listen.tcp

Defines the TCP port to bind LibP2P to. Any available system port if set to 0. The default value is 9222.

p2p.listen.udp

Sets the UDP port to bind Discv5 to. It will be the same as the TCP port if left at 0. The default value is 0.

p2p.nat

Enables NAT traversal with PMP/UPNP devices to learn external IP. The default value is false.

p2p.netrestrict

Specifies a comma-separated list of CIDR masks. P2P will only try to connect on these networks.

p2p.no-discovery

Disables Discv5 (node discovery). The default value is false.

p2p.peers.grace

Determines the grace period to keep a newly connected peer around, if it is not misbehaving. The default value is 30s.

p2p.peers.hi

Sets the high-tide peer count. The node starts pruning peer connections slowly after reaching this number. The default value is 30.

p2p.peers.lo

Determines the low-tide peer count. The node actively searches for new peer connections if below this amount. The default value is 20.

p2p.peerstore.path

Specifies the Peerstore database location. Persisted peerstores help recover peers after restarts. Set to 'memory' to never persist the peerstore. Warning: a copy of the priv network key of the local peer will be persisted here. The default value is "opnode_peerstore_db".

p2p.priv.path

Defines the file path for reading the hex-encoded 32-byte private key for the peer ID. Created if not already exists. Important for maintaining the same network identity after restarting. The default value is "opnode_p2p_priv.txt".

p2p.scoring

Sets the peer scoring strategy for the P2P stack. Options include 'none' or 'light'. The default value is "light".

p2p.sequencer.key

Hex-encoded private key for signing off on p2p application messages as sequencer.

p2p.static

Comma-separated multiaddr-format peer list. Static connections to make and maintain, these peers will be regarded as trusted. Addresses of the local peer are ignored. Duplicate/Alternative addresses for the same peer all apply, but only a single connection per peer is maintained.

p2p.sync.req-resp

Enables P2P req-resp alternative sync method, on both server and client side. Default is true.

pprof.addr

pprof listening address. Default is "0.0.0.0".

pprof.enabled

Enable the pprof server. Default is false.

pprof.path

pprof file path. If it is a directory, the path is {dir}/{profileType}.prof

pprof.port

pprof listening port. Default is 6060.

pprof.type

pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs

rollup.config

Rollup chain parameters.

rollup.halt

Opt-in option to halt on incompatible protocol version requirements of the given level (major/minor/patch/none), as signaled onchain in L1.

rollup.load-protocol-versions

Load protocol versions from the superchain L1 ProtocolVersions contract (if available), and report in logs and metrics. Default is false.

rpc.addr

RPC listening address. Default is "127.0.0.1".

rpc.admin-state

File path used to persist state changes made via the admin API so they persist across restarts. Disabled if not set.

rpc.enable-admin

Enable the admin API (experimental). Default is false.

rpc.port

RPC listening port. Default is 9545.

sequencer.enabled

Enable sequencing of new L2 blocks. A separate batch submitter has to be deployed to publish the data for verifiers. Default is false.

sequencer.l1-confs

Number of L1 blocks to keep distance from the L1 head as a sequencer for picking an L1 origin. Default is 4.

sequencer.max-safe-lag

Maximum number of L2 blocks for restricting the distance between L2 safe and unsafe. Disabled if 0. Default is 0.

sequencer.stopped

Initialize the sequencer in a stopped state. The sequencer can be started using the admin_startSequencer RPC. Default is false.

snapshotlog.file

Path to the snapshot log file.

verifier.l1-confs

Number of L1 blocks to keep distance from the L1 head before deriving L2 data from. Reorgs are supported, but may be slow to perform. Default is 0.

MISC

--help, -h

Show help. The default value is false.

--version, -v

Print the version. The default value is false.

op-geth

op-geth implements the Execution-Layer, with minimal changes for a secure Ethereum-equivalent application environment. The following are options from v1.101308.0 (opens in a new tab)

Please note that the executable is still named geth to maintain a minimal diff (opens in a new tab).

GLOBAL OPTIONS

ACCOUNT

allow-insecure-unlock

Allows insecure account unlocking when account-related RPCs are exposed by HTTP. The default value is false.

keystore

Directory for the keystore. The default is inside the data directory.

lightkdf

Reduce key-derivation RAM & CPU usage at some expense of KDF strength. The default value is false.

password

Password file to use for non-interactive password input.

pcscdpath

Path to the smartcard daemon (pcscd) socket file. The default value is "/run/pcscd/pcscd.comm".

signer

External signer (url or path to ipc file).

unlock

Comma separated list of accounts to unlock.

usb

Enable monitoring and management of USB hardware wallets. The default value is false.

API AND CONSOLE

authrpc.addr

Listening address for authenticated APIs. The default value is "localhost".

authrpc.jwtsecret

Path to a JWT secret to use for authenticated RPC endpoints.

authrpc.port

Listening port for authenticated APIs. The default value is 8551.

authrpc.vhosts

Comma separated list of virtual hostnames from which to accept requests (server enforced). The default value is "localhost". Accepts '*' wildcard.

exec

Execute JavaScript statement.

graphql

Enable GraphQL on the HTTP-RPC server. Note that GraphQL can only be started if an HTTP server is started as well. The default value is false.

graphql.corsdomain

Comma separated list of domains from which to accept cross origin requests (browser enforced).

graphql.vhosts

Comma separated list of virtual hostnames from which to accept requests (server enforced). The default value is "localhost". Accepts '*' wildcard.

header

Pass custom headers to the RPC server when using --remotedb or the geth attach console. This flag can be given multiple times.

http

Enable the HTTP-RPC server. The default value is false.

http.addr

HTTP-RPC server listening interface. The default value is "localhost".

http.api

API's offered over the HTTP-RPC interface.

http.corsdomain

Comma separated list of domains from which to accept cross origin requests (browser enforced).

http.port

HTTP-RPC server listening port. The default value is 8545.

http.rpcprefix`\

HTTP path prefix on which JSON-RPC is served. Use '/' to serve on all paths.

http.vhosts

Comma separated list of virtual hostnames from which to accept requests (server enforced). The default value is "localhost". Accepts '*' wildcard.

ipcdisable

Disable the IPC-RPC server. The default value is false.

ipcpath

Filename for IPC socket/pipe within the datadir (explicit paths escape it).

jspath

JavaScript root path for loadScript. The default value is . (current directory).

preload

Comma separated list of JavaScript files to preload into the console.

rpc.allow-unprotected-txs

Allow for unprotected (non EIP155 signed) transactions to be submitted via RPC. The default value is false.

rpc.batch-request-limit

Maximum number of requests in a batch. The default value is 1000.

rpc.batch-response-max-size

Maximum number of bytes returned from a batched call. The default value is 25000000.

rpc.enabledeprecatedpersonal

Enables the (deprecated) personal namespace. The default value is false.

rpc.evmtimeout

Sets a timeout used for eth_call (0=infinite). The default value is 5s.

rpc.gascap

Sets a cap on gas that can be used in eth_call/estimateGas (0=infinite). The default value is 50000000.

rpc.txfeecap

Sets a cap on transaction fee (in ether) that can be sent via the RPC APIs (0 = no cap). The default value is 1.

ws

Enable the WS-RPC server. The default value is false.

ws.addr

WS-RPC server listening interface. The default value is "localhost".

ws.api

API's offered over the WS-RPC interface.

ws.origins

Origins from which to accept websockets requests.

ws.port

WS-RPC server listening port. The default value is 8546.

ws.rpcprefix

HTTP path prefix on which JSON-RPC is served over WS. Use '/' to serve on all paths.

DEVELOPER CHAIN

dev

Ephemeral proof-of-authority network with a pre-funded developer account, mining enabled. The default value is false.

dev.gaslimit

Initial block gas limit. The default value is 11500000.

dev.period

Block period to use in developer mode (0 = mine only if transaction pending). The default value is 0.

ETHEREUM

bloomfilter.size

Megabytes of memory allocated to bloom-filter for pruning. The default value is 2048.

config

TOML configuration file.

datadir

Data directory for the databases and keystore. The default value is /home/<user>/.ethereum.

datadir.ancient

Root directory for ancient data (default = inside chaindata).

datadir.minfreedisk

Minimum free disk space in MB, once reached triggers auto shut down (default = --cache.gc converted to MB, 0 = disabled).

db.engine

Backing database implementation to use ('pebble' or 'leveldb').

eth.requiredblocks

Comma separated block number-to-hash mappings to require for peering (<number>=<hash>).

exitwhensynced

Exits after block synchronization completes. The default value is false.

goerli

Görli network: pre-configured proof-of-authority test network. The default value is false.

holesky

Holesky network: pre-configured proof-of-stake test network. The default value is false.

mainnet

Ethereum mainnet. The default value is false.

networkid

Explicitly set network id (integer). The default value is 1. For testnets: use --goerli, --sepolia, --holesky instead.

op-network, beta.op-network

Select a pre-configured OP-Stack network (warning: op-mainnet and op-goerli require special sync, datadir is recommended), options: base-devnet-0-goerli-dev-0, base-devnet-0-sepolia-dev-0, base-goerli, base-mainnet, base-sepolia, conduit-devnet-0-goerli-dev-0, lyra-mainnet, mode-mainnet, op-goerli, op-labs-chaosnet-0-goerli-dev-0, op-labs-devnet-0-goerli-dev-0, op-mainnet, op-sepolia, oplabs-devnet-0-sepolia-dev-0, orderly-mainnet, pgn-mainnet, pgn-sepolia, zora-mainnet, zora-sepolia

override.cancun

Manually specify the Cancun fork timestamp, overriding the bundled setting. The default value is 0.

override.canyon

Manually specify the Optimism Canyon fork timestamp, overriding the bundled setting. The default value is 0.

override.ecotone

Manually specify the Optimism Ecotone fork timestamp, overriding the bundled setting. The default value is 0.

override.interop

Manually specify the Optimism Interop feature-set fork timestamp, overriding the bundled setting. The default value is 0.

override.verkle

Manually specify the Verkle fork timestamp, overriding the bundled setting. The default value is 0.

sepolia

Sepolia network: pre-configured proof-of-work test network. The default value is false.

snapshot

Enables snapshot-database mode. The default value is true.

GAS PRICE ORACLE

gpo.blocks

Number of recent blocks to check for gas prices. The default value is 20.

gpo.ignoreprice

Gas price below which GPO will ignore transactions. The default value is 2.

gpo.maxprice

Maximum transaction priority fee (or gasprice before London fork) to be recommended by GPO. The default value is 500000000000.

gpo.minsuggestedpriorityfee

Minimum transaction priority fee to suggest. Used on OP chains when blocks are not full. The default value is 1000000.

gpo.percentile

Suggested gas price is the given percentile of a set of recent transaction gas prices. The default value is 60.

LIGHT CLIENT

light.egress

Outgoing bandwidth limit for serving light clients (deprecated). The default value is 0.

light.ingress

Incoming bandwidth limit for serving light clients (deprecated). The default value is 0.

light.maxpeers

Maximum number of light clients to serve, or light servers to attach to (deprecated). The default value is 100.

light.nopruning

Disable ancient light chain data pruning (deprecated). The default value is false.

light.nosyncserve

Enables serving light clients before syncing (deprecated) The default value is false.

light.serve

Maximum percentage of time allowed for serving LES requests (deprecated). The default value is 0.

LOGGING AND DEBUGGING

log.compress

Compress the log files. The default value is false.

log.file

Write logs to a file.

log.format

Log format to use (json|logfmt|terminal).

log.maxage

Maximum number of days to retain a log file. The default value is 30.

log.maxbackups

Maximum number of log files to retain. The default value is 10.

log.maxsize

Maximum size in MBs of a single log file. The default value is 100.

log.rotate

Enables log file rotation. The default value is false.

log.vmodule

Per-module verbosity: comma-separated list of <pattern>=<level> (e.g. eth/*=5,p2p=4).

nocompaction

Disables database compaction after import. The default value is false.

pprof

Enable the pprof HTTP server. The default value is false.

pprof.addr

pprof HTTP server listening interface. The default value is "127.0.0.1".

pprof.blockprofilerate

Turn on block profiling with the given rate. The default value is 0.

pprof.cpuprofile

Write CPU profile to the given file.

pprof.memprofilerate

Turn on memory profiling with the given rate. The default value is 524288.

pprof.port

pprof HTTP server listening port. The default value is 6060.

remotedb

URL for remote database.

trace

Write execution trace to the given file.

verbosity

Logging verbosity: 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail. The default value is 3.

METRICS AND STATS

ethstats

Reporting URL of an ethstats service (nodename:secret@host:port).

metrics

Enable metrics collection and reporting. The default value is false.

metrics.addr

Enable stand-alone metrics HTTP server listening interface.

metrics.expensive

Enable expensive metrics collection and reporting. The default value is false.

metrics.influxdb

Enable metrics export/push to an external InfluxDB database. The default value is false.

metrics.influxdb.bucket

InfluxDB bucket name to push reported metrics to (v2 only). The default value is "geth".

metrics.influxdb.database

InfluxDB database name to push reported metrics to. The default value is "geth".

metrics.influxdb.endpoint

InfluxDB API endpoint to report metrics to. The default value is "http://localhost:8086".

metrics.influxdb.organization

InfluxDB organization name (v2 only). The default value is "geth".

metrics.influxdb.password

Password to authorize access to the database. The default value is "test".

metrics.influxdb.tags

Comma-separated InfluxDB tags (key/values) attached to all measurements. The default value is "host=localhost".

metrics.influxdb.token

Token to authorize access to the database (v2 only). The default value is "test".

metrics.influxdb.username

Username to authorize access to the database. The default value is "test".

metrics.influxdbv2

Enable metrics export/push to an external InfluxDB v2 database. The default value is false.

metrics.port

Metrics HTTP server listening port. The default value is 6060. Please note that --metrics.addr must be set to start the server.

MINER

mine

Enable mining. The default value is false.

miner.etherbase

0x prefixed public address for block mining rewards.

miner.extradata

Block extra data set by the miner (default = client version).

miner.gaslimit

Target gas ceiling for mined blocks. The default value is 30000000.

miner.gasprice

Minimum gas price for mining a transaction. The default value is 0.

miner.newpayload-timeout

Specify the maximum time allowance for creating a new payload. The default value is 2s.

miner.recommit

Time interval to recreate the block being mined. The default value is 2s.

MISC

help

Show help. This is typically used to display command-line options and usage information.

synctarget

Hash of the block to full sync to (dev testing feature).

version

Print the version. This option is typically used to display the version of the software.

NETWORKING

bootnodes

Comma separated enode URLs for P2P discovery bootstrap.

discovery.dns

Sets DNS discovery entry points (use "" to disable DNS).

discovery.port

Use a custom UDP port for P2P discovery. The default value is 30303.

discovery.v4

Enables the V4 discovery mechanism. The default value is true.

discovery.v5

Enables the experimental RLPx V5 (Topic Discovery) mechanism. The default value is false.

identity

Custom node name.

maxpeers

Maximum number of network peers (network disabled if set to 0). The default value is 50.

maxpendpeers

Maximum number of pending connection attempts (defaults used if set to 0). The default value is 0.

nat

NAT port mapping mechanism (any|none|upnp|pmp|pmp:<IP>|extip:<IP>). The default value is "any".

netrestrict

Restricts network communication to the given IP networks (CIDR masks).

nodekey

P2P node key file.

nodekeyhex

P2P node key as hex (for testing).

nodiscover

Disables the peer discovery mechanism (manual peer addition). The default value is false.

port

Network listening port. The default value is 30303.

PERFORMANCE TUNING

cache

Megabytes of memory allocated to internal caching. The default is 4096 MB for mainnet full node and 128 MB for light mode.

cache.blocklogs

Size (in number of blocks) of the log cache for filtering. The default value is 32.

cache.database

Percentage of cache memory allowance to use for database I/O. The default value is 50.

cache.gc

Percentage of cache memory allowance to use for trie pruning. The default is 25% for full mode and 0% for archive mode.

cache.noprefetch

Disable heuristic state prefetch during block import (less CPU and disk IO, more time waiting for data). The default value is false.

cache.preimages

Enable recording the SHA3/keccak preimages of trie keys. The default value is false.

cache.snapshot

Percentage of cache memory allowance to use for snapshot caching. The default is 10% for full mode and 20% for archive mode.

cache.trie

Percentage of cache memory allowance to use for trie caching. The default is 15% for full mode and 30% for archive mode.

crypto.kzg

KZG library implementation to use; gokzg (recommended) or ckzg. The default value is "gokzg".

fdlimit

Raise the open file descriptor resource limit. The default is the system fd limit.

ROLLUP NODE

rollup.computependingblock

By default, the pending block equals the latest block to save resources and not leak transactions from the tx-pool. This flag enables computing of the pending block from the tx-pool instead. The default value is false.

rollup.disabletxpoolgossip

Disable transaction pool gossip. The default value is false.

rollup.halt

Opt-in option to halt on incompatible protocol version requirements of the given level (major/minor/patch/none), as signaled through the Engine API by the rollup node.

rollup.historicalrpc

RPC endpoint for historical data.

rollup.historicalrpctimeout

Timeout for historical RPC requests. The default value is 5s.

rollup.sequencerhttp

HTTP endpoint for the sequencer mempool.

rollup.superchain-upgrades

Apply superchain-registry config changes to the local chain-configuration. The default value is true.

STATE HISTORY MANAGEMENT

gcmode

Blockchain garbage collection mode, only relevant in state.scheme=hash. Options are "full" and "archive". The default value is "full".

history.state

Number of recent blocks to retain state history for. The default is 90000 blocks, with 0 representing the entire chain.

history.transactions

Number of recent blocks to maintain transactions index for. The default is about one year (2350000 blocks), with 0 representing the entire chain.

state.scheme

Scheme to use for storing Ethereum state. Options are 'hash' or 'path'.

syncmode

Blockchain sync mode. Options are "snap", or "full". The default value is "snap".

TRANSACTION POOL (BLOB)

blobpool.datacap

Disk space to allocate for pending blob transactions (soft limit). The default value is 10737418240.

blobpool.pricebump

Price bump percentage to replace an already existing blob transaction. The default value is 100.

TRANSACTION POOL (EVM)

txpool.accountqueue

Maximum number of non-executable transaction slots permitted per account. The default value is 64.

txpool.accountslots

Minimum number of executable transaction slots guaranteed per account. The default value is 16.

txpool.globalqueue

Maximum number of non-executable transaction slots for all accounts. The default value is 1024.

txpool.globalslots

Maximum number of executable transaction slots for all accounts. The default value is 5120.

txpool.journal

Disk journal for local transactions to survive node restarts. The default value is "transactions.rlp".

txpool.journalremotes

Includes remote transactions in the journal. The default value is false.

txpool.lifetime

Maximum amount of time non-executable transactions are queued. The default value is 3h0m0s.

txpool.locals

Comma-separated accounts to treat as locals (no flush, priority inclusion).

txpool.nolocals

Disables price exemptions for locally submitted transactions. The default value is false.

txpool.pricebump

Price bump percentage to replace an already existing transaction. The default value is 10.

txpool.pricelimit

Minimum gas price tip to enforce for acceptance into the pool. The default value is 1.

txpool.rejournal

Time interval to regenerate the local transaction journal. The default value is 1h0m0s.

VIRTUAL MACHINE

vmdebug

Record information useful for VM and contract debugging. The default value is false.