Builders
Node Operators
Configuration
Consensus Layer Configuration

Consensus Layer Configuration Options (op-node)

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 list all configuration options for 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.7.5 (opens in a new tab).

Global Options

conductor.enabled

Enable the conductor service. The default value is false.

--conductor.enabled=<boolean>

conductor.rpc

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

--conductor.rpc=<value>

conductor.rpc-timeout value

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

--conductor.rpc-timeout value=<value>

l1

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

--l1=<value>

l1.beacon

Address of L1 Beacon-node HTTP endpoint to use.

--l1.beacon=<value>

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.fetch-all-sidecars=<boolean>

l1.beacon.ignore

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

--l1.beacon.ignore=<boolean>

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.epoch-poll-interval=<value>

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.http-poll-interval=<value>

l1.max-concurrency

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

--l1.max-concurrency=<value>

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-max-batch-size=<value>

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.rpc-rate-limit=<value>

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.rpckind=<value>

For details on additional values, see RPC Receipts (opens in a new tab).

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.runtime-config-reload-interval=<value>

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.

If you're running an Erigon Ethereum execution client for your L1 provider you will need to include --l1.trustrpc. At the time of writing, Erigon doesn't support the eth_getProof that we prefer to use to load L1 data for some processing in op-node. The trustrpc flag makes it use something else that erigon supports, but the op-node can't verify for correctness.

--l1.trustrpc=<boolean>

l2

Address of L2 Engine JSON-RPC endpoints to use (engine and eth namespace required). This is referred to as authrpc by Geth and Reth.

--l2=<value>

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.

--l2.jwt-secret=<value>

l2.enginekind

The kind of engine client, used to control the behavior of optimism in respect to different types of engine clients. Valid options: geth, reth, erigon. The default value is geth.

--l2.enginekind=<value>

log.color

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

--log.color=<boolean>

log.format

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

--log.format=<value>

log.level

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

--log.level=<value>

Node Log Levels

Node log levels determine the verbosity of log messages, allowing operators to filter messages based on importance and detail. The log levels for the op-node (used in Optimism) are as follows:

  1. Silent (0): No log messages are displayed. This level is rarely used as it provides no feedback on the node's status.

  2. Error (1): Only error messages are displayed. Use this level to focus on critical issues that need immediate attention.

  3. Warn (2): Displays error messages and warnings. This level helps to identify potential problems that might not be immediately critical but require attention.

  4. Info (3): Displays error messages, warnings, and normal activity logs. This is the default level and provides a balanced view of the node's operations without being too verbose.

  5. Debug (4): All info-level messages plus additional debugging information. Use this level when troubleshooting issues or developing the node software.

  6. Detail (5): The most verbose level, including detailed debugging information and low-level system operations. This level generates a large amount of log data and is typically used only for in-depth troubleshooting.

To set the log level, use the --log.level flag when running the op-node command. For example, to set the log level to debug:

op-node --log.level=debug

By adjusting the log level, operators can control the amount and type of information that gets logged, helping to manage log data volume and focus on relevant details during different operational scenarios.

metrics.addr

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

--metrics.addr=<value>

metrics.enabled

Enable the metrics server. The default value is false.

--metrics.enabled=<boolean>

metrics.port

Metrics listening port. The default value is 7300.

--metrics.port=<value>

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.

--network=<value>

override.canyon

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

--override.canyon=<value>

override.delta

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

--override.delta=<value>

override.ecotone

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

--override.ecotone=<value>

override.fjord

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

--override.fjord=<value>

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.ip=<value>

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.tcp=<value>

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.advertise.udp=<value>

p2p.ban.duration

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

--p2p.ban.duration=<value>

p2p.ban.peers

Enables peer banning. The default value is true.

--p2p.ban.peers=<boolean>

p2p.ban.threshold

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

--p2p.ban.threshold=<value>

p2p.bootnodes

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

--p2p.bootnodes=<value>

p2p.disable

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

--p2p.disable=<boolean>

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.discovery.path=<value>

p2p.listen.ip

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

--p2p.listen.ip=<value>

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.tcp=<value>

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.listen.udp=<value>

p2p.nat

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

--p2p.nat=<boolean>

p2p.netrestrict

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

--p2p.netrestrict=<value>

p2p.no-discovery

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

--p2p.no-discovery=<boolean>

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.grace=<value>

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.hi=<value>

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.peers.lo=<number>

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.peerstore.path=<path>

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.priv.path=<file-path>

p2p.scoring

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

--p2p.scoring=<strategy>

p2p.sequencer.key

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

--p2p.sequencer.key=<value>

p2p.static

Comma-separated multiaddr-format(an unsigned address, containing: IP, TCP port, PeerID) 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.static=<value>

p2p.sync.req-resp

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

--p2p.sync.req-resp=[true|false]

pprof.addr

pprof listening address. Default is "0.0.0.0".

--pprof.addr=<value>

pprof.enabled

Enable the pprof server. Default is false.

--pprof.enabled=[true|false]

pprof.path

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

--pprof.path=<path>

pprof.port

pprof listening port. Default is 6060.

--pprof.port=<value>

pprof.type

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

--pprof.type=<value>

rollup.config

Rollup chain parameters.

--rollup.config=<value>

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.halt=<value>

rollup.load-protocol-versions

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

--rollup.load-protocol-versions=[true|false]

rpc.addr

RPC listening address. Default is "127.0.0.1".

--rpc.addr=<value>

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.admin-state=<value>

rpc.enable-admin

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

--rpc.enable-admin=[true|false]

rpc.port

RPC listening port. Default is 9545.

--rpc.port=<value>

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.enabled=[true|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.l1-confs=<value>
⚠️

The maximum value for sequencer.l1-confs cannot exceed the sequencer drift, currently set to 30 minutes (1800 seconds or 150 blocks). Setting a value higher than this limit will prevent the sequencer from producing blocks within the sequence window.

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.max-safe-lag=<value>

sequencer.stopped

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

--sequencer.stopped=[true|false]

snapshotlog.file

Path to the snapshot log file.

--snapshotlog.file=<value>

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.

--verifier.l1-confs=<value>

While verifier.l1-confs has no strict limit, it's recommended to keep this value within 12-13 minutes (typically 10-20 blocks) for optimal performance. Exceeding this range may impact the verifier's data processing efficiency.

Miscellaneous

--help, -h

Show help. The default value is false.

--help OR -h

--version, -v

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

Print the version. The default value is false.

--version OR -v