diff --git a/node-operators/guides/consensus-config.mdx b/node-operators/guides/consensus-config.mdx index 891daa890..e43d946a4 100644 --- a/node-operators/guides/consensus-config.mdx +++ b/node-operators/guides/consensus-config.mdx @@ -12,42 +12,125 @@ description: Learn additional configuration and command line options for op-node 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](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.7.5). +This page lists all configuration options for `op-node`. `op-node` implements most rollup-specific functionality as the Consensus-Layer, similar to an L1 beacon-node. +The following options are from the `--help` in [v1.10.2](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.10.2). -## Global options +## Recommended configuration -### conductor.enabled +For most node operators, the following configuration provides a good starting point for running op-node. -Enable the conductor service. The default value is `false`. +### Essential flags for a replica node - - `--conductor.enabled=` - `--conductor.enabled=false` - `OP_NODE_CONDUCTOR_ENABLED=false` - +These are the minimum required flags to run op-node as a replica (non-sequencer): -### conductor.rpc +```bash +op-node \ + --l1=https://ethereum-rpc-endpoint.example.com \ + --l2=http://localhost:8551 \ + --l2.jwt-secret=/path/to/jwt-secret.txt \ + --network=op-mainnet \ + --rpc.addr=0.0.0.0 \ + --rpc.port=9545 +``` -Conductor service rpc endpoint. The default value is `http://127.0.0.1:8547`. +### Recommended flags for production - - `--conductor.rpc=` - `--conductor.rpc=http://127.0.0.1:8547` - `OP_NODE_CONDUCTOR_RPC=http://127.0.0.1:8547` - +For production deployments, add these flags for better reliability and observability: -### conductor.rpc-timeout value +```bash +op-node \ + --l1=https://ethereum-rpc-endpoint.example.com \ + --l1.beacon=https://ethereum-beacon-endpoint.example.com \ + --l2=http://localhost:8551 \ + --l2.jwt-secret=/path/to/jwt-secret.txt \ + --network=op-mainnet \ + --rpc.addr=0.0.0.0 \ + --rpc.port=9545 \ + --rpc.enable-admin \ + --metrics.enabled \ + --metrics.addr=0.0.0.0 \ + --metrics.port=7300 \ + --pprof.enabled \ + --pprof.addr=0.0.0.0 \ + --pprof.port=6060 \ + --p2p.disable=false \ + --p2p.listen.ip=0.0.0.0 \ + --p2p.listen.tcp=9222 \ + --p2p.listen.udp=9222 +``` -Conductor service rpc timeout. The default value is `1s`. +### Sequencer configuration - - `--conductor.rpc-timeout value=` - `--conductor.rpc-timeout value=1s` - `OP_NODE_CONDUCTOR_RPC_TIMEOUT=1s` - +If you're running a sequencer node, use these additional flags: + +```bash +op-node \ + --l1=https://ethereum-rpc-endpoint.example.com \ + --l1.beacon=https://ethereum-beacon-endpoint.example.com \ + --l2=http://localhost:8551 \ + --l2.jwt-secret=/path/to/jwt-secret.txt \ + --rollup.config=/path/to/rollup.json \ + --rpc.addr=0.0.0.0 \ + --rpc.port=9545 \ + --rpc.enable-admin \ + --sequencer.enabled \ + --sequencer.l1-confs=4 \ + --p2p.sequencer.key= +``` + + +Keep your sequencer private key secure and never commit it to version control. +Use environment variables or secure key management systems in production. + + +## Important configuration files + +When running op-node, you'll work with several important files: + +### JWT secret (`--l2.jwt-secret`) + +A hex-encoded 32-byte secret used for authenticated communication between op-node (consensus layer) and op-geth (execution layer). +This file must be identical to the one used by op-geth. + +Example of generating a JWT secret: +```bash +openssl rand -hex 32 > jwt-secret.txt +``` + +### Rollup configuration (`--rollup.config`) + +The rollup configuration file defines the chain parameters, including: +- Genesis block information +- L1 contract addresses +- Fork activation timestamps +- Block time and sequence window + +For standard networks (op-mainnet, base-mainnet, etc.), you can use the `--network` flag instead. +Custom chains require a rollup.json file. + +### P2P private key (`--p2p.priv.path`) + +The P2P private key file maintains your node's network identity across restarts. +Default location: `opnode_p2p_priv.txt` + +This file is automatically generated if it doesn't exist. Keep it persistent to maintain peer connections across restarts. + +### Peerstore database (`--p2p.peerstore.path`) -### l1 +The peerstore persists discovered peer information to speed up P2P bootstrapping after restarts. +Default location: `opnode_peerstore_db` + +Set to `memory` to disable persistence (peers must be rediscovered on every restart). + +## Configuration options reference + +The following sections provide detailed documentation for all available op-node configuration options, organized by functionality. + +### L1 and L2 connection settings + +Configure how op-node connects to L1 (Ethereum) and L2 (execution layer) endpoints. + +#### l1 Address of L1 User JSON-RPC endpoint to use (eth namespace required). The default value is `"http://127.0.0.1:8545"`. @@ -57,7 +140,7 @@ Address of L1 User JSON-RPC endpoint to use (eth namespace required). The defaul `OP_NODE_L1_ETH_RPC="http://127.0.0.1:8545"` -### l1.beacon +#### l1.beacon Address of L1 Beacon-node HTTP endpoint to use. @@ -67,7 +150,27 @@ Address of L1 Beacon-node HTTP endpoint to use. `OP_NODE_L1_BEACON="http://127.0.0.1:3500"` -### l1.beacon.fetch-all-sidecars +#### l1.beacon-fallbacks + +Addresses of L1 Beacon-API compatible HTTP fallback endpoints. Used to fetch blob sidecars not available at the l1.beacon (e.g. expired blobs). + + + `--l1.beacon-fallbacks=` + `--l1.beacon-fallbacks="http://fallback1.example.com,http://fallback2.example.com"` + `OP_NODE_L1_BEACON_FALLBACKS="http://fallback1.example.com,http://fallback2.example.com"` + + +#### l1.beacon-header + +Optional HTTP header to add to all requests to the L1 Beacon endpoint. Format: 'X-Key: Value' + + + `--l1.beacon-header=` + `--l1.beacon-header="Authorization: Bearer token"` + `OP_NODE_L1_BEACON_HEADER="Authorization: Bearer token"` + + +#### l1.beacon.fetch-all-sidecars If true, all sidecars are fetched and filtered locally. Workaround for buggy Beacon nodes. The default value is `false`. @@ -77,7 +180,7 @@ If true, all sidecars are fetched and filtered locally. Workaround for buggy Bea `OP_NODE_L1_BEACON=false` -### l1.beacon.ignore +#### l1.beacon.ignore When false, halts `op-node` startup if the healthcheck to the Beacon-node endpoint fails. The default value is `false`. @@ -87,7 +190,17 @@ When false, halts `op-node` startup if the healthcheck to the Beacon-node endpoi `OP_NODE_L1_BEACON_IGNORE=false` -### l1.epoch-poll-interval +#### l1.cache-size + +Cache size for blocks, receipts and transactions. If this flag is set to 0, 3/2 of the sequencing window size is used (usually 2400). The default value of 900 (~3h of L1 blocks) is good for (high-throughput) networks that see frequent safe head increments. On (low-throughput) networks with infrequent safe head increments, it is recommended to set this value to 0, or a value that well covers the typical span between safe head increments. Note that higher values will cause significantly increased memory usage. The default value is `900`. + + + `--l1.cache-size=` + `--l1.cache-size=900` + `OP_NODE_L1_CACHE_SIZE=900` + + +#### 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`. @@ -97,7 +210,7 @@ Poll interval for retrieving new L1 epoch updates such as safe and finalized blo `OP_NODE_L1_EPOCH_POLL_INTERVAL=6m24s` -### l1.http-poll-interval +#### 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`. @@ -107,7 +220,7 @@ Polling interval for latest-block subscription when using an HTTP RPC provider. `OP_NODE_L1_HTTP_POLL_INTERVAL=12s` -### l1.max-concurrency +#### l1.max-concurrency Maximum number of concurrent RPC requests to make to the L1 RPC provider. The default value is `10`. @@ -117,7 +230,7 @@ Maximum number of concurrent RPC requests to make to the L1 RPC provider. The de `OP_NODE_L1_MAX_CONCURRENCY=10` -### l1.rpc-max-batch-size +#### 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`. @@ -127,7 +240,7 @@ Maximum number of RPC requests to bundle, e.g., during L1 blocks receipt fetchin `OP_NODE_L1_RPC_MAX_BATCH_SIZE=20` -### l1.rpc-rate-limit +#### 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`. @@ -137,7 +250,7 @@ Optional self-imposed global rate-limit on L1 RPC requests, specified in request `OP_NODE_L1_RPC_RATE_LIMIT=0` -### l1.rpckind +#### 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`. @@ -151,7 +264,7 @@ The kind of RPC provider, used to inform optimal transactions receipts fetching, For details on additional values, see [RPC Receipts](https://github.com/ethereum-optimism/optimism/blob/844cc20084a2e9716631b4092ce7eca4804a8e0a/op-service/sources/receipts_rpc.go#L239-L322). -### l1.runtime-config-reload-interval +#### 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`. @@ -161,7 +274,7 @@ Poll interval for reloading the runtime config, useful when config events are no `OP_NODE_L1_RUNTIME_CONFIG_RELOAD_INTERVAL=10m0s` -### l1.trustrpc +#### 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`. @@ -177,7 +290,7 @@ Trust the L1 RPC, sync faster at risk of malicious/buggy RPC providing bad or in `OP_NODE_L1_TRUST_RPC=false` -### l2 +#### 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. @@ -187,7 +300,17 @@ Address of L2 Engine JSON-RPC endpoints to use (engine and eth namespace require `OP_NODE_L2_ENGINE_RPC=http://127.0.0.1:8751` -### l2.jwt-secret +#### l2.engine-rpc-timeout + +L2 engine client rpc timeout. The default value is `10s`. + + + `--l2.engine-rpc-timeout=` + `--l2.engine-rpc-timeout=10s` + `OP_NODE_L2_ENGINE_RPC_TIMEOUT=10s` + + +#### 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. @@ -197,7 +320,7 @@ Path to JWT secret key. Keys are 32 bytes, hex encoded in a file. A new key will `OP_NODE_L2_ENGINE_AUTH=/path/to/jwt/secret` -### l2.enginekind +#### 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`. @@ -207,7 +330,191 @@ The kind of engine client, used to control the behavior of optimism in respect t `OP_NODE_L2_ENGINE_KIND=geth` -### log.color +### Network selection and rollup configuration + +Configure which OP Stack network to connect to and manage rollup-specific settings. + +#### network + +Predefined network selection. Available networks: 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. + + + `--network=` + `--network=op-mainnet` + `OP_NODE_NETWORK=op-mainnet` + + +#### rollup.config + +Rollup chain parameters. + + + `--rollup.config=` + `--rollup.config=[ConfigValueHere]` + `OP_NODE_ROLLUP_CONFIG=[ConfigValueHere]` + + +#### 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=` + `--rollup.halt=[HaltOptionHere]` + `OP_NODE_ROLLUP_HALT=[HaltOptionHere]` + + +#### rollup.l1-chain-config + +Path to .json file with the chain configuration for the L1, either in the direct format or genesis.json format (i.e. embedded under the .config property). Not necessary / will be ignored if using Ethereum mainnet or Sepolia as an L1. + + + `--rollup.l1-chain-config=` + `--rollup.l1-chain-config=/path/to/l1-config.json` + `OP_NODE_ROLLUP_L1_CHAIN_CONFIG=/path/to/l1-config.json` + + +#### 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]` + `--rollup.load-protocol-versions=false` + `OP_NODE_ROLLUP_LOAD_PROTOCOL_VERSIONS=false` + + +#### syncmode + +Blockchain sync mode. Options are "consensus-layer" or "execution-layer". The default value is `consensus-layer`. + + + `--syncmode=` + `--syncmode=consensus-layer` + `OP_NODE_SYNCMODE=consensus-layer` + + +### Fork overrides + +Manually override fork activation timestamps for testing or custom deployments. + +#### override.canyon + +Manually specify the Canyon fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.canyon=` + `--override.canyon=0` + `OP_NODE_OVERRIDE_CANYON=0` + + +#### override.delta + +Manually specify the Delta fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.delta=` + `--override.delta=0` + `OP_NODE_OVERRIDE_DELTA=0` + + +#### override.ecotone + +Manually specify the ecotone fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.ecotone=` + `--override.ecotone=0` + `OP_NODE_OVERRIDE_ECOTONE=0` + + +#### override.fjord + +Manually specify the fjord fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.fjord=` + `--override.fjord=0` + `OP_NODE_OVERRIDE_FJORD=0` + + +#### override.granite + +Manually specify the granite fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.granite=` + `--override.granite=0` + `OP_NODE_OVERRIDE_GRANITE=0` + + +#### override.holocene + +Manually specify the holocene fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.holocene=` + `--override.holocene=0` + `OP_NODE_OVERRIDE_HOLOCENE=0` + + +#### override.isthmus + +Manually specify the isthmus fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.isthmus=` + `--override.isthmus=0` + `OP_NODE_OVERRIDE_ISTHMUS=0` + + +#### override.interop + +Manually specify the Interop fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.interop=` + `--override.interop=0` + `OP_NODE_OVERRIDE_INTEROP=0` + + +#### override.jovian + +Manually specify the Jovian fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.jovian=` + `--override.jovian=0` + `OP_NODE_OVERRIDE_JOVIAN=0` + + +#### override.pectrablobschedule + +Manually specify the PectraBlobSchedule fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.pectrablobschedule=` + `--override.pectrablobschedule=0` + `OP_NODE_OVERRIDE_PECTRABLOBSCHEDULE=0` + + +### Logging configuration + +Control log output format, level, and color. + +#### log.color Color the log output if in terminal mode. The default value is `false`. @@ -217,7 +524,7 @@ Color the log output if in terminal mode. The default value is `false`. `OP_NODE_LOG_COLOR=false` -### log.format +#### log.format Format the log output. Supported formats: 'text', 'terminal', 'logfmt', 'json', 'json-pretty'. The default value is `text`. @@ -227,7 +534,7 @@ Format the log output. Supported formats: 'text', 'terminal', 'logfmt', 'json', `OP_NODE_LOG_FORMAT=text` -### log.level +#### log.level The lowest log level that will be output. The default value is `info`. @@ -237,43 +544,65 @@ The lowest log level that will be output. The default value is `info`. `OP_NODE_LOG_LEVEL=info` -### Node log levels +#### log.pid -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: +Show pid in the log. The default value is `false`. -1. Silent (0): No log messages are displayed. This level is rarely used as it provides - no feedback on the node's status. + + `--log.pid=` + `--log.pid=false` + `OP_NODE_LOG_PID=false` + -2. Error (1): Only error messages are displayed. Use this level to focus on critical - issues that need immediate attention. +### Logging and RPC -3. Warn (2): Displays error messages and warnings. This level helps to identify - potential problems that might not be immediately critical but require attention. +Configure RPC API endpoints and admin functionality. -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. +#### rpc.addr -5. Debug (4): All info-level messages plus additional debugging information. Use this - level when troubleshooting issues or developing the node software. +RPC listening address. Default is `"0.0.0.0"`. -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. + + `--rpc.addr=` + `--rpc.addr=0.0.0.0` + `OP_NODE_RPC_ADDR=0.0.0.0` + -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: +#### rpc.admin-state -```bash -op-node --log.level=debug -``` +File path used to persist state changes made via the admin API so they persist across restarts. Disabled if not set. -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. + + `--rpc.admin-state=` + `--rpc.admin-state=[FilePathHere]` + `OP_NODE_RPC_ADMIN_STATE=[FilePathHere]` + -### metrics.addr +#### rpc.enable-admin + +Enable the admin API (experimental). Default is `false`. + + + `--rpc.enable-admin=[true|false]` + `--rpc.enable-admin=false` + `OP_NODE_RPC_ENABLE_ADMIN=false` + + +#### rpc.port + +RPC listening port. Default is `9545`. + + + `--rpc.port=` + `--rpc.port=9545` + `OP_NODE_RPC_PORT=9545` + + +### Metrics and profiling + +Enable observability through metrics and performance profiling. + +#### metrics.addr Metrics listening address. The default value is `"0.0.0.0"`. @@ -283,7 +612,7 @@ Metrics listening address. The default value is `"0.0.0.0"`. `OP_NODE_METRICS_ADDR="0.0.0.0"` -### metrics.enabled +#### metrics.enabled Enable the metrics server. The default value is `false`. @@ -293,7 +622,7 @@ Enable the metrics server. The default value is `false`. `OP_NODE_METRICS_ENABLED=false` -### metrics.port +#### metrics.port Metrics listening port. The default value is `7300`. @@ -303,92 +632,61 @@ Metrics listening port. The default value is `7300`. `OP_NODE_METRICS_PORT=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. - - - `--network=` - `--network=op-mainnet` - `OP_NODE_NETWORK=op-mainnet` - - -### override.canyon - -Manually specify the Canyon fork timestamp, overriding the bundled setting. The default value is `0`. - - - `--override.canyon=` - `--override.canyon=0` - `OP_NODE_OVERRIDE_CANYON=0` - - -### override.delta +#### pprof.addr -Manually specify the Delta fork timestamp, overriding the bundled setting. The default value is `0`. +pprof listening address. Default is `"0.0.0.0"`. - `--override.delta=` - `--override.delta=0` - `OP_NODE_OVERRIDE_DELTA=0` + `--pprof.addr=` + `--pprof.addr=0.0.0.0` + `OP_NODE_PPROF_ADDR=0.0.0.0` -### override.ecotone +#### pprof.enabled -Manually specify the ecotone fork timestamp, overriding the bundled setting. The default value is `0`. +Enable the pprof server. Default is `false`. - `--override.ecotone=` - `--override.ecotone=0` - `OP_NODE_OVERRIDE_ECOTONE=0` + `--pprof.enabled=[true|false]` + `--pprof.enabled=false` + `OP_NODE_PPROF_ENABLED=false` -### override.fjord +#### pprof.path -Manually specify the fjord fork timestamp, overriding the bundled setting. The default value is `0`. +pprof file path. If it is a directory, the path is \{dir}/\{profileType}.prof - `--override.fjord=` - `--override.fjord=0` - `OP_NODE_OVERRIDE_FJORD=0` + `--pprof.path=` + `--pprof.path={dir}/{profileType}.prof` + `OP_NODE_PPROF_PATH={dir}/{profileType}.prof` -### override.granite +#### pprof.port -Manually specify the granite fork timestamp, overriding the bundled setting. The default value is `0`. +pprof listening port. Default is `6060`. - `--override.granite=` - `--override.granite=0` - `OP_NODE_OVERRIDE_GRANITE=0` + `--pprof.port=` + `--pprof.port=6060` + `OP_NODE_PPROF_PORT=6060` -### override.holocene +#### pprof.type -Manually specify the holocene fork timestamp, overriding the bundled setting. The default value is `0`. +pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs - `--override.holocene=` - `--override.holocene=0` - `OP_NODE_OVERRIDE_HOLOCENE=0` + `--pprof.type=` + `--pprof.type=cpu` + `OP_NODE_PPROF_TYPE=cpu` -### override.isthmus +### P2P networking -Manually specify the isthmus fork timestamp, overriding the bundled setting. The default value is `0`. - - - `--override.isthmus=` - `--override.isthmus=0` - `OP_NODE_OVERRIDE_ISTHMUS=0` - +Configure peer-to-peer networking, discovery, and connection management. -### p2p.advertise.ip +#### 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. @@ -398,7 +696,7 @@ The IP address to advertise in Discv5, put into the ENR of the node. This may al `OP_NODE_P2P_ADVERTISE_IP=YourIPAddressOrHostnameHere` -### p2p.advertise.tcp +#### 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`. @@ -408,7 +706,7 @@ The TCP port to advertise in Discv5, put into the ENR of the node. Set to p2p.li `OP_NODE_P2P_ADVERTISE_TCP=3456` -### p2p.advertise.udp +#### 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`. @@ -418,7 +716,7 @@ The UDP port to advertise in Discv5 as a fallback if not determined by Discv5, p `OP_NODE_P2P_ADVERTISE_UDP=3457` -### p2p.ban.duration +#### p2p.ban.duration The duration that peers are banned for. The default value is `1h0m0s`. @@ -428,7 +726,7 @@ The duration that peers are banned for. The default value is `1h0m0s`. `OP_NODE_P2P_PEER_BANNING_DURATION=1h0m0s` -### p2p.ban.peers +#### p2p.ban.peers Enables peer banning. The default value is `true`. @@ -438,7 +736,7 @@ Enables peer banning. The default value is `true`. `OP_NODE_P2P_PEER_BANNING=true` -### p2p.ban.threshold +#### p2p.ban.threshold The minimum score below which peers are disconnected and banned. The default value is `-100`. @@ -448,7 +746,7 @@ The minimum score below which peers are disconnected and banned. The default val `OP_NODE_P2P_PEER_BANNING_THRESHOLD=-100` -### p2p.bootnodes +#### p2p.bootnodes Comma-separated base64-format ENR list. Bootnodes to start discovering other node records from. @@ -458,7 +756,7 @@ Comma-separated base64-format ENR list. Bootnodes to start discovering other nod `OP_NODE_P2P_BOOTNODES=YourBootnodesListHere` -### p2p.disable +#### p2p.disable Completely disable the P2P stack. The default value is `false`. @@ -468,7 +766,7 @@ Completely disable the P2P stack. The default value is `false`. `OP_NODE_P2P_DISABLE=false` -### p2p.discovery.path +#### 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`. @@ -478,7 +776,17 @@ Enables persistent storage of discovered ENRs in a database to recover from a re `OP_NODE_P2P_DISCOVERY_PATH=opnode_discovery_db` -### p2p.listen.ip +#### p2p.gossip.timestamp.threshold + +Threshold for rejecting gossip messages with payload timestamps older than this duration. The default value is `1m0s`. + + + `--p2p.gossip.timestamp.threshold=` + `--p2p.gossip.timestamp.threshold=1m0s` + `OP_NODE_P2P_GOSSIP_TIMESTAMP_THRESHOLD=1m0s` + + +#### p2p.listen.ip Specifies the IP to bind LibP2P and Discv5 to. The default value is `0.0.0.0`. @@ -488,7 +796,7 @@ Specifies the IP to bind LibP2P and Discv5 to. The default value is `0.0.0.0`. `OP_NODE_P2P_LISTEN_IP=0.0.0.0` -### p2p.listen.tcp +#### p2p.listen.tcp Defines the TCP port to bind LibP2P to. Any available system port if set to 0. The default value is `9222`. @@ -498,7 +806,7 @@ Defines the TCP port to bind LibP2P to. Any available system port if set to 0. T `OP_NODE_P2P_LISTEN_TCP_PORT=9222` -### p2p.listen.udp +#### 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`. @@ -508,7 +816,7 @@ Sets the UDP port to bind Discv5 to. It will be the same as the TCP port if left `OP_NODE_P2P_LISTEN_UDP_PORT=0` -### p2p.nat +#### p2p.nat Enables NAT traversal with PMP/UPNP devices to learn external IP. The default value is `false`. @@ -518,7 +826,7 @@ Enables NAT traversal with PMP/UPNP devices to learn external IP. The default va `OP_NODE_P2P_NAT=false` -### p2p.netrestrict +#### p2p.netrestrict Specifies a comma-separated list of CIDR masks. P2P will only try to connect on these networks. @@ -528,7 +836,7 @@ Specifies a comma-separated list of CIDR masks. P2P will only try to connect on `OP_NODE_P2P_NETRESTRICT=` -### p2p.no-discovery +#### p2p.no-discovery Disables Discv5 (node discovery). The default value is `false`. @@ -538,7 +846,7 @@ Disables Discv5 (node discovery). The default value is `false`. `OP_NODE_P2P_NO_DISCOVERY=false` -### p2p.peers.grace +#### p2p.peers.grace Determines the grace period to keep a newly connected peer around, if it is not misbehaving. The default value is `30s`. @@ -548,7 +856,7 @@ Determines the grace period to keep a newly connected peer around, if it is not `OP_NODE_P2P_PEERS_GRACE=30s` -### p2p.peers.hi +#### 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`. @@ -558,7 +866,7 @@ Sets the high-tide peer count. The node starts pruning peer connections slowly a `OP_NODE_P2P_PEERS_HI=30` -### p2p.peers.lo +#### 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`. @@ -568,7 +876,7 @@ Determines the low-tide peer count. The node actively searches for new peer conn `OP_NODE_P2P_PEERS_LO=20` -### p2p.peerstore.path +#### 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"`. @@ -578,7 +886,7 @@ Specifies the Peerstore database location. Persisted peerstores help recover pee `OP_NODE_P2P_PEERSTORE_PATH=opnode_peerstore_db` -### p2p.priv.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"`. @@ -588,7 +896,7 @@ Defines the file path for reading the hex-encoded 32-byte private key for the pe `OP_NODE_P2P_PRIV_PATH=opnode_p2p_priv.txt` -### p2p.scoring +#### p2p.scoring Sets the peer scoring strategy for the P2P stack. Options include 'none' or 'light'. The default value is `"light"`. @@ -598,7 +906,7 @@ Sets the peer scoring strategy for the P2P stack. Options include 'none' or 'lig `OP_NODE_P2P_PEER_SCORING=light` -### p2p.sequencer.key +#### p2p.sequencer.key Hex-encoded private key for signing off on p2p application messages as sequencer. @@ -608,7 +916,7 @@ Hex-encoded private key for signing off on p2p application messages as sequencer `OP_NODE_P2P_SEQUENCER_KEY=[YourKeyHere]` -### p2p.static +#### p2p.static Comma-separated multiaddr-format(an unsigned address, containing: IP, TCP port, [PeerID](/operators/node-operators/json-rpc#opp2p_self)) peer list. Static connections to make and maintain, these peers will be regarded as trusted. Addresses of the local peer @@ -621,7 +929,7 @@ only a single connection per peer is maintained. `OP_NODE_P2P_STATIC=/ip4/127.0.0.1/tcp/9222/p2p/16Uiu2HAm2y6DXp6THWHCyquczNUh8gVAm4spo6hjP3Ns1dGRiAdE` -### p2p.sync.onlyreqtostatic +#### p2p.sync.onlyreqtostatic Restricts `RequestL2Range` sync requests to static peers only. Useful for enforcing trusted peer sync. When enabled, non-static peers are skipped during sync. Default is `false`. @@ -631,7 +939,7 @@ Restricts `RequestL2Range` sync requests to static peers only. Useful for enforc `OP_NODE_P2P_SYNC_ONLYREQTOSTATIC=true` -### p2p.sync.req-resp +#### p2p.sync.req-resp Enables P2P req-resp alternative sync method, on both server and client side. Default is `true`. @@ -641,205 +949,367 @@ Enables P2P req-resp alternative sync method, on both server and client side. De `OP_NODE_P2P_SYNC_REQ_RESP=true` -### pprof.addr +### Sequencer options -pprof listening address. Default is `"0.0.0.0"`. +Configuration for running op-node as a sequencer. + +#### 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`. - `--pprof.addr=` - `--pprof.addr=0.0.0.0` - `OP_NODE_PPROF_ADDR=0.0.0.0` + `--sequencer.enabled=[true|false]` + `--sequencer.enabled=false` + `OP_NODE_SEQUENCER_ENABLED=false` -### pprof.enabled +#### sequencer.l1-confs -Enable the pprof server. Default is `false`. +Number of L1 blocks to keep distance from the L1 head as a sequencer for picking an L1 origin. Default is `4`. - `--pprof.enabled=[true|false]` - `--pprof.enabled=false` - `OP_NODE_PPROF_ENABLED=false` + `--sequencer.l1-confs=` + `--sequencer.l1-confs=4` + `OP_NODE_SEQUENCER_L1_CONFS=4` -### pprof.path + +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. + -pprof file path. If it is a directory, the path is \{dir}/\{profileType}.prof +#### sequencer.max-safe-lag + +Maximum number of L2 blocks for restricting the distance between L2 safe and unsafe. Disabled if 0. Default is `0`. - `--pprof.path=` - `--pprof.path={dir}/{profileType}.prof` - `OP_NODE_PPROF_PATH={dir}/{profileType}.prof` + `--sequencer.max-safe-lag=` + `--sequencer.max-safe-lag=0` + `OP_NODE_SEQUENCER_MAX_SAFE_LAG=0` -### pprof.port +#### sequencer.recover -pprof listening port. Default is `6060`. +Forces the sequencer to strictly prepare the next L1 origin and create empty L2 blocks. Default is `false`. - `--pprof.port=` - `--pprof.port=6060` - `OP_NODE_PPROF_PORT=6060` + `--sequencer.recover=[true|false]` + `--sequencer.recover=false` + `OP_NODE_SEQUENCER_RECOVER=false` -### pprof.type +#### sequencer.stopped -pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs +Initialize the sequencer in a stopped state. The sequencer can be started using the admin\_startSequencer RPC. Default is `false`. - `--pprof.type=` - `--pprof.type=cpu` - `OP_NODE_PPROF_TYPE=cpu` + `--sequencer.stopped=[true|false]` + `--sequencer.stopped=false` + `OP_NODE_SEQUENCER_STOPPED=false` -### rollup.config +### Verifier options -Rollup chain parameters. +Configuration for running op-node as a verifier (replica node). + +#### 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`. - `--rollup.config=` - `--rollup.config=[ConfigValueHere]` - `OP_NODE_ROLLUP_CONFIG=[ConfigValueHere]` + `--verifier.l1-confs=` + `--verifier.l1-confs=0` + `OP_NODE_VERIFIER_L1_CONFS=0` -### rollup.halt + +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. + + +### Conductor mode -Opt-in option to halt on incompatible protocol version requirements of the given level (major/minor/patch/none), as signaled onchain in L1. +Options for running op-node in conductor mode (for conductor-enabled chains). + +#### conductor.enabled + +Enable the conductor service. The default value is `false`. - `--rollup.halt=` - `--rollup.halt=[HaltOptionHere]` - `OP_NODE_ROLLUP_HALT=[HaltOptionHere]` + `--conductor.enabled=` + `--conductor.enabled=false` + `OP_NODE_CONDUCTOR_ENABLED=false` -### rollup.load-protocol-versions +#### conductor.rpc -Load protocol versions from the superchain L1 ProtocolVersions contract (if available), and report in logs and metrics. Default is `false`. +Conductor service rpc endpoint. The default value is `http://127.0.0.1:8547`. - `--rollup.load-protocol-versions=[true|false]` - `--rollup.load-protocol-versions=false` - `OP_NODE_ROLLUP_LOAD_PROTOCOL_VERSIONS=false` + `--conductor.rpc=` + `--conductor.rpc=http://127.0.0.1:8547` + `OP_NODE_CONDUCTOR_RPC=http://127.0.0.1:8547` -### rpc.addr +#### conductor.rpc-timeout -RPC listening address. Default is `"127.0.0.1"`. +Conductor service rpc timeout. The default value is `1s`. - `--rpc.addr=` - `--rpc.addr=127.0.0.1` - `OP_NODE_RPC_ADDR=127.0.0.1` + `--conductor.rpc-timeout=` + `--conductor.rpc-timeout=1s` + `OP_NODE_CONDUCTOR_RPC_TIMEOUT=1s` -### rpc.admin-state +### Database and state persistence -File path used to persist state changes made via the admin API so they persist across restarts. Disabled if not set. +Configure persistent storage for node state and snapshot data. + +#### safedb.path + +File path used to persist safe head update data. Disabled if not set. - `--rpc.admin-state=` - `--rpc.admin-state=[FilePathHere]` - `OP_NODE_RPC_ADMIN_STATE=[FilePathHere]` + `--safedb.path=` + `--safedb.path=/db` + `OP_NODE_SAFEDB_PATH=/db` -### rpc.enable-admin +#### snapshotlog.file -Enable the admin API (experimental). Default is `false`. +Path to the snapshot log file. - `--rpc.enable-admin=[true|false]` - `--rpc.enable-admin=false` - `OP_NODE_RPC_ENABLE_ADMIN=false` + `--snapshotlog.file=` + `--snapshotlog.file=[FilePathHere]` + `OP_NODE_SNAPSHOT_LOG=[FilePathHere]` -### rpc.port +### Signer configuration -RPC listening port. Default is `9545`. +Options for configuring an external signer for P2P messages. + +#### signer.address + +Address the signer is signing requests for. - `--rpc.port=` - `--rpc.port=9545` - `OP_NODE_RPC_PORT=9545` + `--signer.address=` + `--signer.address=0x1234...` + `OP_NODE_SIGNER_ADDRESS=0x1234...` -### safedb.path +#### signer.endpoint -File path used to persist safe head update data. Disabled if not set. +Signer endpoint the client will connect to. - `--safedb.path=` - `--safedb.path=/db` - `OP_NODE_SAFEDB_PATH=/db` + `--signer.endpoint=` + `--signer.endpoint=https://signer.example.com` + `OP_NODE_SIGNER_ENDPOINT=https://signer.example.com` -### sequencer.enabled +#### signer.header -Enable sequencing of new L2 blocks. A separate batch submitter has to be deployed to publish the data for verifiers. Default is `false`. +Headers to pass to the remote signer. Format `key=value`. Value can contain any character allowed in a HTTP header. When using env vars, split with commas. When using flags one key value pair per flag. - `--sequencer.enabled=[true|false]` - `--sequencer.enabled=false` - `OP_NODE_SEQUENCER_ENABLED=false` + `--signer.header=` + `--signer.header="Authorization: Bearer token"` + `OP_NODE_SIGNER_HEADER="Authorization: Bearer token"` -### sequencer.l1-confs +#### signer.tls.ca -Number of L1 blocks to keep distance from the L1 head as a sequencer for picking an L1 origin. Default is `4`. +TLS ca cert path. The default value is `"tls/ca.crt"`. - `--sequencer.l1-confs=` - `--sequencer.l1-confs=4` - `OP_NODE_SEQUENCER_L1_CONFS=4` + `--signer.tls.ca=` + `--signer.tls.ca="tls/ca.crt"` + `OP_NODE_SIGNER_TLS_CA="tls/ca.crt"` - -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. - +#### signer.tls.cert -### sequencer.max-safe-lag +TLS cert path. The default value is `"tls/tls.crt"`. -Maximum number of L2 blocks for restricting the distance between L2 safe and unsafe. Disabled if 0. Default is `0`. + + `--signer.tls.cert=` + `--signer.tls.cert="tls/tls.crt"` + `OP_NODE_SIGNER_TLS_CERT="tls/tls.crt"` + + +#### signer.tls.enabled + +Enable or disable TLS client authentication for the signer. The default value is `true`. - `--sequencer.max-safe-lag=` - `--sequencer.max-safe-lag=0` - `OP_NODE_SEQUENCER_MAX_SAFE_LAG=0` + `--signer.tls.enabled=` + `--signer.tls.enabled=true` + `OP_NODE_SIGNER_TLS_ENABLED=true` -### sequencer.stopped +#### signer.tls.key -Initialize the sequencer in a stopped state. The sequencer can be started using the admin\_startSequencer RPC. Default is `false`. +TLS key path. The default value is `"tls/tls.key"`. - `--sequencer.stopped=[true|false]` - `--sequencer.stopped=false` - `OP_NODE_SEQUENCER_STOPPED=false` + `--signer.tls.key=` + `--signer.tls.key="tls/tls.key"` + `OP_NODE_SIGNER_TLS_KEY="tls/tls.key"` -### snapshotlog.file +### Alt-DA (Experimental) -Path to the snapshot log file. + +Alt-DA Mode is a Beta feature of the MIT licensed OP Stack. While it has received initial review from core contributors, it is still undergoing testing, and may have bugs or other issues. + + +Configuration options for Alternative Data Availability mode. + +#### altda.enabled + +Enable Alt-DA mode. The default value is `false`. - `--snapshotlog.file=` - `--snapshotlog.file=[FilePathHere]` - `OP_NODE_SNAPSHOT_LOG=[FilePathHere]` + `--altda.enabled=` + `--altda.enabled=false` + `OP_NODE_ALTDA_ENABLED=false` -### verifier.l1-confs +#### altda.da-server -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`. +HTTP address of a DA Server. - `--verifier.l1-confs=` - `--verifier.l1-confs=0` - `OP_NODE_VERIFIER_L1_CONFS=0` + `--altda.da-server=` + `--altda.da-server=http://da-server.example.com` + `OP_NODE_ALTDA_DA_SERVER=http://da-server.example.com` - -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. - +#### altda.da-service + +Use DA service type where commitments are generated by Alt-DA server. The default value is `false`. + + + `--altda.da-service=` + `--altda.da-service=false` + `OP_NODE_ALTDA_DA_SERVICE=false` + + +#### altda.get-timeout + +Timeout for get requests. 0 means no timeout. The default value is `0s`. + + + `--altda.get-timeout=` + `--altda.get-timeout=0s` + `OP_NODE_ALTDA_GET_TIMEOUT=0s` + + +#### altda.max-concurrent-da-requests + +Maximum number of concurrent requests to the DA server. The default value is `1`. + + + `--altda.max-concurrent-da-requests=` + `--altda.max-concurrent-da-requests=1` + `OP_NODE_ALTDA_MAX_CONCURRENT_DA_REQUESTS=1` + + +#### altda.put-timeout + +Timeout for put requests. 0 means no timeout. The default value is `0s`. + + + `--altda.put-timeout=` + `--altda.put-timeout=0s` + `OP_NODE_ALTDA_PUT_TIMEOUT=0s` + + +#### altda.verify-on-read + +Verify input data matches the commitments from the DA storage service. The default value is `true`. + + + `--altda.verify-on-read=` + `--altda.verify-on-read=true` + `OP_NODE_ALTDA_VERIFY_ON_READ=true` + + +### Interop (Super Experimental) + + +Interop is a highly experimental feature. Use with caution in production environments. + + +Configuration options for OP Stack interop networks. + +#### interop.dependency-set + +Dependency-set configuration, point at JSON file. + + + `--interop.dependency-set=` + `--interop.dependency-set=/path/to/dependency-set.json` + `OP_NODE_INTEROP_DEPENDENCY_SET=/path/to/dependency-set.json` + -## Miscellaneous +#### interop.jwt-secret + +Interop RPC server authentication. Path to JWT secret key. Keys are 32 bytes, hex encoded in a file. A new key will be generated if the file is empty. Applies only to Interop-enabled networks. + + + `--interop.jwt-secret=` + `--interop.jwt-secret=/path/to/interop-jwt-secret.txt` + `OP_NODE_INTEROP_JWT_SECRET=/path/to/interop-jwt-secret.txt` + + +#### interop.rpc.addr + +Interop Websocket-only RPC listening address, for supervisor service to manage syncing of the op-node. Applies only to Interop-enabled networks. Optional, disabled if left empty. Do not enable if you do not run a supervisor service. + + + `--interop.rpc.addr=` + `--interop.rpc.addr=0.0.0.0` + `OP_NODE_INTEROP_RPC_ADDR=0.0.0.0` + + +#### interop.rpc.port + +Interop RPC listening port, to serve supervisor syncing. Applies only to Interop-enabled networks. The default value is `9645`. + + + `--interop.rpc.port=` + `--interop.rpc.port=9645` + `OP_NODE_INTEROP_RPC_PORT=9645` + + +### Experimental and miscellaneous + +Additional experimental features and utility flags. + +#### experimental.sequencer-api + +Enables experimental test sequencer RPC functionality. The default value is `false`. + + + `--experimental.sequencer-api=` + `--experimental.sequencer-api=false` + `OP_NODE_EXPERIMENTAL_SEQUENCER_API=false` + + +#### fetch-withdrawal-root-from-state + +Read withdrawal_storage_root (aka message passer storage root) from state trie (via execution layer) instead of the block header. Restores pre-Isthmus behavior, requires an archive EL client. The default value is `false`. + + + `--fetch-withdrawal-root-from-state=` + `--fetch-withdrawal-root-from-state=false` + `OP_NODE_FETCH_WITHDRAWAL_ROOT_FROM_STATE=false` + + +## General options + +Help and version information. ### --help, -h @@ -863,3 +1333,39 @@ Print the version. The default value is `false`. `--version` OR `-v` `--version` + +### 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: + +```bash +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. diff --git a/node-operators/guides/execution-config.mdx b/node-operators/guides/execution-config.mdx index 92fe97fdd..f89d46190 100644 --- a/node-operators/guides/execution-config.mdx +++ b/node-operators/guides/execution-config.mdx @@ -3,29 +3,120 @@ title: Execution layer configuration options (op-geth) description: Learn additional configuration and command line options for op-geth and the Execution-Layer. --- +# Execution layer configuration options (op-geth) + -You can configure your node using the command line options below (also called flags). +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-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](https://github.com/ethereum-optimism/op-geth/releases/tag/v1.101308.0) +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](https://github.com/ethereum-optimism/op-geth/releases/tag/v1.101603.3-rc.3) Please note that the executable is still named `geth` to maintain a [minimal diff](https://op-geth.optimism.io/?utm_source=op-docs&utm_medium=docs). -## Global options - -### Account - -#### allow-insecure-unlock - -Allows insecure account unlocking when account-related RPCs are exposed by HTTP. The default value is `false`. - - - `--allow-insecure-unlock` - `--allow-insecure-unlock=false` - `GETH_ALLOW_INSECURE_UNLOCK=false` - +## 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: + +```bash +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: + +```bash +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: +```bash +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: +```bash +geth dumpconfig > config.toml +``` + +Edit the file and run with: +```bash +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 @@ -77,16 +168,6 @@ External signer (url or path to ipc file). `GETH_SIGNER=/path/to/ipcfile` -#### unlock - -Comma separated list of accounts to unlock. - - - `--unlock ` - `--unlock=0x1234,0x5678` - `GETH_UNLOCK=0x1234,0x5678` - - #### usb Enable monitoring and management of USB hardware wallets. The default value is `false`. @@ -97,7 +178,9 @@ Enable monitoring and management of USB hardware wallets. The default value is ` `GETH_USB=false` -### API and Console +### RPC and API configuration + +Configure HTTP, WebSocket, authenticated RPC endpoints, and console access. #### authrpc.addr @@ -331,16 +414,6 @@ Maximum number of bytes returned from a batched call. The default value is `2500 `GETH_RPC_BATCH_RESPONSE_MAX_SIZE=25000000` -#### rpc.enabledeprecatedpersonal - -Enables the (deprecated) personal namespace. The default value is `false`. - - - `--rpc.enabledeprecatedpersonal` - `--rpc.enabledeprecatedpersonal=false` - `GETH_RPC_ENABLEDEPRECATEDPERSONAL=false` - - #### rpc.evmtimeout Sets a timeout used for eth\_call (0=infinite). The default value is `5s`. @@ -431,7 +504,9 @@ HTTP path prefix on which JSON-RPC is served over WS. Use '/' to serve on all pa `GETH_WS_RPCPREFIX="/"` -### Developer Chain +### Development Chain + +Options for running a local development chain with pre-funded accounts. #### dev @@ -464,7 +539,9 @@ Block period to use in developer mode (0 = mine only if transaction pending). Th `GETH_DEV_PERIOD=0` -### Ethereum +### Chain and network selection + +Configure which network to connect to and manage blockchain data storage. #### bloomfilter.size @@ -506,6 +583,16 @@ Root directory for ancient data (default = inside chaindata). `GETH_DATADIR_ANCIENT=` +#### datadir.era + +Root directory for era1 history (default = inside ancient/chain). + + + `--datadir.era=` + Default value inside ancient/chain + `GETH_DATADIR_ERA=` + + #### datadir.minfreedisk Minimum free disk space in MB, once reached triggers auto shut down (default = --cache.gc converted to MB, 0 = disabled). @@ -546,16 +633,6 @@ Exits after block synchronization completes. The default value is `false`. `GETH_EXITWHENSYNCED=false` -#### goerli - -Görli network: pre-configured proof-of-authority test network. The default value is `false`. - - - `--goerli` - `--goerli=false` - `GETH_GOERLI=false` - - #### holesky Holesky network: pre-configured proof-of-stake test network. The default value is `false`. @@ -566,6 +643,16 @@ Holesky network: pre-configured proof-of-stake test network. The default value i `GETH_HOLESKY=false` +#### hoodi + +Hoodi network: pre-configured proof-of-stake test network. The default value is `false`. + + + `--hoodi` + `--hoodi=false` + `GETH_HOODI=false` + + #### mainnet Ethereum mainnet. The default value is `false`. @@ -578,7 +665,7 @@ 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. +Explicitly set network id (integer). The default value is `0`. For testnets: use --sepolia, --holesky, --hoodi instead. `--networkid ` @@ -590,12 +677,19 @@ Explicitly set network id (integer). The default value is `1`. For testnets: use 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 +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 `--op-network=` @@ -643,6 +737,26 @@ Manually specify the Optimism Fjord fork timestamp, overriding the bundled setti `GETH_OVERRIDE_FJORD=0` +#### override.granite + +Manually specify the Optimism Granite fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.granite=` + `--override.granite=0` + `GETH_OVERRIDE_GRANITE=0` + + +#### override.holocene + +Manually specify the Optimism Holocene fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.holocene=` + `--override.holocene=0` + `GETH_OVERRIDE_HOLOCENE=0` + + #### `override.interop` Manually specify the Optimism Interop feature-set fork timestamp, overriding the bundled setting. @@ -654,6 +768,36 @@ The default value is `0`. `GETH_OVERRIDE_INTEROP=0` +#### override.isthmus + +Manually specify the Optimism Isthmus fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.isthmus=` + `--override.isthmus=0` + `GETH_OVERRIDE_ISTHMUS=0` + + +#### override.jovian + +Manually specify the Optimism Jovian fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.jovian=` + `--override.jovian=0` + `GETH_OVERRIDE_JOVIAN=0` + + +#### override.osaka + +Manually specify the Osaka fork timestamp, overriding the bundled setting. The default value is `0`. + + + `--override.osaka=` + `--override.osaka=0` + `GETH_OVERRIDE_OSAKA=0` + + #### override.verkle Manually specify the Verkle fork timestamp, overriding the bundled setting. The default value is `0`. @@ -684,7 +828,9 @@ Enables snapshot-database mode. The default value is `true`. `GETH_SNAPSHOT=true` -### Gas Price Oracle +### Gas price oracle + +Configure how gas prices are estimated and suggested to users. #### gpo.blocks @@ -738,72 +884,20 @@ Suggested gas price is the given percentile of a set of recent transaction gas p `GETH_GPO_PERCENTILE=60` -### Light Client - -#### light.egress - -Outgoing bandwidth limit for serving light clients (deprecated). The default value is `0`. - - - `--light.egress=` - `--light.egress=0` - `GETH_LIGHT_EGRESS=0` - - -#### light.ingress +### Logging and debugging -Incoming bandwidth limit for serving light clients (deprecated). The default value is `0`. +Control log output, profiling, and debugging tools. - - `--light.ingress=` - `--light.ingress=0` - `GETH_LIGHT_INGRESS=0` - - -#### light.maxpeers +#### go-execution-trace -Maximum number of light clients to serve, or light servers to attach to (deprecated). -The default value is `100`. +Write Go execution trace to the given file. - `--light.maxpeers=` - `--light.maxpeers=100` - `GETH_LIGHT_MAXPEERS=100` + `--go-execution-trace ` + `--go-execution-trace=/path/to/trace.out` + `GETH_GO_EXECUTION_TRACE=/path/to/trace.out` -#### light.nopruning - -Disable ancient light chain data pruning (deprecated). The default value is `false`. - - - `--light.nopruning` - `--light.nopruning=false` - `GETH_LIGHT_NOPRUNING=false` - - -#### light.nosyncserve - -Enables serving light clients before syncing (deprecated) The default value is `false`. - - - `--light.nosyncserve` - `--light.nosyncserve=false` - `GETH_LIGHT_NOSYNCSERVE=false` - - -#### light.serve - -Maximum percentage of time allowed for serving LES requests (deprecated). -The default value is `0`. - - - `--light.serv=` - `--light.serve=0` - `GETH_LIGHT_SERVE=0` - - -### Logging and Debugging - #### log.compress Compress the log files. The default value is `false`. @@ -963,16 +1057,6 @@ URL for remote database. `GETH_REMOTEDB=http://example.com/db` -#### trace - -Write execution trace to the given file. - - - `--trace=` - `--trace=/path/to/trace.file` - `GETH_TRACE=/path/to/trace.file` - - #### verbosity Logging verbosity: 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail. The default value is `3`. @@ -983,7 +1067,9 @@ Logging verbosity: 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail. The def `GETH_VERBOSITY=3` -### Metrics and Stats +### Metrics and monitoring + +Enable metrics collection and export to monitoring systems. #### ethstats @@ -1136,79 +1222,9 @@ Please note that `--metrics.addr` must be set to start the server. `GETH_METRICS_PORT=6060` -### Miner - -#### mine - -Enable mining. The default value is `false`. - - - `--mine` - `--mine=false` - `GETH_MINE=false` - - -#### miner.etherbase - -0x prefixed public address for block mining rewards. - - - `--miner.etherbase=` - `--miner.etherbase=0x123...` - `GETH_MINER_ETHERBASE=0x123...` - - -#### miner.extradata - -Block extra data set by the miner (default = client version). - - - `--miner.extradata=` - `--miner.extradata="Some extra data"` - `GETH_MINER_EXTRADATA="Some extra data"` - - -#### miner.gaslimit - -Target gas ceiling for mined blocks. The default value is `30000000`. - - - `--miner.gaslimit=` - `--miner.gaslimit=30000000` - `GETH_MINER_GASLIMIT=30000000` - - -#### miner.gasprice +### General options -Minimum gas price for mining a transaction. The default value is `0`. - - - `--miner.gasprice=` - `--miner.gasprice=0` - `GETH_MINER_GASPRICE=0` - - -#### miner.newpayload-timeout - -Specify the maximum time allowance for creating a new payload. The default value is `2s`. - - - `--miner.newpayload-timeout=` - `--miner.newpayload-timeout=2s` - `GETH_MINER_NEWPAYLOAD_TIMEOUT=2s` - - -#### miner.recommit - -Time interval to recreate the block being mined. The default value is `2s`. - - - `--miner.recommit=` - `--miner.recommit=2s` - `GETH_MINER_RECOMMIT=2s` - - -### Miscellaneous +Help, version, and other general-purpose flags. #### help @@ -1243,7 +1259,9 @@ Print the version. This option is typically used to display the version of the s `--version` -### Networking +### Peer-to-peer networking + +Configure P2P connections, peer discovery, and network settings. #### bootnodes @@ -1327,7 +1345,7 @@ Maximum number of pending connection attempts (defaults used if set to 0). The d #### nat -NAT port mapping mechanism (any|none|upnp|pmp|pmp:`|extip:`). The default value is `"any"`. +NAT port mapping mechanism (any|none|upnp|pmp|pmp:``|extip:``|stun:``). The default value is `"any"`. `--nat=` @@ -1385,7 +1403,9 @@ Network listening port. The default value is `30303`. `GETH_PORT=30303` -### Performance Tuning +### Performance and resource management + +Tune memory usage, caching, and other performance-related settings. #### `cache` @@ -1493,7 +1513,9 @@ Raise the open file descriptor resource limit. The default is the system fd limi `GETH_FDLIMIT=0` -### Rollup Node +### OP Stack specific options + +Configuration options specific to OP Stack rollup functionality. #### rollup.computependingblock @@ -1517,6 +1539,17 @@ Disable transaction pool gossip. The default value is `false`. `GETH_ROLLUP_DISABLETXPOOLGOSSIP=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.enabletxpooladmission` + `--rollup.enabletxpooladmission=false` + `GETH_ROLLUP_ENABLETXPOOLADMISSION=false` + + #### rollup.halt Opt-in option to halt on incompatible protocol version requirements of the @@ -1549,6 +1582,27 @@ Timeout for historical RPC requests. The default value is `5s`. `GETH_ROLLUP_HISTORICALRPCTIMEOUT=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.interopmempoolfiltering` + `--rollup.interopmempoolfiltering=false` + `GETH_ROLLUP_INTEROPMEMPOOLFILTERING=false` + + +#### rollup.interoprpc + +RPC endpoint for interop message verification (experimental). + + + `--rollup.interoprpc ` + `--rollup.interoprpc="http://example.com"` + `GETH_ROLLUP_INTEROPRPC="http://example.com"` + + #### rollup.sequencerhttp HTTP endpoint for the sequencer mempool. @@ -1559,6 +1613,28 @@ HTTP endpoint for the sequencer mempool. `GETH_ROLLUP_SEQUENCERHTTP="http://example.com"` +#### rollup.sequencertxconditionalcostratelimit + +Maximum cost -- storage lookups -- allowed for conditional transactions in a given second. +The default value is `5000`. + + + `--rollup.sequencertxconditionalcostratelimit ` + `--rollup.sequencertxconditionalcostratelimit=5000` + `GETH_ROLLUP_SEQUENCERTXCONDITIONALCOSTRATELIMIT=5000` + + +#### rollup.sequencertxconditionalenabled + +Serve the eth_sendRawTransactionConditional endpoint and apply the conditional constraints on mempool inclusion & block building. +The default value is `false`. + + + `--rollup.sequencertxconditionalenabled` + `--rollup.sequencertxconditionalenabled=false` + `GETH_ROLLUP_SEQUENCERTXCONDITIONALENABLED=false` + + #### rollup.superchain-upgrades Apply superchain-registry config changes to the local chain-configuration. @@ -1570,11 +1646,13 @@ The default value is `true`. `GETH_ROLLUP_SUPERCHAIN_UPGRADES=true` -### State History Management +### 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`. +Blockchain garbage collection mode, only relevant in `state.scheme=hash`. Options are "full" and "archive". The default value is `"full"`. @@ -1583,10 +1661,50 @@ Options are "full" and "archive". The default value is `"full"`. `GETH_GCMODE="full"` +#### history.chain + +Blockchain history retention ("all" or "postmerge"). The default value is `"all"`. + + + `--history.chain=` + `--history.chain="all"` + `GETH_HISTORY_CHAIN="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=` + `--history.logs=2350000` + `GETH_HISTORY_LOGS=2350000` + + +#### history.logs.disable + +Do not maintain log search index. The default value is `false`. + + + `--history.logs.disable` + `--history.logs.disable=false` + `GETH_HISTORY_LOGS_DISABLE=false` + + +#### history.logs.export + +Export checkpoints to file in go source file format. + + + `--history.logs.export ` + `--history.logs.export="/path/to/export.go"` + `GETH_HISTORY_LOGS_EXPORT="/path/to/export.go"` + + #### history.state -Number of recent blocks to retain state history for. The default is `90000` -blocks, with `0` representing the entire chain. +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.state=` @@ -1596,8 +1714,8 @@ blocks, with `0` representing the entire chain. #### history.transactions -Number of recent blocks to maintain transactions index for. -The default is about two months (`2350000` blocks), with `0` representing the entire chain. +Number of recent blocks to maintain transactions index for. +The default is about one year (`2350000` blocks), with `0` representing the entire chain. `--history.transactions=` @@ -1625,17 +1743,29 @@ Blockchain sync mode. Options are "snap", or "full". The default value is `"snap `GETH_SYNCMODE="full"` -### Transaction Pool (Blob) +### 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 `10737418240`. +Disk space to allocate for pending blob transactions (soft limit). +The default value is `2684354560`. `--blobpool.datacap=` - `--blobpool.datacap=10737418240` - `GETH_BLOBPOOL_DATACAP=10737418240` + `--blobpool.datacap=2684354560` + `GETH_BLOBPOOL_DATACAP=2684354560` + + +#### blobpool.datadir + +Data directory to store blob transactions in. The default value is `"blobpool"`. + + + `--blobpool.datadir=` + `--blobpool.datadir="blobpool"` + `GETH_BLOBPOOL_DATADIR="blobpool"` #### blobpool.pricebump @@ -1649,7 +1779,9 @@ The default value is `100`. `GETH_BLOBPOOL_PRICEBUMP=100` -### Transaction Pool (EVM) +### Transaction pool - Standard transactions + +Configure the standard EVM transaction pool. #### txpool.accountqueue @@ -1737,6 +1869,16 @@ Comma-separated accounts to treat as locals (no flush, priority inclusion). `GETH_TXPOOL_LOCALS="0x123...,0x456..."` +#### 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.maxtxgas=` + `--txpool.maxtxgas=0` + `GETH_TXPOOL_MAXTXGAS=0` + + #### txpool.nolocals Disables price exemptions for locally submitted transactions. The default value is `false`. @@ -1777,7 +1919,9 @@ Time interval to regenerate the local transaction journal. The default value is `GETH_TXPOOL_REJOURNAL=1h0m0s` -### Virtual machine +### EVM configuration + +Options for EVM debugging and instrumentation. #### vmdebug @@ -1788,3 +1932,23 @@ Record information useful for VM and contract debugging. The default value is `f `--vmdebug=false` `GETH_VMDEBUG=false` + +#### vmtrace + +Name of tracer which should record internal VM operations (costly). + + + `--vmtrace ` + `--vmtrace="callTracer"` + `GETH_VMTRACE="callTracer"` + + +#### vmtrace.jsonconfig + +Tracer configuration (JSON). The default value is `"{}"`. + + + `--vmtrace.jsonconfig ` + `--vmtrace.jsonconfig="{}"` + `GETH_VMTRACE_JSONCONFIG="{}"` +