impl guide: Update Collator Generation (#7250)

* impl guide: Update Collator Generation

* Address review comments

* Fix compile errors

I don't remember why I did this. Maybe it only made sense with the async backing
changes.

* Remove leftover glossary

polkadot/node/collation-generation/src/lib.rs

@@ -15,6 +15,17 @@
 // along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
 
 //! 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.
+//!   * 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)]
 

polkadot/roadmap/implementers-guide/src/node/collators/README.md

 # 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.

polkadot/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,34 @@ 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**
 
-* 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)`.
+  - Contains collator's authentication key, collator function, and
+    parachain ID.
 
 [CP]: collator-protocol.md
-[CPM]: ../../types/overseer-protocol.md#collatorprotocolmessage