Struct EpochManager 

pub struct EpochManager { /* private fields */ }

Primary state machine managing the current epoch’s lifecycle and archiving completed epochs.

Uses parking_lot::RwLock for interior mutability (start.md Hard Requirement 12). Read operations allow concurrent access; write operations block all other access.

Implementations

impl EpochManager

pub fn new( network_id: Bytes32, genesis_l1_height: u32, initial_state_root: Bytes32, ) -> Self

Creates an EpochManager at epoch 0 with empty history and a fresh Pending competition.

network_id and genesis_l1_height are immutable for the lifetime of this manager. The initial EpochInfo starts at GENESIS_HEIGHT in BlockProduction phase.

pub fn current_epoch(&self) -> u64

Returns the current epoch number.

pub fn current_epoch_info(&self) -> EpochInfo

Returns a clone of the current epoch’s full state.

pub fn current_phase(&self) -> EpochPhase

Returns the current phase of the current epoch.

pub fn genesis_l1_height(&self) -> u32

Returns the network’s genesis L1 height.

pub fn network_id(&self) -> Bytes32

Returns the network ID.

pub fn epoch_for_l1_height(&self, l1_height: u32) -> u64

Maps an L1 height to its epoch number using genesis_l1_height.

Heights before genesis map to epoch 0.

pub fn l1_range_for_epoch(&self, epoch: u64) -> (u32, u32)

Returns (start_l1, end_l1) for the given epoch.

pub fn update_phase(&self, l1_height: u32) -> Option<PhaseTransition>

Recalculates the phase from l1_height. Returns Some(PhaseTransition) if the phase changed, None if unchanged.

pub fn should_advance(&self, _l1_height: u32) -> bool

Returns true when the current phase is Complete.

pub fn record_block(&self, fees: u64, tx_count: u64) -> Result<(), EpochError>

Records a block in the current epoch.

Returns Err(PhaseMismatch) if not in BlockProduction.

pub fn set_current_epoch_chain_totals(&self, blocks: u32, fees: u64, txns: u64)

Overwrites the current epoch’s block production statistics.

Used for resync / correction. No phase restriction; values are replaced, not incremented.

pub fn set_current_epoch_dfsp_close_snapshot( &self, snap: DfspCloseSnapshot, ) -> Result<(), EpochError>

Applies DFSP close values to the current epoch before advance.

Returns Err(PhaseMismatch) if not in Finalization.

pub fn advance_epoch( &self, _l1_height: u32, state_root: Bytes32, ) -> Result<u64, EpochError>

Archives the current epoch and transitions to epoch + 1.

Preconditions:

• Current phase is Complete.
• Current competition is Finalized.

Both preconditions are checked before any state mutation.

pub fn get_epoch_info(&self) -> EpochInfo

Returns a clone of the current EpochInfo.

pub fn get_epoch_summary(&self, epoch: u64) -> Option<EpochSummary>

Returns the EpochSummary for a specific completed epoch, or None.

pub fn recent_summaries(&self, n: usize) -> Vec<EpochSummary>

Returns the last n summaries from the tail, preserving epoch order.

pub fn total_stats(&self) -> EpochStats

Aggregate statistics across all completed epochs plus the current one.

pub fn get_rewards(&self, epoch: u64) -> Option<RewardDistribution>

Returns the RewardDistribution for epoch, or None.

pub fn store_rewards(&self, distribution: RewardDistribution)

Archives a RewardDistribution keyed by its epoch field.

pub fn competition(&self) -> CheckpointCompetition

Returns a clone of the current competition. Read-only.

pub fn start_checkpoint_competition(&self) -> Result<(), EpochError>

Transitions the current competition from Pending to Collecting.

Phase-gated to Checkpoint. Delegates to CheckpointCompetition::start for the state transition.

pub fn submit_checkpoint( &self, submission: CheckpointSubmission, ) -> Result<bool, EpochError>

Records a checkpoint submission against the current epoch’s competition.

Phase-gated to Checkpoint. Returns Ok(true) when the submission becomes the new leader, Ok(false) is never returned (non-leading submissions return Err(ScoreNotHigher)). Delegates scoring to CheckpointCompetition::submit.

pub fn finalize_competition( &self, epoch: u64, l1_height: u32, ) -> Result<Option<Checkpoint>, EpochError>

Finalizes the competition for epoch at l1_height, transitioning status to Finalized and setting the winning checkpoint on the current EpochInfo.

Phase-gated to Finalization when epoch matches the current epoch. Returns the winning checkpoint on success, or Ok(None) if no winner was selected.

pub fn get_competition(&self, epoch: u64) -> Option<CheckpointCompetition>

Returns a clone of the competition for epoch.

Only the current epoch’s competition is tracked; returns None for past or future epochs.