Struct ParticipationTracker 

pub struct ParticipationTracker { /* private fields */ }

Per-validator two-epoch attestation-flag store.

Implements DSL-078 (+ DSL-079/080 in later commits). Traces to SPEC §8.2.

Fields

• current_epoch — flags accumulated during the in-flight epoch.
• previous_epoch — flags from the just-completed epoch. Read by reward / penalty delta computation (DSL-082..086).
• current_epoch_number — monotonically advancing epoch counter. Driven forward by rotate_epoch (DSL-080).

Storage size

Both vecs are sized at construction to validator_count. Out-of-range indices return ParticipationError::IndexOutOfRange rather than panicking — record_attestation is called with adversary-controllable indices (attesters may be newly registered or slashed between admission and record), and the tracker is expected to degrade gracefully.

Implementations

impl ParticipationTracker

pub fn new(validator_count: usize, initial_epoch: u64) -> Self

New tracker sized for validator_count slots, starting at initial_epoch. Both epoch vectors initialise to ParticipationFlags::default() (all-zero).

pub fn current_epoch_number(&self) -> u64

Current epoch counter. Advanced by rotate_epoch (DSL-080).

pub fn current_flags(&self, validator_index: u32) -> Option<ParticipationFlags>

Flag bits accumulated for validator_index during the current epoch. None when the index is out of range.

pub fn previous_flags(&self, validator_index: u32) -> Option<ParticipationFlags>

Flag bits from the previous (finalisable) epoch for validator_index. None when the index is out of range. Consumed by DSL-082/083 reward-delta math.

pub fn validator_count(&self) -> usize

Number of validator slots the tracker can address. attesting_indices with values >= validator_count return IndexOutOfRange.

pub fn rotate_epoch(&mut self, new_epoch: u64, validator_count: usize)

Advance to a new epoch: swap current → previous, reset current to validator_count zero-initialised slots, and update current_epoch_number.

Implements DSL-080. Traces to SPEC §8.2, §10.

Ordering

1. swap(previous, current) — what was accumulated during the just-finished epoch moves into previous_epoch. DSL-082..086 reward / penalty math reads these bits.
2. current.clear(); current.resize(validator_count, 0) — accept validator-set growth at the boundary. New validators that activated this epoch get zero flags.
3. current_epoch_number = new_epoch.

Shrinking validator set

If validator_count < old.len(), the trailing entries are dropped. This is the correct behaviour for exited validators — their previous-epoch flags are preserved (in the just-swapped previous_epoch), only the current -epoch slot is discarded.

Previous-epoch sizing

previous_epoch keeps whatever length current had before rotation. Downstream reward math reads previous_flags(idx) via .get(idx).copied(), so out-of-range reads return None rather than panicking.

pub fn rewind_on_reorg( &mut self, new_tip_epoch: u64, validator_count: usize, ) -> u64

Rewind the tracker on fork-choice reorg.

Implements the participation leg of DSL-130 rewind_all_on_reorg. Drops both flag vectors and reinstates new_tip_epoch as the current epoch with zero-initialised flags.

Why zero-fill instead of restoring pre-reorg state: the tracker does NOT retain historical snapshots (each rotate_epoch overwrites in place). Post-rewind, flag accumulation resumes fresh from the new canonical tip — the reward-delta pass at the NEXT epoch boundary observes no activity over the rewound span (conservative; no false reward credits from a ghost chain). Also zero- fills the previous_epoch slot so the first post-rewind compute_flag_deltas cannot read ghost data.

Returns the number of epochs dropped (old_current_epoch - new_tip_epoch, saturating at 0 when the tip is already current or ahead).

pub fn record_attestation( &mut self, _data: &AttestationData, attesting_indices: &[u32], flags: ParticipationFlags, ) -> Result<(), ParticipationError>

Record an attestation: apply flags to every entry in attesting_indices via bit-OR into the current epoch’s per-validator bucket.

Implements DSL-078.

Errors

Returns ParticipationError::IndexOutOfRange(i) for the FIRST offending index; later indices are not touched. Structural non-ascending / duplicate checks land in DSL-079 and run before this bit-OR pass in that cycle.

Behaviour

• Bit-OR is additive. record_attestation(.., TIMELY_SOURCE) followed by record_attestation(.., TIMELY_TARGET) on the same validator leaves both bits set.
• current_epoch_number is NOT mutated — epoch advancement is the sole responsibility of rotate_epoch (DSL-080).

Trait Implementations

impl Clone for ParticipationTracker

fn clone(&self) -> ParticipationTracker

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ParticipationTracker

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.