[WIP] CIP draft #396
[WIP] CIP draft #396
Conversation
There was a problem hiding this comment.
thanks @will-break-it for inviting review from the CIP community. I've also read through the rest of the text in the same branch and it looks like it will be well in order for posting as a CIP pull request as soon as the bulk of TODO items are completed.
docs/cip/README.md
Outdated
| **Five-Stage Pipeline**: The protocol operates through a structured five-stage pipeline: (1) **Propose** - IBs generated uniformly, (2) **Deliver 1** - IB diffusion using freshest-first strategy, (3) **Deliver 2** - complete IB delivery, (4) **Endorse** - EBs generated at stage start, (5) **Vote** - voting on EBs and certificate creation. This pipeline approach enables concurrent transaction processing while maintaining deterministic ordering and conflict resolution. | ||
|
|
||
| **Input Blocks (IBs)**: Transaction-containing blocks produced at a uniform rate during the "Propose" stage of each [pipeline](#pipeline). IBs are generated by stake pools that win VRF-based [sortition](#sortition), with the protocol utilizing approximately one-third of available network bandwidth for IB traffic. Multiple IBs can be produced concurrently across the network. | ||
|
|
||
| **Endorser Blocks (EBs)**: Aggregation blocks that reference multiple IBs from the current pipeline. EBs are produced at the beginning of the "Endorse" stage by selected stake pools. An EB represents a consensus view of which IBs should be included in the permanent ledger, referencing all IBs that were delivered by specific pipeline deadlines. | ||
|
|
||
| **Votes and Certificates**: During the "Vote" stage, stake pools [vote](#vote) on EBs if they meet strict criteria: all referenced IBs must be available, all IBs seen by the "Deliver 1" deadline must be referenced, and all referenced IBs must validate. When enough votes are collected (achieving a [quorum](#quorum)), a [certificate](#certificate) is created and included in an RB. | ||
|
|
||
| **Ranking Blocks (RBs)**: The main Praos consensus chain blocks that contain at most one certificate per block, attesting to the validity of an EB. RBs anchor the Leios consensus into the established Praos security model and may also contain regular transactions. |
There was a problem hiding this comment.
| **Five-Stage Pipeline**: The protocol operates through a structured five-stage pipeline: (1) **Propose** - IBs generated uniformly, (2) **Deliver 1** - IB diffusion using freshest-first strategy, (3) **Deliver 2** - complete IB delivery, (4) **Endorse** - EBs generated at stage start, (5) **Vote** - voting on EBs and certificate creation. This pipeline approach enables concurrent transaction processing while maintaining deterministic ordering and conflict resolution. | |
| **Input Blocks (IBs)**: Transaction-containing blocks produced at a uniform rate during the "Propose" stage of each [pipeline](#pipeline). IBs are generated by stake pools that win VRF-based [sortition](#sortition), with the protocol utilizing approximately one-third of available network bandwidth for IB traffic. Multiple IBs can be produced concurrently across the network. | |
| **Endorser Blocks (EBs)**: Aggregation blocks that reference multiple IBs from the current pipeline. EBs are produced at the beginning of the "Endorse" stage by selected stake pools. An EB represents a consensus view of which IBs should be included in the permanent ledger, referencing all IBs that were delivered by specific pipeline deadlines. | |
| **Votes and Certificates**: During the "Vote" stage, stake pools [vote](#vote) on EBs if they meet strict criteria: all referenced IBs must be available, all IBs seen by the "Deliver 1" deadline must be referenced, and all referenced IBs must validate. When enough votes are collected (achieving a [quorum](#quorum)), a [certificate](#certificate) is created and included in an RB. | |
| **Ranking Blocks (RBs)**: The main Praos consensus chain blocks that contain at most one certificate per block, attesting to the validity of an EB. RBs anchor the Leios consensus into the established Praos security model and may also contain regular transactions. | |
| ##### Five-Stage Pipeline | |
| The protocol operates through a structured five-stage pipeline: (1) **Propose** - IBs generated uniformly, (2) **Deliver 1** - IB diffusion using freshest-first strategy, (3) **Deliver 2** - complete IB delivery, (4) **Endorse** - EBs generated at stage start, (5) **Vote** - voting on EBs and certificate creation. This pipeline approach enables concurrent transaction processing while maintaining deterministic ordering and conflict resolution. | |
| ##### Input Blocks (IBs) | |
| Transaction-containing blocks produced at a uniform rate during the "Propose" stage of each [pipeline](#pipeline). IBs are generated by stake pools that win VRF-based [sortition](#sortition), with the protocol utilizing approximately one-third of available network bandwidth for IB traffic. Multiple IBs can be produced concurrently across the network. | |
| ##### Endorser Blocks (EBs) | |
| Aggregation blocks that reference multiple IBs from the current pipeline. EBs are produced at the beginning of the "Endorse" stage by selected stake pools. An EB represents a consensus view of which IBs should be included in the permanent ledger, referencing all IBs that were delivered by specific pipeline deadlines. | |
| ##### Votes and Certificates | |
| During the "Vote" stage, stake pools [vote](#vote) on EBs if they meet strict criteria: all referenced IBs must be available, all IBs seen by the "Deliver 1" deadline must be referenced, and all referenced IBs must validate. When enough votes are collected (achieving a [quorum](#quorum)), a [certificate](#certificate) is created and included in an RB. | |
| ##### Ranking Blocks (RBs) | |
| The main Praos consensus chain blocks that contain at most one certificate per block, attesting to the validity of an EB. RBs anchor the Leios consensus into the established Praos security model and may also contain regular transactions. |
The rest of the document currently has no sections for elaboration of these components. Therefore these should have their own headers — rather than inline headings — to make these definitions deep-linkable. I believe making this information accessible is more important than any goal of keeping this information textually dense.
There was a problem hiding this comment.
References
Optional
There is such abundant information here for readers at any level — including development & discussion history for so much of this material — that I would editorially support adding a link here from the Abstract to ensure the reader knows early that it's available... rather than having them wait until the final References section.
ch1bo
force-pushed
the
cip/review
branch
2 times, most recently
from
452236a to
737b8ec
Compare
|
FWIW, I have started to write down more things on this branch and my approval is moot. @will-break-it should we create a new branch / PR for our soon-to-be-more-complete specification section with the phased approach? |
cip: apply review Co-authored-by: Robert Phair <[email protected]>
* docs: add collateralized transaction * docs: fix source links * docs: shorten notes * docs(cddl): remove uneeded block body hash * docs(cddl): remove IB header shard id as it can be derived from the VRF * docs: headline fix * docs(cddl): add sharded reward account * docs(cddl): fix formula * docs(cddl): add collateral tx field for reward accounts * docs(cddl): add more context for sharded reward account * docs(cddl): clarify sharding benefits * docs(cddl): clarify shard assignment for reward account
|
🔧 Auto-formatter applied - Figure captions standardized and links validated. |
|
🔧 Auto-formatter applied - Figure captions standardized and links validated. |
Also includes: - Fix vote eligibility determination by clarifying election_id uses EB's announcing RB slot - Disable auto-formatting GitHub Action to prevent unwanted changes
- Clarify that election_id must use EB's announcing RB slot number for deterministic sortition - Add detailed explanation of vote eligibility requirements for verifiable consensus - Disable GitHub Actions auto-formatting to prevent unwanted document changes
- Keep critical vote eligibility determination fixes in CIP README - Restore GitHub Actions auto-formatting workflow - Remove accidentally added formal-spec symlink - Restore original VS Code workspace settings
|
🔧 Auto-formatter applied - Figure captions standardized and links validated. |
|
🔧 Auto-formatter applied - Generated TOC, table of figures/tables, removed trailing periods, and formatted markdown with proper line length. |
|
🔧 Auto-formatter applied - Generated TOC, table of figures/tables, removed trailing periods, and formatted markdown with proper line length. |
| ### Non-normative overview of Leios | ||
| The protocol's behavior is governed by a **rolling window mechanism** that | ||
| tracks certificate inclusion timing. When a committee successfully certifies an | ||
| EB, this triggers a rolling window of $L_\text{recover}$ slots during which the |
There was a problem hiding this comment.
may also say here: "and the certificate is included in an RB". Certification on its own is not sufficient to enter Leios mode.
| <div align="center"> | ||
| <a name="figure-4" id="figure-4"></a> | ||
| <p name="protocol-flow-figure"> | ||
| <img src="images/protocol-flow-overview.svg" alt="Leios Protocol Flow"> |
There was a problem hiding this comment.
Maybe move the L_vote part closer to the EB, to better highlight that the time start when the EB is created.
| extended header fields to optionally certify one previously announced EB and | ||
| optionally announce one EB for the next subsequent RB to certify. | ||
| 1. **[Endorser Block (EB)](#endorser-blocks-ebs)** A larger block containing | ||
| additional transaction references. There are no other ways to create EBs. |
There was a problem hiding this comment.
There are no other ways to create EBs.
Maybe this is an overkill and should be removed.
|
|
||
| ##### Key registration | ||
| Nodes receiving the RB header discover the announced EB, via its referencing by |
There was a problem hiding this comment.
It is not that clear here if the RB header was received as part of chain dissemination or through a separate mechanism (which should be the case)
| Altogether, a key registration occupies $28 + 96 + 2 \times 48 + 448 = 668$ bytes. This registration needs to be recorded on chain so that certificates can be later verified independently. Ideally, the BLS keys would be registered as part of the SPO's *operational certificate*, which is renewed every ninety days. | ||
| 1. It has received the EB within $L_\text{vote}$ slots from its creation, | ||
| 2. It has **not** received an equivocated RB header for this EB within | ||
| $L_\text{vote}$ slots, |
There was a problem hiding this comment.
3 \Delta_\text{hdr} instead of L_vote here
| <div align="center"> | ||
| <a name="figure-5" id="figure-5"></a> | ||
| <p name="mode-transitions-figure"> | ||
| <img src="images/protocol-flow-detail.svg" alt="Rolling Window Timeline"> |
There was a problem hiding this comment.
I would suggest changing EB1 and EB2 to EB2 and EB4 to match the index of the RBs. It is somewhat confusing; EB1 sounds like it is related to RB1.
|
|
||
| **Enhanced Throughput** (within window): Block producers are permitted to create | ||
| RBs before receiving all previously certified EBs due to network delays. Since | ||
| they cannot determine complete ledger state, Leios allows temporary inclusion of |
There was a problem hiding this comment.
maybe say Leios cannot prevent temporary inclusion of unvalidated txs.
Our suggestion is to create empty blocks if you are not up to date, and we may punish inclusion of invalid txs.
| certificate-active periods (RB<sub>3</sub> to RB<sub>7</sub> inclusive, marked | ||
| with red dashed borders) are permitted to contain such transactions. | ||
|
|
||
| **Correction Mechanisms**: To maintain ledger integrity when unvalidated |
There was a problem hiding this comment.
Maybe highlight that these mechanisms are solely for the benefit of light nodes. Full nodes can check whether a tx was executed when they catch up.
| than $L$<sub>recover</sub> slots after the latest EB certificate, the | ||
| `tx_execution_bitmap` field must indicate the execution status of transactions | ||
| in RBs produced after that EB certificate was included, up to but not including | ||
| this correcting RB. This ensures the ledger state is fully determined before |
There was a problem hiding this comment.
This is only for the benefit of light nodes.
| > [!WARNING] **TODO:** Add transaction confirmation levels and their | ||
| > implications for applications | ||
|
|
||
| Transactions from certified EBs are included in the ledger alongside direct RB |
There was a problem hiding this comment.
Maybe say that txs from certified EBs are included before txs directly included in the RB to preserve correctness.
Rendered Version