Crate dig_epoch 

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 (Cargo.toml dependency set only). The module tree below is introduced by STR-002 per SPEC.md § 13 — each module is a stub whose real contents arrive in the per-domain requirements listed in 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 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, 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.

Re-exports

pub use manager::EpochManager;

pub use types::CheckpointCompetition;

pub use types::CompetitionStatus;

pub use types::DfspCloseSnapshot;

pub use types::EpochBlockLink;

pub use types::EpochCheckpointData;

pub use types::EpochCheckpointSignMaterial;

pub use types::EpochEvent;

pub use types::EpochInfo;

pub use types::EpochPhase;

pub use types::EpochStats;

pub use types::EpochSummary;

pub use types::PhaseTransition;

pub use types::RewardDistribution;

pub use arithmetic::ensure_checkpoint_block_empty;

pub use arithmetic::epoch_checkpoint_height;

pub use arithmetic::epoch_for_block_height;

pub use arithmetic::first_height_in_epoch;

pub use arithmetic::is_checkpoint_class_block;

pub use arithmetic::is_epoch_checkpoint_block;

pub use arithmetic::is_first_block_after_epoch_checkpoint;

pub use arithmetic::is_genesis_checkpoint_block;

pub use arithmetic::l1_range_for_epoch;

pub use arithmetic::last_committed_height_in_epoch;

pub use phase::l1_progress_phase_for_network_epoch;

pub use rewards::block_reward_at_height;

pub use rewards::burned_fee_remainder;

pub use rewards::compute_reward_distribution;

pub use rewards::epoch_reward_with_floor;

pub use rewards::proposer_fee_share;

pub use rewards::total_block_reward;

pub use verification::compute_epoch_block_root;

pub use verification::compute_epoch_withdrawals_root;

pub use verification::epoch_block_inclusion_proof;

pub use verification::epoch_checkpoint_sign_material_from_l2_blocks;

pub use verification::stored_checkpoint_from_epoch_sign_material_with_aggregate_v1;

pub use verification::verify_block_inclusion_proof;

pub use error::CheckpointCompetitionError;

pub use error::EpochError;

pub use constants::*;

Modules

arithmetic

Pure height-to-epoch arithmetic. Filled by the height_epoch_arithmetic domain (HEA-*).

constants

Compile-time epoch constants. Filled by the constants domain (CON-*).

dfsp

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.

error

Crate-wide error enums (EpochError, CheckpointCompetitionError). Filled by the error_types domain (ERR-*).

manager

EpochManager struct and methods. Filled by STR-004 (constructor) and the epoch_manager domain (MGR-*).

phase

L1-progress phase calculation. Filled by the phase_state_machine domain (PHS-*).

rewards

Block-reward and distribution computation. Filled by the reward_economics domain (REW-*).

test_helpers

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.

types

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).

verification

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.

Structs

Checkpoint

Epoch summary checkpoint: aggregate stats and Merkle roots for one L1-anchored epoch (SPEC §2.6, CKP-001).

CheckpointSubmission

Signed checkpoint submission: epoch summary plus validator attestation material (SPEC §2.7, CKP-002).

Type Aliases

Bytes32