Peras vote aggregation and certificate forging

This module implements the core voting logic for the Peras protocol, which aggregates stake-weighted votes on chain blocks and forges certificates when quorum is reached.

Overview

In Peras, validators vote on specific blocks during designated voting rounds. Each vote carries a stake weight, and votes are aggregated by:

• Round: each vote belongs to a specific PerasRoundNo
• Target: within a round, votes are cast for different block Points

As votes arrive, the system tracks the total stake backing each candidate block. When one target accumulates enough stake to exceed the configured quorum threshold, a certificate is automatically forged for that block, making it a winner for that round.

State Machine

For every round being voted for, the aggregation follows a state machine:

1. Quorum not reached: multiple block targets are candidates, each accumulating votes and stake. All targets compete to reach quorum first.
2. Quorum reached: once a target reaches quorum, it becomes the winner and a certificate is forged. All other targets become losers and continue tracking votes without affecting the outcome.

Quorum Threshold and Multiple Winners

The quorum threshold is parameterized via PerasCfg. Depending on this configuration and the stake distribution, it may be theoretically possible for multiple targets to exceed the threshold within the same round.

This module treats multiple winners as an error condition and rejects votes that would cause this, raising instead a RoundVoteStateLoserAboveQuorum exception. This indicates that either: * The quorum threshold is misconfigured, or that * We were extremely unlucky when randomly selecting the voting committee.

With a correct threshold configuration (e.g., > 3/4 of total stake + a small safety margin to account for an unlucky local sortition when selecting non-persistent voters during committee selection), multiple winners should be impossible given honest stake distribution.

Key Types

• PerasRoundVoteState: tracks all voting activity for a single round, and its logically split between separate NoQuorum and Quorum types representing the two states (1) and (2) described above, respectively.
• PerasTargetVoteState: tracks votes for one specific block target
• PerasTargetVoteTally: raw vote count and stake accumulation
• PerasTargetVoteStatus: type-level status (CandidateWinnerLoser)
• UpdateRoundVoteStateError: errors from invalid state transitions

Usage

The primary entry point is updatePerasRoundVoteStates, which adds a new vote to the aggregate state. Pattern synonyms VoteGeneratedNewCert and VoteDidntGenerateNewCert allow clients to observe when certificates are freshly forged (as opposed to voting on an already-won target).