Execution layer configuration options (op-geth)

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

This page lists all configuration options for op-geth. op-geth implements the Execution-Layer, with minimal changes for a secure Ethereum-equivalent application environment. The following are options from v1.101603.3-rc.3 Please note that the executable is still named geth to maintain a minimal diff.

Recommended configuration

For most node operators, the following configuration provides a good starting point. This configuration assumes you’re running a full node (not a sequencer).

Essential flags

These are the minimum required flags to run op-geth:

geth \
  --datadir=/data/optimism \
  --http \
  --http.addr=0.0.0.0 \
  --http.port=8545 \
  --http.api=eth,net,web3 \
  --authrpc.addr=localhost \
  --authrpc.port=8551 \
  --authrpc.jwtsecret=/path/to/jwt-secret.txt \
  --op-network=op-mainnet \
  --syncmode=full \
  --maxpeers=50 \
  --rollup.disabletxpoolgossip

Recommended flags for production

For production deployments, add these flags to improve performance and reliability:

geth \
  --datadir=/data/optimism \
  --http \
  --http.addr=0.0.0.0 \
  --http.port=8545 \
  --http.api=eth,net,web3 \
  --http.vhosts=* \
  --http.corsdomain=* \
  --ws \
  --ws.addr=0.0.0.0 \
  --ws.port=8546 \
  --ws.api=eth,net,web3 \
  --authrpc.addr=localhost \
  --authrpc.port=8551 \
  --authrpc.jwtsecret=/path/to/jwt-secret.txt \
  --op-network=op-mainnet \
  --syncmode=full \
  --gcmode=full \
  --maxpeers=50 \
  --cache=4096 \
  --rollup.disabletxpoolgossip \
  --metrics \
  --metrics.addr=0.0.0.0 \
  --metrics.port=6060

The --http.vhosts and --http.corsdomain flags shown above with * values are for example purposes. In production, you should restrict these to specific domains for security.

Important configuration files

When running op-geth, you’ll work with several important files and directories:

Data directory (`--datadir`)

The data directory contains all blockchain data, including:

chaindata/ - The blockchain database
keystore/ - Account keystores (if using local accounts)
geth.ipc - IPC endpoint for local RPC connections

Default location: ~/.ethereum (should be changed in production)

JWT secret (`--authrpc.jwtsecret`)

A hex-encoded 32-byte secret used for authenticated communication between op-geth (execution layer) and op-node (consensus layer). This file must be identical for both op-geth and op-node. Example of generating a JWT secret:

openssl rand -hex 32 > jwt-secret.txt

TOML configuration file (`--config`)

Instead of using command-line flags, you can use a TOML configuration file. Generate a template with:

geth dumpconfig > config.toml

Edit the file and run with:

geth --config config.toml

Configuration options reference

The following sections provide detailed documentation for all available op-geth configuration options, organized by functionality.

Account management

Options for managing accounts, keystores, and external signers.

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

usb

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

RPC and API configuration

Configure HTTP, WebSocket, authenticated RPC endpoints, and console access.

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.

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

Development Chain

Options for running a local development chain with pre-funded accounts.

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.

Chain and network selection

Configure which network to connect to and manage blockchain data storage.

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

Root directory for era1 history (default = inside ancient/chain).

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.

holesky

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

hoodi

Hoodi 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 0. For testnets: use —sepolia, —holesky, —hoodi 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: arena-z-mainnet, arena-z-sepolia, automata-mainnet, base-devnet-0-sepolia-dev-0, base-mainnet, base-sepolia, bob-mainnet, camp-sepolia, creator-chain-testnet-sepolia, cyber-mainnet, cyber-sepolia, ethernity-mainnet, ethernity-sepolia, fraxtal-mainnet, funki-mainnet, funki-sepolia, hashkeychain-mainnet, ink-mainnet, ink-sepolia, lisk-mainnet, lisk-sepolia, lyra-mainnet, metal-mainnet, metal-sepolia, mint-mainnet, mode-mainnet, mode-sepolia, op-mainnet, op-sepolia, oplabs-devnet-0-sepolia-dev-0, orderly-mainnet, ozean-sepolia, pivotal-sepolia, polynomial-mainnet, race-mainnet, race-sepolia, radius_testnet-sepolia, redstone-mainnet, rehearsal-0-bn-0-rehearsal-0-bn, rehearsal-0-bn-1-rehearsal-0-bn, settlus-mainnet-mainnet, settlus-sepolia-sepolia, shape-mainnet, shape-sepolia, silent-data-mainnet-mainnet, snax-mainnet, soneium-mainnet, soneium-minato-sepolia, sseed-mainnet, swan-mainnet, swell-mainnet, tbn-mainnet, tbn-sepolia, unichain-mainnet, unichain-sepolia, worldchain-mainnet, worldchain-sepolia, xterio-eth-mainnet, 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.fjord

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

override.granite

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

override.holocene

Manually specify the Optimism Holocene 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.isthmus

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

override.jovian

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

override.osaka

Manually specify the Osaka 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

Configure how gas prices are estimated and suggested to users.

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.

Logging and debugging

Control log output, profiling, and debugging tools.

go-execution-trace

Write Go execution trace to the given file.

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.

verbosity

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

Metrics and monitoring

Enable metrics collection and export to monitoring systems.

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.

General options

Help, version, and other general-purpose flags.

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

Nodes built from source do not output the correct version numbers that are reported on the GitHub release page.

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

Peer-to-peer networking

Configure P2P connections, peer discovery, and network settings.

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

discovery.v5

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

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

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 and resource management

Tune memory usage, caching, and other performance-related settings.

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

OP Stack specific options

Configuration options specific to OP Stack rollup functionality.

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

Add RPC-submitted transactions to the txpool (on by default if —rollup.sequencerhttp is not set). 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.interopmempoolfiltering

If using interop, transactions are checked for interop validity before being added to the mempool (experimental). The default value is false.

rollup.interoprpc

RPC endpoint for interop message verification (experimental).

rollup.sequencerhttp

HTTP endpoint for the sequencer mempool.

rollup.sequencertxconditionalcostratelimit

Maximum cost — storage lookups — allowed for conditional transactions in a given second. The default value is 5000.

rollup.sequencertxconditionalenabled

Serve the eth_sendRawTransactionConditional endpoint and apply the conditional constraints on mempool inclusion & block building. The default value is false.

rollup.superchain-upgrades

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

State and history management

Control how much historical state and transaction data to retain.

gcmode

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

history.chain

Blockchain history retention (“all” or “postmerge”). The default value is "all".

history.logs

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

history.logs.disable

Do not maintain log search index. The default value is false.

history.logs.export

Export checkpoints to file in go source file format.

history.state

Number of recent blocks to retain state history for, only relevant in state.scheme=path. 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 transactions

Configure the blob transaction pool (EIP-4844).

blobpool.datacap

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

blobpool.datadir

Data directory to store blob transactions in. The default value is "blobpool".

blobpool.pricebump

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

Transaction pool - Standard transactions

Configure the standard EVM transaction pool.

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

Maximum gas limit for individual transactions (0 = no limit). Transactions exceeding this limit will be rejected by the transaction pool. The default value is 0.

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.

EVM configuration

Options for EVM debugging and instrumentation.

vmdebug

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

vmtrace

Name of tracer which should record internal VM operations (costly).

vmtrace.jsonconfig

Tracer configuration (JSON). The default value is "{}".

Guides

Tutorials

Reference

​Execution layer configuration options (op-geth)

​Recommended configuration

​Essential flags

​Recommended flags for production

​Important configuration files

​Data directory (--datadir)

​JWT secret (--authrpc.jwtsecret)

​TOML configuration file (--config)

​Configuration options reference

​Account management

​keystore

​lightkdf

​password

​pcscdpath

​signer

​usb

​RPC and API configuration

​authrpc.addr

​authrpc.jwtsecret

​authrpc.port

​authrpc.vhosts

​exec

​graphql

​graphql.corsdomain

​graphql.vhosts

​header

​http

​http.addr

​http.api

​http.corsdomain

​http.port

​http.rpcprefix`\

​http.vhosts

​ipcdisable

​ipcpath

​jspath

​preload

​rpc.allow-unprotected-txs

​rpc.batch-request-limit

​rpc.batch-response-max-size

​rpc.evmtimeout

​rpc.gascap

​rpc.txfeecap

​ws

​ws.addr

​ws.api

​ws.origins

​ws.port

​ws.rpcprefix

​Development Chain

​dev

​dev.gaslimit

​dev.period

​Chain and network selection

​bloomfilter.size

​config

​datadir

​datadir.ancient

​datadir.era

​datadir.minfreedisk

​db.engine

​eth.requiredblocks

​exitwhensynced

​holesky

​hoodi

​mainnet

​networkid

​op-network, beta.op-network

​override.cancun

​override.canyon

​override.ecotone

​override.fjord

​override.granite

​override.holocene

​override.interop

​override.isthmus

​override.jovian

Execution layer configuration options (op-geth)

Recommended configuration

Essential flags

Recommended flags for production

Important configuration files

Data directory (`--datadir`)

JWT secret (`--authrpc.jwtsecret`)

TOML configuration file (`--config`)

Configuration options reference

Account management

keystore

lightkdf

password

pcscdpath

signer

usb

RPC and API configuration

authrpc.addr

authrpc.jwtsecret

authrpc.port

authrpc.vhosts

exec

graphql

graphql.corsdomain

graphql.vhosts

header

http

http.addr

http.api

http.corsdomain

http.port

http.rpcprefix`\

http.vhosts

ipcdisable

ipcpath

jspath

preload

rpc.allow-unprotected-txs

rpc.batch-request-limit

rpc.batch-response-max-size

rpc.evmtimeout

rpc.gascap

rpc.txfeecap

ws

ws.addr

ws.api

ws.origins

ws.port

ws.rpcprefix

Development Chain

dev

dev.gaslimit

dev.period

Chain and network selection

bloomfilter.size

config

datadir

datadir.ancient

datadir.era

datadir.minfreedisk

db.engine

eth.requiredblocks

exitwhensynced

holesky

hoodi

mainnet

networkid

op-network, beta.op-network

override.cancun

override.canyon

override.ecotone

override.fjord

override.granite

override.holocene

`override.interop`

override.isthmus

override.jovian

override.osaka

override.verkle

sepolia