Struct SpanBatch

pub struct SpanBatch {
    pub parent_check: FixedBytes<20>,
    pub l1_origin_check: FixedBytes<20>,
    pub genesis_timestamp: u64,
    pub chain_id: u64,
    pub batches: Vec<SpanBatchElement>,
    pub origin_bits: SpanBatchBits,
    pub block_tx_counts: Vec<u64>,
    pub txs: SpanBatchTransactions,
}

Container for the inputs required to build a span of L2 blocks in derived form.

A SpanBatch represents a compressed format for multiple L2 blocks that enables significant space savings compared to individual single batches. The format uses differential encoding, bit packing, and shared data structures to minimize the L1 footprint while maintaining all necessary information for L2 block reconstruction.

Compression Techniques

Temporal Compression

• Relative timestamps: Store timestamps relative to genesis to reduce size
• Differential encoding: Encode changes between consecutive blocks
• Epoch sharing: Multiple blocks can share the same L1 origin

Spatial Compression

• Shared prefixes: Common data shared across all blocks in span
• Transaction batching: Transactions grouped and compressed together
• Bit packing: Use minimal bits for frequently-used fields

Format Structure

SpanBatch {
  prefix: {
    rel_timestamp,     // Relative to genesis
    l1_origin_num,     // Final L1 block number  
    parent_check,      // First 20 bytes of parent hash
    l1_origin_check,   // First 20 bytes of L1 origin hash
  },
  payload: {
    block_count,       // Number of blocks in span
    origin_bits,       // Bit array indicating L1 origin changes
    block_tx_counts,   // Transaction count per block
    txs,              // Compressed transaction data
  }
}

Validation and Integrity

The span batch format includes several integrity checks:

• Parent check: Validates continuity with previous span
• L1 origin check: Ensures proper L1 origin binding
• Transaction count validation: Verifies transaction distribution
• Bit field consistency: Ensures origin bits match block count

Fields

parent_check: FixedBytes<20>

First 20 bytes of the parent hash of the first block in the span.

This field provides a collision-resistant check to ensure the span batch builds properly on the expected parent block. Using only 20 bytes saves space while maintaining strong integrity guarantees.

l1_origin_check: FixedBytes<20>

First 20 bytes of the L1 origin hash of the last block in the span.

This field enables validation that the span batch references the correct L1 origin block, ensuring proper derivation ordering and preventing replay attacks across different L1 contexts.

genesis_timestamp: u64

Genesis block timestamp for relative timestamp calculations.

All timestamps in the span batch are stored relative to this genesis timestamp to minimize storage requirements. This enables efficient timestamp compression while maintaining full precision.

chain_id: u64

Chain ID for transaction validation and network identification.

Required for proper transaction signature validation and to prevent cross-chain replay attacks. All transactions in the span must be valid for this chain ID.

batches: Vec<SpanBatchElement>

Ordered list of block elements contained in this span.

Each element represents the derived data for one L2 block, including timestamp, epoch information, and transaction references. The order must match the intended L2 block sequence.

origin_bits: SpanBatchBits

Cached bit array indicating L1 origin changes between consecutive blocks.

This compressed representation allows efficient encoding of which blocks in the span advance to a new L1 origin. Bit i is set if block i+1 has a different L1 origin than block i.

block_tx_counts: Vec<u64>

Cached transaction count for each block in the span.

Pre-computed transaction counts enable efficient random access to transactions for specific blocks without scanning the entire transaction list. Index i contains the transaction count for block i.

txs: SpanBatchTransactions

Cached compressed transaction data for all blocks in the span.

Contains all transactions from all blocks in a compressed format that enables efficient encoding and decoding. Transactions are grouped and compressed using span-specific techniques.

Implementations

impl SpanBatch

pub fn starting_timestamp(&self) -> u64

Returns the starting timestamp for the first batch in the span.

This is the absolute timestamp (not relative to genesis) of the first block in the span batch. Used for validation and block sequencing.

Panics

Panics if the span batch contains no elements (batches is empty). This should never happen in valid span batches as they must contain at least one block.

Usage

Typically used during span batch validation to ensure proper temporal ordering with respect to the parent block and L1 derivation window.

pub fn final_timestamp(&self) -> u64

Returns the final timestamp for the last batch in the span.

This is the absolute timestamp (not relative to genesis) of the last block in the span batch. Used for validation and determining the span’s temporal range.

Panics

Panics if the span batch contains no elements (batches is empty). This should never happen in valid span batches as they must contain at least one block.

Usage

Used during validation to ensure the span doesn’t exceed maximum temporal ranges and fits within L1 derivation windows.

pub fn starting_epoch_num(&self) -> u64

Returns the L1 epoch number for the first batch in the span.

The epoch number corresponds to the L1 block number that serves as the L1 origin for the first L2 block in this span. This establishes the L1 derivation context for the span.

Panics

Panics if the span batch contains no elements (batches is empty). This should never happen in valid span batches as they must contain at least one block.

Usage

Used during validation to ensure proper L1 origin sequencing and that the span begins with the expected L1 context.

pub fn check_origin_hash(&self, hash: FixedBytes<32>) -> bool

Validates that the L1 origin hash matches the span’s L1 origin check.

Compares the first 20 bytes of the provided hash against the stored l1_origin_check field. This provides a collision-resistant validation that the span batch was derived from the expected L1 context.

Arguments

• hash - The full 32-byte L1 origin hash to validate

Returns

• true - If the first 20 bytes match the span’s L1 origin check
• false - If there’s a mismatch, indicating invalid L1 context

Algorithm

l1_origin_check[0..20] == hash[0..20]

Using only 20 bytes provides strong collision resistance (2^160 space) while saving 12 bytes per span compared to storing full hashes.

pub fn check_parent_hash(&self, hash: FixedBytes<32>) -> bool

Validates that the parent hash matches the span’s parent check.

Compares the first 20 bytes of the provided hash against the stored parent_check field. This ensures the span batch builds on the expected parent block, maintaining chain continuity.

Arguments

• hash - The full 32-byte parent hash to validate

Returns

• true - If the first 20 bytes match the span’s parent check
• false - If there’s a mismatch, indicating discontinuity

Algorithm

parent_check[0..20] == hash[0..20]

This validation is critical for maintaining the integrity of the L2 chain and preventing insertion of span batches in wrong locations.

pub fn to_raw_span_batch(&self) -> Result<RawSpanBatch, SpanBatchError>

Converts this span batch to its raw serializable format.

Transforms the derived span batch into a RawSpanBatch that can be serialized and transmitted over the network. This involves organizing the cached data into the proper prefix and payload structure.

Returns

• Ok(RawSpanBatch) - Successfully converted raw span batch
• Err(SpanBatchError) - Conversion failed, typically due to empty batch

Errors

Returns SpanBatchError::EmptySpanBatch if the span contains no blocks, which is invalid as span batches must contain at least one block.

Algorithm

The conversion process:

1. Validation: Ensure the span is not empty
2. Prefix Construction: Build prefix with temporal and origin data
3. Payload Assembly: Package cached data into payload structure
4. Relative Timestamp Calculation: Convert absolute to relative timestamp

The relative timestamp is calculated as:

rel_timestamp = first_block_timestamp - genesis_timestamp

This enables efficient timestamp encoding in the serialized format.

pub fn get_singular_batches( &self, l1_origins: &[BlockInfo], l2_safe_head: L2BlockInfo, ) -> Result<Vec<SingleBatch>, SpanBatchError>

Converts all SpanBatchElements after the L2 safe head to SingleBatches. The resulting SingleBatches do not contain a parent hash, as it is populated by the Batch Queue stage.

pub fn append_singular_batch( &mut self, singular_batch: SingleBatch, seq_num: u64, ) -> Result<(), SpanBatchError>

Append a SingleBatch to the SpanBatch. Updates the L1 origin check if need be.

pub async fn check_batch<BV: BatchValidationProvider>( &self, cfg: &RollupConfig, l1_blocks: &[BlockInfo], l2_safe_head: L2BlockInfo, inclusion_block: &BlockInfo, fetcher: &mut BV, ) -> BatchValidity

Checks if the span batch is valid.

pub async fn check_batch_prefix<BF: BatchValidationProvider>( &self, cfg: &RollupConfig, l1_origins: &[BlockInfo], l2_safe_head: L2BlockInfo, inclusion_block: &BlockInfo, fetcher: &mut BF, ) -> (BatchValidity, Option<L2BlockInfo>)

Checks the validity of the batch’s prefix.

This function is used for post-Holocene hardfork to perform batch validation as each batch is being loaded in.

Trait Implementations

impl Clone for SpanBatch

fn clone(&self) -> SpanBatch

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SpanBatch

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SpanBatch

fn default() -> SpanBatch

Returns the “default value” for a type.

impl PartialEq for SpanBatch

fn eq(&self, other: &SpanBatch) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for SpanBatch

impl StructuralPartialEq for SpanBatch