Implementers guide: update Collation types (#4084)

* Implementers guide: update Collation types

* Update roadmap/implementers-guide/src/node/collators/collation-generation.md

Co-authored-by: Andronik Ordian <write@reusable.software>

* Update roadmap/implementers-guide/src/node/collators/collation-generation.md

Co-authored-by: Andronik Ordian <write@reusable.software>

* Update roadmap/implementers-guide/src/node/collators/collation-generation.md

Co-authored-by: Andronik Ordian <write@reusable.software>

* Update roadmap/implementers-guide/src/node/collators/collation-generation.md

Co-authored-by: Andronik Ordian <write@reusable.software>

* Convert indents to 2 spaces

Co-authored-by: Andronik Ordian <write@reusable.software>

polkadot/roadmap/implementers-guide/src/node/collators/collation-generation.md

@@ -21,27 +21,49 @@ Output: `CollationDistributionMessage`
 The process of generating a collation for a parachain is very parachain-specific. As such, the details of how to do so are left beyond the scope of this description. The subsystem should be implemented as an abstract wrapper, which is aware of this configuration:
 
 ```rust
+/// The output of a collator.
+///
+/// This differs from `CandidateCommitments` in two ways:
+///
+/// - does not contain the erasure root; that's computed at the Polkadot level, not at Cumulus
+/// - contains a proof of validity.
 pub struct Collation {
   /// Messages destined to be interpreted by the Relay chain itself.
   pub upward_messages: Vec<UpwardMessage>,
+  /// The horizontal messages sent by the parachain.
+  pub horizontal_messages: Vec<OutboundHrmpMessage<ParaId>>,
   /// New validation code.
   pub new_validation_code: Option<ValidationCode>,
   /// The head-data produced as a result of execution.
   pub head_data: HeadData,
   /// Proof to verify the state transition of the parachain.
   pub proof_of_validity: PoV,
+  /// The number of messages processed from the DMQ.
+  pub processed_downward_messages: u32,
+  /// The mark which specifies the block number up to which all inbound HRMP messages are processed.
+  pub hrmp_watermark: BlockNumber,
 }
 
 /// Result of the [`CollatorFn`] invocation.
 pub struct CollationResult {
-	/// The collation that was build.
+  /// The collation that was build.
-	collation: Collation,
+  pub collation: Collation,
-	/// An optional result sender that should be informed about a successfully seconded collation.
+  /// An optional result sender that should be informed about a successfully seconded collation.
-	///
+  ///
-	/// There is no guarantee that this sender is informed ever about any result, it is completly okay to just drop it.
+  /// There is no guarantee that this sender is informed ever about any result, it is completely okay to just drop it.
-	/// However, if it is called, it should be called with the signed statement of a parachain validator seconding the
+  /// However, if it is called, it should be called with the signed statement of a parachain validator seconding the
-	/// collation.
+  /// collation.
-	result_sender: Option<oneshot::Sender<SignedFullStatement>>,
+  pub result_sender: Option<oneshot::Sender<CollationSecondedSignal>>,
+}
+
+/// Signal that is being returned when a collation was seconded by a validator.
+pub struct CollationSecondedSignal {
+  /// The hash of the relay chain block that was used as context to sign [`Self::statement`].
+  pub relay_parent: Hash,
+  /// The statement about seconding the collation.
+  ///
+  /// Anything else than `Statement::Seconded` is forbidden here.
+  pub statement: SignedFullStatement,
 }
 
 /// Collation function.
@@ -51,18 +73,22 @@ pub struct CollationResult {
 ///
 /// Returns an optional [`CollationResult`].
 pub type CollatorFn = Box<
-	dyn Fn(Hash, &PersistedValidationData) -> Pin<Box<dyn Future<Output = Option<CollationResult>> + Send>>
+  dyn Fn(
-		+ Send
+      Hash,
-		+ Sync,
+      &PersistedValidationData,
+    ) -> Pin<Box<dyn Future<Output = Option<CollationResult>> + Send>>
+    + Send
+    + Sync,
 >;
 
-struct CollationGenerationConfig {
+/// Configuration for the collation generator
-  key: CollatorPair,
+pub struct CollationGenerationConfig {
-  /// Collate will be called with the relay chain hash the parachain should build
+  /// Collator's authentication key, so it can sign things.
-  /// a block on and the `ValidationData` that provides information about the state
+  pub key: CollatorPair,
-  /// of the parachain on the relay chain.
+  /// Collation function. See [`CollatorFn`] for more details.
-  collator: CollatorFn,
+  pub collator: CollatorFn,
-  para_id: ParaId,
+  /// The parachain that this collator collates for
+  pub para_id: ParaId,
 }
 ```