Crate dig_block 

dig-block — DIG L2 block format, production, and validation

dig-block is a self-contained Rust library for the DIG Network L2 blockchain. It owns three concerns in one crate:

1. Block format — type definitions for L2BlockHeader, L2Block, AttestedBlock, Checkpoint, CheckpointSubmission, and supporting types (SPEC §2).
2. Block production — BlockBuilder and CheckpointBuilder construct structurally valid blocks and epoch summaries from their inputs (SPEC §6).
3. Block validation — a three-tier pipeline (structural / execution / state) rejects any block that does not match consensus rules (SPEC §5, §7).

Scope

The crate operates on single, isolated blocks. External state (coin existence, chain tip, wall-clock time, validator set) is injected through two traits:

• CoinLookup — coin-set queries for Tier-3 state validation.
• BlockSigner — proposer signing hook for block production.

dig-block never reads from a database, never makes network calls, and never maintains state across blocks (SPEC §11). Downstream crates (dig-coinstore, dig-epoch, dig-gossip) provide the trait implementations, storage, chain management, and networking.

Quickstart — build a block

use dig_block::{BlockBuilder, BlockSigner, Bytes32, Signature};
use dig_block::traits::SignerError;

// 1. Implement BlockSigner for your key material (or use a test mock).
struct MySigner;
impl BlockSigner for MySigner {
    fn sign_block(&self, _header_hash: &Bytes32) -> Result<Signature, SignerError> {
        Ok(Signature::default())
    }
}

// 2. Construct a builder anchored to the chain / L1 context.
let parent_hash = Bytes32::default();
let l1_hash = Bytes32::default();
let mut builder = BlockBuilder::new(/*height=*/ 1, /*epoch=*/ 0, parent_hash, 100, l1_hash, 0);

// 3. (Optional) add spend bundles via builder.add_spend_bundle(...).
// 4. Build a signed L2Block.
let state_root = Bytes32::default();
let receipts_root = Bytes32::default();
let block = builder.build(state_root, receipts_root, &MySigner).expect("build");

Quickstart — validate a block

use dig_block::{CoinLookup, L2Block, PublicKey};
use chia_protocol::{Bytes32, CoinState};
use dig_clvm::ValidationConfig;

struct MyCoinLookup;
impl CoinLookup for MyCoinLookup {
    fn get_coin_state(&self, _id: &Bytes32) -> Option<CoinState> { None }
    fn get_chain_height(&self) -> u64 { 0 }
    fn get_chain_timestamp(&self) -> u64 { 0 }
}

fn validate(block: &L2Block, pk: &PublicKey) -> Result<Bytes32, dig_block::BlockError> {
    let config = ValidationConfig::default();
    let genesis = Bytes32::default();
    // Runs Tier 1 (structural) → Tier 2 (execution) → Tier 3 (state) and returns the
    // computed state root on success.
    block.validate_full(&config, &genesis, &MyCoinLookup, pk)
}

Module map

Module	SPEC section	Purpose
primitives	§2.1	Bytes32, Cost, Signature, PublicKey, version tags
constants	§2.11	EMPTY_ROOT, MAX_BLOCK_SIZE, MAX_COST_PER_BLOCK, etc.
types	§2.2–§2.10	L2BlockHeader, L2Block, AttestedBlock, checkpoint types, Receipt, SignerBitmap, status enums
error	§4	BlockError, CheckpointError, BuilderError, SignerBitmapError, ReceiptError
hash	§3.3	hash_leaf, hash_node (0x01/0x02 domain separation)
traits	§7.2	CoinLookup, BlockSigner
builder	§6	BlockBuilder, CheckpointBuilder
validation	§5, §7	Structural (Tier 1), Execution (Tier 2), State (Tier 3)

Public API

All protocol types and helpers are re-exported at the crate root (SPEC §10). For convenience, prelude re-exports the most common items as a glob.

use dig_block::prelude::*;

Dependencies

dig-block reuses the Chia Rust ecosystem and does not reimplement CLVM, BLS, or Merkle primitives (SPEC §1.2):

Concern	Crate
Core protocol types (Bytes32, Coin, SpendBundle, CoinSpend, CoinState)	chia-protocol
BLS12-381 signatures (Signature, PublicKey, verify)	chia-bls
CLVM execution + condition parsing	dig-clvm (wraps chia-consensus)
Merkle set roots (additions, removals)	chia-consensus::compute_merkle_set_root
Binary Merkle trees (spends, receipts, slash proposals)	chia-sdk-types::MerkleTree
SHA-256	chia-sha2
CLVM tree hashing	clvm-utils::tree_hash
Bincode serialization	bincode + serde
BIP-158 compact block filter	bitcoin::bip158

CLVM execution is always routed through dig_clvm::validate_spend_bundle; dig-block never calls chia-consensus::run_spendbundle directly (EXE-003 enforced by a grep-based architectural lint in tests/test_exe_003_clvm_delegation.rs).

Re-exports

pub use types::attested::AttestedBlock;

pub use types::block::L2Block;

pub use types::checkpoint::Checkpoint;

pub use types::checkpoint::CheckpointSubmission;

pub use types::header::L2BlockHeader;

pub use types::receipt::Receipt;

pub use types::receipt::ReceiptList;

pub use types::receipt::ReceiptStatus;

pub use types::signer_bitmap::SignerBitmap;

pub use types::signer_bitmap::MAX_VALIDATORS;

pub use types::status::BlockStatus;

pub use types::status::CheckpointStatus;

pub use error::BlockError;

pub use error::BuilderError;

pub use error::CheckpointError;

pub use error::ReceiptError;

pub use error::SignerBitmapError;

pub use primitives::Cost;

pub use primitives::VERSION_V1;

pub use primitives::VERSION_V2;

pub use hash::hash_leaf;

pub use hash::hash_node;

pub use types::receipt::compute_receipts_root;

pub use traits::BlockSigner;

pub use traits::CoinLookup;

pub use builder::block_builder::BlockBuilder;

pub use builder::checkpoint_builder::CheckpointBuilder;

pub use validation::execution::collect_pending_assertions_from_conditions;

pub use validation::execution::compute_state_root_from_delta;

pub use validation::execution::map_clvm_validation_error;

pub use validation::execution::verify_coin_spend_puzzle_hash;

pub use validation::execution::AssertionKind;

pub use validation::execution::ExecutionResult;

pub use validation::execution::PendingAssertion;

pub use constants::*;

Modules

builder

Block and checkpoint construction (SPEC §6).

constants

Protocol-wide limits and sentinel values for the DIG L2 block format.

error

Error enums for dig-block.

hash

Tagged Merkle hashing for binary Merkle trees (HSH-007).

prelude

Common imports for dig-block consumers.

primitives

Fundamental type aliases, protocol version tags, and Chia type re-exports (BLK-006).

traits

External integration traits: CoinLookup and BlockSigner.

types

Block, checkpoint, and supporting type definitions (SPEC §2).

validation

Three-tier block validation pipeline (SPEC §5, §7).

Structs

PublicKey

Signature

Functions

compact_block_filter_encoded

BIP-158 encoded filter bytes (Golomb–Rice GCS) for block light-client filtering (HSH-006).

compute_additions_root

additions_root (header field, SPEC §3.4) — Merkle-set root over created coins grouped by puzzle_hash.

compute_filter_hash

filter_hash (header field, SPEC §3.6) — SHA-256 over BIP-158 compact filter bytes.

compute_removals_root

removals_root (header field, SPEC §3.5) — Merkle-set root over all spent coin IDs in the block.

compute_spends_root

Spends root (header spends_root, SPEC §3.3) — Merkle root over ordered spend-bundle leaf digests.

Type Aliases

Bytes32