guide: new dispute inherent flow

roadmap/implementers-guide/src/node/disputes/dispute-coordinator.md

@@ -32,18 +32,21 @@ struct CandidateVotes {
     invalid: Vec<(InvalidDisputeStatementKind, ValidatorIndex, ValidatorSignature)>,
 }
 
-// The implication of a dispute for a block containing the candidate.
-enum BlockImplication {
-    // A dispute which is ongoing or has concluded against a candidate
-    // implies that any blocks containing it should be avoided.
-    Avoid,
-    // A dispute which has had supermajority approval is fine to accept.
-    Accept,
+// The status of the dispute.
+enum DisputeStatus {
+  // Dispute is still active.
+  Active,
+  // Dispute concluded positive (2/3 supermajority) along with what
+  // timestamp it concluded at.
+  ConcludedPositive(Timestamp),
+  // Dispute concluded negative (2/3 supermajority, takes precedence over
+  // positive in the case of many double-votes).
+  ConcludedNegative(Timestamp),
 }
 
 struct RecentDisputes {
     // sorted by session index and then by candidate hash.
-    disputed: Vec<(SessionIndex, CandidateHash, BlockImplication)>,
+    disputed: Vec<(SessionIndex, CandidateHash, DisputeStatus)>,
 }
 ```
 
@@ -97,15 +100,19 @@ Do nothing.
 * Add an entry to the respective `valid` or `invalid` list of the `CandidateVotes` for each statement in `statements`.
 * Write the `CandidateVotes` to the underyling DB.
 * If the both `valid` and `invalid` lists now have non-zero length where previously one or both had zero length, the candidate is now freshly disputed.
-* If freshly disputed, load `"recent-disputes"` and add the candidate hash and session index with an `Avoid` implication. Also issue a [`DisputeParticipationMessage::Participate`][DisputeParticipationMessage].
-* If the dispute now has supermajority votes in the "valid" direction, according to the `SessionInfo` of the dispute candidate's session, the `BlockImplication` should be set to 'Accept'. The dispute will be pruned after some time.
-* If the dispute now has supermajority votes in the "invalid" direction, the `BlockImplication` should be set to `Avoid`. It will be pruned after some time and all chains containing the disputed block will be reverted by the runtime.
+* If freshly disputed, load `"recent-disputes"` and add the candidate hash and session index with an `Active` status. Also issue a [`DisputeParticipationMessage::Participate`][DisputeParticipationMessage].
+* If the dispute now has supermajority votes in the "valid" direction, according to the `SessionInfo` of the dispute candidate's session, the `DisputeStatus` should be set to `ConcludedPositive(now)` unless it was already `ConcludedNegative`.
+* If the dispute now has supermajority votes in the "invalid" direction, the `DisputeStatus` should be set to `ConcludedNegative(now)`. If it was `ConcludedPositive` before, the timestamp `now` should be copied from the previous status. It will be pruned after some time and all chains containing the disputed block will be reverted by the runtime and chain-selection subsystem.
 * Write `"recent-disputes"`
 
 ### On `DisputeCoordinatorMessage::RecentDisputes`
 
 * Load `"recent-disputes"` and return the data contained within.
 
+### On `DisputeCoordinatorMessage::ActiveDisputes`
+
+* Load `"recent-disputes"` and filter out any disputes which have been concluded for over 5 minutes. Return the filtered data
+
 ### On `DisputeCoordinatorMessage::QueryCandidateVotes`
 
 * Load `"candidate-votes"` and return the data within or `None` if missing.
@@ -125,7 +132,7 @@ Do nothing.
 * Deconstruct into parts `{ base_number, block_descriptions, rx }`
 * Starting from the beginning of `block_descriptions`:
   1. Check the `RecentDisputes` for a dispute of each candidate in the block description.
-  1. If there is a dispute which has an `Avoid` implication, exit the loop.
+  1. If there is a dispute which is active or concluded negative, exit the loop.
 * For the highest index `i` reached in the `block_descriptions`, send `(base_number + i + 1, block_hash)` on the channel, unless `i` is 0, in which case `None` should be sent. The `block_hash` is determined by inspecting `block_descriptions[i]`.
 
 [DisputeTypes]: ../../types/disputes.md

roadmap/implementers-guide/src/node/utility/provisioner.md

@@ -75,25 +75,11 @@ The end result of this process is a vector of `BackedCandidate`s, sorted in orde
 
 This is the point at which the block author provides further votes to active disputes or initiates new disputes in the runtime state.
 
-We must take care not to overwhelm the "spam slots" of the chain. That is, to avoid too many votes from the same validators being placed into the chain, which would trigger the anti-spam protection functionality of the [disputes module](../../runtime/disputes.md).
+The block-authoring logic of the runtime has an extra step between handling the inherent-data and producing the actual inherent call, which we assume performs the work of filtering out disputes which are not relevant to the on-chain state.
 
 To select disputes:
 
-- Make a `DisputesInfo` runtime API call and decompose into `{ spam_slots, disputes }`. Bind `disputes` to `onchain_disputes`.
-- Issue a `DisputeCoordinatorMessage::ActiveDisputes` message and wait for the response. Assign the value to `offchain_disputes`.
-- Make a `CandidatesIncluded` runtime API call for each dispute in `offchain_disputes` and tag each offchain dispute as local if the result for it is `true`.
-- Initialize `NewSpamSlots: Map<(SessionIndex, ValidatorIndex), u32>` as an empty map.
-- For each dispute in `offchain_disputes`:
-  1. Make a `RuntimeApiRequest::SessionInfo` against the parent hash for the session of the dispute. If `None`, continue - this chain is in the past relative to the session the dispute belongs to and we can import it when it reaches that session.
-  1. Load the spam slots from `spam_slots` for the given session. If it isn't present, treat as though all zeros.
-  1. construct a `DisputeStatementSet` of all offchain votes we are aware of that the onchain doesn't already have a `valid` or `invalid` bit set for, respectively.
-  1. If the `onchain_disputes` contains an entry for the dispute, load that. Otherwise, treat as empty.
-  1. If the offchain dispute is local or the `DisputeStatementSet` and the onchain dispute together have at least `byzantine_threshold + 1` validators in it, continue to the next offchain dispute.
-  1. Otherwise
-    1. Filter out all votes from the `DisputeStatementSet` where the amount of spam slots occupied on-chain by the validator, plus the `NewSpamSlots` value, plus 1, is greater than `spam_slots.max_spam_slots`.
-    1. After filtering, if either the `valid` or `invalid` lists in the combination of the `DisputeStatementSet` and the onchain dispute is empty, skip this dispute.
-    1. Add 1 to the `NewSpamSlots` value for each validator in the `DisputeStatementSet`.
-- Construct a `MultiDisputeStatementSet` for each `DisputeStatement` and return that.
+- Issue a `DisputeCoordinatorMessage::RecentDisputes` message and wait for the response. This is a set of all disputes in recent sessions which we are aware of.
 
 ### Determining Bitfield Availability
 

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

@@ -440,7 +440,11 @@ enum DisputeCoordinatorMessage {
         /// successfully.
         pending_confirmation: oneshot::Sender<()>,
     },
+    /// Fetch a list of all recent disputes that the co-ordinator is aware of.
+    /// These are disputes which have occured any time in recent sessions, which may have already concluded.
+    RecentDisputes(ResponseChannel<Vec<(SessionIndex, CandidateHash)>>),
     /// Fetch a list of all active disputes that the co-ordinator is aware of.
+    /// These disputes are either unconcluded or recently concluded.
     ActiveDisputes(ResponseChannel<Vec<(SessionIndex, CandidateHash)>>),
     /// Get candidate votes for a candidate.
     QueryCandidateVotes(SessionIndex, CandidateHash, ResponseChannel<Option<CandidateVotes>>),