Optimism Documentation

This page catalogues op-conductor’s configuration options and its admin RPC methods. For how the service works, see OP Conductor; to add it to a running network, follow the setup guide.

Configuration options

The flag tables below are generated directly from op-conductor’s flag definitions in the monorepo (op-conductor/flags) at the release tag named in the provenance line, and are regenerated when a new finalized release is published, so they cannot silently fall behind. Every flag can also be set through the environment variable listed next to it. Generated from op-conductor/v0.9.4 flag definitions. 61 flags: 9 required, 52 optional.

Required flags

Flag	Description	Environment variable
`--consensus.addr`	Address (excluding port) to listen for consensus connections.	`OP_CONDUCTOR_CONSENSUS_ADDR`
`--consensus.port`	Port to listen for consensus connections. May be 0 to let the system select a port.	`OP_CONDUCTOR_CONSENSUS_PORT`
`--execution.rpc`	HTTP provider URL for execution layer	`OP_CONDUCTOR_EXECUTION_RPC`
`--healthcheck.interval`	Interval between health checks	`OP_CONDUCTOR_HEALTHCHECK_INTERVAL`
`--healthcheck.min-peer-count`	Minimum number of peers required to be considered healthy	`OP_CONDUCTOR_HEALTHCHECK_MIN_PEER_COUNT`
`--healthcheck.unsafe-interval`	Interval allowed between unsafe head and now measured in seconds	`OP_CONDUCTOR_HEALTHCHECK_UNSAFE_INTERVAL`
`--node.rpc`	HTTP provider URL for op-node	`OP_CONDUCTOR_NODE_RPC`
`--raft.server.id`	Unique ID for this server used by raft consensus	`OP_CONDUCTOR_RAFT_SERVER_ID`
`--raft.storage.dir`	Directory to store raft data	`OP_CONDUCTOR_RAFT_STORAGE_DIR`

Optional flags

Flag	Description	Default	Environment variable
`--consensus.advertised`	Full address (host and port) for other peers to contact the consensus server. Optional: if left empty, the local address is advertised.	—	`OP_CONDUCTOR_CONSENSUS_ADVERTISED`
`--healthcheck.execution-p2p-check-api`	Type of EL P2P check to perform. If not set, the default `net` type will be used corresponding to the `net_peerCount` RPC call.	`"net"`	`OP_CONDUCTOR_HEALTHCHECK_EXECUTION_P2P_CHECK_API`
`--healthcheck.execution-p2p-enabled`	Whether to enable EL P2P checks	`false`	`OP_CONDUCTOR_HEALTHCHECK_EXECUTION_P2P_ENABLED`
`--healthcheck.execution-p2p-min-peer-count`	Minimum number of EL P2P peers required to be considered healthy	`0`	`OP_CONDUCTOR_HEALTHCHECK_EXECUTION_P2P_MIN_PEER_COUNT`
`--healthcheck.execution-p2p-rpc-url`	URL override for the execution layer RPC client for the sake of p2p healthcheck. If not set, the execution RPC URL will be used.	—	`OP_CONDUCTOR_HEALTHCHECK_EXECUTION_P2P_RPC_URL`
`--healthcheck.rollup-boost-partial-healthiness-tolerance-interval-seconds`	The time frame within which rollup-boost partial healthiness tolerance is evaluated	`0`	`OP_CONDUCTOR_HEALTHCHECK_ROLLUP_BOOST_PARTIAL_HEALTHINESS_TOLERANCE_INTERVAL_SECONDS`
`--healthcheck.rollup-boost-partial-healthiness-tolerance-limit`	Sets the count of rollup-boost partial healthiness failures to occur before marking op-conducto as unhealthy. Default is 0 with which a single occurrence of rollup-boost partial healthiness is enough to set op-conductor as unhealthy	`0`	`OP_CONDUCTOR_HEALTHCHECK_ROLLUP_BOOST_PARTIAL_HEALTHINESS_TOLERANCE_LIMIT`
`--healthcheck.safe-enabled`	Whether to enable safe head progression checks	`false`	`OP_CONDUCTOR_HEALTHCHECK_SAFE_ENABLED`
`--healthcheck.safe-interval`	Interval between safe head progression measured in seconds	`1200`	`OP_CONDUCTOR_HEALTHCHECK_SAFE_INTERVAL`
`--log.color`	Color the log output if in terminal mode	`false`	`OP_CONDUCTOR_LOG_COLOR`
`--log.format`	Format the log output. Supported formats: text, terminal, logfmt, logfmtms, json, jsonms	`text`	`OP_CONDUCTOR_LOG_FORMAT`
`--log.level`	The lowest log level that will be output	`INFO`	`OP_CONDUCTOR_LOG_LEVEL`
`--log.pid`	Show pid in the log	`false`	`OP_CONDUCTOR_LOG_PID`
`--metrics.addr`	Metrics listening address	`"0.0.0.0"`	`OP_CONDUCTOR_METRICS_ADDR`
`--metrics.enabled`	Enable the metrics server	`false`	`OP_CONDUCTOR_METRICS_ENABLED`
`--metrics.port`	Metrics listening port	`7300`	`OP_CONDUCTOR_METRICS_PORT`
`--network`	Predefined network selection. Available networks: every chain bundled from the superchain-registry at the release; run `op-conductor --help` for the exact list	—	`OP_CONDUCTOR_NETWORK`
`--override.canyon`	Manually specify the canyon fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_CANYON`
`--override.delta`	Manually specify the delta fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_DELTA`
`--override.ecotone`	Manually specify the ecotone fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_ECOTONE`
`--override.fjord`	Manually specify the fjord fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_FJORD`
`--override.granite`	Manually specify the granite fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_GRANITE`
`--override.holocene`	Manually specify the holocene fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_HOLOCENE`
`--override.interop`	Manually specify the interop fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_INTEROP`
`--override.isthmus`	Manually specify the isthmus fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_ISTHMUS`
`--override.jovian`	Manually specify the jovian fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_JOVIAN`
`--override.karst`	Manually specify the karst fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_KARST`
`--override.pectrablobschedule`	Manually specify the pectrablobschedule fork timestamp, overriding the bundled setting	`0`	`OP_CONDUCTOR_OVERRIDE_PECTRABLOBSCHEDULE`
`--paused`	Whether the conductor is paused	`false`	`OP_CONDUCTOR_PAUSED`
`--pprof.addr`	pprof listening address	`"0.0.0.0"`	`OP_CONDUCTOR_PPROF_ADDR`
`--pprof.enabled`	Enable the pprof server	`false`	`OP_CONDUCTOR_PPROF_ENABLED`
`--pprof.path`	pprof file path. If it is a directory, the path is {dir}/{profileType}.prof	—	`OP_CONDUCTOR_PPROF_PATH`
`--pprof.port`	pprof listening port	`6060`	`OP_CONDUCTOR_PPROF_PORT`
`--pprof.type`	pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs	—	`OP_CONDUCTOR_PPROF_TYPE`
`--raft.bootstrap`	If this node should bootstrap a new raft cluster	`false`	`OP_CONDUCTOR_RAFT_BOOTSTRAP`
`--raft.heartbeat-timeout`	Heartbeat interval timeout	`1s`	`OP_CONDUCTOR_RAFT_HEARTBEAT_TIMEOUT`
`--raft.lease-timeout`	Leader lease timeout	`500ms`	`OP_CONDUCTOR_RAFT_LEASE_TIMEOUT`
`--raft.round-robin-leader-transfer`	Enable deterministic round-robin leader transfer instead of Raft’s default log-based selection. Must be enabled on all conductors in the cluster.	`false`	`OP_CONDUCTOR_RAFT_ROUND_ROBIN_LEADER_TRANSFER`
`--raft.snapshot-interval`	The interval to check if a snapshot should be taken.	`2m0s`	`OP_CONDUCTOR_RAFT_SNAPSHOT_INTERVAL`
`--raft.snapshot-threshold`	Number of logs to trigger a snapshot	`8192`	`OP_CONDUCTOR_RAFT_SNAPSHOT_THRESHOLD`
`--raft.trailing-logs`	Number of logs to keep after a snapshot	`10240`	`OP_CONDUCTOR_RAFT_TRAILING_LOGS`
`--rollup-boost.enabled`	Enable the rollup-boost healthcheck that uses HTTP status codes (200/206/503). Healthchecks are performed against execution.rpc + ‘/healthz’ (path appended automatically). Mutually exclusive with rollup-boost.next-enabled.	`false`	`OP_CONDUCTOR_ROLLUP_BOOST_ENABLED`
`--rollup-boost.healthcheck-timeout`	Timeout for rollup-boost healthchecks (applies to both standard and next)	`5s`	`OP_CONDUCTOR_ROLLUP_BOOST_HEALTHCHECK_TIMEOUT`
`--rollup-boost.next-enabled`	Enable rollup-boost healthcheck using JSON response parsing. Requires rollup-boost.next-healthcheck-url. Mutually exclusive with rollup-boost.enabled.	`false`	`OP_CONDUCTOR_ROLLUP_BOOST_NEXT_ENABLED`
`--rollup-boost.next-healthcheck-url`	Full URL including path for the rollup-boost health endpoint (e.g., ‘http://localhost:8080/healthz’). Required when rollup-boost.next-enabled is true.	—	`OP_CONDUCTOR_ROLLUP_BOOST_NEXT_HEALTHCHECK_URL`
`--rollup.config`	Rollup chain parameters	—	`OP_CONDUCTOR_ROLLUP_CONFIG`
`--rollupboost.ws-url`	WebSocket URL for the rollup boost to listen for payload streams.	—	`OP_CONDUCTOR_ROLLUPBOOST_WS_URL`
`--rpc.addr`	rpc listening address	`"0.0.0.0"`	`OP_CONDUCTOR_RPC_ADDR`
`--rpc.enable-admin`	Enable the admin API	`false`	`OP_CONDUCTOR_RPC_ENABLE_ADMIN`
`--rpc.enable-proxy`	Enable the RPC proxy to underlying sequencer services	`true`	`OP_CONDUCTOR_RPC_ENABLE_PROXY`
`--rpc.port`	rpc listening port	`8545`	`OP_CONDUCTOR_RPC_PORT`
`--websocket.server-port`	Port for the conductor to run a WebSocket server that pushes payload streams out.	`8546`	`OP_CONDUCTOR_WEBSOCKET_SERVER_PORT`

Notes on selected flags

raft.bootstrap

For bootstrapping a new cluster. This should only be used on the sequencer that is currently active and can only be started once with this flag, otherwise the flag has to be removed or the raft log must be deleted before re-bootstrapping the cluster.

paused

There is no configuration state, so if you unpause via RPC and then restart, it will start paused again.

RPCs

Conductor exposes admin RPCs on the conductor namespace.

conductor_overrideLeader

OverrideLeader is used to override the leader status, this is only used to return true for Leader() & LeaderWithID() calls. It does not impact the actual raft consensus leadership status. It is supposed to be used when the cluster is unhealthy and the node is the only one up, to allow batcher to be able to connect to the node so that it could download blocks from the manually started sequencer.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_overrideLeader","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_overrideLeader --rpc-url http://127.0.0.1:8547

conductor_pause

Pause pauses op-conductor.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_pause","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_pause --rpc-url http://127.0.0.1:8547

conductor_resume

Resume resumes op-conductor.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_resume","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_resume --rpc-url http://127.0.0.1:8547

conductor_paused

Paused returns true if the op-conductor is paused.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_paused","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_paused --rpc-url http://127.0.0.1:8547

conductor_stopped

Stopped returns true if the op-conductor is stopped.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_stopped","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_stopped --rpc-url http://127.0.0.1:8547

conductor_sequencerHealthy

SequencerHealthy returns true if the sequencer is healthy.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_sequencerHealthy","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_sequencerHealthy --rpc-url http://127.0.0.1:8547

conductor_leader

API related to consensus.

Leader returns true if the server is the leader.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_leader","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_leader --rpc-url http://127.0.0.1:8547

conductor_leaderWithID

API related to consensus.

LeaderWithID returns the current leader’s server info.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_leaderWithID","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_leaderWithID --rpc-url http://127.0.0.1:8547

conductor_addServerAsVoter

API related to consensus.

AddServerAsVoter adds a server as a voter to the cluster.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_addServerAsVoter","params":[<raft-server-id>, <raft-consensus-addr>, <raft-config-version>],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_addServerAsVoter <raft-server-id> <raft-consensus-addr> <raft-config-version> --rpc-url http://127.0.0.1:8547 

conductor_addServerAsNonvoter

API related to consensus.

AddServerAsNonvoter adds a server as a non-voter to the cluster. non-voter The non-voter will not participate in the leader election.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_addServerAsNonvoter","params":[<raft-server-id>, <raft-consensus-addr>, <raft-config-version>],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_addServerAsNonvoter <raft-server-id> <raft-consensus-addr> <raft-config-version> --rpc-url http://127.0.0.1:8547

conductor_removeServer

API related to consensus.

RemoveServer removes a server from the cluster.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_removeServer","params":[<raft-server-id>, <raft-config-version>],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_removeServer <raft-server-id> <raft-config-version> --rpc-url http://127.0.0.1:8547

conductor_transferLeader

API related to consensus.

TransferLeader transfers leadership to another server (resigns).

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_transferLeader","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_transferLeader --rpc-url http://127.0.0.1:8547

conductor_transferLeaderToServer

API related to consensus.

TransferLeaderToServer transfers leadership to a specific server.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_transferLeaderToServer","params":[<raft-server-id>, <raft-consensus-addr>, <raft-config-version>],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_transferLeaderToServer <raft-server-id> <raft-consensus-addr> <raft-config-version> --rpc-url http://127.0.0.1:8547

conductor_clusterMembership

ClusterMembership returns the current cluster membership configuration.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_clusterMembership","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_clusterMembership --rpc-url http://127.0.0.1:8547

conductor_active

API called by op-node.

Active returns true if the op-conductor is active (not paused or stopped).

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_active","params":[],"id":1}'  \
    http://127.0.0.1:8547

cast rpc conductor_active --rpc-url http://127.0.0.1:8547

conductor_commitUnsafePayload

API called by op-node.

CommitUnsafePayload commits an unsafe payload (latest head) to the consensus layer. This method is typically called by the op-node to commit execution payload envelopes.

curl
cast

curl -X POST -H "Content-Type: application/json" --data \
    '{"jsonrpc":"2.0","method":"conductor_commitUnsafePayload","params":[{
        "executionPayload": {
            "parentHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
            "feeRecipient": "0x4200000000000000000000000000000000000019",
            "stateRoot": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
            "receiptsRoot": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
            "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
            "prevRandao": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
            "blockNumber": "0x64",
            "gasLimit": "0x1c9c380",
            "gasUsed": "0x5208",
            "timestamp": "0x12345678",
            "extraData": "0x",
            "baseFeePerGas": "0x7",
            "blockHash": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
            "transactions": []
        }
    }],"id":1}'  \
    http://127.0.0.1:8547

# Example with basic payload structure
cast rpc conductor_commitUnsafePayload \
    '{"executionPayload":{"parentHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","feeRecipient":"0x4200000000000000000000000000000000000019","stateRoot":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890","receiptsRoot":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","prevRandao":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","blockNumber":"0x64","gasLimit":"0x1c9c380","gasUsed":"0x5208","timestamp":"0x12345678","extraData":"0x","baseFeePerGas":"0x7","blockHash":"0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba","transactions":[]}}' \
    --rpc-url http://127.0.0.1:8547

Quickstart

Use cases

Guides

Tutorials

Tools

Reference

Archive

Configuration and RPCs

Configuration options

Required flags

Optional flags

Notes on selected flags

raft.bootstrap

paused

RPCs

conductor_overrideLeader

conductor_pause

conductor_resume

conductor_paused

conductor_stopped

conductor_sequencerHealthy

conductor_leader

conductor_leaderWithID

conductor_addServerAsVoter

conductor_addServerAsNonvoter

conductor_removeServer

conductor_transferLeader

conductor_transferLeaderToServer

conductor_clusterMembership

conductor_active

conductor_commitUnsafePayload

​Configuration options

​Required flags

​Optional flags

​Notes on selected flags

​raft.bootstrap

​paused

​RPCs

​conductor_overrideLeader

​conductor_pause

​conductor_resume

​conductor_paused

​conductor_stopped

​conductor_sequencerHealthy

​conductor_leader

​conductor_leaderWithID

​conductor_addServerAsVoter

​conductor_addServerAsNonvoter

​conductor_removeServer

​conductor_transferLeader

​conductor_transferLeaderToServer

​conductor_clusterMembership

​conductor_active

​conductor_commitUnsafePayload

Configuration options

Required flags

Optional flags

Notes on selected flags

raft.bootstrap

paused

RPCs

conductor_overrideLeader

conductor_pause

conductor_resume

conductor_paused

conductor_stopped

conductor_sequencerHealthy

conductor_leader

conductor_leaderWithID

conductor_addServerAsVoter

conductor_addServerAsNonvoter

conductor_removeServer

conductor_transferLeader

conductor_transferLeaderToServer

conductor_clusterMembership

conductor_active

conductor_commitUnsafePayload