Skip to main content

Module block_builder

dig_block::builder

Module block_builder 

Source
Expand description

BlockBuilder — incremental construction of signed crate::L2Block instances.

§Requirements trace

  • BLD-001 — struct fields and new() constructor.
  • BLD-002 — add_spend_bundle() with cost/size budget enforcement, remaining_cost(), spend_bundle_count().
  • BLD-003 — add_slash_proposal() with count/size limits.
  • BLD-004 — set_l1_proofs(), set_dfsp_roots(), set_extension_data().
  • BLD-005 — build() pipeline: compute all derived fields, sign header.
  • BLD-006 — crate::BlockSigner integration in build() (see tests/test_bld_006_block_signer_integration.rs).
  • BLD-007 — structural validity guarantee: output always passes validate_structure().
  • NORMATIVE — full block production domain.
  • SPEC §6 — block production lifecycle.

§Build pipeline overview (BLD-005)

1. compute spends_root        ← MerkleTree(sha256(bundle)) per HSH-003
2. compute additions_root     ← compute_merkle_set_root(grouped by puzzle_hash) per HSH-004
3. compute removals_root      ← compute_merkle_set_root(coin IDs) per HSH-005
4. compute filter_hash        ← SHA-256(BIP158 compact filter) per HSH-006
5. compute slash_proposals_root ← MerkleTree(sha256(payload)) per BLK-004
6. count all items            ← spend_bundle_count, additions_count, removals_count, slash_proposal_count
7. auto-detect version        ← protocol_version_for_height(height) per BLK-007
8. set timestamp              ← current wall-clock time
9. compute block_size         ← two-pass: assemble with size=0, measure, update
10. sign header               ← signer.sign_block(&header_hash) per BLD-006

§Design decisions

  • Consuming build(self): Takes ownership so the builder cannot be reused after producing a block, preventing accidental double-build or stale state.
  • Budget enforcement on add, not build: add_spend_bundle() rejects bundles that would exceed MAX_COST_PER_BLOCK or MAX_BLOCK_SIZE before mutating state (BLD-002). This means a rejected bundle leaves the builder unchanged — callers can try a smaller bundle.
  • State root and receipts_root are parameters to build(): The builder doesn’t maintain coin state, so the caller (proposer layer) must compute these externally and pass them in.

§Status

BLD-001–BLD-007 are implemented: successful BlockBuilder::build / BlockBuilder::build_with_dfsp_activation outputs pass crate::L2Block::validate_structure (BLD-007, tests/test_bld_007_builder_validity_guarantee.rs).

Structs§

BlockBuilder
Incremental accumulator for a single L2 block body and header metadata (SPEC §6.1–6.2, BLD-001).