dig_block/
constants.rs

1//! Protocol-wide limits and sentinel values for the DIG L2 block format.
2//!
3//! **Requirement:** [BLK-005](docs/requirements/domains/block_types/specs/BLK-005.md) /
4//! [NORMATIVE § BLK-005](docs/requirements/domains/block_types/NORMATIVE.md#blk-005-protocol-constants) /
5//! [SPEC §2.11](docs/resources/SPEC.md) (protocol constants).
6//!
7//! **Rationale:** Centralizing these values avoids magic numbers in validation ([`crate::validation`]),
8//! builders ([`crate::builder`]), and hashing ([`crate::hash`]). Limits are chosen to bound worst-case
9//! block work (cost, size) and slash-proposal abuse while staying aligned with mainnet-style CLVM budgets.
10//!
11//! **Types:** Numeric limits use the widths required by BLK-005 (`u32` for byte/count caps, `u64` for
12//! height/timestamp fields). [`Cost`] and [`Bytes32`] are defined in [`crate::primitives`] (BLK-006).
13
14use crate::primitives::{Bytes32, Cost};
15
16/// Digest of the empty byte string, i.e. SHA-256 of `""`.
17///
18/// Used wherever an “empty” Merkle accumulator or trie root must be represented canonically (for example
19/// pre-DFSP roots and empty subtrees). The value is fixed by the protocol; clients must not substitute
20/// [`ZERO_HASH`] for this purpose.
21///
22/// **Proof obligation:** [`tests/test_protocol_constants.rs`](../../tests/test_protocol_constants.rs)
23/// compares this constant to [`chia_sha2::Sha256`] of the empty input so we satisfy BLK-005 without
24/// recomputing at runtime in production code.
25pub const EMPTY_ROOT: Bytes32 = Bytes32::new([
26    0xe3, 0xb0, 0xc4, 0x42, 0x98, 0xfc, 0x1c, 0x14, 0x9a, 0xfb, 0xf4, 0xc8, 0x99, 0x6f, 0xb9, 0x24,
27    0x27, 0xae, 0x41, 0xe4, 0x64, 0x9b, 0x93, 0x4c, 0xa4, 0x95, 0x99, 0x1b, 0x78, 0x52, 0xb8, 0x55,
28]);
29
30/// 32 zero bytes — a distinct sentinel from [`EMPTY_ROOT`].
31///
32/// **Rationale:** Header hashing and optional fields use an all-zero hash to mean “absent” or “zeroed
33/// placeholder” per SPEC; Merkle empty roots must still use [`EMPTY_ROOT`]. Keeping both constants avoids
34/// ambiguous “empty” semantics that would break second-layer verifiers.
35pub const ZERO_HASH: Bytes32 = Bytes32::new([0u8; 32]);
36
37/// Maximum serialized block size in bytes (10 MiB).
38///
39/// Structural validation and [`crate::builder::BlockBuilder`] must reject blocks that would exceed this
40/// size ([`crate::validation::structural`], BLD-002 / SVL-003 in requirements).
41pub const MAX_BLOCK_SIZE: u32 = 10_000_000;
42
43/// CLVM execution budget allowed in a single block.
44///
45/// **Decision:** Typed as [`Cost`] (alias of `u64`) so execution checks share the same unit as bundle
46/// cost fields throughout the stack; see BLK-006 for the full primitive-type surface.
47pub const MAX_COST_PER_BLOCK: Cost = 550_000_000_000;
48
49/// Upper bound on slash-proposal payloads included in one block.
50///
51/// Paired with [`MAX_SLASH_PROPOSAL_PAYLOAD_BYTES`] to cap slash metadata volume (structural validation
52/// and builder paths; see SVL-006 / BLD-003).
53pub const MAX_SLASH_PROPOSALS_PER_BLOCK: u32 = 64;
54
55/// Maximum size of a single slash-proposal payload in bytes (64 KiB).
56pub const MAX_SLASH_PROPOSAL_PAYLOAD_BYTES: u32 = 65_536;
57
58/// Block height at which DFSP (decentralized fraud/slashing protocol) features activate.
59///
60/// **Decision:** Defaults to `u64::MAX` so DFSP is effectively off until governance updates this constant;
61/// [`crate::types::header::L2BlockHeader`] auto-versioning (BLK-007) treats this as “always pre-DFSP” in
62/// the default configuration.
63pub const DFSP_ACTIVATION_HEIGHT: u64 = u64::MAX;
64
65/// Maximum allowed block timestamp skew into the future (seconds).
66///
67/// Used by header structural checks (SVL-004) to bound clock abuse while tolerating reasonable skew.
68pub const MAX_FUTURE_TIMESTAMP_SECONDS: u64 = 300;
69
70/// Domain-separation prefix for Merkle leaf nodes (0x01).
71///
72/// **Rationale:** Prefixing leaf and internal node hashes prevents second-preimage ambiguity between
73/// leaf-level data and hashed pairs; see [HSH-007](docs/requirements/domains/hashing/specs/HSH-007.md) and BLK-005.
74///
75/// **Wire formula:** [`crate::hash::hash_leaf`] — production trees use [`chia_sdk_types::MerkleTree`] with the same byte.
76pub const HASH_LEAF_PREFIX: u8 = 0x01;
77
78/// Domain-separation prefix for Merkle internal nodes (0x02).
79///
80/// **Wire formula:** [`crate::hash::hash_node`]; [`chia_sdk_types::MerkleTree`] uses the same prefix for parent nodes.
81pub const HASH_TREE_PREFIX: u8 = 0x02;
dig_block/constants.rs

dig_block/
constants.rs
