dig-epoch

DIG L2 epoch geometry, phase machine, manager, checkpoint competition, reward economics, verification, and serialization — as a single Rust crate.

Canonical spec: docs/resources/SPEC.md
Requirements tree: docs/requirements/README.md
Implementation checklist: docs/requirements/IMPLEMENTATION_ORDER.md
Project notes: CLAUDE.md

This README is the authoritative entry point for consumers of the public API. Everything listed under Public interface below is reachable via use dig_epoch::<name> — no submodule paths required.

What this crate does

Given an L1-anchored blockchain with a fixed cadence, dig-epoch is the state machine that partitions time into epochs and drives each epoch through four phases:

BlockProduction (0–50%)  →  Checkpoint (50–75%)  →  Finalization (75–100%)  →  Complete

Each epoch has:

An L1 window of EPOCH_L1_BLOCKS heights (genesis + epoch * EPOCH_L1_BLOCKS).
An L2 window of BLOCKS_PER_EPOCH blocks (first = epoch * BLOCKS_PER_EPOCH + 1).
A CheckpointCompetition that collects submissions and selects a winner.
A reward split (5 roles + 50/50 fee split) derived by the economic rules.
A DfspCloseSnapshot of the storage-protocol state at epoch close.
An EpochSummary archived at advance_epoch.

It does not redefine block types — Checkpoint / CheckpointSubmission come from dig-block; Bytes32 comes from chia-protocol. Both are re-exported from dig_epoch for single-crate ergonomics.

Installation

[dependencies]
dig-epoch = "0.1"

Transitive deps: chia-protocol, chia-bls, chia-consensus, chia-sha2, chia-sdk-types, chia-sdk-signer, clvm-utils, dig-block, dig-constants, bincode (v1), serde, thiserror, parking_lot.

Pins are intentional — DIG crates track 0.1, Chia low-level crates track 0.26, Chia SDK crates track 0.30. See Cargo.toml header for rationale.

Quick start

use dig_epoch::{
    Bytes32, EpochManager, EpochPhase, DfspCloseSnapshot,
    compute_reward_distribution, epoch_reward_with_floor, total_block_reward,
    BLOCKS_PER_EPOCH,
};
use dig_epoch::test_helpers::mock_checkpoint_submission;

fn run() -> Result<(), dig_epoch::EpochError> {
    let network_id = Bytes32::new([0x01; 32]);
    let initial_state_root = Bytes32::new([0xAA; 32]);
    let m = EpochManager::new(network_id, /* genesis_l1 */ 100, initial_state_root);

    // Phase 1: produce blocks.
    for _ in 0..16 {
        m.record_block(/* fees */ 500, /* tx_count */ 2)?;
    }

    // Cross 50% → Checkpoint. Start the competition, submit, confirm winner.
    m.update_phase(116);
    m.start_checkpoint_competition()?;
    m.submit_checkpoint(mock_checkpoint_submission(0, 75, 16))?;

    // Cross 75% → Finalization. Stage DFSP snapshot + finalize the winner.
    m.update_phase(124);
    m.set_current_epoch_dfsp_close_snapshot(DfspCloseSnapshot {
        collateral_registry_root: Bytes32::new([0; 32]),
        cid_state_root: Bytes32::new([0; 32]),
        node_registry_root: Bytes32::new([0; 32]),
        namespace_epoch_root: Bytes32::new([0; 32]),
        dfsp_issuance_total: 0,
        active_cid_count: 0,
        active_node_count: 0,
    })?;
    m.finalize_competition(/* epoch */ 0, /* l1_height */ 132)?;

    // Cross 100% → Complete. Store rewards, then advance.
    m.update_phase(133);
    let total_fees = m.current_epoch_info().total_fees;
    let base: u64 = (1..=BLOCKS_PER_EPOCH).map(|h| total_block_reward(h, h == 1)).sum();
    let total_reward = epoch_reward_with_floor(base);
    m.store_rewards(compute_reward_distribution(0, total_reward, total_fees));
    let next = m.advance_epoch(133, Bytes32::new([0xFE; 32]))?;
    assert_eq!(next, 1);
    Ok(())
}

A full end-to-end run lives in tests/integration/end_to_end_test.rs.

Public interface

Types

Name	Kind	Role
`EpochManager`	struct	Stateful orchestrator. Owns current epoch + history + competition + rewards.
`EpochPhase`	enum	`BlockProduction` / `Checkpoint` / `Finalization` / `Complete`.
`PhaseTransition`	struct	`{ epoch, from, to, l1_height }` — emitted by `update_phase`.
`EpochInfo`	struct	17-field mutable state for the current epoch.
`EpochSummary`	struct	13-field immutable archive of a completed epoch.
`DfspCloseSnapshot`	struct	7-field DFSP state captured at epoch close.
`EpochEvent`	enum	`EpochStarted` / `PhaseChanged` / `EpochFinalized` / `EpochFailed`.
`EpochStats`	struct	Aggregate stats across all epochs (total_epochs, blocks, fees, txns).
`EpochBlockLink`	struct	Parent/child block-hash pair for epoch chains.
`CheckpointCompetition`	struct	Per-epoch submission set + status.
`CompetitionStatus`	enum	`Pending` / `Collecting` / `WinnerSelected` / `Finalized` / `Failed`.
`RewardDistribution`	struct	8-field per-epoch reward allocation (5 roles + fee split).
`EpochCheckpointData`	struct	Network-bound checkpoint identity (network_id + roots + hash).
`EpochCheckpointSignMaterial`	struct	`EpochCheckpointData` + score + signing_digest for BLS.
`EpochError`	enum	Primary error type (see Errors below).
`CheckpointCompetitionError`	enum	Competition-specific errors; wraps into `EpochError::Competition`.
`Bytes32` (re-exported)	struct	From `chia-protocol`. 32-byte hash.
`Checkpoint` (re-exported)	struct	From `dig-block`. Epoch summary wire type.
`CheckpointSubmission` (re-exported)	struct	From `dig-block`. Signed checkpoint + score + submitter.

`EpochManager` methods

Construction:

Signature	Description
`new(network_id: Bytes32, genesis_l1_height: u32, initial_state_root: Bytes32) -> Self`	Starts at epoch 0, `BlockProduction`. Empty history/competitions/rewards.

Accessors (read locks; concurrent-safe):

Signature	Returns
`current_epoch(&self) -> u64`	Current epoch number.
`current_epoch_info(&self) -> EpochInfo`	Clone of current state.
`current_phase(&self) -> EpochPhase`	Current phase.
`genesis_l1_height(&self) -> u32`	Immutable genesis L1 height.
`network_id(&self) -> Bytes32`	Immutable network ID.
`epoch_for_l1_height(&self, l1_height: u32) -> u64`	L1 → epoch mapping.
`l1_range_for_epoch(&self, epoch: u64) -> (u32, u32)`	Inclusive L1 window.
`competition(&self) -> CheckpointCompetition`	Clone of current competition.
`should_advance(&self, _l1_height: u32) -> bool`	`true` when phase is `Complete`.

Writes (write locks):

Signature	Effect
`update_phase(&self, l1_height: u32) -> Option<PhaseTransition>`	Recalculates phase; `Some` on transition.
`record_block(&self, fees: u64, tx_count: u64) -> Result<(), EpochError>`	Increments counters. Requires `BlockProduction`.
`set_current_epoch_chain_totals(&self, blocks: u32, fees: u64, txns: u64)`	Overwrites counters (no phase gate). For resync.
`set_current_epoch_dfsp_close_snapshot(&self, snap: DfspCloseSnapshot) -> Result<(), EpochError>`	Applies DFSP close. Requires `Finalization`.
`advance_epoch(&self, _l1_height: u32, state_root: Bytes32) -> Result<u64, EpochError>`	Archives summary, creates `epoch+1`. Requires `Complete` + finalized competition.

Checkpoint competition (SPEC §6.5):

Signature	Effect
`start_checkpoint_competition(&self) -> Result<(), EpochError>`	`Pending` → `Collecting`. Requires `Checkpoint` phase.
`submit_checkpoint(&self, submission: CheckpointSubmission) -> Result<bool, EpochError>`	Returns `true` when submission beats current leader. Records every submission.
`finalize_competition(&self, epoch: u64, l1_height: u32) -> Result<Option<Checkpoint>, EpochError>`	`WinnerSelected` → `Finalized`. Sets checkpoint on `EpochInfo`. `Ok(None)` if no submissions (→ `Failed`).
`get_competition(&self, epoch: u64) -> Option<CheckpointCompetition>`	Returns clone when `epoch` matches current competition.

Query + history (SPEC §6.7, §6.9):

Signature	Returns
`get_epoch_info(&self) -> EpochInfo`	Alias for `current_epoch_info`.
`get_epoch_summary(&self, epoch: u64) -> Option<EpochSummary>`	Archived summary for completed epoch.
`recent_summaries(&self, n: usize) -> Vec<EpochSummary>`	Last `n` in ascending epoch order.
`total_stats(&self) -> EpochStats`	Aggregates across archived + current.
`get_rewards(&self, epoch: u64) -> Option<RewardDistribution>`	Looks up stored rewards.
`store_rewards(&self, distribution: RewardDistribution)`	Archives rewards keyed by `distribution.epoch`.

Free functions

Height arithmetic (arithmetic, HEA-*):

epoch_for_block_height(height: u64) -> u64
first_height_in_epoch(epoch: u64) -> u64
epoch_checkpoint_height(epoch: u64) -> u64
last_committed_height_in_epoch(epoch: u64, tip_height: u64) -> u64
is_genesis_checkpoint_block(height: u64) -> bool
is_epoch_checkpoint_block(height: u64) -> bool
is_checkpoint_class_block(height: u64) -> bool
is_first_block_after_epoch_checkpoint(height: u64) -> bool
l1_range_for_epoch(genesis_l1_height: u32, epoch: u64) -> (u32, u32)
ensure_checkpoint_block_empty(height: u64, bundles: u32, cost: u64, fees: u64) -> Result<(), EpochError>

Phase (phase, PHS-001):

l1_progress_phase_for_network_epoch(
    genesis_l1_height: u32,
    network_epoch: u64,
    current_l1_height: u32,
) -> EpochPhase

Reward economics (rewards, REW-*):

block_reward_at_height(height: u64) -> u64
total_block_reward(height: u64, is_first_of_epoch: bool) -> u64
proposer_fee_share(total_fees: u64) -> u64
burned_fee_remainder(total_fees: u64) -> u64
compute_reward_distribution(epoch: u64, total_reward: u64, total_fees: u64) -> RewardDistribution
epoch_reward_with_floor(computed_epoch_reward: u64) -> u64

Verification (verification, VER-*):

compute_epoch_block_root(block_hashes: &[Bytes32]) -> Bytes32
epoch_block_inclusion_proof(block_hashes: &[Bytes32], index: usize) -> Option<MerkleProof>
verify_block_inclusion_proof(leaf: Bytes32, proof: &MerkleProof, root: Bytes32) -> bool
compute_epoch_withdrawals_root(withdrawal_hashes: &[Bytes32]) -> Bytes32
epoch_checkpoint_sign_material_from_l2_blocks(
    network_id: Bytes32,
    epoch: u64,
    block_hashes: &[Bytes32],
    state_root: Bytes32,
    withdrawal_hashes: &[Bytes32],
    prev_checkpoint: Bytes32,
    total_fees: u64,
    tx_count: u64,
    stake_percentage: u64,
) -> EpochCheckpointSignMaterial
stored_checkpoint_from_epoch_sign_material_with_aggregate_v1(
    material: &EpochCheckpointSignMaterial,
    validator_set: &[(u32, PublicKey)],
    per_validator: &[(u32, PublicKey, Signature)],
    submitter: u32,
) -> Result<CheckpointSubmission, EpochError>

MerkleProof is chia_sdk_types::MerkleProof. PublicKey / Signature are chia_bls::PublicKey / chia_bls::Signature.

Test helpers (`test_helpers`)

Exposed as pub mod so integration tests can reuse deterministic fixtures. Not production-safe — synthetic BLS signatures do not verify.

test_network_id() -> Bytes32
test_initial_state_root() -> Bytes32
TEST_GENESIS_L1_HEIGHT: u32 = 100
test_epoch_manager() -> EpochManager
advance_through_phases(&EpochManager) -> Vec<PhaseTransition>
mock_checkpoint_submission(epoch: u64, stake_percentage: u64, block_count: u32) -> CheckpointSubmission
build_n_block_epoch(&EpochManager, n: u32, fee_per_block: u64, tx_per_block: u64) -> (u64, u64)

Constants

Epoch geometry: BLOCKS_PER_EPOCH = 32, EPOCH_L1_BLOCKS = 32, GENESIS_HEIGHT = 1.

Phase boundaries: PHASE_BLOCK_PRODUCTION_END_PCT = 50, PHASE_CHECKPOINT_END_PCT = 75, PHASE_FINALIZATION_END_PCT = 100.

Reward economics: MOJOS_PER_L2, L2_BLOCK_TIME_MS, L2_BLOCKS_PER_10_MIN, INITIAL_EMISSION_PER_10_MIN, TAIL_EMISSION_PER_10_MIN, INITIAL_BLOCK_REWARD, TAIL_BLOCK_REWARD, HALVING_INTERVAL_BLOCKS, HALVINGS_BEFORE_TAIL = 4, INITIAL_EPOCH_REWARD, HALVING_INTERVAL_EPOCHS, MINIMUM_EPOCH_REWARD, EPOCH_FIRST_BLOCK_BONUS.

Fee + reward split: FEE_PROPOSER_SHARE_PCT = 50, FEE_BURN_SHARE_PCT = 50, PROPOSER_REWARD_SHARE = 10, ATTESTER_REWARD_SHARE = 80, EF_SPAWNER_REWARD_SHARE = 3, SCORE_SUBMITTER_REWARD_SHARE = 4, FINALIZER_REWARD_SHARE = 3.

DFSP / consensus / slashing: DFSP_WALL_CLOCK_EPOCH_SECONDS, DFSP_GRACE_PERIOD_NETWORK_EPOCHS, DFSP_GENESIS_ISSUANCE_SUBSIDY_MOJOS_V1, DFSP_ACTIVATION_HEIGHT, DIG_DFSP_ACTIVATION_HEIGHT_ENV, SOFT_FINALITY_THRESHOLD_PCT, HARD_FINALITY_THRESHOLD_PCT, CHECKPOINT_THRESHOLD_PCT, CORRELATION_WINDOW_EPOCHS, SLASH_LOOKBACK_EPOCHS, DFSP_SLASH_LOOKBACK_EPOCHS, WITHDRAWAL_DELAY_EPOCHS.

Sentinel: EMPTY_ROOT = SHA-256("").

Inputs and outputs

Canonical inputs

Input	Where it enters	Validation
`network_id: Bytes32`	`EpochManager::new`	Stored immutably. Binds all sign material to prevent cross-network replay.
`genesis_l1_height: u32`	`EpochManager::new`	Stored immutably. Defines epoch 0's L1 window.
`initial_state_root: Bytes32`	`EpochManager::new`	Used as `EpochInfo::start_state_root` for epoch 0.
`(fees, tx_count)`	`record_block`	Added to current epoch counters. Rejected unless `BlockProduction`.
`l1_height: u32`	`update_phase`	Drives phase recalculation via `(l1_now - start) * 100 / EPOCH_L1_BLOCKS`.
`CheckpointSubmission`	`submit_checkpoint`	Rejected unless `Checkpoint` phase + competition `Collecting`/`WinnerSelected` + `submission.epoch == competition.epoch` + `score > current`.
`DfspCloseSnapshot`	`set_current_epoch_dfsp_close_snapshot`	Copied field-wise onto `EpochInfo`. Requires `Finalization`.
`(epoch, l1_height)`	`finalize_competition`	Requires `Finalization` + `epoch == competition.epoch`.
`state_root: Bytes32`	`advance_epoch`	Initial `start_state_root` for `epoch+1`. Requires `Complete` + finalized competition.
`RewardDistribution`	`store_rewards`	Keyed by `distribution.epoch`.
`block_hashes: &[Bytes32]`	`compute_epoch_block_root`, `epoch_block_inclusion_proof`	Ordered. Empty → `EMPTY_ROOT`.
`withdrawal_hashes: &[Bytes32]`	`compute_epoch_withdrawals_root`	Order-independent (Merkle set). Empty → `EMPTY_ROOT`.
`(validator_set, per_validator, submitter)`	`stored_checkpoint_from_epoch_sign_material_with_aggregate_v1`	BLS-aggregated. `per_validator` non-empty.

Canonical outputs

Output	Produced by	Shape
`EpochInfo`	`current_epoch_info` / `get_epoch_info`	Clone of current state (17 fields).
`EpochSummary`	`get_epoch_summary`, `recent_summaries`, appended on `advance_epoch`	Immutable 13-field archive.
`EpochStats`	`total_stats`	Aggregate over archived + current.
`EpochPhase`	`current_phase`, phase free function	One of four variants.
`PhaseTransition`	`update_phase`	`{ epoch, from, to, l1_height }` when phase changed.
`CheckpointCompetition`	`competition`, `get_competition`	Clone of current competition.
`Option<Checkpoint>`	`finalize_competition`	Winning checkpoint or `None` when no submissions.
`bool`	`submit_checkpoint`	`true` when submission became leader.
`u64`	`advance_epoch`	New epoch number.
`RewardDistribution`	`compute_reward_distribution`, `get_rewards`	8-field split. Sum of role rewards == `total_reward`.
`Bytes32`	Merkle root functions	32-byte canonical hash.
`MerkleProof`	`epoch_block_inclusion_proof`	Leaf-keyed proof; verify with `verify_block_inclusion_proof`.
`EpochCheckpointData` / `EpochCheckpointSignMaterial`	`epoch_checkpoint_sign_material_from_l2_blocks`	Ready for BLS signing.
`Vec<u8>`	`to_bytes()` on each serializable type	bincode-encoded.
`Result<T, EpochError>`	Every fallible method	See Errors below.

Invariants

Phase gating — each mutating method requires a specific phase. Mismatches return EpochError::PhaseMismatch { expected, got }.
Append-only history — summaries only grows (via advance_epoch), ordered by ascending epoch, with consecutive numbers.
Reward sum — compute_reward_distribution guarantees proposer + attester + ef_spawner + score_submitter + finalizer == total_reward (attester absorbs rounding).
Fee sum — proposer_fee_share(f) + burned_fee_remainder(f) == f for all f: u64.
Checkpoint-class blocks — ensure_checkpoint_block_empty rejects non-zero bundles/cost/fees at checkpoint heights.
Merkle roots — empty input → EMPTY_ROOT (SHA-256 of empty string). Block root is order-dependent; withdrawals root is order-independent.
Concurrency — all mutations go through a single parking_lot::RwLock<EpochManagerInner>. Reads allow concurrency; writes are exclusive; no poisoning.
Network binding — EpochCheckpointData::signing_digest() includes network_id to prevent cross-network replay.
Serialization — to_bytes() is infallible; from_bytes() returns Result<Self, EpochError>. Round-trip preserves every field across all 6 serializable types (EpochInfo, EpochSummary, DfspCloseSnapshot, CheckpointCompetition, RewardDistribution, EpochCheckpointData).

Errors

pub enum EpochError {
    EpochNotComplete(u64),
    NoFinalizedCheckpoint(u64),
    CheckpointBlockNotEmpty(u64, u32, u64, u64),   // (height, bundles, cost, fees)
    PhaseMismatch { expected: EpochPhase, got: EpochPhase },
    EpochMismatch { expected: u64, got: u64 },
    InvalidHeight(u64),
    DfspNotActive(u64),
    DfspBoundary(String),
    Competition(#[from] CheckpointCompetitionError),
    InvalidData(String),                           // bincode / malformed input
}

pub enum CheckpointCompetitionError {
    InvalidData(String),
    NotFound(u64),
    ScoreNotHigher { current: u64, submitted: u64 },
    EpochMismatch { expected: u64, got: u64 },
    AlreadyFinalized,
    NotStarted,
}

All variants implement std::error::Error via thiserror. EpochError auto-converts from CheckpointCompetitionError via ?.

Epoch lifecycle diagram

┌──────────────────────────────────────────────────────────────────────────┐
│                            EpochManager (epoch N)                        │
│                                                                          │
│   BlockProduction  ──(l1 at 50%)──►  Checkpoint  ──(l1 at 75%)──►        │
│   │  record_block                    │  start_checkpoint_competition     │
│   │  set_chain_totals                │  submit_checkpoint × K            │
│                                      │                                   │
│                                      ▼                                   │
│                               Finalization  ──(l1 at 100%)──►  Complete  │
│                               │  set_dfsp_close_snapshot       │         │
│                               │  finalize_competition          │         │
│                                                                │         │
│                                                                ▼         │
│                                                    store_rewards         │
│                                                    advance_epoch ───────►│
│                                                    ╔═════════════════════╝
│                                                    ║  epoch N+1 starts
│                                                    ║  BlockProduction
└──────────────────────────────────────────────────────────────────────────┘

Every phase boundary is enforced server-side: calling the wrong method returns EpochError::PhaseMismatch.

Module layout

Module	Purpose
`constants`	Compile-time epoch/phase/reward/DFSP constants (CON-*).
`types`	Data types grouped by concern (TYP-*, CKP-001, REW-007, VER-004).
`arithmetic`	Pure height ↔ epoch math (HEA-*).
`phase`	Stateless L1-progress phase calculation (PHS-001).
`rewards`	Reward economics (REW-*).
`manager`	`EpochManager` struct + methods (MGR-*).
`verification`	Merkle roots, inclusion proofs, sign material, BLS aggregate (VER-*).
`dfsp`	Root-level DFSP processing (DFS-*, currently deferred).
`error`	`EpochError` + `CheckpointCompetitionError` (ERR-*).
`test_helpers`	Deterministic test fixtures (STR-005).

types/ submodules: epoch_phase, epoch_info, epoch_summary, dfsp, events, checkpoint_competition, reward, verification. Each is pub mod so the full type can also be addressed by its fully-qualified path (e.g. dig_epoch::types::checkpoint_competition::CompetitionStatus) in addition to the flat dig_epoch::CompetitionStatus.

Implementation scope

Phase	Requirements	Status
0. Crate structure	STR-001..005	Complete
1. Constants	CON-001..006	Complete
2. Error types	ERR-001..003	Complete
3. Epoch types	TYP-001..007	Complete
4. Height arithmetic	HEA-001..007	Complete
5. Phase machine	PHS-001..004	Complete
6. Reward economics	REW-001..007	Complete
7. Epoch manager	MGR-001..008	Complete
8. Checkpoint competition	CKP-001..005	Complete
9. Verification	VER-001..005	Complete
10. DFSP processing	DFS-001..008	Deferred (not in current scope)
11. Serialization	SER-001..003	Complete

See docs/requirements/IMPLEMENTATION_ORDER.md for the checklist and each domain's TRACKING.yaml for per-requirement test pointers.

Testing

cargo test              # 63 test suites, 470+ tests
cargo clippy --lib -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --lib
cargo fmt --check

Each requirement owns its own test file under tests/<domain>/<id>_test.rs (e.g. tests/epoch_manager/mgr_004_test.rs). The full-lifecycle cohesion test lives in tests/integration/end_to_end_test.rs.

License

MIT.

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.claude/skills		.claude/skills
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
docs		docs
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
Cargo.toml		Cargo.toml
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

dig-epoch

What this crate does

Installation

Quick start

Public interface

Types

`EpochManager` methods

Free functions

Test helpers (`test_helpers`)

Constants

Inputs and outputs

Canonical inputs

Canonical outputs

Invariants

Errors

Epoch lifecycle diagram

Module layout

Implementation scope

Testing

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

dig-epoch

What this crate does

Installation

Quick start

Public interface

Types

EpochManager methods

Free functions

Test helpers (test_helpers)

Constants

Inputs and outputs

Canonical inputs

Canonical outputs

Invariants

Errors

Epoch lifecycle diagram

Module layout

Implementation scope

Testing

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`EpochManager` methods

Test helpers (`test_helpers`)

Packages