Genesis Milestone 14: documentation #1174
Conversation
nbacquey
added
do-not-merge
Genesis
facundominguez
force-pushed
the
genesis/milestone-13
branch
2 times, most recently
from
5680c0b
to
53ea76c
Compare
amesgen
force-pushed
the
genesis/milestone-14-documentation
branch
from
3b72b0a
to
ec4b33b
Compare
Co-authored-by: Facundo Domínguez <facundominguez@gmail.com> Co-authored-by: Nicolas BACQUEY <nicolas.bacquey@tweag.io> Co-authored-by: Nicolas Frisby <nick.frisby@iohk.io> Co-authored-by: Nicolas “Niols” Jeannerod <nicolas.jeannerod@tweag.io>
amesgen
requested review from
nfrisby,
jasagredo,
amesgen,
fraser-iohk,
dnadales and
RenateEilers
as code owners
| @@ -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. | |||
There was a problem hiding this comment.
| 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). |
There was a problem hiding this comment.
Would it make sense to link to modules or documentation where the mini-protocols are defined and/or explained?
|
|
||
| ## Notation | ||
|
|
||
| - {X Y Z} indicates the definition of X Y Z, helpful for use with search functionality, such as CTRL-F. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| - 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 |
There was a problem hiding this comment.
Shouldn't non-Genesis-exclusive terms such as "valency" or "Δ" also be in the glossary?
| - {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_. |
There was a problem hiding this comment.
| 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. |
There was a problem hiding this comment.
Can we link to the parameter tuning section here?
| ``` | ||
|
|
||
| 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. |
There was a problem hiding this comment.
Shouldn't we use the same order? Otherwise it's a bit confusing. But maybe there's a reason for inverting the numbers.
| 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. |
There was a problem hiding this comment.
Is there a reason why this component has not been renamed accordingly?
| 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. |
There was a problem hiding this comment.
I might have missed this, but why are we using this unit of measure?
| - 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). |
There was a problem hiding this comment.
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.
This PR adds all documentation relevant to the Genesis syncing algorithm.