Coordinator ensures that there will be one and only one instance of Optimism sequencer is producing blocks at any given time.
The Optimism sequencer plays a critical role in the production of blocks within the optimistic rollup. However, the current block production process lacks decentralization and is controlled by a single entity. Additionally, the existing implementation of the Optimism sequencer lacks a fail-over mechanism, making it a single point of failure. If the sequencer goes down, the entire optimistic rollup halts block production.
To address these issues, the Coordinator has been introduced. It ensures that only one instance of the Optimism sequencer is actively producing blocks, and in the event of a failure, it can be replaced by another instance.
Auto-Election is a feature that ensures only one instance of the Optimism sequencer is producing blocks at any given time.
Optimism node maintains a state flag sequencerActive to indicate its right to produce blocks. Meanwhile, node provide a set of admin_ HTTP API to query and control the state flag:
admin_sequencerActivequery whether the node have right to active produce blocksadmin_startSequencergrant the node right to active produce blocksadmin_stopSequencerrevoke the node right to active produce blocks
So Coordinator control the right to active produce blocks via admin_ API. It ensures that only one sequencer will peoduce blocks at any time, named as active sequencer, and act fail-over when the current active sequencer is fault detected. The details will follow.
Refers the a node that runs with --sequencer.enabled=true.
A sequencer maintains a state flag sequencerActive to indicate its right to produce blocks. When the sequencerActive is true, we refer this sequencer as an active sequencer, otherwise inactive sequencer.
Coordinator ensures that there will be at most 1 active sequencer at any time.
See also active-sequencer.
The hash returned by [active sequencer] when calling admin_stopSequencer.
Fault detection mechanism is used for judging whether a sequencer is healthy.
Coordinator periodically requests optimism_syncStatus and eth_getBlockByNumber("latest") to sequencers and predicates their health status. in addition, to eliminate false predication caused by network jitter, we choose latest 5 (configurable) responses, if the latest 5 responses are all errored, the corresponding sequencer is unhealthy, otherwise it's healthy.
When the current active sequencer becomes unhealthy, the fail-over mechanism was activated.
(1) query the state flag sequencerActive to current active sequencer via admin_sequencerActive.
(2) When the flag is true, call admin_stopSequencer to revoke block-production right and record the responded hash as stopped hash; when the flag is false, call optimism_syncStatus and record the responsed unsafe_l2.hash as stopped hash.
Whenever errors occur, go back to (1) and retry.
Elect a new sequencer as candidate active sequencer. The candidate sequencer must:
- Be healthy;
- Response OK for calling
eth_getBlockByHash(stopped hash); - Maintain the highest chain number amount healthy sequencers.
Grant block-production right to the candidate sequencer by calling admin_startSequencer(stopped hash).
go install github.com/node-real/op-coordinatorop-coordinator start --config config.yamlReturns the current active sequencer name.
RPC:
{"method": "coordinator_getActiveSequencer", "params": []}
Sets the active sequencer name manually.
RPC:
{"method": "coordinator_setActiveSequencer", "params": [nodeName]}
nodeName: A string represents the node name that will be set as the active sequencer.
Enables the auto-detection and auto-election process. See StopElection for more details.
RPC:
{"method": "coordinator_startElection", "params": []}
Disables the auto-detection and auto-election process. When the election is stopped, the active sequencer will not be changed even if the current active sequencer is down. The election process can be started again by calling StartElection.
This API is used for debugging purpose and handling accidental situations.
RPC:
{"method": "coordinator_stopElection", "params": []}
Returns whether the auto-election process is stopped.
RPC:
{"method": "coordinator_electionStopped", "params": []}
Returns whether the requesting node is allowed to build a block.
RequestBuildingBlock is called by the sequencer to request a building block. According to the high-availability design, the active sequencer is the only node that can request a building block. If the active sequencer is not the node that calls this function, the function returns an error. In another word, RequestBuildingBlock ensures that only the active sequencer will build new blocks, so that we enforce the data consistency.
Note that the nodeName parameter should be identical to the node name in the configuration file.
RPC:
{"method": "coordinator_requestBuildingBlock", "params": [nodeName]}
nodeName: the node name that requests to build a block.
See https://community.optimism.io/docs/developers/build/json-rpc/#eth-getblockrange
See https://community.optimism.io/docs/developers/build/json-rpc/#optimism-outputatblock
See https://community.optimism.io/docs/developers/build/json-rpc/#optimism-rollupconfig
See https://community.optimism.io/docs/developers/build/json-rpc/#optimism-version
Returns information of the block matching the given block number.
RPC:
{"method": "eth_getBlockByNumber", "params": [blockTag, detail]}
blockTag: The block number in hexadecimal format or the string latest, earliest, pending, safe or finalized.detail: The method returns the full transaction objects when this value is true otherwise, it returns only the hashes of the transactions.