Notify collators about seconded collation (#2430)

* Notify collators about seconded collation

This pr adds functionality to inform a collator that its collation was
seconded by a parachain validator. Before this signed statement was only
gossiped over the validation substream. Now, we explicitly send the
seconded statement to the collator after it was validated successfully.

Besides that it changes the `CollatorFn` to return an optional result
sender that is informed when the build collation was seconded by a
parachain validator.

* Add test

* Make sure we only send `Seconded` statements

* Make sure we only receive valid statements

* Review feedback

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

@@ -32,8 +32,28 @@ pub struct Collation {
   pub proof_of_validity: PoV,
 }
 
-type CollatorFn = Box<
-  dyn Fn(Hash, &PeristedValidationData) -> Pin<Box<dyn Future<Output = Option<Collation>>>>
+/// Result of the [`CollatorFn`] invocation.
+pub struct CollationResult {
+	/// The collation that was build.
+	collation: 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.
+	/// However, if it is called, it should be called with the signed statement of a parachain validator seconding the
+	/// collation.
+	result_sender: Option<oneshot::Sender<SignedFullStatement>>,
+}
+
+/// Collation function.
+///
+/// Will be called with the hash of the relay chain block the parachain block should be build on and the
+/// [`ValidationData`] that provides information about the state of the parachain on the relay chain.
+///
+/// Returns an optional [`CollationResult`].
+pub type CollatorFn = Box<
+	dyn Fn(Hash, &PersistedValidationData) -> Pin<Box<dyn Future<Output = Option<CollationResult>> + Send>>
+		+ Send
+		+ Sync,
 >;
 
 struct CollationGenerationConfig {

polkadot/roadmap/implementers-guide/src/node/subsystems-and-jobs.md

@@ -257,24 +257,18 @@ with implementing a gossip protocol:
 sequenceDiagram
     participant SD as StatementDistribution
     participant NB as NetworkBridge
-    participant Listener
 
     alt On receipt of a<br/>SignedStatement from CandidateBacking
         % fn circulate_statement_and_dependents
         SD ->> NB: SendValidationMessage
 
         Note right of NB: Bridge sends validation message to all appropriate peers
-    else On initialization, from other subsystems:
-        Listener ->> SD: RegisterStatementListener
     else On receipt of peer validation message
         NB ->> SD: NetworkBridgeUpdateV1
 
         % fn handle_incoming_message
         alt if we aren't already aware of the relay parent for this statement
             SD ->> NB: ReportPeer
-        else the statement corresponds to our View
-            Note over SD,Listener: Forward the statement to each registered listener
-            SD ->> Listener: SignedFullStatement
         end
 
         % fn circulate_statement

polkadot/roadmap/implementers-guide/src/types/network.md

@@ -105,6 +105,8 @@ enum CollatorProtocolV1Message {
 	RequestCollation(RequestId, Hash, ParaId),
 	/// A requested collation.
 	Collation(RequestId, CandidateReceipt, CompressedPoV),
+	/// A collation sent to a validator was seconded.
+	CollationSeconded(SignedFullStatement),
 }
 ```
 

polkadot/roadmap/implementers-guide/src/types/overseer-protocol.md

@@ -234,10 +234,12 @@ These messages are sent to the [Candidate Selection subsystem](../node/backing/c
 
 ```rust
 enum CandidateSelectionMessage {
-  /// A candidate collation can be fetched from a collator and should be considered for seconding.
-  Collation(RelayParent, ParaId, CollatorId),
-  /// We recommended a particular candidate to be seconded, but it was invalid; penalize the collator.
-  Invalid(CandidateReceipt),
+    /// A candidate collation can be fetched from a collator and should be considered for seconding.
+    Collation(RelayParent, ParaId, CollatorId),
+    /// We recommended a particular candidate to be seconded, but it was invalid; penalize the collator.
+    Invalid(RelayParent, CandidateReceipt),
+    /// The candidate we recommended to be seconded was validated successfully.
+    Seconded(RelayParent, SignedFullStatement),
 }
 ```
 
@@ -290,15 +292,20 @@ enum CollatorProtocolMessage {
     ///
     /// This should be sent before any `DistributeCollation` message.
     CollateOn(ParaId),
-    /// Provide a collation to distribute to validators.
-    DistributeCollation(CandidateReceipt, PoV),
+    /// Provide a collation to distribute to validators with an optional result sender.
+    ///
+    /// The result sender should be informed when at least one parachain validator seconded the collation. It is also
+    /// completely okay to just drop the sender.
+    DistributeCollation(CandidateReceipt, PoV, Option<oneshot::Sender<SignedFullStatement>>),
     /// Fetch a collation under the given relay-parent for the given ParaId.
     FetchCollation(Hash, ParaId, ResponseChannel<(CandidateReceipt, PoV)>),
     /// Report a collator as having provided an invalid collation. This should lead to disconnect
     /// and blacklist of the collator.
     ReportCollator(CollatorId),
     /// Note a collator as having provided a good collation.
-    NoteGoodCollation(CollatorId),
+    NoteGoodCollation(CollatorId, SignedFullStatement),
+    /// Notify a collator that its collation was seconded.
+    NotifyCollationSeconded(CollatorId, SignedFullStatement),
 }
 ```
 
@@ -539,8 +546,6 @@ enum StatementDistributionMessage {
     /// The statement distribution subsystem assumes that the statement should be correctly
     /// signed.
     Share(Hash, SignedFullStatement),
-    /// Register a listener to be notified on any new statements.
-    RegisterStatementListener(ResponseChannel<SignedFullStatement>),
 }
 ```