engine

type BlockInsertionErrType ¶

type BlockInsertionErrType uint

const (
	// BlockInsertOK indicates that the payload was successfully executed and appended to the canonical chain.
	BlockInsertOK BlockInsertionErrType = iota
	// BlockInsertTemporaryErr indicates that the insertion failed but may succeed at a later time without changes to the payload.
	BlockInsertTemporaryErr
	// BlockInsertPrestateErr indicates that the pre-state to insert the payload could not be prepared, e.g. due to missing chain data.
	BlockInsertPrestateErr
	// BlockInsertPayloadErr indicates that the payload was invalid and cannot become canonical.
	BlockInsertPayloadErr
)

type BuildCancelEvent ¶

type BuildCancelEvent struct {
	Info  eth.PayloadInfo
	Force bool
}

func (ev BuildCancelEvent) String() string

type BuildInvalidEvent ¶

type BuildInvalidEvent struct {
	Attributes *derive.AttributesWithParent
	Err        error
}

BuildInvalidEvent is an internal engine event, to post-process upon invalid attributes. Not for temporary processing problems.

func (ev BuildInvalidEvent) String() string

type BuildSealEvent ¶

type BuildSealEvent struct {
	Info         eth.PayloadInfo
	BuildStarted time.Time
	// if payload should be promoted to safe (must also be pending safe, see DerivedFrom)
	Concluding bool
	// payload is promoted to pending-safe if non-zero
	DerivedFrom eth.L1BlockRef
}

func (ev BuildSealEvent) String() string

type BuildSealedEvent ¶

type BuildSealedEvent struct {
	// if payload should be promoted to (local) safe (must also be pending safe, see DerivedFrom)
	Concluding bool
	// payload is promoted to pending-safe if non-zero
	DerivedFrom  eth.L1BlockRef
	BuildStarted time.Time

	Info     eth.PayloadInfo
	Envelope *eth.ExecutionPayloadEnvelope
	Ref      eth.L2BlockRef
}

BuildSealedEvent is emitted by the engine when a payload finished building, but is not locally inserted as canonical block yet

func (ev BuildSealedEvent) String() string

type BuildStartEvent ¶

type BuildStartEvent struct {
	Attributes *derive.AttributesWithParent
}

func (ev BuildStartEvent) String() string

type BuildStartedEvent ¶

type BuildStartedEvent struct {
	Info eth.PayloadInfo

	BuildStarted time.Time

	Parent eth.L2BlockRef

	// if payload should be promoted to (local) safe (must also be pending safe, see DerivedFrom)
	Concluding bool
	// payload is promoted to pending-safe if non-zero
	DerivedFrom eth.L1BlockRef
}

func (ev BuildStartedEvent) String() string

type CrossSafeUpdateEvent ¶ added in v1.9.3

type CrossSafeUpdateEvent struct {
	CrossSafe eth.L2BlockRef
	LocalSafe eth.L2BlockRef
}

func (ev CrossSafeUpdateEvent) String() string

type CrossUnsafeUpdateEvent ¶ added in v1.9.3

type CrossUnsafeUpdateEvent struct {
	CrossUnsafe eth.L2BlockRef
	LocalUnsafe eth.L2BlockRef
}

CrossUnsafeUpdateEvent signals that the given block is now considered cross-unsafe.

func (ev CrossUnsafeUpdateEvent) String() string

type CrossUpdateRequestEvent ¶ added in v1.9.3

type CrossUpdateRequestEvent struct {
	CrossUnsafe bool
	CrossSafe   bool
}

CrossUpdateRequestEvent triggers update events to be emitted, repeating the current state.

func (ev CrossUpdateRequestEvent) String() string

type EngDeriver ¶

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

func NewEngDeriver(log log.Logger, ctx context.Context, cfg *rollup.Config,
	metrics Metrics, ec *EngineController,
) *EngDeriver

func (d *EngDeriver) AttachEmitter(em event.Emitter)

func (d *EngDeriver) OnEvent(ev event.Event) bool

type Engine ¶

type Engine interface {
	ExecEngine
	derive.L2Source
}

type EngineController ¶

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

func NewEngineController(engine ExecEngine, log log.Logger, metrics derive.Metrics,
	rollupCfg *rollup.Config, syncCfg *sync.Config, emitter event.Emitter,
) *EngineController

func (e *EngineController) BackupUnsafeL2Head() eth.L2BlockRef

func (e *EngineController) CrossUnsafeL2Head() eth.L2BlockRef

func (e *EngineController) Finalized() eth.L2BlockRef

func (e *EngineController) InsertUnsafePayload(ctx context.Context, envelope *eth.ExecutionPayloadEnvelope, ref eth.L2BlockRef) error

func (e *EngineController) IsEngineSyncing() bool

func (e *EngineController) LocalSafeL2Head() eth.L2BlockRef

func (e *EngineController) PendingSafeL2Head() eth.L2BlockRef

func (e *EngineController) SafeL2Head() eth.L2BlockRef

func (e *EngineController) SetBackupUnsafeL2Head(r eth.L2BlockRef, triggerReorg bool)

func (e *EngineController) SetCrossUnsafeHead(r eth.L2BlockRef)

func (e *EngineController) SetFinalizedHead(r eth.L2BlockRef)

func (e *EngineController) SetLocalSafeHead(r eth.L2BlockRef)

func (e *EngineController) SetPendingSafeL2Head(r eth.L2BlockRef)

func (e *EngineController) SetSafeHead(r eth.L2BlockRef)

func (e *EngineController) SetUnsafeHead(r eth.L2BlockRef)

func (e *EngineController) TryBackupUnsafeReorg(ctx context.Context) (bool, error)

func (e *EngineController) TryUpdateEngine(ctx context.Context) error

func (e *EngineController) UnsafeL2Head() eth.L2BlockRef

type EngineResetConfirmedEvent ¶

type EngineResetConfirmedEvent struct {
	LocalUnsafe eth.L2BlockRef
	CrossUnsafe eth.L2BlockRef
	LocalSafe   eth.L2BlockRef
	CrossSafe   eth.L2BlockRef
	Finalized   eth.L2BlockRef
}

func (ev EngineResetConfirmedEvent) String() string

type EngineResetDeriver ¶

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

func NewEngineResetDeriver(ctx context.Context, log log.Logger, cfg *rollup.Config,
	l1 sync.L1Chain, l2 sync.L2Chain, syncCfg *sync.Config) *EngineResetDeriver

func (d *EngineResetDeriver) AttachEmitter(em event.Emitter)

func (d *EngineResetDeriver) OnEvent(ev event.Event) bool

type EngineState ¶

type EngineState interface {
	Finalized() eth.L2BlockRef
	UnsafeL2Head() eth.L2BlockRef
	SafeL2Head() eth.L2BlockRef
}

EngineState provides a read-only interface of the forkchoice state properties of the L2 Engine.

type ExecEngine ¶

type ExecEngine interface {
	GetPayload(ctx context.Context, payloadInfo eth.PayloadInfo) (*eth.ExecutionPayloadEnvelope, error)
	ForkchoiceUpdate(ctx context.Context, state *eth.ForkchoiceState, attr *eth.PayloadAttributes) (*eth.ForkchoiceUpdatedResult, error)
	NewPayload(ctx context.Context, payload *eth.ExecutionPayload, parentBeaconBlockRoot *common.Hash) (*eth.PayloadStatusV1, error)
	L2BlockRefByLabel(ctx context.Context, label eth.BlockLabel) (eth.L2BlockRef, error)
}

type FinalizedUpdateEvent ¶ added in v1.9.5

type FinalizedUpdateEvent struct {
	Ref eth.L2BlockRef
}

FinalizedUpdateEvent signals that a block has been marked as finalized.

func (ev FinalizedUpdateEvent) String() string

type ForkchoiceRequestEvent ¶

type ForkchoiceRequestEvent struct{}

ForkchoiceRequestEvent signals to the engine that it should emit an artificial forkchoice-update event, to signal the latest forkchoice to other derivers. This helps decouple derivers from the actual engine state, while also not making the derivers wait for a forkchoice update at random.

func (ev ForkchoiceRequestEvent) String() string

type ForkchoiceUpdateEvent ¶

type ForkchoiceUpdateEvent struct {
	UnsafeL2Head, SafeL2Head, FinalizedL2Head eth.L2BlockRef
}

func (ev ForkchoiceUpdateEvent) String() string

type InteropInvalidateBlockEvent ¶ added in v1.11.0

type InteropInvalidateBlockEvent struct {
	Invalidated eth.BlockRef
	Attributes  *derive.AttributesWithParent
}

InteropInvalidateBlockEvent is emitted when a block needs to be invalidated, and a replacement is needed.

func (ev InteropInvalidateBlockEvent) String() string

type InteropReplacedBlockEvent ¶ added in v1.11.0

type InteropReplacedBlockEvent struct {
	Ref      eth.BlockRef
	Envelope *eth.ExecutionPayloadEnvelope
}

InteropReplacedBlockEvent is emitted when a replacement is done.

func (ev InteropReplacedBlockEvent) String() string

type InvalidPayloadAttributesEvent ¶

type InvalidPayloadAttributesEvent struct {
	Attributes *derive.AttributesWithParent
	Err        error
}

InvalidPayloadAttributesEvent is a signal to external derivers that the attributes were invalid.

func (ev InvalidPayloadAttributesEvent) String() string

type Kind ¶

type Kind string

Kind identifies the engine client's kind, used to control the behavior of optimism in different engine clients.

const (
	Geth   Kind = "geth"
	Reth   Kind = "reth"
	Erigon Kind = "erigon"
)

func (kind *Kind) Clone() any

func (kind *Kind) Set(value string) error

func (kind Kind) String() string

func (kind Kind) SupportsPostFinalizationELSync() bool

type LocalEngineControl ¶

type LocalEngineControl interface {
	LocalEngineState
	ResetEngineControl
}

type LocalEngineState ¶

type LocalEngineState interface {
	EngineState

	PendingSafeL2Head() eth.L2BlockRef
	BackupUnsafeL2Head() eth.L2BlockRef
}

type LocalSafeUpdateEvent ¶ added in v1.9.3

type LocalSafeUpdateEvent struct {
	Ref    eth.L2BlockRef
	Source eth.L1BlockRef
}

LocalSafeUpdateEvent signals that a block is now considered to be local-safe.

func (ev LocalSafeUpdateEvent) String() string

type Metrics ¶

type Metrics interface {
	CountSequencedTxsInBlock(txns int, deposits int)

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

type PayloadInvalidEvent ¶

type PayloadInvalidEvent struct {
	Envelope *eth.ExecutionPayloadEnvelope
	Err      error
}

func (ev PayloadInvalidEvent) String() string

type PayloadProcessEvent ¶

type PayloadProcessEvent struct {
	// if payload should be promoted to (local) safe (must also be pending safe, see DerivedFrom)
	Concluding bool
	// payload is promoted to pending-safe if non-zero
	DerivedFrom  eth.L1BlockRef
	BuildStarted time.Time

	Envelope *eth.ExecutionPayloadEnvelope
	Ref      eth.L2BlockRef
}

func (ev PayloadProcessEvent) String() string

type PayloadSealExpiredErrorEvent ¶

type PayloadSealExpiredErrorEvent struct {
	Info eth.PayloadInfo
	Err  error

	Concluding  bool
	DerivedFrom eth.L1BlockRef
}

PayloadSealExpiredErrorEvent identifies a form of failed payload-sealing that is not coupled to the attributes themselves, but rather the build-job process. The user should re-attempt by starting a new build process. The payload-sealing job should not be re-attempted, as it most likely expired, timed out, or referenced an otherwise invalidated block-building job identifier.

func (ev PayloadSealExpiredErrorEvent) String() string

type PayloadSealInvalidEvent ¶

type PayloadSealInvalidEvent struct {
	Info eth.PayloadInfo
	Err  error

	Concluding  bool
	DerivedFrom eth.L1BlockRef
}

PayloadSealInvalidEvent identifies a permanent in-consensus problem with the payload sealing.

func (ev PayloadSealInvalidEvent) String() string

type PayloadSuccessEvent ¶

type PayloadSuccessEvent struct {
	// if payload should be promoted to (local) safe (must also be pending safe, see DerivedFrom)
	Concluding bool
	// payload is promoted to pending-safe if non-zero
	DerivedFrom   eth.L1BlockRef
	BuildStarted  time.Time
	InsertStarted time.Time

	Envelope *eth.ExecutionPayloadEnvelope
	Ref      eth.L2BlockRef
}

func (ev PayloadSuccessEvent) String() string

type PendingSafeRequestEvent ¶

type PendingSafeRequestEvent struct{}

func (ev PendingSafeRequestEvent) String() string

type PendingSafeUpdateEvent ¶

type PendingSafeUpdateEvent struct {
	PendingSafe eth.L2BlockRef
	Unsafe      eth.L2BlockRef // tip, added to the signal, to determine if there are existing blocks to consolidate
}

func (ev PendingSafeUpdateEvent) String() string

type ProcessAttributesEvent ¶

type ProcessAttributesEvent struct {
	Attributes *derive.AttributesWithParent
}

ProcessAttributesEvent signals to immediately process the attributes.

func (ev ProcessAttributesEvent) String() string

type ProcessUnsafePayloadEvent ¶

type ProcessUnsafePayloadEvent struct {
	Envelope *eth.ExecutionPayloadEnvelope
}

func (ev ProcessUnsafePayloadEvent) String() string

type PromoteCrossUnsafeEvent ¶ added in v1.9.3

type PromoteCrossUnsafeEvent struct {
	Ref eth.L2BlockRef
}

PromoteCrossUnsafeEvent signals that the given block may be promoted to cross-unsafe.

func (ev PromoteCrossUnsafeEvent) String() string

type PromoteFinalizedEvent ¶

type PromoteFinalizedEvent struct {
	Ref eth.L2BlockRef
}

PromoteFinalizedEvent signals that a block can be marked as finalized.

func (ev PromoteFinalizedEvent) String() string

type PromoteLocalSafeEvent ¶ added in v1.9.3

type PromoteLocalSafeEvent struct {
	Ref    eth.L2BlockRef
	Source eth.L1BlockRef
}

PromoteLocalSafeEvent signals that a block can be promoted to local-safe.

func (ev PromoteLocalSafeEvent) String() string

type PromotePendingSafeEvent ¶

type PromotePendingSafeEvent struct {
	Ref        eth.L2BlockRef
	Concluding bool // Concludes the pending phase, so can be promoted to (local) safe
	Source     eth.L1BlockRef
}

PromotePendingSafeEvent signals that a block can be marked as pending-safe, and/or safe.

func (ev PromotePendingSafeEvent) String() string

type PromoteSafeEvent ¶ added in v1.9.3

type PromoteSafeEvent struct {
	Ref    eth.L2BlockRef
	Source eth.L1BlockRef
}

PromoteSafeEvent signals that a block can be promoted to cross-safe.

func (ev PromoteSafeEvent) String() string

type PromoteUnsafeEvent ¶ added in v1.9.3

type PromoteUnsafeEvent struct {
	Ref eth.L2BlockRef
}

PromoteUnsafeEvent signals that the given block may now become a canonical unsafe block. This is pre-forkchoice update; the change may not be reflected yet in the EL. Note that the legacy pre-event-refactor code-path (processing P2P blocks) does fire this, but manually, duplicate with the newer events processing code-path. See EngineController.InsertUnsafePayload.

func (ev PromoteUnsafeEvent) String() string

type RequestCrossSafeEvent ¶ added in v1.9.3

type RequestCrossSafeEvent struct{}

RequestCrossSafeEvent signals that a CrossSafeUpdate is needed.

func (ev RequestCrossSafeEvent) String() string

type RequestCrossUnsafeEvent ¶ added in v1.9.3

type RequestCrossUnsafeEvent struct{}

RequestCrossUnsafeEvent signals that a CrossUnsafeUpdateEvent is needed.

func (ev RequestCrossUnsafeEvent) String() string

type RequestFinalizedUpdateEvent ¶ added in v1.9.5

type RequestFinalizedUpdateEvent struct{}

RequestFinalizedUpdateEvent signals that a FinalizedUpdateEvent is needed.

func (ev RequestFinalizedUpdateEvent) String() string

type ResetEngineControl ¶

type ResetEngineControl interface {
	SetUnsafeHead(eth.L2BlockRef)
	SetCrossUnsafeHead(ref eth.L2BlockRef)
	SetLocalSafeHead(ref eth.L2BlockRef)
	SetSafeHead(eth.L2BlockRef)
	SetFinalizedHead(eth.L2BlockRef)
	SetBackupUnsafeL2Head(block eth.L2BlockRef, triggerReorg bool)
	SetPendingSafeL2Head(eth.L2BlockRef)
}

type ResetEngineRequestEvent ¶

type ResetEngineRequestEvent struct{}

ResetEngineRequestEvent requests the EngineResetDeriver to walk the L2 chain backwards until it finds a plausible unsafe head, and find an L2 safe block that is guaranteed to still be from the L1 chain. This event is not used in interop.

func (ev ResetEngineRequestEvent) String() string

type SafeDerivedEvent ¶

type SafeDerivedEvent struct {
	Safe   eth.L2BlockRef
	Source eth.L1BlockRef
}

SafeDerivedEvent signals that a block was determined to be safe, and derived from the given L1 block. This is signaled upon successful processing of PromoteSafeEvent.

func (ev SafeDerivedEvent) String() string

type TryBackupUnsafeReorgEvent ¶

type TryBackupUnsafeReorgEvent struct{}

func (ev TryBackupUnsafeReorgEvent) String() string

type TryUpdateEngineEvent ¶

type TryUpdateEngineEvent struct {
	// These fields will be zero-value (BuildStarted,InsertStarted=time.Time{}, Envelope=nil) if
	// this event is emitted outside of engineDeriver.onPayloadSuccess
	BuildStarted  time.Time
	InsertStarted time.Time
	Envelope      *eth.ExecutionPayloadEnvelope
}

func (ev TryUpdateEngineEvent) String() string

type UnsafeUpdateEvent ¶ added in v1.9.3

type UnsafeUpdateEvent struct {
	Ref eth.L2BlockRef
}

UnsafeUpdateEvent signals that the given block is now considered safe. This is pre-forkchoice update; the change may not be reflected yet in the EL.

func (ev UnsafeUpdateEvent) String() string