Node-side subsystems for Disputes (#2566)

* dispute subsystem files

* rename

* fix linkcheck

* flesh out section README

* coordinator schema

* DisputeCoordinatorMessage

* stub & coordinator protocol

* dispute coordinator

* add some more message fields

* move links to bottom

* dispute participation

* Cleen It Up !

* runtime: store candidate receipts in dispute state

yeah, this is a little heavier. why are you reading this?

* Revert "runtime: store candidate receipts in dispute state"

This reverts commit 51c10bfd4d866e287e6bd88f317ed57ed987eaee.

* add dispute availability statement type and prepare for availability

* add 'spam slots' to disputes runtmie

* return Spam Slots info from runtime

* rework `ImportStatement` to `ImportStatements`

* some more methods for dispute coordinator

* candidates-included runtime API

* algo for providing disputes to runtime.

* handle signing with coordinator

* dispute coordinator chain ops

* remove dead file

* remove keystore from dispute participation

* adjust ApprovedAncestor to return the necssary data

* discuss how approved ancestor and determine undisputed chain are used together

* add TODO

* initiate disputes from approval voting

* route statements from candidate backing and approval voting

* fix guide build

polkadot/roadmap/implementers-guide/src/node/approval/approval-voting.md

@@ -134,7 +134,7 @@ struct State {
     earliest_session: SessionIndex,
     session_info: Vec<SessionInfo>,
     babe_epoch: Option<BabeEpoch>, // information about a cached BABE epoch.
-    keystore: KeyStorePtr,
+    keystore: KeyStore,
 
     // A scheduler which keeps at most one wakeup per hash, candidate hash pair and
     // maps such pairs to `Tick`s.
@@ -215,16 +215,18 @@ On receiving a `CheckAndImportApproval(indirect_approval_vote, response_channel)
   * Fetch the `CandidateEntry` from the indirect approval vote's `candidate_index`. If the block did not trigger inclusion of enough candidates, return `ApprovalCheckResult::Bad`.
   * Construct a `SignedApprovalVote` using the candidate hash and check against the validator's approval key, based on the session info of the block. If invalid or no such validator, return `ApprovalCheckResult::Bad`.
   * Send `ApprovalCheckResult::Accepted`
+  * Dispatch a [`DisputeCoordinatorMessage::ImportStatement`](../../types/overseer-protocol.md#dispute-coordinator-message) with the approval statement.
   * [Import the checked approval vote](#import-checked-approval)
 
 #### `ApprovalVotingMessage::ApprovedAncestor`
 
 On receiving an `ApprovedAncestor(Hash, BlockNumber, response_channel)`:
-  * Iterate over the ancestry of the hash all the way back to block number given, starting from the provided block hash.
-  * Keep track of an `all_approved_max: Option<(Hash, BlockNumber)>`.
+  * Iterate over the ancestry of the hash all the way back to block number given, starting from the provided block hash. Load the `CandidateHash`es from each block entry.
+  * Keep track of an `all_approved_max: Option<(Hash, BlockNumber, Vec<(Hash, Vec<CandidateHash>))>`.
   * For each block hash encountered, load the `BlockEntry` associated. If any are not found, return `None` on the response channel and conclude.
   * If the block entry's `approval_bitfield` has all bits set to 1 and `all_approved_max == None`, set `all_approved_max = Some((current_hash, current_number))`.
   * If the block entry's `approval_bitfield` has any 0 bits, set `all_approved_max = None`.
+  * If `all_approved_max` is `Some`, push the current block hash and candidate hashes onto the list of blocks and candidates `all_approved_max`.
   * After iterating all ancestry, return `all_approved_max`.
 
 ### Updates and Auxiliary Logic
@@ -278,7 +280,9 @@ On receiving an `ApprovedAncestor(Hash, BlockNumber, response_channel)`:
     * Wait for the available data
     * Issue a `CandidateValidationMessage::ValidateFromExhaustive` message
     * Wait for the result of validation
+    * Check that the result of validation, if valid, matches the commitments in the receipt.
     * If valid, issue a message on `background_tx` detailing the request.
+    * If any of the data, the candidate, or the commitments are invalid, issue on `background_tx` a [`DisputeCoordinatorMessage::IssueLocalStatement`](../../types/overseer-protocol.md#dispute-coordinator-message) with `valid = false` to initiate a dispute.
 
 #### Issue Approval Vote
   * Fetch the block entry and candidate entry. Ignore if `None` - we've probably just lost a race with finality.