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 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL