sync

Documentation

Overview

The sync package is responsible for reconciling L1 and L2.

The Ethereum chain is a DAG of blocks with the root block being the genesis block. At any given time, the head (or tip) of the chain can change if an offshoot/branch of the chain has a higher total difficulty. This is known as a re-organization of the canonical chain. Each block points to a parent block and the node is responsible for deciding which block is the head and thus the mapping from block number to canonical block.

The Optimism (L2) chain has similar properties, but also retains references to the Ethereum (L1) chain. Each L2 block retains a reference to an L1 block (its "L1 origin", i.e. L1 block associated with the epoch that the L2 block belongs to) and to its parent L2 block. The L2 chain node must satisfy the following validity rules:

1. l2block.number == l2block.l2parent.block.number + 1
2. l2block.l1Origin.number >= l2block.l2parent.l1Origin.number
3. l2block.l1Origin is in the canonical chain on L1
4. l1_rollup_genesis is an ancestor of l2block.l1Origin

During normal operation, both the L1 and L2 canonical chains can change, due to a re-organisation or due to an extension (new L1 or L2 block).

When one of these changes occurs, the rollup node needs to determine what the new L2 head blocks should be. We track two L2 head blocks:

• The *unsafe L2 block*: This is the highest L2 block whose L1 origin is a plausible (1) extension of the canonical L1 chain (as known to the op-node).
• The *safe L2 block*: This is the highest L2 block whose epoch's sequencing window is complete within the canonical L1 chain (as known to the op-node).

(1) Plausible meaning that the blockhash of the L2 block's L1 origin (as reported in the L1

Attributes deposit within the L2 block) is not canonical at another height in the L1 chain,
and the same holds for all its ancestors.

In particular, in the case of L1 extension, the L2 unsafe head will generally remain the same, but in the case of an L1 re-org, we need to search for the new safe and unsafe L2 block.

Index

• Constants
• Variables
• func FindL2Heads(ctx context.Context, start eth.L2BlockRef, seqWindowSize uint64, l1 L1Chain, ...) (unsafe eth.L2BlockRef, safe eth.L2BlockRef, err error)
• type L1Chain
• type L2Chain

Constants

const MaxReorgDepth = 500

Variables

var TooDeepReorgErr = errors.New("reorg is too deep")

var WrongChainErr = errors.New("wrong chain")

Functions

func FindL2Heads

func FindL2Heads(ctx context.Context, start eth.L2BlockRef, seqWindowSize uint64,
	l1 L1Chain, l2 L2Chain, genesis *rollup.Genesis) (unsafe eth.L2BlockRef, safe eth.L2BlockRef, err error)

FindL2Heads walks back from `start` (the previous unsafe L2 block) and finds the unsafe and safe L2 blocks.

• The *unsafe L2 block*: This is the highest L2 block whose L1 origin is a plausible (1) extension of the canonical L1 chain (as known to the op-node).
• The *safe L2 block*: This is the highest L2 block whose epoch's sequencing window is complete within the canonical L1 chain (as known to the op-node).

(1) Plausible meaning that the blockhash of the L2 block's L1 origin (as reported in the L1

Attributes deposit within the L2 block) is not canonical at another height in the L1 chain,
and the same holds for all its ancestors.

Types

type L1Chain

type L1Chain interface {
	L1HeadBlockRef(ctx context.Context) (eth.L1BlockRef, error)
	L1BlockRefByNumber(ctx context.Context, number uint64) (eth.L1BlockRef, error)
}

type L2Chain

type L2Chain interface {
	L2BlockRefByHash(ctx context.Context, l2Hash common.Hash) (eth.L2BlockRef, error)
}