[Peras #1] Introduce basic types to support Peras #1673

tbagrel1 · 2025-09-11T10:16:11Z

This pull request introduces some base datatypes and functionality required for Peras, along with supporting tests, benchmarks, and documentation.

Specifically, it adds:

PerasWeight and PerasCert, which associate a weight with a block.
PerasWeightSnapshot, a type for capturing the known weight state of blocks
Functions for computing weights of chains and fragments.
Tests, microbenchmarks, documentation, and runnable examples for weight-related utilities.

Peras types and weight computation

Added module Ouroboros.Consensus.Block.SupportsPeras, defining types and logic for Peras weights and certificates.
- Key elements are re-exported via Ouroboros.Consensus.Block.
Added module Ouroboros.Consensus.Peras.Weight, introducing PerasWeightSnapshot and weight computation functions for chains and fragments.

Documentation

Added glossary entries for Peras, weight boost, and chain fragment weight in glossary.md.
Created a new benchmarks page explaining how to run Peras-related microbenchmarks and their purpose.

Tests and benchmarks

Introduced benchmark suite PerasCertDB-bench, including a weight computation microbenchmark (bench/PerasCertDB-bench/Main.hs).
Added module Test.Consensus.Peras.WeightSnapshot with property-based tests for weight computation on chains and fragments.

Regression

The new code added with this PR is not actually used, so it shouldn't introduce regressions.

Co-authored-by: Agustin Mista <[email protected]> Co-authored-by: Alexander Esgen <[email protected]> Co-authored-by: Georgy Lukyanov <[email protected]> Co-authored-by: Thomas BAGREL <[email protected]> Co-authored-by: Nicolas BACQUEY <[email protected]> Co-authored-by: Nicolas "Niols" Jeannerod <[email protected]>

dnadales · 2025-09-19T14:56:52Z

ouroboros-consensus/bench/PerasCertDB-bench/Main.hs

+import Test.Tasty.Bench
+
+data BenchmarkParams = BenchmarkParams
+  { blockRate :: SlotNo


Aren't rates expressed as ratios? This might be a misnomer.

Changed to

{ slotGap :: Word64 -- ^ The slot gap between blocks on the fragments, ie the inverse of the -- active slot coefficient.

in 7faa0d1

dnadales · 2025-09-19T14:58:16Z

ouroboros-consensus/bench/PerasCertDB-bench/Main.hs

+  { blockRate :: SlotNo
+  -- ^ How often the fragments will contain blocks, in slots
+  , fragmentLenghtSamplingRate :: Natural
+  -- ^ The rate of length increase for generate chain fragments


"generated"?

Also the comment does not seem to refer to sampling. I wonder if this field deserves a better explanation.

Changed to

, fragmentLengthStepSize :: Natural -- ^ Step size for the fragment lengths between different benchmarks.

in 7faa0d1

dnadales · 2025-09-19T14:58:40Z

ouroboros-consensus/bench/PerasCertDB-bench/Main.hs

+  , fragmentLenghtSamplingRate :: Natural
+  -- ^ The rate of length increase for generate chain fragments
+  , fragmentMaxLenght :: Natural
+  -- ^ the maximum length of a fragment


Suggested change

-- ^ the maximum length of a fragment

-- ^ The maximum length of a fragment

Does this Natural express a number of slots?

Does this Natural express a number of slots?

It is a number of blocks, added to the comment in 7faa0d1

ouroboros-consensus/bench/PerasCertDB-bench/Main.hs

dnadales · 2025-09-19T15:01:03Z

ouroboros-consensus/bench/PerasCertDB-bench/Main.hs

+--   implemented by the by the
+--   'Ouroboros.Consensus.Peras.Weight.weightBoostOfFragment' function.
+--
+--   We benchmark the calculation on a static sequence of chain fragments of increasing


Wouldn't it make sense to refer to benchmarkParams directly. Otherwise we'll have to modify this comment as well if we alter said variable.

Good idea, done in 7faa0d1

dnadales · 2025-09-19T15:24:00Z

ouroboros-consensus/test/consensus-test/Test/Consensus/Peras/WeightSnapshot.hs

+  snap = mkPerasWeightSnapshot $ Map.toList tsWeights
+
+  weightBoostOfPointReference :: Point TestBlock -> PerasWeight
+  weightBoostOfPointReference pt = Map.findWithDefault mempty pt tsWeights


Aren't we re-implementing weightBoostOfPoint here?

weightBoostOfPoint (PerasWeightSnapshot weightByPoint) pt = Map.findWithDefault mempty pt weightByPoint

If so, I wonder if this test adds much value. It seems a couple of unit tests would be more useful.

Yes, though the actual implementation also changes in #1613, just like you already mentioned in #1673 (comment)

So the tests are currently a bit degenerate indeed; I think it is a good idea to add some simple unit tests and a property like you suggest in #1673 (comment) 👍

Actually, we already have unit tests in this PR via the doctests in the main module, which are also checked via CI since #1622.

ouroboros-consensus/test/consensus-test/Test/Consensus/Peras/WeightSnapshot.hs

dnadales · 2025-09-19T15:30:30Z

ouroboros-consensus/test/consensus-test/Test/Consensus/Peras/WeightSnapshot.hs

+    "PerasWeightSnapshot"
+    [ testProperty "correctness" prop_perasWeightSnapshot
+    ]
+


I wonder if we could express the correctness through some algebraic properties that need not copy the implementation. Something like:

weight [] = empty weight (x:xs) = weight x <> weight xs

Added this (slightly generalized) in c4959e2

dnadales · 2025-09-19T15:32:16Z

ouroboros-consensus/test/consensus-test/Test/Consensus/Peras/WeightSnapshot.hs

+
+  shrink ts =
+    concat
+      [ [ ts{tsWeights = Map.fromList tsWeights'}


Can't we shrink the map directly to avoid a fromList/toList conversion?

AFAICT this would require an Arbitrary instance for Point TestBlock, and I don't really see a good way to shrink individual points without further contexts.

dnadales · 2025-09-19T15:33:01Z

ouroboros-consensus/test/consensus-test/Test/Consensus/Peras/WeightSnapshot.hs

+      [ [ ts{tsWeights = Map.fromList tsWeights'}
+        | tsWeights' <-
+            shrinkList
+              -- Shrink boosted points to have weight 1.


Why assigning them weight 1 instead of shrinking the weight as well?

Yeah, we could shrink the weight incrementally (reducing it until it is 1 and then remove the point).

Done in 28e845e

fraser-iohk · 2025-09-23T13:13:39Z

ouroboros-consensus/bench/PerasCertDB-bench/Main.hs

+data BenchmarkParams = BenchmarkParams
+  { blockRate :: SlotNo
+  -- ^ How often the fragments will contain blocks, in slots
+  , fragmentLenghtSamplingRate :: Natural


this should be length

Fixed in 7faa0d1

fraser-iohk · 2025-09-23T13:15:47Z

ouroboros-consensus/bench/PerasCertDB-bench/Main.hs

+import Test.Tasty.Bench
+
+data BenchmarkParams = BenchmarkParams
+  { blockRate :: SlotNo


separately to Damian's comment, is this using SlotNo to represent to a period between two different slots? if so, should it be a different SlotPeriod or SlotDifference type?

It is a slot gap 👍 We sadly don't have a dedicated type for that, eg the HFC uses just Word64 (see eg countSlots). I changed it to Word64 for consistency in 7faa0d1.

(Long-term, we could adopt some proper torsor stuff for this common relationship of absolute values and "distances" between them)

fraser-iohk · 2025-09-23T16:41:02Z

ouroboros-consensus/test/consensus-test/Test/Consensus/Peras/WeightSnapshot.hs

+  deriving stock Show
+
+instance Arbitrary TestSetup where
+  arbitrary = do


could this arbitrary be split out a bit so things have names / type annotations and it's a bit easier to follow?

Good point, I added comments and factored out some stuff in ef2d685

amesgen added the Peras label Sep 11, 2025

tbagrel1 force-pushed the main-pr/basic-peras-types branch from d3cd2fc to 8df7902 Compare September 12, 2025 07:59

tbagrel1 changed the title ~~Introduce basic types to support Peras~~ [Peras #1] Introduce basic types to support Peras Sep 12, 2025

tbagrel1 force-pushed the main-pr/basic-peras-types branch 4 times, most recently from 738daaf to f3fbd4f Compare September 16, 2025 11:36

tbagrel1 marked this pull request as ready for review September 16, 2025 12:59

tbagrel1 requested review from nfrisby, jasagredo, amesgen, fraser-iohk, dnadales and geo2a as code owners September 16, 2025 12:59

tbagrel1 and others added 4 commits September 16, 2025 15:49

tbagrel1 force-pushed the main-pr/basic-peras-types branch from f3fbd4f to 01e1c69 Compare September 16, 2025 13:50

tbagrel1 mentioned this pull request Sep 17, 2025

[Peras #2] Introduce PerasCertDB and related tests #1674

Draft

dnadales added this to Consensus Team Backlog Sep 19, 2025

dnadales moved this to 👀 In review in Consensus Team Backlog Sep 19, 2025

dnadales assigned amesgen Sep 19, 2025

dnadales reviewed Sep 19, 2025

View reviewed changes

fraser-iohk reviewed Sep 23, 2025

View reviewed changes

amesgen added 4 commits September 23, 2025 20:32

fixup! Add microbenchmarks for PerasWeightSnapshot

7faa0d1

fixup! Add tests for PerasWeightSnapshot

ef2d685

fixup! Add tests for PerasWeightSnapshot

28e845e

fixup! Add tests for PerasWeightSnapshot

c4959e2

	-- ^ the maximum length of a fragment
	-- ^ The maximum length of a fragment

[Peras #1] Introduce basic types to support Peras #1673

Are you sure you want to change the base?

[Peras #1] Introduce basic types to support Peras #1673

Conversation

tbagrel1 commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Peras types and weight computation

Documentation

Tests and benchmarks

Regression

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!

Choose a reason for hiding this comment

Uh oh!

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!

amesgen Sep 19, 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!

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!

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!

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!

tbagrel1 commented Sep 11, 2025 •

edited

Loading

amesgen Sep 19, 2025 •

edited

Loading