Genesis Milestone 14: documentation #1174

nbacquey · 2024-07-01T17:17:37Z

This PR adds all documentation relevant to the Genesis syncing algorithm.

Co-authored-by: Facundo Domínguez <[email protected]> Co-authored-by: Nicolas BACQUEY <[email protected]> Co-authored-by: Nicolas Frisby <[email protected]> Co-authored-by: Nicolas “Niols” Jeannerod <[email protected]>

dnadales · 2024-09-10T08:35:23Z

docs/website/contents/for-developers/Genesis.md

@@ -0,0 +1,718 @@
+# Cardano Genesis
+
+This document is the High-Level Design for the addition of Ouroboros Genesis to the existing Cardano implementation of Ouroboros Praos.


Suggested change

This document is the High-Level Design for the addition of Ouroboros Genesis to the existing Cardano implementation of Ouroboros Praos.

This document contains the High-Level Design for adding Ouroboros Genesis to the existing Cardano implementation of Ouroboros Praos.

dnadales · 2024-09-10T08:36:27Z

docs/website/contents/for-developers/Genesis.md

+
+The following is taken for granted.
+
+- The reader is familir with the core architecture of the existing Praos implementation (ChainSync mini protocol, Block Fetch mini protocol and decision logic, etc).


Would it make sense to link to modules or documentation where the mini-protocols are defined and/or explained?

dnadales · 2024-09-10T08:39:51Z

docs/website/contents/for-developers/Genesis.md

+
+## Notation
+
+- {X Y Z} indicates the definition of X Y Z, helpful for use with search functionality, such as CTRL-F.


In the glossary, we use ;X Y Z, as discussed with @nfrisby a while ago. Shouldn't we use the same notation throughout? FWIW, I'm not sure the extra } helps when typing a search term. I'd say readers who will use the Ctrl+F functionality would probably type either ; or { plus a prefix of the definition they are looking for.

I see now that {X Y Z} is superior to the ; notation when creating an inlined definition. In that case, I suggest we change the notation in the Glossary to use the former as well.

dnadales · 2024-09-10T08:42:03Z

docs/website/contents/for-developers/Genesis.md

+- The reader is familir with the core architecture of the existing Praos implementation (ChainSync mini protocol, Block Fetch mini protocol and decision logic, etc).
+- The reader is aware of the motivation for Ouroboros Genesis ([paper](https://iohk.io/en/research/library/papers/ouroboros-genesis-composable-proof-of-stake-blockchains-with-dynamic-availability/) & [blog post](https://iohk.io/en/blog/posts/2023/02/09/ouroboros-genesis-enhanced-security-in-a-dynamic-environment/)) over Ouroboros Praos ([paper](https://iohk.io/en/research/library/papers/ouroboros-praos-an-adaptively-secure-semi-synchronous-proof-of-stake-protocol/)), ie safe decentralized syncing.
+
+## Notation


Shouldn't non-Genesis-exclusive terms such as "valency" or "Δ" also be in the glossary?

dnadales · 2024-09-10T08:46:01Z

docs/website/contents/for-developers/Genesis.md

+- {Sync Safety}: If the syncing node always has at least one peer that is honest, not itself syncing, and connected with reasonable latency and bandwidth to the syncing node as well as the honest network, then the syncing node will never select more than Kcp blocks of a chain that is not extended by a recent selection of some honest nodes in the network (ie approximately within Δ).
+  The antecedent of that implication is the {Honest Availability Assumption} ({HAA}).
+  It is beyond the scope of this design to ensure the HAA, but it seems viable even if non-trivial (see the Diffusion Layer's _Ledger Peers_ design).
+  It is important that the Sync Safety requirement directly prevents the original motivation for Ouroboros Genesis, the _long-range attack_.


Suggested change

It is important that the Sync Safety requirement directly prevents the original motivation for Ouroboros Genesis, the _long-range attack_.

It is important to note that the Sync Safety requirement directly prevents the _long-range attack_, which was the original motivation for Ouroboros Genesis.

dnadales · 2024-09-10T09:52:13Z

docs/website/contents/for-developers/Genesis.md

+
+In the "with CSJ" section below, the GDD is enriched beyond its primary responsibility for the sake of the CSJ design.
+
+To prevent this component from spoiling Sync Liveness, this relatively-expensive calculation is rate-limited with a parameter {GddRateLimit}; see the Parameter Tuning section.


Can we link to the parameter tuning section here?

dnadales · 2024-09-10T10:05:44Z

docs/website/contents/for-developers/Genesis.md

+```
+
+Suppose Adversary 1 is the Dynamo first, serves its chain up to the block 5-8, and then the peer disconnects.
+If Adversary 2 or 3 becomes the Dynamo and Adversary 3 or 2 becomes the Objector, then the (HAA-satisfying) honest peer is dormant as a PreObjector.


Shouldn't we use the same order? Otherwise it's a bit confusing. But maybe there's a reason for inverting the numbers.

Suggested change

If Adversary 2 or 3 becomes the Dynamo and Adversary 3 or 2 becomes the Objector, then the (HAA-satisfying) honest peer is dormant as a PreObjector.

If Adversary 2 or 3 becomes the Dynamo and Adversary 2 or 3 becomes the Objector, then the (HAA-satisfying) honest peer is dormant as a PreObjector.

dnadales · 2024-09-10T10:10:10Z

docs/website/contents/for-developers/Genesis.md

+
+### The Devoted BlockFetch Component
+
+> Note that in the code, this component is still called *BulkSync BlockFetch* at the moment.


Is there a reason why this component has not been renamed accordingly?

dnadales · 2024-09-10T10:31:45Z

docs/website/contents/for-developers/Genesis.md

+  If the LoP is spuriously disconnecting from honest nodes unacceptably often, then TCAP could be increased.
+  The duration for which an adversary could potentially leash the syncing node increases somewhat proportionally, but that's a less severe risk than the syncing node eclipsing itself.
+
+- GddRateLimit ~ 1 Hz.


I might have missed this, but why are we using this unit of measure?

dnadales · 2024-09-10T10:42:41Z

docs/website/contents/for-developers/Genesis.md

+   - Integrate GSM into the peer simulator and test for consecutive periods of Syncing and CaughtUp states.
+     This would require some rethinking on expressivity of the point schedules.
+   - Adjust genesis tests to allow for a non-zero GDD rate limit.
+     [WIP code here](https://github.com/IntersectMBO/ouroboros-consensus/commit/4ff3138e6b6bfaf06f7f9ba49bab4d8b1e77a969).


How are we going to ensure that this branch remains open? I can imagine that after a few years, if this improvement is not made, we might have to delete the branch because it has bitrot. Maybe a dead-links checker would suffice to detect this link is stale.

nbacquey added do-not-merge Genesis PRs related to Genesis testing and implementation labels Jul 1, 2024

Niols changed the base branch from main to genesis/milestone-13 July 3, 2024 11:46

facundominguez force-pushed the genesis/milestone-13 branch 2 times, most recently from 5680c0b to 53ea76c Compare July 11, 2024 17:28

Base automatically changed from genesis/milestone-13 to main July 11, 2024 19:12

Add Genesis keywords to the glossary

ec4b33b

amesgen force-pushed the genesis/milestone-14-documentation branch from 3b72b0a to ec4b33b Compare August 5, 2024 12:44

Add high-level Genesis documentation

97485fb

Co-authored-by: Facundo Domínguez <[email protected]> Co-authored-by: Nicolas BACQUEY <[email protected]> Co-authored-by: Nicolas Frisby <[email protected]> Co-authored-by: Nicolas “Niols” Jeannerod <[email protected]>

amesgen removed the do-not-merge label Aug 9, 2024

amesgen marked this pull request as ready for review August 9, 2024 13:55

amesgen requested review from nfrisby, jasagredo, amesgen, fraser-iohk, dnadales and RenateEilers as code owners August 9, 2024 13:55

nbacquey added the documentation Improvements or additions to documentation label Aug 12, 2024

dnadales approved these changes Sep 10, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Genesis Milestone 14: documentation #1174

Genesis Milestone 14: documentation #1174

nbacquey commented Jul 1, 2024 •

edited

Loading

dnadales Sep 10, 2024

dnadales Sep 10, 2024

dnadales Sep 10, 2024

dnadales Sep 10, 2024

dnadales Sep 10, 2024

dnadales Sep 10, 2024

dnadales Sep 10, 2024

dnadales Sep 10, 2024

dnadales Sep 10, 2024

dnadales Sep 10, 2024

dnadales Sep 10, 2024

		@@ -0,0 +1,718 @@
		# Cardano Genesis

		This document is the High-Level Design for the addition of Ouroboros Genesis to the existing Cardano implementation of Ouroboros Praos.

	This document is the High-Level Design for the addition of Ouroboros Genesis to the existing Cardano implementation of Ouroboros Praos.
	This document contains the High-Level Design for adding Ouroboros Genesis to the existing Cardano implementation of Ouroboros Praos.


		The following is taken for granted.

		- The reader is familir with the core architecture of the existing Praos implementation (ChainSync mini protocol, Block Fetch mini protocol and decision logic, etc).


		## Notation

		- {X Y Z} indicates the definition of X Y Z, helpful for use with search functionality, such as CTRL-F.

	It is important that the Sync Safety requirement directly prevents the original motivation for Ouroboros Genesis, the _long-range attack_.
	It is important to note that the Sync Safety requirement directly prevents the _long-range attack_, which was the original motivation for Ouroboros Genesis.


		In the "with CSJ" section below, the GDD is enriched beyond its primary responsibility for the sake of the CSJ design.

		To prevent this component from spoiling Sync Liveness, this relatively-expensive calculation is rate-limited with a parameter {GddRateLimit}; see the Parameter Tuning section.

	If Adversary 2 or 3 becomes the Dynamo and Adversary 3 or 2 becomes the Objector, then the (HAA-satisfying) honest peer is dormant as a PreObjector.
	If Adversary 2 or 3 becomes the Dynamo and Adversary 2 or 3 becomes the Objector, then the (HAA-satisfying) honest peer is dormant as a PreObjector.


		### The Devoted BlockFetch Component

		> Note that in the code, this component is still called BulkSync BlockFetch at the moment.

Genesis Milestone 14: documentation #1174

Are you sure you want to change the base?

Genesis Milestone 14: documentation #1174

Conversation

nbacquey commented Jul 1, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nbacquey commented Jul 1, 2024 •

edited

Loading