driver

package
v1.4.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 3, 2024 License: MIT, MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrSequencerAlreadyStarted = errors.New("sequencer already running")
	ErrSequencerAlreadyStopped = errors.New("sequencer not running")
)

Functions

func NewConfDepth 

func NewConfDepth(depth uint64, l1Head func() eth.L1BlockRef, fetcher derive.L1Fetcher) *confDepth

Types

type AltSync 

type AltSync interface {
	// RequestL2Range informs the sync source that the given range of L2 blocks is missing,
	// and should be retrieved from any available alternative syncing source.
	// The start and end of the range are exclusive:
	// the start is the head we already have, the end is the first thing we have queued up.
	// It's the task of the alt-sync mechanism to use this hint to fetch the right payloads.
	// Note that the end and start may not be consistent: in this case the sync method should fetch older history
	//
	// If the end value is zeroed, then the sync-method may determine the end free of choice,
	// e.g. sync till the chain head meets the wallclock time. This functionality is optional:
	// a fixed target to sync towards may be determined by picking up payloads through P2P gossip or other sources.
	//
	// The sync results should be returned back to the driver via the OnUnsafeL2Payload(ctx, payload) method.
	// The latest requested range should always take priority over previous requests.
	// There may be overlaps in requested ranges.
	// An error may be returned if the scheduling fails immediately, e.g. a context timeout.
	RequestL2Range(ctx context.Context, start, end eth.L2BlockRef) error
}

type Config 

type Config struct {
	// VerifierConfDepth is the distance to keep from the L1 head when reading L1 data for L2 derivation.
	VerifierConfDepth uint64 `json:"verifier_conf_depth"`

	// SequencerConfDepth is the distance to keep from the L1 head as origin when sequencing new L2 blocks.
	// If this distance is too large, the sequencer may:
	// - not adopt a L1 origin within the allowed time (rollup.Config.MaxSequencerDrift)
	// - not adopt a L1 origin that can be included on L1 within the allowed range (rollup.Config.SeqWindowSize)
	// and thus fail to produce a block with anything more than deposits.
	SequencerConfDepth uint64 `json:"sequencer_conf_depth"`

	// SequencerEnabled is true when the driver should sequence new blocks.
	SequencerEnabled bool `json:"sequencer_enabled"`

	// SequencerStopped is false when the driver should sequence new blocks.
	SequencerStopped bool `json:"sequencer_stopped"`

	// SequencerMaxSafeLag is the maximum number of L2 blocks for restricting the distance between L2 safe and unsafe.
	// Disabled if 0.
	SequencerMaxSafeLag uint64 `json:"sequencer_max_safe_lag"`
}

type DerivationPipeline 

type DerivationPipeline interface {
	Reset()
	Step(ctx context.Context) error
	AddUnsafePayload(payload *eth.ExecutionPayloadEnvelope)
	Finalize(ref eth.L1BlockRef)
	FinalizedL1() eth.L1BlockRef
	Origin() eth.L1BlockRef
	EngineReady() bool
	LowestQueuedUnsafeBlock() eth.L2BlockRef
}

type Downloader 

type Downloader interface {
	InfoByHash(ctx context.Context, hash common.Hash) (eth.BlockInfo, error)
	FetchReceipts(ctx context.Context, blockHash common.Hash) (eth.BlockInfo, types.Receipts, error)
}

type Driver 

type Driver struct {
	// contains filtered or unexported fields
}

func NewDriver 

func NewDriver(
	driverCfg *Config,
	cfg *rollup.Config,
	l2 L2Chain,
	l1 L1Chain,
	l1Blobs derive.L1BlobsFetcher,
	altSync AltSync,
	network Network,
	log log.Logger,
	snapshotLog log.Logger,
	metrics Metrics,
	sequencerStateListener SequencerStateListener,
	safeHeadListener derive.SafeHeadListener,
	syncCfg *sync.Config,
	sequencerConductor conductor.SequencerConductor,
	plasma derive.PlasmaInputFetcher,
) *Driver

NewDriver composes an events handler that tracks L1 state, triggers L2 derivation, and optionally sequences new L2 blocks.

func (*Driver) BlockRefWithStatus 

func (s *Driver) BlockRefWithStatus(ctx context.Context, num uint64) (eth.L2BlockRef, *eth.SyncStatus, error)

BlockRefWithStatus blocks the driver event loop and captures the syncing status, along with an L2 block reference by number consistent with that same status. If the event loop is too busy and the context expires, a context error is returned.

func (*Driver) BlockRefsWithStatus 

func (s *Driver) BlockRefsWithStatus(ctx context.Context, num uint64) (eth.L2BlockRef, eth.L2BlockRef, *eth.SyncStatus, error)

[Kroma: START] BlockRefsWithStatus blocks the driver event loop and captures the syncing status, along with L2 blocks reference by number and number plus 1 consistent with that same status. If the event loop is too busy and the context expires, a context error is returned.

func (*Driver) Close 

func (s *Driver) Close() error

func (*Driver) OnL1Finalized 

func (s *Driver) OnL1Finalized(ctx context.Context, finalized eth.L1BlockRef) error

func (*Driver) OnL1Head 

func (s *Driver) OnL1Head(ctx context.Context, unsafe eth.L1BlockRef) error

OnL1Head signals the driver that the L1 chain changed the "unsafe" block, also known as head of the chain, or "latest".

func (*Driver) OnL1Safe 

func (s *Driver) OnL1Safe(ctx context.Context, safe eth.L1BlockRef) error

OnL1Safe signals the driver that the L1 chain changed the "safe", also known as the justified checkpoint (as seen on L1 beacon-chain).

func (*Driver) OnUnsafeL2Payload 

func (s *Driver) OnUnsafeL2Payload(ctx context.Context, envelope *eth.ExecutionPayloadEnvelope) error

func (*Driver) ResetDerivationPipeline 

func (s *Driver) ResetDerivationPipeline(ctx context.Context) error

ResetDerivationPipeline forces a reset of the derivation pipeline. It waits for the reset to occur. It simply unblocks the caller rather than fully cancelling the reset request upon a context cancellation.

func (*Driver) SequencerActive 

func (s *Driver) SequencerActive(ctx context.Context) (bool, error)

func (*Driver) Start 

func (s *Driver) Start() error

Start starts up the state loop. The loop will have been started iff err is not nil.

func (*Driver) StartSequencer 

func (s *Driver) StartSequencer(ctx context.Context, blockHash common.Hash) error

func (*Driver) StopSequencer 

func (s *Driver) StopSequencer(ctx context.Context) (common.Hash, error)

func (*Driver) SyncStatus 

func (s *Driver) SyncStatus(ctx context.Context) (*eth.SyncStatus, error)

SyncStatus blocks the driver event loop and captures the syncing status. If the event loop is too busy and the context expires, a context error is returned.

type EngineMetrics 

type EngineMetrics interface {
	RecordSequencingError()
	CountSequencedTxs(count int)

	RecordSequencerBuildingDiffTime(duration time.Duration)
	RecordSequencerSealingTime(duration time.Duration)
}

type L1Blocks 

type L1Blocks interface {
	derive.L1BlockRefByHashFetcher
	derive.L1BlockRefByNumberFetcher
}

type L1Chain 

type L1Chain interface {
	derive.L1Fetcher
	L1BlockRefByLabel(context.Context, eth.BlockLabel) (eth.L1BlockRef, error)
}

type L1FetcherMetrics 

type L1FetcherMetrics interface {
	RecordL1RequestTime(method string, duration time.Duration)
}

type L1Metrics 

type L1Metrics interface {
	RecordL1ReorgDepth(d uint64)
	RecordL1Ref(name string, ref eth.L1BlockRef)
}

type L1OriginSelector 

type L1OriginSelector struct {
	// contains filtered or unexported fields
}

func NewL1OriginSelector 

func NewL1OriginSelector(log log.Logger, cfg *rollup.Config, l1 L1Blocks) *L1OriginSelector

func (*L1OriginSelector) FindL1Origin 

func (los *L1OriginSelector) FindL1Origin(ctx context.Context, l2Head eth.L2BlockRef) (eth.L1BlockRef, error)

FindL1Origin determines what the next L1 Origin should be. The L1 Origin is either the L2 Head's Origin, or the following L1 block if the next L2 block's time is greater than or equal to the L2 Head's Origin.

type L1OriginSelectorIface 

type L1OriginSelectorIface interface {
	FindL1Origin(ctx context.Context, l2Head eth.L2BlockRef) (eth.L1BlockRef, error)
}

type L1State 

type L1State struct {
	// contains filtered or unexported fields
}

L1State tracks L1 head, safe and finalized blocks. It is not safe to write and read concurrently.

func NewL1State 

func NewL1State(log log.Logger, metrics L1Metrics) *L1State

func (*L1State) HandleNewL1FinalizedBlock 

func (s *L1State) HandleNewL1FinalizedBlock(finalized eth.L1BlockRef)

func (*L1State) HandleNewL1HeadBlock 

func (s *L1State) HandleNewL1HeadBlock(head eth.L1BlockRef)

func (*L1State) HandleNewL1SafeBlock 

func (s *L1State) HandleNewL1SafeBlock(safe eth.L1BlockRef)

func (*L1State) L1Finalized 

func (s *L1State) L1Finalized() eth.L1BlockRef

L1Finalized returns either the stored L1 finalized block or an empty block reference if the L1 finalized block has not been initialized yet.

func (*L1State) L1Head 

func (s *L1State) L1Head() eth.L1BlockRef

L1Head returns either the stored L1 head or an empty block reference if the L1 Head has not been initialized yet.

func (*L1State) L1Safe 

func (s *L1State) L1Safe() eth.L1BlockRef

L1Safe returns either the stored L1 safe block or an empty block reference if the L1 safe block has not been initialized yet.

type L1StateIface 

type L1StateIface interface {
	HandleNewL1HeadBlock(head eth.L1BlockRef)
	HandleNewL1SafeBlock(safe eth.L1BlockRef)
	HandleNewL1FinalizedBlock(finalized eth.L1BlockRef)

	L1Head() eth.L1BlockRef
	L1Safe() eth.L1BlockRef
	L1Finalized() eth.L1BlockRef
}

type L2Chain 

type L2Chain interface {
	derive.Engine
	L2BlockRefByLabel(ctx context.Context, label eth.BlockLabel) (eth.L2BlockRef, error)
	L2BlockRefByHash(ctx context.Context, l2Hash common.Hash) (eth.L2BlockRef, error)
	L2BlockRefByNumber(ctx context.Context, num uint64) (eth.L2BlockRef, error)
}

type MeteredEngine 

type MeteredEngine struct {
	// contains filtered or unexported fields
}

MeteredEngine wraps an EngineControl and adds metrics such as block building time diff and sealing time

func NewMeteredEngine 

func NewMeteredEngine(cfg *rollup.Config, inner derive.EngineControl, metrics EngineMetrics, log log.Logger) *MeteredEngine

func (*MeteredEngine) BuildingPayload 

func (m *MeteredEngine) BuildingPayload() (onto eth.L2BlockRef, id eth.PayloadID, safe bool)

func (*MeteredEngine) CancelPayload 

func (m *MeteredEngine) CancelPayload(ctx context.Context, force bool) error

func (*MeteredEngine) ConfirmPayload 

func (m *MeteredEngine) ConfirmPayload(ctx context.Context, agossip async.AsyncGossiper, sequencerConductor conductor.SequencerConductor) (out *eth.ExecutionPayloadEnvelope, errTyp derive.BlockInsertionErrType, err error)

func (*MeteredEngine) Finalized 

func (m *MeteredEngine) Finalized() eth.L2BlockRef

func (*MeteredEngine) SafeL2Head 

func (m *MeteredEngine) SafeL2Head() eth.L2BlockRef

func (*MeteredEngine) StartPayload 

func (m *MeteredEngine) StartPayload(ctx context.Context, parent eth.L2BlockRef, attrs *derive.AttributesWithParent, updateSafe bool) (errType derive.BlockInsertionErrType, err error)

func (*MeteredEngine) UnsafeL2Head 

func (m *MeteredEngine) UnsafeL2Head() eth.L2BlockRef

type MeteredL1Fetcher 

type MeteredL1Fetcher struct {
	// contains filtered or unexported fields
}

func NewMeteredL1Fetcher 

func NewMeteredL1Fetcher(inner derive.L1Fetcher, metrics L1FetcherMetrics) *MeteredL1Fetcher

func (*MeteredL1Fetcher) FetchReceipts 

func (m *MeteredL1Fetcher) FetchReceipts(ctx context.Context, blockHash common.Hash) (eth.BlockInfo, types.Receipts, error)

func (*MeteredL1Fetcher) InfoAndTxsByHash 

func (m *MeteredL1Fetcher) InfoAndTxsByHash(ctx context.Context, hash common.Hash) (eth.BlockInfo, types.Transactions, error)

func (*MeteredL1Fetcher) InfoByHash 

func (m *MeteredL1Fetcher) InfoByHash(ctx context.Context, hash common.Hash) (eth.BlockInfo, error)

func (*MeteredL1Fetcher) L1BlockRefByHash 

func (m *MeteredL1Fetcher) L1BlockRefByHash(ctx context.Context, hash common.Hash) (eth.L1BlockRef, error)

func (*MeteredL1Fetcher) L1BlockRefByLabel 

func (m *MeteredL1Fetcher) L1BlockRefByLabel(ctx context.Context, label eth.BlockLabel) (eth.L1BlockRef, error)

func (*MeteredL1Fetcher) L1BlockRefByNumber 

func (m *MeteredL1Fetcher) L1BlockRefByNumber(ctx context.Context, num uint64) (eth.L1BlockRef, error)

type Metrics 

type Metrics interface {
	RecordPipelineReset()
	RecordPublishingError()
	RecordDerivationError()

	RecordReceivedUnsafePayload(payload *eth.ExecutionPayloadEnvelope)

	RecordL1Ref(name string, ref eth.L1BlockRef)
	RecordL2Ref(name string, ref eth.L2BlockRef)
	RecordChannelInputBytes(inputCompressedBytes int)
	RecordHeadChannelOpened()
	RecordChannelTimedOut()
	RecordFrame()

	RecordDerivedBatches(batchType string)

	RecordUnsafePayloadsBuffer(length uint64, memSize uint64, next eth.BlockID)

	SetDerivationIdle(idle bool)

	RecordL1ReorgDepth(d uint64)

	EngineMetrics
	L1FetcherMetrics
	SequencerMetrics
}

type Network 

type Network interface {
	// PublishL2Payload is called by the driver whenever there is a new payload to publish, synchronously with the driver main loop.
	PublishL2Payload(ctx context.Context, payload *eth.ExecutionPayloadEnvelope) error
}

type Sequencer 

type Sequencer struct {
	// contains filtered or unexported fields
}

Sequencer implements the sequencing interface of the driver: it starts and completes block building jobs.

func NewSequencer 

func NewSequencer(log log.Logger, rollupCfg *rollup.Config, engine derive.EngineControl, attributesBuilder derive.AttributesBuilder, l1OriginSelector L1OriginSelectorIface, metrics SequencerMetrics) *Sequencer

func (*Sequencer) BuildingOnto 

func (d *Sequencer) BuildingOnto() eth.L2BlockRef

BuildingOnto returns the L2 head reference that the latest block is or was being built on top of.

func (*Sequencer) CancelBuildingBlock 

func (d *Sequencer) CancelBuildingBlock(ctx context.Context)

CancelBuildingBlock cancels the current open block building job. This sequencer only maintains one block building job at a time.

func (*Sequencer) CompleteBuildingBlock 

func (d *Sequencer) CompleteBuildingBlock(ctx context.Context, agossip async.AsyncGossiper, sequencerConductor conductor.SequencerConductor) (*eth.ExecutionPayloadEnvelope, error)

CompleteBuildingBlock takes the current block that is being built, and asks the engine to complete the building, seal the block, and persist it as canonical. Warning: the safe and finalized L2 blocks as viewed during the initiation of the block building are reused for completion of the block building. The Execution engine should not change the safe and finalized blocks between start and completion of block building.

func (*Sequencer) PlanNextSequencerAction 

func (d *Sequencer) PlanNextSequencerAction() time.Duration

PlanNextSequencerAction returns a desired delay till the RunNextSequencerAction call.

func (*Sequencer) RunNextSequencerAction 

func (d *Sequencer) RunNextSequencerAction(ctx context.Context, agossip async.AsyncGossiper, sequencerConductor conductor.SequencerConductor) (*eth.ExecutionPayloadEnvelope, error)

RunNextSequencerAction starts new block building work, or seals existing work, and is best timed by first awaiting the delay returned by PlanNextSequencerAction. If a new block is successfully sealed, it will be returned for publishing, nil otherwise.

Only critical errors are bubbled up, other errors are handled internally. Internally starting or sealing of a block may fail with a derivation-like error:

  • If it is a critical error, the error is bubbled up to the caller.
  • If it is a reset error, the ResettableEngineControl used to build blocks is requested to reset, and a backoff applies. No attempt is made at completing the block building.
  • If it is a temporary error, a backoff is applied to reattempt building later.
  • If it is any other error, a backoff is applied and building is cancelled.

Upon L1 reorgs that are deep enough to affect the L1 origin selection, a reset-error may occur, to direct the engine to follow the new L1 chain before continuing to sequence blocks. It is up to the EngineControl implementation to handle conflicting build jobs of the derivation process (as verifier) and sequencing process. Generally it is expected that the latest call interrupts any ongoing work, and the derivation process does not interrupt in the happy case, since it can consolidate previously sequenced blocks by comparing sequenced inputs with derived inputs. If the derivation pipeline does force a conflicting block, then an ongoing sequencer task might still finish, but the derivation can continue to reset until the chain is correct. If the engine is currently building safe blocks, then that building is not interrupted, and sequencing is delayed.

func (*Sequencer) StartBuildingBlock 

func (d *Sequencer) StartBuildingBlock(ctx context.Context) error

StartBuildingBlock initiates a block building job on top of the given L2 head, safe and finalized blocks, and using the provided l1Origin.

type SequencerIface 

type SequencerIface interface {
	StartBuildingBlock(ctx context.Context) error
	CompleteBuildingBlock(ctx context.Context, agossip async.AsyncGossiper, sequencerConductor conductor.SequencerConductor) (*eth.ExecutionPayloadEnvelope, error)
	PlanNextSequencerAction() time.Duration
	RunNextSequencerAction(ctx context.Context, agossip async.AsyncGossiper, sequencerConductor conductor.SequencerConductor) (*eth.ExecutionPayloadEnvelope, error)
	BuildingOnto() eth.L2BlockRef
	CancelBuildingBlock(ctx context.Context)
}

type SequencerMetrics 

type SequencerMetrics interface {
	RecordSequencerInconsistentL1Origin(from eth.BlockID, to eth.BlockID)
	RecordSequencerReset()
}

type SequencerStateListener 

type SequencerStateListener interface {
	SequencerStarted() error
	SequencerStopped() error
}

type SyncStatus deprecated 

type SyncStatus = eth.SyncStatus

Deprecated: use eth.SyncStatus instead.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.