derive

package
v1.0.3-rc.1 Latest Latest
Warning

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

 Go to latest Published: Dec 11, 2023 License: MIT, MIT Imports: 27 Imported by: 0

Documentation

Overview

Package derive provides the data transformation functions that take L1 data and turn it into L2 blocks and results. Certain L2 data is also able to turned back into L1 data.

The flow is data is as follows receipts, batches -> eth.PayloadAttributes, by parsing the L1 data and deriving L2 inputs l2.PayloadAttributes -> l2.ExecutionPayload, by running the EVM (using an Execution Engine) L2 block -> Corresponding L1 block info, by parsing the first deposited transaction

The Payload Attributes derivation stage is a pure function. The Execution Payload derivation stage relies on the L2 execution engine to perform the state update. The inversion step is a pure function.

The steps should be kept separate to enable easier testing.

Index

Constants

View Source 
const (
	// BatchDrop indicates that the batch is invalid, and will always be in the future, unless we reorg
	BatchDrop = iota
	// BatchAccept indicates that the batch is valid and should be processed
	BatchAccept
	// BatchUndecided indicates we are lacking L1 information until we can proceed batch filtering
	BatchUndecided
	// BatchFuture indicates that the batch may be valid, but cannot be processed yet and should be checked again later
	BatchFuture
)
View Source 
const (
	UserDepositSourceDomain   = 0
	L1InfoDepositSourceDomain = 1
)
View Source 
const (
	L1InfoFuncSignature = "setL1BlockValues(uint64,uint64,uint256,bytes32,uint64,bytes32,uint256,uint256,uint256)"
	L1InfoArguments     = 9
	L1InfoLen           = 4 + 32*L1InfoArguments
	SystemTxGas         = 1_000_000
)
View Source 
const (
	BatchV1Type = iota
)
View Source 
const ChannelIDLength = 16

ChannelIDLength defines the length of the channel IDs

View Source 
const DerivationVersion0 = 0
View Source 
const FinalityDelay = 64

FinalityDelay is the number of L1 blocks to traverse before trying to finalize L2 blocks again. We do not want to do this too often, since it requires fetching a L1 block by number, so no cache data.

View Source 
const FrameV0OverHeadSize = 23

FrameV0OverHeadSize is the absolute minimum size of a frame. This is the fixed overhead frame size, calculated as specified in the Frame Format specs: 16 + 2 + 4 + 1 = 23 bytes.

View Source 
const MaxChannelBankSize = 100_000_000

MaxChannelBankSize is the amount of memory space, in number of bytes, till the bank is pruned by removing channels, starting with the oldest channel.

View Source 
const MaxFrameLen = 1_000_000

Frames cannot be larger than 1 MB. Data transactions that carry frames are generally not larger than 128 KB due to L1 network conditions, but we leave space to grow larger anyway (gas limit allows for more data).

View Source 
const MaxRLPBytesPerChannel = 10_000_000

MaxRLPBytesPerChannel is the maximum amount of bytes that will be read from a channel. This limit is set when decoding the RLP.

Variables

View Source 
var (
	ErrMaxFrameSizeTooSmall = errors.New("maxSize is too small to fit the fixed frame overhead")
	ErrNotDepositTx         = errors.New("first transaction in block is not a deposit tx")
	ErrTooManyRLPBytes      = errors.New("batch would cause RLP bytes to go over limit")
)
View Source 
var (
	DepositEventABI      = "TransactionDeposited(address,address,uint256,bytes)"
	DepositEventABIHash  = crypto.Keccak256Hash([]byte(DepositEventABI))
	DepositEventVersion0 = common.Hash{}
)
View Source 
var (
	ErrTemporary = NewTemporaryError(nil)
	ErrReset     = NewResetError(nil)
	ErrCritical  = NewCriticalError(nil)
)

Sentinel errors, use these to get the severity of errors by calling errors.Is(err, ErrTemporary) for example.

View Source 
var (
	L1InfoFuncBytes4       = crypto.Keccak256([]byte(L1InfoFuncSignature))[:4]
	L1InfoDepositerAddress = common.HexToAddress("0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001")
	L1BlockAddress         = predeploys.L1BlockAddr
)
View Source 
var (
	SystemConfigUpdateBatcher               = common.Hash{31: 0}
	SystemConfigUpdateGasConfig             = common.Hash{31: 1}
	SystemConfigUpdateGasLimit              = common.Hash{31: 2}
	SystemConfigUpdateUnsafeBlockSigner     = common.Hash{31: 3}
	SystemConfigUpdateValidatorRewardScalar = common.Hash{31: 4}
)
View Source 
var (
	ConfigUpdateEventABI      = "ConfigUpdate(uint256,uint8,bytes)"
	ConfigUpdateEventABIHash  = crypto.Keccak256Hash([]byte(ConfigUpdateEventABI))
	ConfigUpdateEventVersion0 = common.Hash{}
)
View Source 
var DuplicateErr = errors.New("duplicate frame")

DuplicateErr is returned when a newly read frame is already known

View Source 
var ErrEngineP2PSyncing = errors.New("engine is P2P syncing")

ErrEngineP2PSyncing implies that the execution engine is currently in progress of P2P sync.

View Source 
var ErrNotEnoughData = errors.New("not enough data")

ErrNotEnoughData implies that the function currently does not have enough data to progress but if it is retried enough times, it will eventually return a real value or io.EOF

Functions

func AttributesMatchBlock 

func AttributesMatchBlock(attrs *eth.PayloadAttributes, parentHash common.Hash, block *eth.ExecutionPayload, l log.Logger) error

AttributesMatchBlock checks if the L2 attributes pre-inputs match the output nil if it is a match. If err is not nil, the error contains the reason for the mismatch

func BatchReader 

func BatchReader(r io.Reader, l1InclusionBlock eth.L1BlockRef) (func() (BatchWithL1InclusionBlock, error), error)

BatchReader provides a function that iteratively consumes batches from the reader. The L1Inclusion block is also provided at creation time.

func BlockToBatch 

func BlockToBatch(block *types.Block) (*BatchData, L1BlockInfo, error)

BlockToBatch transforms a block into a batch object that can easily be RLP encoded.

func DataFromEVMTransactions 

func DataFromEVMTransactions(config *rollup.Config, batcherAddr common.Address, txs types.Transactions, log log.Logger) []eth.Data

DataFromEVMTransactions filters all of the transactions and returns the calldata from transactions that are sent to the batch inbox address from the batch sender address. This will return an empty array if no valid transactions are found.

func DeriveDeposits 

func DeriveDeposits(receipts []*types.Receipt, depositContractAddr common.Address) ([]hexutil.Bytes, error)

func ForceCloseTxData 

func ForceCloseTxData(frames []Frame) ([]byte, error)

ForceCloseTxData generates the transaction data for a transaction which will force close a channel. It should be given every frame of that channel which has been submitted on chain. The frames should be given in order that they appear on L1.

func L1InfoDeposit 

func L1InfoDeposit(seqNumber uint64, block eth.BlockInfo, sysCfg eth.SystemConfig) (*types.DepositTx, error)

L1InfoDeposit creates a L1 Info deposit transaction based on the L1 block, and the L2 block-height difference with the start of the epoch.

func L1InfoDepositBytes 

func L1InfoDepositBytes(seqNumber uint64, l1Info eth.BlockInfo, sysCfg eth.SystemConfig) ([]byte, error)

L1InfoDepositBytes returns a serialized L1-info attributes transaction.

func L2BlockToBlockRef 

func L2BlockToBlockRef(block L2BlockRefSource, genesis *rollup.Genesis) (eth.L2BlockRef, error)

L2BlockToBlockRef extracts the essential L2BlockRef information from an L2 block ref source, falling back to genesis information if necessary.

func MarshalDepositLogEvent 

func MarshalDepositLogEvent(depositContractAddr common.Address, deposit *types.DepositTx) (*types.Log, error)

MarshalDepositLogEvent returns an EVM log entry that encodes a TransactionDeposited event from the deposit contract. This is the reverse of the deposit transaction derivation.

func NewCriticalError 

func NewCriticalError(err error) error

NewCriticalError returns a critical error.

func NewError 

func NewError(err error, level Level) error

NewError returns a custom Error.

func NewResetError 

func NewResetError(err error) error

NewResetError returns a pipeline reset error.

func NewTemporaryError 

func NewTemporaryError(err error) error

NewTemporaryError returns a temporary error.

func PayloadToBlockRef 

func PayloadToBlockRef(payload *eth.ExecutionPayload, genesis *rollup.Genesis) (eth.L2BlockRef, error)

PayloadToBlockRef extracts the essential L2BlockRef information from an execution payload, falling back to genesis information if necessary.

func PayloadToSystemConfig 

func PayloadToSystemConfig(payload *eth.ExecutionPayload, cfg *rollup.Config) (eth.SystemConfig, error)

func ProcessSystemConfigUpdateLogEvent 

func ProcessSystemConfigUpdateLogEvent(destSysCfg *eth.SystemConfig, ev *types.Log) error

ProcessSystemConfigUpdateLogEvent decodes an EVM log entry emitted by the system config contract and applies it as a system config change.

parse log data for: 

event ConfigUpdate(
    uint256 indexed version,
    UpdateType indexed updateType,
    bytes data
);

func UnmarshalDepositLogEvent 

func UnmarshalDepositLogEvent(ev *types.Log) (*types.DepositTx, error)

UnmarshalDepositLogEvent decodes an EVM log entry emitted by the deposit contract into typed deposit data.

parse log data for: 

event TransactionDeposited(
    address indexed from,
    address indexed to,
    uint256 indexed version,
    bytes opaqueData
);

Additionally, the event log-index and

func UpdateSystemConfigWithL1Receipts 

func UpdateSystemConfigWithL1Receipts(sysCfg *eth.SystemConfig, receipts []*types.Receipt, cfg *rollup.Config) error

UpdateSystemConfigWithL1Receipts filters all L1 receipts to find config updates and applies the config updates to the given sysCfg

func UserDeposits 

func UserDeposits(receipts []*types.Receipt, depositContractAddr common.Address) ([]*types.DepositTx, error)

UserDeposits transforms the L2 block-height and L1 receipts into the transaction inputs for a full L2 block

Types

type AttributesBuilder 

type AttributesBuilder interface {
	PreparePayloadAttributes(ctx context.Context, l2Parent eth.L2BlockRef, epoch eth.BlockID) (attrs *eth.PayloadAttributes, err error)
}

type AttributesQueue 

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

func NewAttributesQueue 

func NewAttributesQueue(log log.Logger, cfg *rollup.Config, builder AttributesBuilder, prev *BatchQueue) *AttributesQueue

func (*AttributesQueue) NextAttributes 

func (aq *AttributesQueue) NextAttributes(ctx context.Context, l2SafeHead eth.L2BlockRef) (*eth.PayloadAttributes, error)

func (*AttributesQueue) Origin 

func (aq *AttributesQueue) Origin() eth.L1BlockRef

func (*AttributesQueue) Reset 

func (aq *AttributesQueue) Reset(ctx context.Context, _ eth.L1BlockRef, _ eth.SystemConfig) error

type BatchData 

type BatchData struct {
	BatchV1
}

func (*BatchData) DecodeRLP 

func (b *BatchData) DecodeRLP(s *rlp.Stream) error

DecodeRLP implements rlp.Decoder

func (*BatchData) EncodeRLP 

func (b *BatchData) EncodeRLP(w io.Writer) error

EncodeRLP implements rlp.Encoder

func (*BatchData) MarshalBinary 

func (b *BatchData) MarshalBinary() ([]byte, error)

MarshalBinary returns the canonical encoding of the batch.

func (*BatchData) UnmarshalBinary 

func (b *BatchData) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes the canonical encoding of batch.

type BatchQueue 

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

BatchQueue contains a set of batches for every L1 block. L1 blocks are contiguous and this does not support reorgs.

func NewBatchQueue 

func NewBatchQueue(log log.Logger, cfg *rollup.Config, prev NextBatchProvider) *BatchQueue

NewBatchQueue creates a BatchQueue, which should be Reset(origin) before use.

func (*BatchQueue) AddBatch 

func (bq *BatchQueue) AddBatch(batch *BatchData, l2SafeHead eth.L2BlockRef)

func (*BatchQueue) NextBatch 

func (bq *BatchQueue) NextBatch(ctx context.Context, safeL2Head eth.L2BlockRef) (*BatchData, error)

func (*BatchQueue) Origin 

func (bq *BatchQueue) Origin() eth.L1BlockRef

func (*BatchQueue) Reset 

func (bq *BatchQueue) Reset(ctx context.Context, base eth.L1BlockRef, _ eth.SystemConfig) error

type BatchV1 

type BatchV1 struct {
	ParentHash common.Hash  // parent L2 block hash
	EpochNum   rollup.Epoch // aka l1 num
	EpochHash  common.Hash  // block hash
	Timestamp  uint64
	// no feeRecipient address input, all fees go to a L2 contract
	Transactions []hexutil.Bytes
}

func (*BatchV1) Epoch 

func (b *BatchV1) Epoch() eth.BlockID

type BatchValidity 

type BatchValidity uint8

func CheckBatch 

func CheckBatch(cfg *rollup.Config, log log.Logger, l1Blocks []eth.L1BlockRef, l2SafeHead eth.L2BlockRef, batch *BatchWithL1InclusionBlock) BatchValidity

CheckBatch checks if the given batch can be applied on top of the given l2SafeHead, given the contextual L1 blocks the batch was included in. The first entry of the l1Blocks should match the origin of the l2SafeHead. One or more consecutive l1Blocks should be provided. In case of only a single L1 block, the decision whether a batch is valid may have to stay undecided.

type BatchWithL1InclusionBlock 

type BatchWithL1InclusionBlock struct {
	L1InclusionBlock eth.L1BlockRef
	Batch            *BatchData
}

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
)

func ConfirmPayload 

func ConfirmPayload(ctx context.Context, log log.Logger, eng Engine, fc eth.ForkchoiceState, id eth.PayloadID, updateSafe bool) (out *eth.ExecutionPayload, errTyp BlockInsertionErrType, err error)

ConfirmPayload ends an execution payload building process in the provided Engine, and persists the payload as the canonical head. If updateSafe is true, then the payload will also be recognized as safe-head at the same time. The severity of the error is distinguished to determine whether the payload was valid and can become canonical.

func StartPayload 

func StartPayload(ctx context.Context, eng Engine, fc eth.ForkchoiceState, attrs *eth.PayloadAttributes) (id eth.PayloadID, errType BlockInsertionErrType, err error)

StartPayload starts an execution payload building process in the provided Engine, with the given attributes. The severity of the error is distinguished to determine whether the same payload attributes may be re-attempted later.

type ByteReader 

type ByteReader interface {
	io.Reader
	io.ByteReader
}

type Channel 

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

A Channel is a set of batches that are split into at least one, but possibly multiple frames. Frames are allowed to be ingested out of order. Each frame is ingested one by one. Once a frame with `closed` is added to the channel, the channel may mark itself as ready for reading once all intervening frames have been added

func NewChannel 

func NewChannel(id ChannelID, openBlock eth.L1BlockRef) *Channel

func (*Channel) AddFrame 

func (ch *Channel) AddFrame(frame Frame, l1InclusionBlock eth.L1BlockRef) error

AddFrame adds a frame to the channel. If the frame is not valid for the channel it returns an error. Otherwise the frame is buffered.

func (*Channel) IsReady 

func (ch *Channel) IsReady() bool

IsReady returns true iff the channel is ready to be read.

func (*Channel) OpenBlockNumber 

func (ch *Channel) OpenBlockNumber() uint64

OpenBlockNumber returns the block number of L1 block that contained the first frame for this channel.

func (*Channel) Reader 

func (ch *Channel) Reader() io.Reader

Reader returns an io.Reader over the channel data. This panics if it is called while `IsReady` is not true. This function is able to be called multiple times.

func (*Channel) Size 

func (ch *Channel) Size() uint64

Size returns the current size of the channel including frame overhead. Reading from the channel does not reduce the size as reading is done on uncompressed data while this size is over compressed data.

type ChannelBank 

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

ChannelBank buffers channel frames, and emits full channel data

func NewChannelBank 

func NewChannelBank(log log.Logger, cfg *rollup.Config, prev NextFrameProvider, fetcher L1Fetcher) *ChannelBank

NewChannelBank creates a ChannelBank, which should be Reset(origin) before use.

func (*ChannelBank) IngestFrame 

func (cb *ChannelBank) IngestFrame(f Frame)

IngestFrame adds new L1 data to the channel bank. Read() should be called repeatedly first, until everything has been read, before adding new data.

func (*ChannelBank) NextData 

func (cb *ChannelBank) NextData(ctx context.Context) ([]byte, error)

NextData pulls the next piece of data from the channel bank. Note that it attempts to pull data out of the channel bank prior to loading data in (unlike most other stages). This is to ensure maintain consistency around channel bank pruning which depends upon the order of operations.

func (*ChannelBank) Origin 

func (cb *ChannelBank) Origin() eth.L1BlockRef

func (*ChannelBank) Read 

func (cb *ChannelBank) Read() (data []byte, err error)

Read the raw data of the first channel, if it's timed-out or closed. Read returns io.EOF if there is nothing new to read.

func (*ChannelBank) Reset 

func (cb *ChannelBank) Reset(ctx context.Context, base eth.L1BlockRef, _ eth.SystemConfig) error

type ChannelID 

type ChannelID [ChannelIDLength]byte

ChannelID is an opaque identifier for a channel. It is 128 bits to be globally unique.

func (ChannelID) MarshalText 

func (id ChannelID) MarshalText() ([]byte, error)

func (ChannelID) String 

func (id ChannelID) String() string

func (ChannelID) TerminalString 

func (id ChannelID) TerminalString() string

TerminalString implements log.TerminalStringer, formatting a string for console output during logging.

func (*ChannelID) UnmarshalText 

func (id *ChannelID) UnmarshalText(text []byte) error

type ChannelInReader 

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

ChannelInReader reads a batch from the channel This does decompression and limits the max RLP size This is a pure function from the channel, but each channel (or channel fragment) must be tagged with an L1 inclusion block to be passed to the batch queue.

func NewChannelInReader 

func NewChannelInReader(log log.Logger, prev *ChannelBank, metrics Metrics) *ChannelInReader

NewChannelInReader creates a ChannelInReader, which should be Reset(origin) before use.

func (*ChannelInReader) NextBatch 

func (cr *ChannelInReader) NextBatch(ctx context.Context) (*BatchData, error)

NextBatch pulls out the next batch from the channel if it has it. It returns io.EOF when it cannot make any more progress. It will return a temporary error if it needs to be called again to advance some internal state.

func (*ChannelInReader) NextChannel 

func (cr *ChannelInReader) NextChannel()

NextChannel forces the next read to continue with the next channel, resetting any decoding/decompression state to a fresh start.

func (*ChannelInReader) Origin 

func (cr *ChannelInReader) Origin() eth.L1BlockRef

func (*ChannelInReader) Reset 

func (cr *ChannelInReader) Reset(ctx context.Context, _ eth.L1BlockRef, _ eth.SystemConfig) error

func (*ChannelInReader) WriteChannel 

func (cr *ChannelInReader) WriteChannel(data []byte) error

TODO: Take full channel for better logging

type ChannelOut 

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

func NewChannelOut 

func NewChannelOut() (*ChannelOut, error)

func (*ChannelOut) AddBatch 

func (co *ChannelOut) AddBatch(batch *BatchData) (uint64, error)

AddBatch adds a batch to the channel. It returns the RLP encoded byte size and an error if there is a problem adding the batch. The only sentinel error that it returns is ErrTooManyRLPBytes. If this error is returned, the channel should be closed and a new one should be made.

AddBatch should be used together with BlockToBatch if you need to access the BatchData before adding a block to the channel. It isn't possible to access the batch data with AddBlock.

func (*ChannelOut) AddBlock 

func (co *ChannelOut) AddBlock(block *types.Block) (uint64, error)

AddBlock adds a block to the channel. It returns the RLP encoded byte size and an error if there is a problem adding the block. The only sentinel error that it returns is ErrTooManyRLPBytes. If this error is returned, the channel should be closed and a new one should be made.

func (*ChannelOut) Close 

func (co *ChannelOut) Close() error

func (*ChannelOut) Flush 

func (co *ChannelOut) Flush() error

Flush flushes the internal compression stage to the ready buffer. It enables pulling a larger & more complete frame. It reduces the compression efficiency.

func (*ChannelOut) ID 

func (co *ChannelOut) ID() ChannelID

func (*ChannelOut) InputBytes 

func (co *ChannelOut) InputBytes() int

InputBytes returns the total amount of RLP-encoded input bytes.

func (*ChannelOut) OutputFrame 

func (co *ChannelOut) OutputFrame(w *bytes.Buffer, maxSize uint64) (uint16, error)

OutputFrame writes a frame to w with a given max size and returns the frame number. Use `ReadyBytes`, `Flush`, and `Close` to modify the ready buffer. Returns an error if the `maxSize` < FrameV0OverHeadSize. Returns io.EOF when the channel is closed & there are no more frames. Returns nil if there is still more buffered data. Returns an error if it ran into an error during processing.

func (*ChannelOut) ReadyBytes 

func (co *ChannelOut) ReadyBytes() int

ReadyBytes returns the number of bytes that the channel out can immediately output into a frame. Use `Flush` or `Close` to move data from the compression buffer into the ready buffer if more bytes are needed. Add blocks may add to the ready buffer, but it is not guaranteed due to the compression stage.

func (*ChannelOut) Reset 

func (co *ChannelOut) Reset() error

TODO: reuse ChannelOut for performance

type DataAvailabilitySource 

type DataAvailabilitySource interface {
	OpenData(ctx context.Context, id eth.BlockID, batcherAddr common.Address) DataIter
}

type DataIter 

type DataIter interface {
	Next(ctx context.Context) (eth.Data, error)
}

func NewDataSource 

func NewDataSource(ctx context.Context, log log.Logger, cfg *rollup.Config, fetcher L1TransactionFetcher, block eth.BlockID, batcherAddr common.Address) DataIter

NewDataSource creates a new calldata source. It suppresses errors in fetching the L1 block if they occur. If there is an error, it will attempt to fetch the result on the next call to `Next`.

type DataSource 

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

DataSource is a fault tolerant approach to fetching data. The constructor will never fail & it will instead re-attempt the fetcher at a later point.

func (*DataSource) Next 

func (ds *DataSource) Next(ctx context.Context) (eth.Data, error)

Next returns the next piece of data if it has it. If the constructor failed, this will attempt to reinitialize itself. If it cannot find the block it returns a ResetError otherwise it returns a temporary error if fetching the block returns an error.

type DataSourceFactory 

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

DataSourceFactory readers raw transactions from a given block & then filters for batch submitter transactions. This is not a stage in the pipeline, but a wrapper for another stage in the pipeline

func NewDataSourceFactory 

func NewDataSourceFactory(log log.Logger, cfg *rollup.Config, fetcher L1TransactionFetcher) *DataSourceFactory

func (*DataSourceFactory) OpenData 

func (ds *DataSourceFactory) OpenData(ctx context.Context, id eth.BlockID, batcherAddr common.Address) DataIter

OpenData returns a DataIter. This struct implements the `Next` function.

type DerivationPipeline 

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

DerivationPipeline is updated with new L1 data, and the Step() function can be iterated on to keep the L2 Engine in sync.

func NewDerivationPipeline 

func NewDerivationPipeline(log log.Logger, cfg *rollup.Config, l1Fetcher L1Fetcher, engine Engine, metrics Metrics, syncCfg *sync.Config) *DerivationPipeline

NewDerivationPipeline creates a derivation pipeline, which should be reset before use.

func (*DerivationPipeline) AddUnsafePayload 

func (dp *DerivationPipeline) AddUnsafePayload(payload *eth.ExecutionPayload)

AddUnsafePayload schedules an execution payload to be processed, ahead of deriving it from L1

func (*DerivationPipeline) BuildingPayload 

func (dp *DerivationPipeline) BuildingPayload() (onto eth.L2BlockRef, id eth.PayloadID, safe bool)

func (*DerivationPipeline) CancelPayload 

func (dp *DerivationPipeline) CancelPayload(ctx context.Context, force bool) error

func (*DerivationPipeline) ConfirmPayload 

func (dp *DerivationPipeline) ConfirmPayload(ctx context.Context) (out *eth.ExecutionPayload, errTyp BlockInsertionErrType, err error)

func (*DerivationPipeline) EngineReady 

func (dp *DerivationPipeline) EngineReady() bool

EngineReady returns true if the engine is ready to be used. When it's being reset its state is inconsistent, and should not be used externally.

func (*DerivationPipeline) EngineSyncTarget added in v1.0.2 

func (dp *DerivationPipeline) EngineSyncTarget() eth.L2BlockRef

func (*DerivationPipeline) Finalize 

func (dp *DerivationPipeline) Finalize(l1Origin eth.L1BlockRef)

func (*DerivationPipeline) Finalized 

func (dp *DerivationPipeline) Finalized() eth.L2BlockRef

func (*DerivationPipeline) FinalizedL1 

func (dp *DerivationPipeline) FinalizedL1() eth.L1BlockRef

FinalizedL1 is the L1 finalization of the inner-most stage of the derivation pipeline, i.e. the L1 chain up to and including this point included and/or produced all the finalized L2 blocks.

func (*DerivationPipeline) Origin 

func (dp *DerivationPipeline) Origin() eth.L1BlockRef

Origin is the L1 block of the inner-most stage of the derivation pipeline, i.e. the L1 chain up to and including this point included and/or produced all the safe L2 blocks.

func (*DerivationPipeline) Reset 

func (dp *DerivationPipeline) Reset()

func (*DerivationPipeline) SafeL2Head 

func (dp *DerivationPipeline) SafeL2Head() eth.L2BlockRef

func (*DerivationPipeline) StartPayload 

func (dp *DerivationPipeline) StartPayload(ctx context.Context, parent eth.L2BlockRef, attrs *eth.PayloadAttributes, updateSafe bool) (errType BlockInsertionErrType, err error)

func (*DerivationPipeline) Step 

func (dp *DerivationPipeline) Step(ctx context.Context) error

Step tries to progress the buffer. An EOF is returned if there pipeline is blocked by waiting for new L1 data. If ctx errors no error is returned, but the step may exit early in a state that can still be continued. Any other error is critical and the derivation pipeline should be reset. An error is expected when the underlying source closes. When Step returns nil, it should be called again, to continue the derivation process.

func (*DerivationPipeline) UnsafeL2Head 

func (dp *DerivationPipeline) UnsafeL2Head() eth.L2BlockRef

UnsafeL2Head returns the head of the L2 chain that we are deriving for, this may be past what we derived from L1

func (*DerivationPipeline) UnsafeL2SyncTarget 

func (dp *DerivationPipeline) UnsafeL2SyncTarget() eth.L2BlockRef

UnsafeL2SyncTarget retrieves the first queued-up L2 unsafe payload, or a zeroed reference if there is none.

type Engine 

type Engine interface {
	GetPayload(ctx context.Context, payloadId eth.PayloadID) (*eth.ExecutionPayload, error)
	ForkchoiceUpdate(ctx context.Context, state *eth.ForkchoiceState, attr *eth.PayloadAttributes) (*eth.ForkchoiceUpdatedResult, error)
	NewPayload(ctx context.Context, payload *eth.ExecutionPayload) (*eth.PayloadStatusV1, error)
	PayloadByHash(context.Context, common.Hash) (*eth.ExecutionPayload, error)
	PayloadByNumber(context.Context, uint64) (*eth.ExecutionPayload, error)
	L2BlockRefByLabel(ctx context.Context, label eth.BlockLabel) (eth.L2BlockRef, error)
	L2BlockRefByHash(ctx context.Context, l2Hash common.Hash) (eth.L2BlockRef, error)
	SystemConfigL2Fetcher
}

type EngineControl 

type EngineControl interface {
	EngineState

	// StartPayload requests the engine to start building a block with the given attributes.
	// If updateSafe, the resulting block will be marked as a safe block.
	StartPayload(ctx context.Context, parent eth.L2BlockRef, attrs *eth.PayloadAttributes, updateSafe bool) (errType BlockInsertionErrType, err error)
	// ConfirmPayload requests the engine to complete the current block. If no block is being built, or if it fails, an error is returned.
	ConfirmPayload(ctx context.Context) (out *eth.ExecutionPayload, errTyp BlockInsertionErrType, err error)
	// CancelPayload requests the engine to stop building the current block without making it canonical.
	// This is optional, as the engine expires building jobs that are left uncompleted, but can still save resources.
	CancelPayload(ctx context.Context, force bool) error
	// BuildingPayload indicates if a payload is being built, and onto which block it is being built, and whether or not it is a safe payload.
	BuildingPayload() (onto eth.L2BlockRef, id eth.PayloadID, safe bool)
}

EngineControl enables other components to build blocks with the Engine, while keeping the forkchoice state and payload-id management internal to avoid state inconsistencies between different users of the EngineControl.

type EngineQueue 

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

EngineQueue queues up payload attributes to consolidate or process with the provided Engine

func NewEngineQueue 

func NewEngineQueue(log log.Logger, cfg *rollup.Config, engine Engine, metrics Metrics, prev NextAttributesProvider, l1Fetcher L1Fetcher, syncCfg *sync.Config) *EngineQueue

NewEngineQueue creates a new EngineQueue, which should be Reset(origin) before use.

func (*EngineQueue) AddUnsafePayload 

func (eq *EngineQueue) AddUnsafePayload(payload *eth.ExecutionPayload)

func (*EngineQueue) BuildingPayload 

func (eq *EngineQueue) BuildingPayload() (onto eth.L2BlockRef, id eth.PayloadID, safe bool)

func (*EngineQueue) CancelPayload 

func (eq *EngineQueue) CancelPayload(ctx context.Context, force bool) error

func (*EngineQueue) ConfirmPayload 

func (eq *EngineQueue) ConfirmPayload(ctx context.Context) (out *eth.ExecutionPayload, errTyp BlockInsertionErrType, err error)

func (*EngineQueue) EngineSyncTarget added in v1.0.2 

func (eq *EngineQueue) EngineSyncTarget() eth.L2BlockRef

func (*EngineQueue) Finalize 

func (eq *EngineQueue) Finalize(l1Origin eth.L1BlockRef)

func (*EngineQueue) Finalized 

func (eq *EngineQueue) Finalized() eth.L2BlockRef

func (*EngineQueue) FinalizedL1 

func (eq *EngineQueue) FinalizedL1() eth.L1BlockRef

FinalizedL1 identifies the L1 chain (incl.) that included and/or produced all the finalized L2 blocks. This may return a zeroed ID if no finalization signals have been seen yet.

func (*EngineQueue) Origin 

func (eq *EngineQueue) Origin() eth.L1BlockRef

Origin identifies the L1 chain (incl.) that included and/or produced all the safe L2 blocks.

func (*EngineQueue) Reset 

func (eq *EngineQueue) Reset(ctx context.Context, _ eth.L1BlockRef, _ eth.SystemConfig) error

Reset walks the L2 chain backwards until it finds an L2 block whose L1 origin is canonical. The unsafe head is set to the head of the L2 chain, unless the existing safe head is not canonical.

func (*EngineQueue) SafeL2Head 

func (eq *EngineQueue) SafeL2Head() eth.L2BlockRef

func (*EngineQueue) SetEngineSyncTarget added in v1.0.2 

func (eq *EngineQueue) SetEngineSyncTarget(head eth.L2BlockRef)

func (*EngineQueue) SetUnsafeHead 

func (eq *EngineQueue) SetUnsafeHead(head eth.L2BlockRef)

func (*EngineQueue) StartPayload 

func (eq *EngineQueue) StartPayload(ctx context.Context, parent eth.L2BlockRef, attrs *eth.PayloadAttributes, updateSafe bool) (errType BlockInsertionErrType, err error)

func (*EngineQueue) Step 

func (eq *EngineQueue) Step(ctx context.Context) error

func (*EngineQueue) SystemConfig 

func (eq *EngineQueue) SystemConfig() eth.SystemConfig

func (*EngineQueue) UnsafeL2Head 

func (eq *EngineQueue) UnsafeL2Head() eth.L2BlockRef

func (*EngineQueue) UnsafeL2SyncTarget 

func (eq *EngineQueue) UnsafeL2SyncTarget() eth.L2BlockRef

UnsafeL2SyncTarget retrieves the first queued-up L2 unsafe payload, or a zeroed reference if there is none.

type EngineQueueStage 

type EngineQueueStage interface {
	EngineControl

	FinalizedL1() eth.L1BlockRef
	Finalized() eth.L2BlockRef
	UnsafeL2Head() eth.L2BlockRef
	SafeL2Head() eth.L2BlockRef
	EngineSyncTarget() eth.L2BlockRef
	Origin() eth.L1BlockRef
	SystemConfig() eth.SystemConfig
	SetUnsafeHead(head eth.L2BlockRef)

	Finalize(l1Origin eth.L1BlockRef)
	AddUnsafePayload(payload *eth.ExecutionPayload)
	UnsafeL2SyncTarget() eth.L2BlockRef
	Step(context.Context) error
}

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 Error 

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

Error is a wrapper for error, description and a severity level.

func (Error) Error 

func (e Error) Error() string

Error satisfies the error interface.

func (Error) Is 

func (e Error) Is(target error) bool

Is satisfies the error Unwrap interface.

func (Error) Unwrap 

func (e Error) Unwrap() error

Unwrap satisfies the Is/As interface.

type FetchingAttributesBuilder 

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

FetchingAttributesBuilder fetches inputs for the building of L2 payload attributes on the fly.

func NewFetchingAttributesBuilder 

func NewFetchingAttributesBuilder(cfg *rollup.Config, l1 L1ReceiptsFetcher, l2 SystemConfigL2Fetcher) *FetchingAttributesBuilder

func (*FetchingAttributesBuilder) PreparePayloadAttributes 

func (ba *FetchingAttributesBuilder) PreparePayloadAttributes(ctx context.Context, l2Parent eth.L2BlockRef, epoch eth.BlockID) (attrs *eth.PayloadAttributes, err error)

PreparePayloadAttributes prepares a PayloadAttributes template that is ready to build a L2 block with deposits only, on top of the given l2Parent, with the given epoch as L1 origin. The template defaults to NoTxPool=true, and no sequencer transactions: the caller has to modify the template to add transactions, by setting NoTxPool=false as sequencer, or by appending batch transactions as syncer. The severity of the error is returned; a crit=false error means there was a temporary issue, like a failed RPC or time-out. A crit=true error means the input arguments are inconsistent or invalid.

type FinalityData 

type FinalityData struct {
	// The last L2 block that was fully derived and inserted into the L2 engine while processing this L1 block.
	L2Block eth.L2BlockRef
	// The L1 block this stage was at when inserting the L2 block.
	// When this L1 block is finalized, the L2 chain up to this block can be fully reproduced from finalized L1 data.
	L1Block eth.BlockID
}

type Frame 

type Frame struct {
	ID          ChannelID `json:"id"`
	FrameNumber uint16    `json:"frame_number"`
	Data        []byte    `json:"data"`
	IsLast      bool      `json:"is_last"`
}

func ParseFrames 

func ParseFrames(data []byte) ([]Frame, error)

ParseFrames parse the on chain serialization of frame(s) in an L1 transaction. Currently only version 0 of the serialization format is supported. All frames must be parsed without error and there must not be any left over data and there must be at least one frame.

func (*Frame) MarshalBinary 

func (f *Frame) MarshalBinary(w io.Writer) error

MarshalBinary writes the frame to `w`. It returns any errors encountered while writing, but generally expects the writer very rarely fail.

func (*Frame) UnmarshalBinary 

func (f *Frame) UnmarshalBinary(r ByteReader) error

UnmarshalBinary consumes a full frame from the reader. If `r` fails a read, it returns the error from the reader The reader will be left in a partially read state.

If r doesn't return any bytes, returns io.EOF. If r unexpectedly stops returning data half-way, returns io.ErrUnexpectedEOF.

type FrameQueue 

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

func NewFrameQueue 

func NewFrameQueue(log log.Logger, prev NextDataProvider) *FrameQueue

func (*FrameQueue) NextFrame 

func (fq *FrameQueue) NextFrame(ctx context.Context) (Frame, error)

func (*FrameQueue) Origin 

func (fq *FrameQueue) Origin() eth.L1BlockRef

func (*FrameQueue) Reset 

func (fq *FrameQueue) Reset(_ context.Context, _ eth.L1BlockRef, _ eth.SystemConfig) error

type L1BlockInfo 

type L1BlockInfo struct {
	Number    uint64
	Time      uint64
	BaseFee   *big.Int
	BlockHash common.Hash
	// Not strictly a piece of L1 information. Represents the number of L2 blocks since the start of the epoch,
	// i.e. when the actual L1 info was first introduced.
	SequenceNumber uint64
	// BatcherHash version 0 is just the address with 0 padding to the left.
	BatcherAddr           common.Address
	L1FeeOverhead         eth.Bytes32
	L1FeeScalar           eth.Bytes32
	ValidatorRewardScalar eth.Bytes32
}

L1BlockInfo presents the information stored in a L1Block.setL1BlockValues call

func L1InfoDepositTxData 

func L1InfoDepositTxData(data []byte) (L1BlockInfo, error)

L1InfoDepositTxData is the inverse of L1InfoDeposit, to see where the L2 chain is derived from

func (*L1BlockInfo) MarshalBinary 

func (info *L1BlockInfo) MarshalBinary() ([]byte, error)

func (*L1BlockInfo) UnmarshalBinary 

func (info *L1BlockInfo) UnmarshalBinary(data []byte) error

type L1BlockRefByHashFetcher 

type L1BlockRefByHashFetcher interface {
	L1BlockRefByHash(context.Context, common.Hash) (eth.L1BlockRef, error)
}

type L1BlockRefByNumberFetcher 

type L1BlockRefByNumberFetcher interface {
	L1BlockRefByNumber(context.Context, uint64) (eth.L1BlockRef, error)
	FetchReceipts(ctx context.Context, blockHash common.Hash) (eth.BlockInfo, types.Receipts, error)
}

type L1Fetcher 

type L1Fetcher interface {
	L1BlockRefByLabel(ctx context.Context, label eth.BlockLabel) (eth.L1BlockRef, error)
	L1BlockRefByNumberFetcher
	L1BlockRefByHashFetcher
	L1ReceiptsFetcher
	L1TransactionFetcher
}

type L1InfoDepositSource 

type L1InfoDepositSource struct {
	L1BlockHash common.Hash
	SeqNumber   uint64
}

func (*L1InfoDepositSource) SourceHash 

func (dep *L1InfoDepositSource) SourceHash() common.Hash

type L1ReceiptsFetcher 

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

L1ReceiptsFetcher fetches L1 header info and receipts for the payload attributes derivation (the info tx and deposits)

type L1Retrieval 

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

func NewL1Retrieval 

func NewL1Retrieval(log log.Logger, dataSrc DataAvailabilitySource, prev NextBlockProvider) *L1Retrieval

func (*L1Retrieval) NextData 

func (l1r *L1Retrieval) NextData(ctx context.Context) ([]byte, error)

NextData does an action in the L1 Retrieval stage If there is data, it pushes it to the next stage. If there is no more data open ourselves if we are closed or close ourselves if we are open

func (*L1Retrieval) Origin 

func (l1r *L1Retrieval) Origin() eth.L1BlockRef

func (*L1Retrieval) Reset 

func (l1r *L1Retrieval) Reset(ctx context.Context, base eth.L1BlockRef, sysCfg eth.SystemConfig) error

Reset re-initializes the L1 Retrieval stage to block of it's `next` progress. Note that we open up the `l1r.datas` here because it is requires to maintain the internal invariants that later propagate up the derivation pipeline.

type L1TransactionFetcher 

type L1TransactionFetcher interface {
	InfoAndTxsByHash(ctx context.Context, hash common.Hash) (eth.BlockInfo, types.Transactions, error)
}

type L1Traversal 

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

func NewL1Traversal 

func NewL1Traversal(log log.Logger, cfg *rollup.Config, l1Blocks L1BlockRefByNumberFetcher) *L1Traversal

func (*L1Traversal) AdvanceL1Block 

func (l1t *L1Traversal) AdvanceL1Block(ctx context.Context) error

AdvanceL1Block advances the internal state of L1 Traversal

func (*L1Traversal) NextL1Block 

func (l1t *L1Traversal) NextL1Block(_ context.Context) (eth.L1BlockRef, error)

NextL1Block returns the next block. It does not advance, but it can only be called once before returning io.EOF

func (*L1Traversal) Origin 

func (l1t *L1Traversal) Origin() eth.L1BlockRef

func (*L1Traversal) Reset 

func (l1t *L1Traversal) Reset(ctx context.Context, base eth.L1BlockRef, cfg eth.SystemConfig) error

Reset sets the internal L1 block to the supplied base. Note that the next call to `NextL1Block` will return the block after `base` TODO: Walk one back/figure this out.

func (*L1Traversal) SystemConfig 

func (l1c *L1Traversal) SystemConfig() eth.SystemConfig

type L2BlockRefSource 

type L2BlockRefSource interface {
	Hash() common.Hash
	ParentHash() common.Hash
	NumberU64() uint64
	Time() uint64
	Transactions() types.Transactions
}

L2BlockRefSource is a source for the generation of a L2BlockRef. E.g. a *types.Block is a L2BlockRefSource.

L2BlockToBlockRef extracts L2BlockRef from a L2BlockRefSource. The first transaction of a source must be a Deposit transaction.

type Level 

type Level uint

Level is the severity level of the error. 

const (
	// LevelTemporary is a temporary error for example due to an RPC or
	// connection issue, and can be safely ignored and retried by the caller
	LevelTemporary Level = iota
	// LevelReset is a pipeline reset error. It must be treated like a reorg.
	LevelReset
	// LevelCritical is a critical error.
	LevelCritical
)

There are three levels currently, out of which only 2 are being used to classify error by severity. LevelTemporary

func (Level) String 

func (lvl Level) String() string

type Metrics 

type Metrics interface {
	RecordL1Ref(name string, ref eth.L1BlockRef)
	RecordL2Ref(name string, ref eth.L2BlockRef)
	RecordUnsafePayloadsBuffer(length uint64, memSize uint64, next eth.BlockID)
	RecordChannelInputBytes(inputCompressedBytes int)
}

type NextAttributesProvider 

type NextAttributesProvider interface {
	Origin() eth.L1BlockRef
	NextAttributes(context.Context, eth.L2BlockRef) (*eth.PayloadAttributes, error)
}

type NextBatchProvider 

type NextBatchProvider interface {
	Origin() eth.L1BlockRef
	NextBatch(ctx context.Context) (*BatchData, error)
}

type NextBlockProvider 

type NextBlockProvider interface {
	NextL1Block(context.Context) (eth.L1BlockRef, error)
	Origin() eth.L1BlockRef
	SystemConfig() eth.SystemConfig
}

type NextDataProvider 

type NextDataProvider interface {
	NextData(context.Context) ([]byte, error)
	Origin() eth.L1BlockRef
}

type NextFrameProvider 

type NextFrameProvider interface {
	NextFrame(ctx context.Context) (Frame, error)
	Origin() eth.L1BlockRef
}

type PayloadsQueue 

type PayloadsQueue struct {
	MaxSize uint64

	SizeFn func(p *eth.ExecutionPayload) uint64
	// contains filtered or unexported fields
}

PayloadsQueue buffers payloads by block number. PayloadsQueue is not safe to use concurrently. PayloadsQueue exposes typed Push/Peek/Pop methods to use the queue, without the need to use heap.Push/heap.Pop as caller. PayloadsQueue maintains a MaxSize by counting and tracking sizes of added eth.ExecutionPayload entries. When the size grows too large, the first (lowest block-number) payload is removed from the queue. PayloadsQueue allows entries with same block number, but does not allow duplicate blocks

func NewPayloadsQueue 

func NewPayloadsQueue(maxSize uint64, sizeFn func(p *eth.ExecutionPayload) uint64) *PayloadsQueue

func (*PayloadsQueue) Len 

func (upq *PayloadsQueue) Len() int

func (*PayloadsQueue) MemSize 

func (upq *PayloadsQueue) MemSize() uint64

func (*PayloadsQueue) Peek 

func (upq *PayloadsQueue) Peek() *eth.ExecutionPayload

Peek retrieves the payload with the lowest block number from the queue in O(1), or nil if the queue is empty.

func (*PayloadsQueue) Pop 

func (upq *PayloadsQueue) Pop() *eth.ExecutionPayload

Pop removes the payload with the lowest block number from the queue in O(log(N)), and may return nil if the queue is empty.

func (*PayloadsQueue) Push 

func (upq *PayloadsQueue) Push(p *eth.ExecutionPayload) error

Push adds the payload to the queue, in O(log(N)).

Don't DoS ourselves by buffering too many unsafe payloads. If the queue size after pushing exceed the allowed memory, then pop payloads until memory is not exceeding anymore.

We prefer higher block numbers over lower block numbers, since lower block numbers are more likely to be conflicts and/or read from L1 sooner. The higher payload block numbers can be preserved, and once L1 contents meets these, they can all be processed in order.

type ResetableStage 

type ResetableStage interface {
	// Reset resets a pull stage. `base` refers to the L1 Block Reference to reset to, with corresponding configuration.
	Reset(ctx context.Context, base eth.L1BlockRef, baseCfg eth.SystemConfig) error
}

type ResettableEngineControl 

type ResettableEngineControl interface {
	EngineControl
	Reset()
}

ResettableEngineControl wraps EngineControl with reset-functionality, which handles reorgs like the derivation pipeline: by determining the last valid block references to continue from.

type SystemConfigL2Fetcher 

type SystemConfigL2Fetcher interface {
	SystemConfigByL2Hash(ctx context.Context, hash common.Hash) (eth.SystemConfig, error)
}

type UserDepositSource 

type UserDepositSource struct {
	L1BlockHash common.Hash
	LogIndex    uint64
}

func (*UserDepositSource) SourceHash 

func (dep *UserDepositSource) SourceHash() common.Hash

Source Files

View all Source files

Directories

Path Synopsis

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.