Add a Statement Gossip Subsystem section to the implementors guide

roadmap/implementors-guide/guide.md

@@ -15,6 +15,8 @@ There are a number of other documents describing the research in more detail. Al
 * [Subsystems](#Subsystems)
   * [Overseer](#Overseer)
   * [Candidate Backing](#Candidate-Backing-Subsystem)
+  * [Statement Gossip](#Statement-Gossip-Subsystem)
+* [Gossip Protocols](#Gossip-Protocols)
 * [Data Structures and Types](#Data-Structures-and-Types)
 * [Glossary / Jargon](#Glossary)
 
@@ -989,12 +991,78 @@ Dispatch a `PovFetchSubsystemMessage(relay_parent, candidate_hash, sender)` and
 
 (TODO: send statements to Statement Distribution subsystem, handle shutdown signal from candidate backing subsystem)
 
+### Statement Gossip Subsystem
+
+The statement gossip subsystem is responsible for gossiping out and receiving [Signed Statements](#Signed-statement-type) from validators.
+
+#### Message Types
+
+This subsystem communicates with the overseer via [two message types](#Candidate-Backing-Subsystem-Messages), one for overseer -> subsystem and another for subsystem -> overseer. Currently this just differentiates between statements that the subsystem has been instructed to gossip out, and statements that the subsystem has received.
+
+#### Functionality
+
+The subsystem needs to contain a handle to a gossiping engine to gossip and recieve messages. This will be cloned into each job that is spawned. Apart from that, it also contains the general structures that all subsystems contain, e.g. channels to communicate with the overseer and handles to spawned jobs in order to shut them down.
+
+On `OverseerSignal::StartWork` it should:
+* Spawn a job and pass in `relay_parent`, a clone of the gossiping engine and a handle to a message validator.
+* Send out a neighbour packet with the `relay_parent` added to the list of accepted chain heads.
+
+On `OverseerSignal::StopWork` it should:
+* Stop the job via the job handle.
+* Send out a neighbour packet with the job's `relay_parent` removed.
+
+On `StatementGossipSubsystemMessageIn::StatementToGossip` it should:
+* Send the signed statement to the job running for the `relay_parent`.
+
+The statement gossip job needs to poll two seperate futures (as well as the exit signal):
+
+* A future that takes the passed-in statements, validates them and gossips them along with the `relay_parent` hash using the gossip engine.
+* A future that takes the messages that the gossip engine receives for the `relay_parent`, validates them and sends to the subsystem.
+
+#### Message Validation
+
+The following conditions needs to be met for an outgoing statement to be sent:
+
+* We must have 'peer knowledge' of what canidates the receiver knows about.
+* If the statement is `Valid` or `Invalid`, the receiver of the statement must know about the candidate that the hash refers to.
+* The statement signature must be valid.
+
+The following conditions need to be met for an incoming statement to be accepted:
+
+* The sender of the statement has to be in the validator set for the relay block.
+* If the statement is `Valid` or `Invalid`, then the candidate that the hash refers to must be known.
+* As only `MAX_CHAIN_HEADS` (currently set to 5) competing parachain heads are accepted at a time, if the statement is `Seconded`, then there must be less than `MAX_CHAIN_HEADS` other candidate receipts for the parachain block.
+* The statement signature must be valid.
+
+I have a basic implementation of this code on the [`ashley-test-statement-gossip-subsystem`](https://github.com/paritytech/polkadot/tree/ashley-test-statement-gossip-subsystem) branch.
+
+(TODO: Do we need a message type for sending a statemen directly to a peer?)  
+(TODO: We probably need to account for backpressure)
+
 ---
 
 [TODO: subsystems for gathering data necessary for block authorship, for networking, for misbehavior reporting, etc.]
 
 ----
 
+## Gossip Protocols
+
+A lot of a relay chain's communication happens via gossiping messages. To avoid this becoming an attack vector, we want to use [Bounded Gossip Protocols](https://github.com/w3f/research/blob/master/docs/polkadot/networking/0-overview.md#bounded-gossip-protocols).
+
+### Functionality
+
+Several components make up a gossiping system:
+
+* A network implementation, that contains things like the actual connections to peers.
+* A propagation pool of messages.
+
+When the node wants to gossip a message:
+* The message is put into the propagation pool and stays there until cleaned up.
+* The message is sent out to the nodes that it is currently connected to.
+
+When a new node connects to our node:
+* All messages in the propagation pool are sent to it, and we receive all of its propagation pool messages.
+
 ## Data Structures and Types
 
 [TODO]
@@ -1072,7 +1140,7 @@ enum OverseerSignal {
 ```
 
 
-#### Candidate Backing subsystem Message
+#### Candidate Backing Subsystem Message
 
 ```rust
 enum CandidateBackingSubsystemMessage {
@@ -1085,6 +1153,22 @@ enum CandidateBackingSubsystemMessage {
 }
 ```
 
+### Statement Gossip Subsystem Messages
+
+```rust
+enum StatementGossipSubsystemIn {
+  /// A statement to be gossiped out to validators.
+  StatementToGossip { relay_parent: Hash, statement: SignedStatement }
+}
+```
+
+```rust
+enum StatementGossipSubsystemOut {
+  /// A statement that we've received from a validator.
+  StatementReceived { relay_parent: Hash, statement: SignedStatement }
+}
+```
+
 #### Host Configuration
 
 The internal-to-runtime configuration of the parachain host. This is expected to be altered only by governance procedures.