sequencer

package
v0.0.0-...-4611198 Latest Latest
Warning

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

Go to latest
Published: May 12, 2023 License: MIT Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// TxLenSize is the number of bytes used to represent the size of a
	// serialized sequencer transaction.
	TxLenSize = 3
)

Variables

View Source
var (
	// ErrBlockWithInvalidContext signals an attempt to generate a
	// BatchContext that specifies a total of zero txs.
	ErrBlockWithInvalidContext = errors.New("attempted to generate batch " +
		"context with 0 queued and 0 sequenced txs")
)
View Source
var (

	// ErrMalformedBatch represents a batch that is not well formed
	// according to the protocol specification
	ErrMalformedBatch = errors.New("malformed batch")
)

Functions

This section is empty.

Types

type AppendSequencerBatchParams

type AppendSequencerBatchParams struct {
	// ShouldStartAtElement specifies the intended starting sequence number
	// of the provided transaction. Upon submission, this should match the
	// CTC's expected value otherwise the transaction will revert.
	ShouldStartAtElement uint64

	// TotalElementsToAppend indicates the number of L2 txs represented by
	// this batch. This includes both sequencer and queued txs.
	TotalElementsToAppend uint64

	// Contexts aggregates redundant L1 block numbers and L1 timestamps for
	// the txns encoded in the Tx slice. Further, they specify consecutive
	// tx windows in Txs and implicitly allow one to compute how many
	// (omitted) queued txs are in a given window.
	Contexts []BatchContext

	// Txs contains all sequencer txs that will be recorded in the L1 CTC
	// contract.
	Txs []*CachedTx
}

AppendSequencerBatchParams holds the raw data required to submit a batch of L2 txs to L1 CTC contract. Rather than encoding the objects using the standard ABI encoding, a custom encoding is and provided in the call data to optimize for gas fees, since batch submission of L2 txs is a primary cost driver.

func GenSequencerBatchParams

func GenSequencerBatchParams(
	shouldStartAtElement uint64,
	blockOffset uint64,
	batch []BatchElement,
) (*AppendSequencerBatchParams, error)

GenSequencerBatchParams generates a valid AppendSequencerBatchParams from a list of BatchElements. The BatchElements are assumed to be ordered in ascending order by L2 block height.

func (*AppendSequencerBatchParams) Read

Read decodes the AppendSequencerBatchParams from a bytes stream. If the byte stream does not terminate cleanly with an EOF while reading a tx_len, this method will return an error. Otherwise, the stream will be parsed according to the following format:

  • should_start_at_element: 5 bytes
  • total_elements_to_append: 3 bytes
  • num_contexts: 3 bytes
  • num_contexts * batch_context: num_contexts * 16 bytes
  • [num txs omitted]
  • tx_len: 3 bytes
  • tx_bytes: tx_len bytes

func (*AppendSequencerBatchParams) Serialize

func (p *AppendSequencerBatchParams) Serialize(
	batchType BatchType,
) ([]byte, error)

Serialize performs the same encoding as Write, but returns the resulting bytes slice.

func (*AppendSequencerBatchParams) Write

func (p *AppendSequencerBatchParams) Write(
	w *bytes.Buffer,
	batchType BatchType,
) error

Write encodes the AppendSequencerBatchParams using the following format:

  • should_start_at_element: 5 bytes
  • total_elements_to_append: 3 bytes
  • num_contexts: 3 bytes
  • num_contexts * batch_context: num_contexts * 16 bytes
  • [num txs omitted]
  • tx_len: 3 bytes
  • tx_bytes: tx_len bytes

Typed batches include a dummy context as the first context where the timestamp is 0. The blocknumber is interpreted as an enum that defines the type. It is impossible to have a timestamp of 0 in practice, so this safely can indicate that the batch is typed. Type 0 batches have a dummy context where the blocknumber is set to 0. The transaction data is compressed with zlib before submitting the transaction to the chain. The fields should_start_at_element, total_elements_to_append, num_contexts and the contexts themselves are not altered.

Note that writing to a bytes.Buffer cannot error, so errors are ignored here

type BatchContext

type BatchContext struct {
	// NumSequencedTxs specifies the number of sequencer txs included in
	// the batch.
	NumSequencedTxs uint64 `json:"num_sequenced_txs"`

	// NumSubsequentQueueTxs specifies the number of queued txs included in
	// the batch
	NumSubsequentQueueTxs uint64 `json:"num_subsequent_queue_txs"`

	// Timestamp is the L1 timestamp of the batch.
	Timestamp uint64 `json:"timestamp"`

	// BlockNumber is the L1 BlockNumber of the batch.
	BlockNumber uint64 `json:"block_number"`
}

BatchContext denotes a range of transactions that belong the same batch. It is used to compress shared fields that would otherwise be repeated for each transaction.

func (BatchContext) IsMarkerContext

func (c BatchContext) IsMarkerContext() bool

IsMarkerContext returns true if the BatchContext is a marker context used to specify the encoding format. This is only valid if called on the first BatchContext in the calldata.

func (BatchContext) MarkerBatchType

func (c BatchContext) MarkerBatchType() BatchType

MarkerBatchType returns the BatchType specified by a marker BatchContext. The return value is only valid if called on the first BatchContext in the calldata and IsMarkerContext returns true.

func (*BatchContext) Read

func (c *BatchContext) Read(r io.Reader) error

Read decodes the BatchContext from the passed reader. If fewer than 16-bytes remain, an error is returned. Otherwise the first 16-bytes will be read using the expected encoding:

  • num_sequenced_txs: 3 bytes
  • num_subsequent_queue_txs: 3 bytes
  • timestamp: 5 bytes
  • block_number: 5 bytes

func (*BatchContext) Write

func (c *BatchContext) Write(w *bytes.Buffer)

Write encodes the BatchContext into a 16-byte stream using the following encoding:

  • num_sequenced_txs: 3 bytes
  • num_subsequent_queue_txs: 3 bytes
  • timestamp: 5 bytes
  • block_number: 5 bytes

Note that writing to a bytes.Buffer cannot error, so errors are ignored here

type BatchElement

type BatchElement struct {
	// Timestamp is the L1 timestamp of the batch.
	Timestamp uint64

	// BlockNumber is the L1 BlockNumber of the batch.
	BlockNumber uint64

	// Tx is the optional transaction that was applied in this batch.
	//
	// NOTE: This field will only be populated for sequencer txs.
	Tx *CachedTx
}

BatchElement reflects the contents of an atomic update to the L2 state. Currently, each BatchElement is constructed from a single block containing exactly one tx.

func BatchElementFromBlock

func BatchElementFromBlock(block *l2types.Block) BatchElement

BatchElementFromBlock constructs a BatchElement from a single L2 block. This method expects that there is exactly ONE tx per block. The returned BatchElement will reflect whether or not the lone tx is a sequencer tx or a queued tx.

func (*BatchElement) IsSequencerTx

func (b *BatchElement) IsSequencerTx() bool

IsSequencerTx returns true if this batch contains a tx that needs to be posted to the L1 CTC contract.

type BatchType

type BatchType int8

BatchType represents the type of batch being submitted. When the first context in the batch has a timestamp of 0, the blocknumber is interpreted as an enum that represets the type.

const (
	// BatchTypeLegacy represets the legacy batch type.
	BatchTypeLegacy BatchType = -1

	// BatchTypeZlib represents a batch type where the transaction data is
	// compressed using zlib.
	BatchTypeZlib BatchType = 0
)

func BatchTypeFromString

func BatchTypeFromString(s string) BatchType

BatchTypeFromString returns the BatchType enum based on a human readable string.

func (BatchType) MarkerContext

func (b BatchType) MarkerContext() *BatchContext

MarkerContext returns the marker context, if any, for the given batch type.

func (BatchType) String

func (b BatchType) String() string

String implements the Stringer interface for BatchType.

type CachedTx

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

func NewCachedTx

func NewCachedTx(tx *l2types.Transaction) *CachedTx

func (*CachedTx) RawTx

func (t *CachedTx) RawTx() []byte

func (*CachedTx) Size

func (t *CachedTx) Size() int

func (*CachedTx) Tx

func (t *CachedTx) Tx() *l2types.Transaction

type Config

type Config struct {
	Name                  string
	L1Client              *ethclient.Client
	L2Client              *l2ethclient.Client
	BlockOffset           uint64
	MinTxSize             uint64
	MaxTxSize             uint64
	MaxPlaintextBatchSize uint64
	CTCAddr               common.Address
	ChainID               *big.Int
	PrivKey               *ecdsa.PrivateKey
	BatchType             BatchType
}

type Driver

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

func NewDriver

func NewDriver(cfg Config) (*Driver, error)

func (*Driver) ClearPendingTx

func (d *Driver) ClearPendingTx(
	ctx context.Context,
	txMgr txmgr.TxManager,
	l1Client *ethclient.Client,
) error

ClearPendingTx a publishes a transaction at the next available nonce in order to clear any transactions in the mempool left over from a prior running instance of the batch submitter.

func (*Driver) CraftBatchTx

func (d *Driver) CraftBatchTx(
	ctx context.Context,
	start, end, nonce *big.Int,
) (*types.Transaction, error)

CraftBatchTx transforms the L2 blocks between start and end into a batch transaction using the given nonce. A dummy gas price is used in the resulting transaction to use for size estimation. A nil transaction is returned if the transaction does not meet the minimum size requirements.

NOTE: This method SHOULD NOT publish the resulting transaction.

func (*Driver) GetBatchBlockRange

func (d *Driver) GetBatchBlockRange(
	ctx context.Context) (*big.Int, *big.Int, error)

GetBatchBlockRange returns the start and end L2 block heights that need to be processed. Note that the end value is *exclusive*, therefore if the returned values are identical nothing needs to be processed.

func (*Driver) Metrics

func (d *Driver) Metrics() metrics.Metrics

Metrics returns the subservice telemetry object.

func (*Driver) Name

func (d *Driver) Name() string

Name is an identifier used to prefix logs for a particular service.

func (*Driver) SendTransaction

func (d *Driver) SendTransaction(
	ctx context.Context,
	tx *types.Transaction,
) error

SendTransaction injects a signed transaction into the pending pool for execution.

func (*Driver) UpdateGasPrice

func (d *Driver) UpdateGasPrice(
	ctx context.Context,
	tx *types.Transaction,
) (*types.Transaction, error)

UpdateGasPrice signs an otherwise identical txn to the one provided but with updated gas prices sampled from the existing network conditions.

NOTE: Thie method SHOULD NOT publish the resulting transaction.

func (*Driver) WalletAddr

func (d *Driver) WalletAddr() common.Address

WalletAddr is the wallet address used to pay for batch transaction fees.

type Metrics

type Metrics struct {
	*metrics.Base

	// BatchPruneCount tracks the number of times a batch of sequencer
	// transactions is pruned in order to meet the desired size requirements.
	BatchPruneCount prometheus.Gauge
}

Metrics extends the BSS core metrics with additional metrics tracked by the sequencer driver.

func NewMetrics

func NewMetrics(subsystem string) *Metrics

NewMetrics initializes a new, extended metrics object.

Jump to

Keyboard shortcuts

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