[Peras 13] Introduce votes and certificate forging API #1801

agustinmista · 2025-12-08T16:06:51Z

This PR comes in preparation to the implementation of the PerasVoteDB, and introduces a couple of new data types related to Peras votes and the certificate forging API:

The main PerasVote type, and its corresponding ValidatedPerasVote.
The auxiliary types PerasVoteTarget, PerasVoterId, PerasVoteStake, PerasVoteStakeDistr
The new Peras parameter PerasQuorumStakeThreshold (corresponding to perasQuorum in the design document, section 2.1)

tbagrel1

Looks perfect to me! 😃

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Block/SupportsPeras.hs

jasagredo · 2025-12-16T10:14:29Z

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Block/SupportsPeras.hs

    pcCertBoostedBlock <- decode
    pure $ PerasCert{pcCertRound, pcCertBoostedBlock}

+instance Serialise (HeaderHash blk) => Serialise (PerasVote blk) where


Why chose Serialise instead of ToCBOR/FromCBOR?

@tbagrel1 maybe you have a better idea?

Ouroboros.Consensus.Network.NodeToNode uses SerialiseNodeToNode class to serialise stuff. For types whose serialisation doesn't depend on a particular NodeToNodeVersion, the instances often fallback to encode/decode from Serialise class. For Peras types we've just followed the same existing pattern :)

jasagredo · 2025-12-16T10:22:48Z

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Node/Serialisation.hs

+  -- Consistent with the 'Serialise' instance for 'PerasVote' defined in Ouroboros.Consensus.Block.SupportsPeras
+  encodeNodeToNode ccfg version PerasVote{..} =
+    encodeListLen 3
+      <> encodeNodeToNode ccfg version pvVoteRound
+      <> encodeNodeToNode ccfg version pvVoteBlock
+      <> encodeNodeToNode ccfg version pvVoteVoterId
+  decodeNodeToNode ccfg version = do
+    decodeListLenOf 3
+    pvVoteRound <- decodeNodeToNode ccfg version
+    pvVoteBlock <- decodeNodeToNode ccfg version
+    pvVoteVoterId <- decodeNodeToNode ccfg version
+    pure $ PerasVote pvVoteRound pvVoteBlock pvVoteVoterId
+
+instance SerialiseNodeToNode blk PerasVoterId where
+  encodeNodeToNode _ccfg _version = KeyHash.toCBOR . unPerasVoterId
+  decodeNodeToNode _ccfg _version = PerasVoterId <$> KeyHash.fromCBOR


I guess the Serialise instance could change as it is used for storing on disk (confirm?), while this one would require a new NTN version etc etc. So if any I would put the comment in the Serialise instance saying that it matches the NTN one.

Also I think I would expose a function

-- Ouroboros.Consensus.Block.SupportsPeras encodeVoteNodeToNode :: CodecConfig blk -> NodeToNodeVersion -> PerasVote blk -> Encoding encodeVoteNodeToNode _ccfg _version = encode

maybe? I should check how we do this in other places but I think this is the pattern we usually use.

Bystander comment: I'm not super familiar with how these two type classes interact with each other but, in any case, we should remember to also apply any transformation to the instance for PerasCert defined above.

fraser-iohk · 2025-12-17T12:40:03Z

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Block/SupportsPeras.hs

+  deriving Semigroup via Sum Rational
+  deriving Monoid via Sum Rational
+
+newtype PerasVoteStakeDistr = PerasVoteStakeDistr


can this be named PerasVoteStakeDistribution?

The current name follows the convention established by PoolDistr, but we can easily change it if you guys prefer that.

Up to you 😸

fraser-iohk · 2025-12-17T12:58:33Z

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Block/SupportsPeras.hs

+newtype PerasVoteStake = PerasVoteStake
+  { unPerasVoteStake :: Rational
+  }
+  deriving newtype (Enum, Eq, Ord, Num, Fractional, NoThunks, Serialise)


can we remove the Enum instance? it's strange having this type be both Fractional and Enum, even if Rational underneath is

fraser-iohk · 2025-12-17T12:58:40Z

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Block/SupportsPeras.hs

+  { vpvVote :: !(PerasVote blk)
+  , vpvVoteStake :: !PerasVoteStake
+  }
+  deriving stock (Show, Eq, Ord, Generic)


do we need this Ord instance for Map/Set at the moment, and can we remove it otherwise? I don't like being able to compare two ValidatedPerasVotes when it's only really a meaningful comparison on the stake when they're both for the same vote

We do have simplified models for the PerasCertDB and (coming soon) PerasVoteDB making use of this Ord instance to store validated certs and votes in sets.

We can refactor those to use an explicit ordering and remove this instance, but I would prefer if we do it in a separate PR. I opened an issue to keep track of this:

tweag/cardano-peras#192

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Peras/Params.hs

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Block/SupportsPeras.hs

fraser-iohk · 2025-12-17T13:12:14Z

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Block/SupportsPeras.hs

+  deriving Show via Quiet PerasVoterId
+
+newtype PerasVoteStake = PerasVoteStake
+  { unPerasVoteStake :: Rational


I don't understand what exactly this Rational represents w.r.t. the stake amount. Are we just using Rational here to precisely represent a fractional value, or are we using the denominator to indicate the total stake (either across the committee or overall)? Should all of the PerasVoteStake values contained within a PerasVoteStakeDistr sum to exactly 1?

At the moment there is no consensus from researchers/engineers on how we go from the absolute stake of a voter in the ledger to the relative stake of their vote in the voting commitee (given that the quorum is expressed as a relative value of the voting commitee total stake). It is still being debated, cf. 2025/12/16 "Peras Acceleration meeting".

So you can consider this Rational as the best approximation we have at the moment of the concrete type for a relative vote stake that can be compared to the quorum value.

It'd be good to clarify the meaning of this in a comment 👍

Added a comment in a0c42b0

This commit introduces a couple of new types to represent Peras votes and their corresponding certificate forging API. Notably, this requires an initial representation of notions like vote targets, vote stakes and stake distributions over multiple stake pools. Co-authored-by: Agustin Mista <agustin.mista@moduscreate.com> Co-authored-by: Alexander Esgen <alexander.esgen@iohk.io> Co-authored-by: Georgy Lukyanov <georgy.lukyanov@iohk.io> Co-authored-by: Thomas BAGREL <thomas.bagrel@tweag.io> Co-authored-by: Nicolas BACQUEY <nicolas.bacquey@tweag.io>

Co-authored-by: Agustin Mista <agustin.mista@moduscreate.com> Co-authored-by: Alexander Esgen <alexander.esgen@iohk.io> Co-authored-by: Georgy Lukyanov <georgy.lukyanov@iohk.io> Co-authored-by: Thomas BAGREL <thomas.bagrel@tweag.io> Co-authored-by: Nicolas BACQUEY <nicolas.bacquey@tweag.io>

agustinmista self-assigned this Dec 8, 2025

agustinmista added the peras label Dec 8, 2025

agustinmista force-pushed the peras/main-pr/votedb-api branch from bf3a52c to 4063507 Compare December 9, 2025 10:39

agustinmista changed the title ~~[Peras 13] Add votes and voting API~~ [Peras 13] Add votes and vote forging API Dec 9, 2025

agustinmista changed the title ~~[Peras 13] Add votes and vote forging API~~ [Peras 13] Add votes and certificate forging API Dec 9, 2025

agustinmista force-pushed the peras/main-pr/votedb-api branch from 4063507 to 06f4e61 Compare December 9, 2025 10:53

agustinmista requested review from nbacquey and tbagrel1 December 9, 2025 11:00

agustinmista changed the title ~~[Peras 13] Add votes and certificate forging API~~ [Peras 13] Introduce votes and certificate forging API Dec 9, 2025

tbagrel1 approved these changes Dec 9, 2025

View reviewed changes

agustinmista marked this pull request as ready for review December 9, 2025 14:48

agustinmista requested review from bladyjoker, dnadales, fraser-iohk, geo2a, jasagredo and nfrisby as code owners December 9, 2025 14:48

tbagrel1 reviewed Dec 11, 2025

View reviewed changes

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Block/SupportsPeras.hs Outdated Show resolved Hide resolved

agustinmista force-pushed the peras/main-pr/votedb-api branch from 06f4e61 to 42bb662 Compare December 12, 2025 13:42

agustinmista force-pushed the peras/main-pr/new-defs-and-plumbing branch 2 times, most recently from c314f45 to bb97f3f Compare December 16, 2025 09:40

agustinmista force-pushed the peras/main-pr/votedb-api branch from 42bb662 to 4f2f0cc Compare December 16, 2025 10:08

jasagredo reviewed Dec 16, 2025

View reviewed changes

agustinmista force-pushed the peras/main-pr/new-defs-and-plumbing branch from bb97f3f to 43c1fdc Compare December 16, 2025 10:44

agustinmista force-pushed the peras/main-pr/votedb-api branch from 4f2f0cc to fd401fc Compare December 16, 2025 10:59

agustinmista force-pushed the peras/main-pr/new-defs-and-plumbing branch from 43c1fdc to e7eadb3 Compare December 16, 2025 12:00

agustinmista force-pushed the peras/main-pr/votedb-api branch from fd401fc to 0006522 Compare December 16, 2025 12:06

fraser-iohk reviewed Dec 17, 2025

View reviewed changes

agustinmista force-pushed the peras/main-pr/new-defs-and-plumbing branch from e7eadb3 to ecff70d Compare December 19, 2025 09:25

agustinmista force-pushed the peras/main-pr/votedb-api branch from 0006522 to d94393a Compare December 19, 2025 12:09

agustinmista force-pushed the peras/main-pr/votedb-api branch from d94393a to dff3d9b Compare December 19, 2025 12:17

agustinmista and others added 2 commits December 19, 2025 13:21

agustinmista force-pushed the peras/main-pr/votedb-api branch from dff3d9b to 4b0c1af Compare December 19, 2025 12:23

[Peras 13] Introduce votes and certificate forging API #1801

Are you sure you want to change the base?

[Peras 13] Introduce votes and certificate forging API #1801

Conversation

agustinmista commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tbagrel1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fraser-iohk Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

agustinmista commented Dec 8, 2025 •

edited

Loading

fraser-iohk Dec 17, 2025 •

edited

Loading