From bfbdd295a43d7a7a73035db7657a19ff41f2306a Mon Sep 17 00:00:00 2001 From: Marcin S Date: Thu, 18 May 2023 09:06:37 -0400 Subject: [PATCH 1/4] impl guide: Update Collator Generation --- node/collation-generation/src/lib.rs | 13 ++ node/overseer/src/lib.rs | 1 - .../src/node/collators/README.md | 3 + .../node/collators/collation-generation.md | 119 +++++++++++++++--- 4 files changed, 118 insertions(+), 18 deletions(-) diff --git a/node/collation-generation/src/lib.rs b/node/collation-generation/src/lib.rs index 79ef490f505c..6101c4d4b19d 100644 --- a/node/collation-generation/src/lib.rs +++ b/node/collation-generation/src/lib.rs @@ -15,6 +15,19 @@ // along with Polkadot. If not, see . //! The collation generation subsystem is the interface between polkadot and the collators. +//! +//! # Protocol +//! +//! On every `ActiveLeavesUpdate`: +//! +//! * If there is no collation generation config, ignore. +//! * Otherwise, for each `activated` head in the update: +//! * Determine if the para is scheduled on any core by fetching the `availability_cores` Runtime API. +//! * Determine an occupied core assumption to make about the para. Scheduled cores can make [`OccupiedCoreAssumption::Free`]. +//! * TODO: What does this mean? +//! * Use the Runtime API subsystem to fetch the full validation data. +//! * Invoke the `collator`, and use its outputs to produce a [`CandidateReceipt`], signed with the configuration's `key`. +//! * Dispatch a [`CollatorProtocolMessage::DistributeCollation`](receipt, pov)`. #![deny(missing_docs)] diff --git a/node/overseer/src/lib.rs b/node/overseer/src/lib.rs index a2d553779fdc..09a101fd8f40 100644 --- a/node/overseer/src/lib.rs +++ b/node/overseer/src/lib.rs @@ -554,7 +554,6 @@ pub struct Overseer { #[subsystem(CollatorProtocolMessage, sends: [ NetworkBridgeTxMessage, - RuntimeApiMessage, CandidateBackingMessage, ])] collator_protocol: CollatorProtocol, diff --git a/roadmap/implementers-guide/src/node/collators/README.md b/roadmap/implementers-guide/src/node/collators/README.md index ae29697bb120..3642e415efab 100644 --- a/roadmap/implementers-guide/src/node/collators/README.md +++ b/roadmap/implementers-guide/src/node/collators/README.md @@ -1,3 +1,6 @@ # Collators Collators are special nodes which bridge a parachain to the relay chain. They are simultaneously full nodes of the parachain, and at least light clients of the relay chain. Their overall contribution to the system is the generation of Proofs of Validity for parachain candidates. + +The **Collation Generation** subsystem triggers collators to produce collations +and then forwards them to **Collator Protocol** to circulate to validators. diff --git a/roadmap/implementers-guide/src/node/collators/collation-generation.md b/roadmap/implementers-guide/src/node/collators/collation-generation.md index d7c62fee39f8..8f8fbe5fef38 100644 --- a/roadmap/implementers-guide/src/node/collators/collation-generation.md +++ b/roadmap/implementers-guide/src/node/collators/collation-generation.md @@ -4,17 +4,32 @@ The collation generation subsystem is executed on collator nodes and produces ca ## Protocol -Input: `CollationGenerationMessage` +Collation generation for Parachains currently works in the following way: -```rust -enum CollationGenerationMessage { - Initialize(CollationGenerationConfig), -} -``` +1. A new relay chain block is imported. +2. The collation generation subsystem checks if the core associated to + the parachain is free and if yes, continues. +3. Collation generation calls our collator callback to generate a PoV. +4. Authoring logic determines if the current node should build a PoV. +5. Build new PoV and give it back to collation generation. + +## Messages -No more than one initialization message should ever be sent to the collation generation subsystem. +### Incoming -Output: `CollationDistributionMessage` +- `ActiveLeaves` + - Notification of a change in the set of active leaves. + - Triggers collation generation procedure outlined in "Protocol" section. +- `CollationGenerationMessage::Initialize` + - Initializes the subsystem. Carries a config. + - No more than one initialization message should ever be sent to the collation + generation subsystem. + - Sent by a collator to initialize this subsystem. + +### Outgoing + +- `CollatorProtocolMessage::DistributeCollation` + - Provides a generated collation to distribute to validators. ## Functionality @@ -94,15 +109,85 @@ pub struct CollationGenerationConfig { The configuration should be optional, to allow for the case where the node is not run with the capability to collate. -On `ActiveLeavesUpdate`: +### Summary in plain English + +- **Collation (output of a collator)** + + - Contains the PoV (proof to verify the state transition of the + parachain) and other data. + +- **Collation result** + + - Contains the collation, and an optional result sender for a + collation-seconded signal. + +- **Collation seconded signal** + + - The signal that is returned when a collation was seconded by a + validator. + +- **Collation function** + + - Called with the relay chain block the parablock will be built on top + of. + - Called with the validation data. + - Provides information about the state of the parachain on the relay + chain. + +- **Collation generation config** + + - Contains collator's authentication key, collator function, and + parachain ID. + +## With Async Backing + +### Protocol + +- This will be more complicated as block production isn't bound to + importing a relay chain block anymore. + +- Parachains will build new blocks in fixed time frames as standalone + chains are doing this, e.g. every 6 seconds. + +- To support this we will need to separate the logic that determines + when to build a block, from the logic that determines on which relay + chain block to build. + +### When to build + +- For determining on when to build a new block we can reuse the slots + logic from Substrate. +- We will let it run with the requested slot duration of the Parachain. +- Then we will implement a custom `SlotWorker`. + - Every time this slot worker is triggered we will need to trigger + some logic to determine the next relay chain block to build on top + of. + - It will return the relay chain block in which context the block + should be built on, and the parachain block to build on top of. + +### On which relay block to build + +- This logic should be generic and should support sync / async backing. +- For **synchronous backing** we will check the best relay chain block + to check if the core of our parachain is free. + - The parachain slot should be calculated based on the timestamp and + this should be calculated using `relay_chain_slot * slot_duration`. +- For **asynchronous backing** we will be more free to choose the block + to build on, as we can also build on older relay chain blocks as well. + - We will probably need some kind of runtime api for the Parachain to + check if we want to build on a given relay chain block. + - So, for example to reject building too many parachain blocks on the + same relay chain block. + - The parachain slot should be calculated based on the timestamp and + this should be calculating using `relay_chain_slot * slot_duration + + parachain_slot_duration * unincluded_segment_len`. + +## Glossary + +- *Slot:* Time is divided into discrete slots. Each validator in the validator + set produces a verifiable random value, using a VRF, per slot. If below a + threshold, this allows the validator to author a new block for that slot. -* If there is no collation generation config, ignore. -* Otherwise, for each `activated` head in the update: - * Determine if the para is scheduled on any core by fetching the `availability_cores` Runtime API. - * Determine an occupied core assumption to make about the para. Scheduled cores can make `OccupiedCoreAssumption::Free`. - * Use the Runtime API subsystem to fetch the full validation data. - * Invoke the `collator`, and use its outputs to produce a `CandidateReceipt`, signed with the configuration's `key`. - * Dispatch a [`CollatorProtocolMessage`][CPM]`::DistributeCollation(receipt, pov)`. +- *VRF:* Verifiable random function. [CP]: collator-protocol.md -[CPM]: ../../types/overseer-protocol.md#collatorprotocolmessage From d2e70301b441b13c87ed987ebcfdaf72f74768e8 Mon Sep 17 00:00:00 2001 From: Marcin S Date: Fri, 19 May 2023 13:34:21 -0400 Subject: [PATCH 2/4] Address review comments --- node/collation-generation/src/lib.rs | 2 - .../node/collators/collation-generation.md | 43 ------------------- 2 files changed, 45 deletions(-) diff --git a/node/collation-generation/src/lib.rs b/node/collation-generation/src/lib.rs index 6101c4d4b19d..03935732d719 100644 --- a/node/collation-generation/src/lib.rs +++ b/node/collation-generation/src/lib.rs @@ -23,8 +23,6 @@ //! * If there is no collation generation config, ignore. //! * Otherwise, for each `activated` head in the update: //! * Determine if the para is scheduled on any core by fetching the `availability_cores` Runtime API. -//! * Determine an occupied core assumption to make about the para. Scheduled cores can make [`OccupiedCoreAssumption::Free`]. -//! * TODO: What does this mean? //! * Use the Runtime API subsystem to fetch the full validation data. //! * Invoke the `collator`, and use its outputs to produce a [`CandidateReceipt`], signed with the configuration's `key`. //! * Dispatch a [`CollatorProtocolMessage::DistributeCollation`](receipt, pov)`. diff --git a/roadmap/implementers-guide/src/node/collators/collation-generation.md b/roadmap/implementers-guide/src/node/collators/collation-generation.md index 8f8fbe5fef38..8468702afdbd 100644 --- a/roadmap/implementers-guide/src/node/collators/collation-generation.md +++ b/roadmap/implementers-guide/src/node/collators/collation-generation.md @@ -139,49 +139,6 @@ The configuration should be optional, to allow for the case where the node is no - Contains collator's authentication key, collator function, and parachain ID. -## With Async Backing - -### Protocol - -- This will be more complicated as block production isn't bound to - importing a relay chain block anymore. - -- Parachains will build new blocks in fixed time frames as standalone - chains are doing this, e.g. every 6 seconds. - -- To support this we will need to separate the logic that determines - when to build a block, from the logic that determines on which relay - chain block to build. - -### When to build - -- For determining on when to build a new block we can reuse the slots - logic from Substrate. -- We will let it run with the requested slot duration of the Parachain. -- Then we will implement a custom `SlotWorker`. - - Every time this slot worker is triggered we will need to trigger - some logic to determine the next relay chain block to build on top - of. - - It will return the relay chain block in which context the block - should be built on, and the parachain block to build on top of. - -### On which relay block to build - -- This logic should be generic and should support sync / async backing. -- For **synchronous backing** we will check the best relay chain block - to check if the core of our parachain is free. - - The parachain slot should be calculated based on the timestamp and - this should be calculated using `relay_chain_slot * slot_duration`. -- For **asynchronous backing** we will be more free to choose the block - to build on, as we can also build on older relay chain blocks as well. - - We will probably need some kind of runtime api for the Parachain to - check if we want to build on a given relay chain block. - - So, for example to reject building too many parachain blocks on the - same relay chain block. - - The parachain slot should be calculated based on the timestamp and - this should be calculating using `relay_chain_slot * slot_duration + - parachain_slot_duration * unincluded_segment_len`. - ## Glossary - *Slot:* Time is divided into discrete slots. Each validator in the validator From b0956f4f506452b45ccc48e710a297d0d7db4379 Mon Sep 17 00:00:00 2001 From: Marcin S Date: Fri, 19 May 2023 13:50:41 -0400 Subject: [PATCH 3/4] Fix compile errors I don't remember why I did this. Maybe it only made sense with the async backing changes. --- node/overseer/src/lib.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/node/overseer/src/lib.rs b/node/overseer/src/lib.rs index 09a101fd8f40..a2d553779fdc 100644 --- a/node/overseer/src/lib.rs +++ b/node/overseer/src/lib.rs @@ -554,6 +554,7 @@ pub struct Overseer { #[subsystem(CollatorProtocolMessage, sends: [ NetworkBridgeTxMessage, + RuntimeApiMessage, CandidateBackingMessage, ])] collator_protocol: CollatorProtocol, From a8d84142c616b50f580f2d3e9e48853ff2c05162 Mon Sep 17 00:00:00 2001 From: Marcin S Date: Sun, 21 May 2023 14:07:26 -0400 Subject: [PATCH 4/4] Remove leftover glossary --- .../src/node/collators/collation-generation.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/roadmap/implementers-guide/src/node/collators/collation-generation.md b/roadmap/implementers-guide/src/node/collators/collation-generation.md index 8468702afdbd..2f0d4742496d 100644 --- a/roadmap/implementers-guide/src/node/collators/collation-generation.md +++ b/roadmap/implementers-guide/src/node/collators/collation-generation.md @@ -139,12 +139,4 @@ The configuration should be optional, to allow for the case where the node is no - Contains collator's authentication key, collator function, and parachain ID. -## Glossary - -- *Slot:* Time is divided into discrete slots. Each validator in the validator - set produces a verifiable random value, using a VRF, per slot. If below a - threshold, this allows the validator to author a new block for that slot. - -- *VRF:* Verifiable random function. - [CP]: collator-protocol.md