Struct L2BlockHeader 

pub struct L2BlockHeader {

    pub version: u16,
    pub height: u64,
    pub epoch: u64,
    pub parent_hash: Bytes32,
    pub state_root: Bytes32,
    pub spends_root: Bytes32,
    pub additions_root: Bytes32,
    pub removals_root: Bytes32,
    pub receipts_root: Bytes32,
    pub l1_height: u32,
    pub l1_hash: Bytes32,
    pub timestamp: u64,
    pub proposer_index: u32,
    pub spend_bundle_count: u32,
    pub total_cost: Cost,
    pub total_fees: u64,
    pub additions_count: u32,
    pub removals_count: u32,
    pub block_size: u32,
    pub filter_hash: Bytes32,
    pub extension_data: Bytes32,
    pub l1_collateral_coin_id: Option<Bytes32>,
    pub l1_reserve_coin_id: Option<Bytes32>,
    pub l1_prev_epoch_finalizer_coin_id: Option<Bytes32>,
    pub l1_curr_epoch_finalizer_coin_id: Option<Bytes32>,
    pub l1_network_coin_id: Option<Bytes32>,
    pub slash_proposal_count: u32,
    pub slash_proposals_root: Bytes32,
    pub collateral_registry_root: Bytes32,
    pub cid_state_root: Bytes32,
    pub node_registry_root: Bytes32,
    pub namespace_update_root: Bytes32,
    pub dfsp_finalize_commitment_root: Bytes32,
}

DIG L2 block header: identity, Merkle commitments, L1 anchor, metadata, optional L1 proofs, slash proposal commitments, and DFSP data-layer roots.

Field layout and semantics follow SPEC §2.2 table Field groups; keep this definition in sync with that section when the wire format evolves.

Fields

version: u16

Protocol version (VERSION_V1 / VERSION_V2; BLK-007 selects from height).

height: u64

Block height (genesis = 0).

epoch: u64

Epoch number.

parent_hash: Bytes32

Hash of the parent block header.

state_root: Bytes32

CoinSet / state Merkle root after this block.

spends_root: Bytes32

Merkle root of spend-bundle hashes.

additions_root: Bytes32

Merkle root of additions (Chia-style grouping by puzzle_hash).

removals_root: Bytes32

Merkle root of removed coin IDs.

receipts_root: Bytes32

Merkle root of execution receipts.

l1_height: u32

Chia L1 block height this L2 block references.

l1_hash: Bytes32

Chia L1 block hash.

timestamp: u64

Unix timestamp (seconds).

proposer_index: u32

Proposer validator index.

spend_bundle_count: u32

Number of spend bundles in the block body.

total_cost: Cost

Aggregate CLVM cost of all spends in the block.

total_fees: u64

Total fees (value in − value out).

additions_count: u32

Number of coin additions.

removals_count: u32

Number of coin removals.

block_size: u32

Serialized full block size in bytes (header + body).

filter_hash: Bytes32

BIP158-style compact block filter hash.

extension_data: Bytes32

Reserved extension field (SPEC: default ZERO_HASH in constructors).

l1_collateral_coin_id: Option<Bytes32>

Proposer L1 collateral proof coin id.

l1_reserve_coin_id: Option<Bytes32>

Network validator collateral set anchor.

l1_prev_epoch_finalizer_coin_id: Option<Bytes32>

Previous epoch finalization proof.

l1_curr_epoch_finalizer_coin_id: Option<Bytes32>

Current epoch finalizer state.

l1_network_coin_id: Option<Bytes32>

Network singleton existence proof.

slash_proposal_count: u32

Number of slash proposal payloads in the body.

slash_proposals_root: Bytes32

Merkle root over per-proposal hashes.

collateral_registry_root: Bytes32

Collateral registry sparse Merkle root.

cid_state_root: Bytes32

CID lifecycle state machine root.

node_registry_root: Bytes32

Node registry sparse Merkle root.

namespace_update_root: Bytes32

Namespace update delta root for this block.

dfsp_finalize_commitment_root: Bytes32

DFSP epoch-boundary commitment digest.

Implementations

impl L2BlockHeader

pub const HASH_PREIMAGE_LEN: usize = 710

Byte length of the fixed preimage fed to Self::hash (all 33 rows of SPEC §3.1).

Accounting: 20×Bytes32 fields + u16 + 6×u64 + 7×u32 = 640 + 70 = 710 bytes. The SPEC prose once said “626 bytes”; summing the §3.1 table yields 710 — this constant is authoritative for code.

pub fn protocol_version_for_height_with_activation( height: u64, dfsp_activation_height: u64, ) -> u16

Protocol version for height given an explicit DFSP activation height (BLK-007).

Rules: If dfsp_activation_height == u64::MAX (DFSP disabled sentinel), returns VERSION_V1. Otherwise returns VERSION_V2 when height >= dfsp_activation_height, else VERSION_V1.

Rationale: Parameterizing activation height lets tests cover pre/post-fork behavior without recompiling DFSP_ACTIVATION_HEIGHT. Production code should call Self::protocol_version_for_height instead.

pub fn protocol_version_for_height(height: u64) -> u16

Protocol version for height using the crate’s DFSP_ACTIVATION_HEIGHT constant.

pub fn validate_with_dfsp_activation_at_unix( &self, dfsp_activation_height: u64, now_secs: u64, ) -> Result<(), BlockError>

Tier-1 header checks SVL-001 through SVL-004 with an explicit DFSP activation height and a fixed now_secs reference for the timestamp bound (SVL-004).

SVL-001 / SPEC §5.1 Step 1: L2BlockHeader::version must match Self::protocol_version_for_height_with_activation for L2BlockHeader::height and dfsp_activation_height; else BlockError::InvalidVersion.

SVL-002 / SPEC §5.1 Step 2: when height < dfsp_activation_height, all five DFSP roots must equal EMPTY_ROOT; else BlockError::InvalidData (fixed message per SVL-002 spec).

SVL-003 / SPEC §5.1 Steps 3–4: total_cost > MAX_COST_PER_BLOCK ⇒ BlockError::CostExceeded; then block_size > MAX_BLOCK_SIZE ⇒ BlockError::TooLarge (SVL-003 spec).

SVL-004 / SPEC §5.1 Step 5: let max_allowed = now_secs + MAX_FUTURE_TIMESTAMP_SECONDS. If timestamp > max_allowed, reject with BlockError::TimestampTooFarInFuture (Chia block_header_validation.py Check 26a analogue). Strict >: timestamp == max_allowed is accepted.

Usage: Production should call Self::validate or Self::validate_with_dfsp_activation (wall-clock now). Integration tests call this method with a synthetic now_secs so boundary arithmetic is deterministic (SVL-004 spec — Implementation Notes).

pub fn validate_with_dfsp_activation( &self, dfsp_activation_height: u64, ) -> Result<(), BlockError>

Same as Self::validate_with_dfsp_activation_at_unix after sampling the host wall clock (Self::unix_secs_wall_clock).

Rationale: Parameterizing dfsp_activation_height mirrors SVL-001 so integration tests can inject a finite fork height; production uses Self::validate → DFSP_ACTIVATION_HEIGHT. With the BLK-005 sentinel u64::MAX, every finite height satisfies height < u64::MAX, so DFSP payloads cannot appear on-chain until governance lowers the constant.

SVL-004: Uses real SystemTime for now_secs. For deterministic timestamp tests, call Self::validate_with_dfsp_activation_at_unix directly.

pub fn validate(&self) -> Result<(), BlockError>

Tier 1 header structural validation using crate-wide constants (SVL-*).

Current steps: SVL-001 (version), SVL-002 (DFSP roots before activation), SVL-003 (cost/size caps on declared header fields), SVL-004 (timestamp vs wall clock + MAX_FUTURE_TIMESTAMP_SECONDS).

pub fn hash_preimage_bytes(&self) -> [u8; 710]

Serialize the exact 710-byte preimage for HSH-001 / SPEC §3.1 (same order as Self::hash).

Usage: Tests and debug tooling can diff preimages without re-deriving field order; Self::hash is SHA-256(self.hash_preimage_bytes()).

Optionals: Each Option<Bytes32> occupies 32 bytes: ZERO_HASH when None, raw bytes when Some.

pub fn hash(&self) -> Bytes32

Canonical block identity: SHA-256 over Self::hash_preimage_bytes (HSH-001).

Requirement: SPEC §3.1. Numeric fields are little-endian; each optional L1 anchor contributes 32 bytes of raw Bytes32 or ZERO_HASH when None (malleability-safe encoding).

Primitive: chia_sha2::Sha256 only (crate::primitives / project crypto rules).

pub fn to_bytes(&self) -> Vec<u8>

Serialize this header to bincode bytes for wire / storage (SER-002, NORMATIVE § SER-002, SPEC §8.2).

Infallible: Uses Result::expect because an in-memory, well-formed L2BlockHeader should always serialize with the crate’s serde schema; a panic indicates programmer error or schema drift, not recoverable I/O.

pub fn from_bytes(bytes: &[u8]) -> Result<Self, BlockError>

Deserialize a header from bincode bytes (SER-002).

Errors: Any bincode failure maps to BlockError::InvalidData (message includes the decoder error) — covers empty input, truncated payloads, corrupted bytes, and schema mismatches.

pub fn new( height: u64, epoch: u64, parent_hash: Bytes32, state_root: Bytes32, spends_root: Bytes32, additions_root: Bytes32, removals_root: Bytes32, receipts_root: Bytes32, l1_height: u32, l1_hash: Bytes32, proposer_index: u32, spend_bundle_count: u32, total_cost: Cost, total_fees: u64, additions_count: u32, removals_count: u32, block_size: u32, filter_hash: Bytes32, ) -> Self

Standard header constructor (SPEC §2.2 Derived methods / new()).

Sets version via Self::protocol_version_for_height; timestamp to 0 (SPEC omits it from the new parameter list—set explicitly or use Self::genesis / block builder for wall clock); L1 proof anchors to None; slash summary to empty; DFSP roots to EMPTY_ROOT; extension_data to ZERO_HASH.

pub fn new_with_collateral( height: u64, epoch: u64, parent_hash: Bytes32, state_root: Bytes32, spends_root: Bytes32, additions_root: Bytes32, removals_root: Bytes32, receipts_root: Bytes32, l1_height: u32, l1_hash: Bytes32, proposer_index: u32, spend_bundle_count: u32, total_cost: Cost, total_fees: u64, additions_count: u32, removals_count: u32, block_size: u32, filter_hash: Bytes32, l1_collateral_coin_id: Bytes32, ) -> Self

Like Self::new but sets L2BlockHeader::l1_collateral_coin_id to the given proof coin id.

pub fn new_with_l1_proofs( height: u64, epoch: u64, parent_hash: Bytes32, state_root: Bytes32, spends_root: Bytes32, additions_root: Bytes32, removals_root: Bytes32, receipts_root: Bytes32, l1_height: u32, l1_hash: Bytes32, proposer_index: u32, spend_bundle_count: u32, total_cost: Cost, total_fees: u64, additions_count: u32, removals_count: u32, block_size: u32, filter_hash: Bytes32, l1_collateral_coin_id: Bytes32, l1_reserve_coin_id: Bytes32, l1_prev_epoch_finalizer_coin_id: Bytes32, l1_curr_epoch_finalizer_coin_id: Bytes32, l1_network_coin_id: Bytes32, ) -> Self

Full L1 proof anchor set (SPEC field order: collateral, reserve, prev/curr finalizer, network coin).

pub fn genesis(network_id: Bytes32, l1_height: u32, l1_hash: Bytes32) -> Self

Genesis header (SER-003, NORMATIVE § SER-003, SPEC §8.3).

Field obligations

• height / epoch: 0 — chain bootstrap position.
• parent_hash: network_id — there is no prior L2 block; binding the parent slot to the network identity blocks cross-network replay of height-0 material (SER-003 summary).
• Merkle / commitment roots: EMPTY_ROOT for state, spends, additions, removals, receipts, filter, slash proposals, and all DFSP layer roots; ZERO_HASH for extension_data (opaque extension slot starts empty).
• Counts / costs / size: all zero; L1 anchor options: all None; slash count: 0.
• l1_height / l1_hash: caller-supplied L1 observation the genesis L2 header is anchored to.
• version: Self::protocol_version_for_height(0) — same BLK-007 auto-detection as every other constructor (not CARGO_PKG_VERSION; see SER-003 spec errata vs older pseudocode).

timestamp: wall-clock Unix seconds from SystemTime::now. Host clocks before 1970 cannot be represented; we panic with a clear message (same contract as “real” wall time for genesis in SPEC §8.3).

Trait Implementations

impl Clone for L2BlockHeader

fn clone(&self) -> L2BlockHeader

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for L2BlockHeader

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for L2BlockHeader

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for L2BlockHeader

fn eq(&self, other: &L2BlockHeader) -> 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 Serialize for L2BlockHeader

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Streamable for L2BlockHeader

fn update_digest(&self, digest: &mut Sha256)

fn stream(&self, out: &mut Vec<u8>) -> Result<()>

fn parse<const TRUSTED: bool>(input: &mut Cursor<&[u8]>) -> Result<Self>

fn to_bytes(&self) -> Result<Vec<u8>, Error>

fn from_bytes(bytes: &[u8]) -> Result<Self, Error>

where Self: Sized,

fn from_bytes_unchecked(bytes: &[u8]) -> Result<Self, Error>

where Self: Sized,

fn hash(&self) -> [u8; 32]

impl Eq for L2BlockHeader

impl StructuralPartialEq for L2BlockHeader