dig-epoch 0.1.0

DIG L2 epoch geometry, phase machine, manager, and checkpoint competition types
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188

//! # dig-epoch
//!
//! Epoch geometry, phase machine, manager, and checkpoint-competition types
//! for the DIG L2.
//!
//! ## Status of this file
//!
//! The crate was first stubbed by
//! [`STR-001`](../docs/requirements/domains/crate_structure/specs/STR-001.md)
//! (Cargo.toml dependency set only). The module tree below is introduced
//! by [`STR-002`](../docs/requirements/domains/crate_structure/specs/STR-002.md)
//! per [`SPEC.md § 13`](../docs/resources/SPEC.md) — each module is a stub
//! whose real contents arrive in the per-domain requirements listed in
//! [`IMPLEMENTATION_ORDER.md`](../docs/requirements/IMPLEMENTATION_ORDER.md).
//!
//! ## Philosophy
//!
//! `dig-epoch` is intentionally thin: all primitive types (blocks,
//! checkpoints, hashes, BLS signatures, Merkle roots) come from the shared
//! DIG / Chia ecosystem crates listed in `Cargo.toml`. This crate
//! contributes the epoch-level *structure* (phases, arithmetic, reward
//! splits, the checkpoint competition) that sits above those primitives.
//!
//! See [`docs/resources/SPEC.md`](../docs/resources/SPEC.md) for the
//! authoritative crate specification.
//!
//! ## Module map (STR-002)
//!
//! The crate exposes a flat module tree with a single `types/` subdirectory:
//!
//! | Module              | Future owner        | Responsibility                               |
//! |---------------------|---------------------|----------------------------------------------|
//! | [`constants`]       | CON-001 … CON-006   | Compile-time epoch constants                 |
//! | [`arithmetic`]      | HEA-001 … HEA-005   | Pure height-epoch mapping functions          |
//! | [`phase`]           | PHS-001 … PHS-004   | L1-progress phase calculation                |
//! | [`rewards`]         | REW-001 … REW-006   | Block-reward / distribution computation      |
//! | [`manager`]         | STR-004, MGR-001…   | `EpochManager` struct + methods              |
//! | [`verification`]    | VER-*               | Root-level verification free functions       |
//! | [`dfsp`]            | DFS-*               | Root-level DFSP processing free functions    |
//! | [`error`]           | ERR-001 … ERR-003   | `EpochError`, `CheckpointCompetitionError`   |
//! | [`types`]           | TYP-*, CKP-*, REW-4 | Data types (see `types/mod.rs` for submods)  |
//!
//! Every module declared here is currently empty apart from a
//! `#[doc(hidden)]` `STR_002_MODULE_PRESENT` sentinel; real content arrives
//! one requirement at a time per `docs/requirements/IMPLEMENTATION_ORDER.md`.
//!
//! ## Re-exports
//!
//! None yet. Public re-exports arrive in
//! [`STR-003`](../docs/requirements/domains/crate_structure/specs/STR-003.md),
//! after the module hierarchy is in place. Consumers of STR-002 access
//! items via their full path (e.g. `dig_epoch::constants::FOO`); the
//! convenience `use dig_epoch::*` idiom becomes available only at STR-003.

// `deny(missing_docs)` would be ideal for a public API crate, but turning it
// on right now would force boilerplate docs on every subsequent requirement.
// We instead enable the softer `warn` so that CI surfaces missing docs without
// breaking the build while the module tree is still being fleshed out. This
// is consistent with the rest of the DIG/Chia ecosystem where crate-level
// docs are gated to the library target.
#![warn(missing_docs)]

// -----------------------------------------------------------------------------
// Module declarations — STR-002 (SPEC §13)
// -----------------------------------------------------------------------------
//
// Ordering rationale: the modules are declared in **responsibility order**
// rather than alphabetical order so that a reader scanning `lib.rs` sees
// the crate's data-flow narrative:
//
//   constants  → primitive compile-time values
//   types      → data shapes that operate over those values
//   arithmetic → pure height/epoch math on those shapes
//   phase      → state machine derived from arithmetic
//   rewards    → economic derivations (uses arithmetic + constants)
//   manager    → stateful orchestrator that wires everything together
//   verification, dfsp — cryptographic / protocol layers built on the
//                        stateful manager
//   error      — last so the error enum can reference the other modules
//                without forward references
//
// Per STR-002, these are declarations only — no `pub use` re-exports yet.
// Re-exports are the subject of STR-003, and adding them here would
// foreshadow that requirement.

/// Compile-time epoch constants. Filled by the `constants` domain (CON-*).
pub mod constants;

/// Data-type definitions for epochs, phases, events, rewards, and checkpoints.
/// Filled by the `epoch_types` domain (TYP-*) and adjacent type-owning
/// requirements (CKP-001 for the competition types, REW-004 for
/// `RewardDistribution`).
pub mod types;

/// Pure height-to-epoch arithmetic. Filled by the `height_epoch_arithmetic`
/// domain (HEA-*).
pub mod arithmetic;

/// L1-progress phase calculation. Filled by the `phase_state_machine`
/// domain (PHS-*).
pub mod phase;

/// Block-reward and distribution computation. Filled by the
/// `reward_economics` domain (REW-*).
pub mod rewards;

/// `EpochManager` struct and methods. Filled by STR-004 (constructor) and
/// the `epoch_manager` domain (MGR-*).
pub mod manager;

/// Root-level verification free functions (epoch block root, inclusion
/// proofs, checkpoint signing material). Filled by the `verification`
/// domain (VER-*). **Note:** distinct from `types::verification`, which
/// hosts the data types these functions produce/consume.
pub mod verification;

/// Root-level DFSP processing free functions (burn policy, digests,
/// rollup, tail roots, activation control). Filled by the `dfsp_processing`
/// domain (DFS-*). **Note:** distinct from `types::dfsp`, which hosts the
/// seven DFSP data types from SPEC §3.14.
pub mod dfsp;

/// Crate-wide error enums (`EpochError`, `CheckpointCompetitionError`).
/// Filled by the `error_types` domain (ERR-*).
pub mod error;

/// Reusable test fixtures (STR-005). Exposed as a public module so
/// integration tests under `tests/` can use them. Not for production use —
/// synthetic signatures and public keys do not verify cryptographically.
pub mod test_helpers;

// -----------------------------------------------------------------------------
// STR-003 — flat public re-exports
// -----------------------------------------------------------------------------
//
// Scope: every symbol reachable at `dig_epoch::<name>` corresponds to an
// implemented requirement. DFSP processing (DFS-*) is deferred per
// IMPLEMENTATION_ORDER.md, so its free functions are not re-exported here;
// the `DfspCloseSnapshot` type (TYP-004) is exposed because it's referenced
// by MGR-006 / the EpochInfo surface.

// -- Manager (MGR-001, STR-004) ----------------------------------------------
pub use manager::EpochManager;

// -- Data types (TYP-*, CKP-001, REW-007, VER-004) ---------------------------
pub use types::{
    CheckpointCompetition, CompetitionStatus, DfspCloseSnapshot, EpochBlockLink,
    EpochCheckpointData, EpochCheckpointSignMaterial, EpochEvent, EpochInfo, EpochPhase,
    EpochStats, EpochSummary, PhaseTransition, RewardDistribution,
};

// -- Constants (CON-001..006) -------------------------------------------------
pub use constants::*;

// -- Height-epoch arithmetic (HEA-001..007) ----------------------------------
pub use arithmetic::{
    ensure_checkpoint_block_empty, epoch_checkpoint_height, epoch_for_block_height,
    first_height_in_epoch, is_checkpoint_class_block, is_epoch_checkpoint_block,
    is_first_block_after_epoch_checkpoint, is_genesis_checkpoint_block, l1_range_for_epoch,
    last_committed_height_in_epoch,
};

// -- Phase machine (PHS-001) -------------------------------------------------
pub use phase::l1_progress_phase_for_network_epoch;

// -- Reward economics (REW-001..005) -----------------------------------------
pub use rewards::{
    block_reward_at_height, burned_fee_remainder, compute_reward_distribution,
    epoch_reward_with_floor, proposer_fee_share, total_block_reward,
};

// -- Verification (VER-001..005) ---------------------------------------------
pub use verification::{
    compute_epoch_block_root, compute_epoch_withdrawals_root, epoch_block_inclusion_proof,
    epoch_checkpoint_sign_material_from_l2_blocks,
    stored_checkpoint_from_epoch_sign_material_with_aggregate_v1, verify_block_inclusion_proof,
};

// -- Errors (ERR-001..003) ---------------------------------------------------
pub use error::{CheckpointCompetitionError, EpochError};

// -- Ecosystem types used in public signatures -------------------------------
//
// Re-exported so consumers have a single-crate import surface. Start.md
// Hard Requirement 1 forbids redefining these — we re-export the canonical
// items from their owning crates instead.
pub use chia_protocol::Bytes32;
pub use dig_block::{Checkpoint, CheckpointSubmission};