Disputes runtime

node/core/approval-voting/src/lib.rs

@@ -38,15 +38,13 @@ use polkadot_primitives::v1::{
 	ValidatorIndex, Hash, SessionIndex, SessionInfo, CandidateHash,
 	CandidateReceipt, BlockNumber, PersistedValidationData,
 	ValidationCode, CandidateDescriptor, ValidatorPair, ValidatorSignature, ValidatorId,
-	CandidateIndex, GroupIndex,
+	CandidateIndex, GroupIndex, ApprovalVote,
 };
 use polkadot_node_primitives::{ValidationResult, PoV};
 use polkadot_node_primitives::approval::{
-	IndirectAssignmentCert, IndirectSignedApprovalVote, ApprovalVote, DelayTranche,
-	BlockApprovalMeta,
+	IndirectAssignmentCert, IndirectSignedApprovalVote, DelayTranche, BlockApprovalMeta,
 };
 use polkadot_node_jaeger as jaeger;
-use parity_scale_codec::Encode;
 use sc_keystore::LocalKeystore;
 use sp_consensus::SyncOracle;
 use sp_consensus_slots::Slot;
@@ -1226,15 +1224,6 @@ async fn handle_approved_ancestor(
 	Ok(all_approved_max)
 }
 
-fn approval_signing_payload(
-	approval_vote: ApprovalVote,
-	session_index: SessionIndex,
-) -> Vec<u8> {
-	const MAGIC: [u8; 4] = *b"APPR";
-
-	(MAGIC, approval_vote, session_index).encode()
-}
-
 // `Option::cmp` treats `None` as less than `Some`.
 fn min_prefer_some<T: std::cmp::Ord>(
 	a: Option<T>,
@@ -1466,10 +1455,8 @@ fn check_and_import_approval<T>(
 		None => respond_early!(ApprovalCheckResult::Bad)
 	};
 
-	let approval_payload = approval_signing_payload(
-		ApprovalVote(approved_candidate_hash),
-		block_entry.session(),
-	);
+	let approval_payload = ApprovalVote(approved_candidate_hash)
+		.signing_payload(block_entry.session());
 
 	let pubkey = match session_info.validators.get(approval.validator.0 as usize) {
 		Some(k) => k,
@@ -2167,10 +2154,7 @@ fn sign_approval(
 ) -> Option<ValidatorSignature> {
 	let key = keystore.key_pair::<ValidatorPair>(public).ok().flatten()?;
 
-	let payload = approval_signing_payload(
-		ApprovalVote(candidate_hash),
-		session_index,
-	);
+	let payload = ApprovalVote(candidate_hash).signing_payload(session_index);
 
 	Some(key.sign(&payload[..]))
 }

node/core/approval-voting/src/tests.rs

@@ -231,7 +231,7 @@ fn sign_approval(
 	candidate_hash: CandidateHash,
 	session_index: SessionIndex,
 ) -> ValidatorSignature {
-	key.sign(&super::approval_signing_payload(ApprovalVote(candidate_hash), session_index)).into()
+	key.sign(&ApprovalVote(candidate_hash).signing_payload(session_index)).into()
 }
 
 #[derive(Clone)]

node/primitives/src/approval.rs

@@ -98,10 +98,6 @@ pub struct IndirectAssignmentCert {
 	pub cert: AssignmentCert,
 }
 
-/// A vote of approval on a candidate.
-#[derive(Debug, Clone, Encode, Decode)]
-pub struct ApprovalVote(pub CandidateHash);
-
 /// A signed approval vote which references the candidate indirectly via the block.
 ///
 /// In practice, we have a look-up from block hash and candidate index to candidate hash,

primitives/src/v0.rs

@@ -672,6 +672,14 @@ pub enum CompactStatement {
 	Valid(CandidateHash),
 }
 
+impl CompactStatement {
+	/// Yields the payload used for validator signatures on this kind
+	/// of statement.
+	pub fn signing_payload(&self, context: &SigningContext) -> Vec<u8> {
+		(self, context).encode()
+	}
+}
+
 // Inner helper for codec on `CompactStatement`.
 #[derive(Encode, Decode)]
 enum CompactStatementInner {

primitives/src/v1/mod.rs

@@ -842,6 +842,22 @@ pub struct SessionInfo {
 	pub needed_approvals: u32,
 }
 
+/// A vote of approval on a candidate.
+#[derive(Clone, RuntimeDebug)]
+pub struct ApprovalVote(pub CandidateHash);
+
+impl ApprovalVote {
+	/// Yields the signing payload for this approval vote.
+	pub fn signing_payload(
+		&self,
+		session_index: SessionIndex,
+	) -> Vec<u8> {
+		const MAGIC: [u8; 4] = *b"APPR";
+
+		(MAGIC, &self.0, session_index).encode()
+	}
+}
+
 sp_api::decl_runtime_apis! {
 	/// The API for querying the state of parachains on-chain.
 	pub trait ParachainHost<H: Decode = Hash, N: Encode + Decode = BlockNumber> {
@@ -1039,6 +1055,11 @@ pub enum ConsensusLog {
 	/// number in the current chain, inclusive.
 	#[codec(index = 3)]
 	ForceApprove(BlockNumber),
+	/// A dispute has concluded with supermajority against a candidate. Block authors
+	/// should no longer build on top of this head and should instead revert to the
+	/// block at the given height which is the last known valid block in this chain.
+	#[codec(index = 4)]
+	Revert(BlockNumber),
 }
 
 impl ConsensusLog {
@@ -1081,10 +1102,10 @@ pub enum ValidDisputeStatementKind {
 	Explicit,
 	/// A seconded statement on a candidate from the backing phase.
 	#[codec(index = 1)]
-	BackingSeconded,
+	BackingSeconded(Hash),
 	/// A valid statement on a candidate from the backing phase.
 	#[codec(index = 2)]
-	BackingValid,
+	BackingValid(Hash),
 	/// An approval vote from the approval checking phase.
 	#[codec(index = 3)]
 	ApprovalChecking,
@@ -1099,7 +1120,7 @@ pub enum InvalidDisputeStatementKind {
 }
 
 /// An explicit statement on a candidate issued as part of a dispute.
-#[derive(Encode, Decode, Clone, PartialEq, RuntimeDebug)]
+#[derive(Clone, PartialEq, RuntimeDebug)]
 pub struct ExplicitDisputeStatement {
 	/// Whether the candidate is valid
 	pub valid: bool,
@@ -1109,6 +1130,15 @@ pub struct ExplicitDisputeStatement {
 	pub session: SessionIndex,
 }
 
+impl ExplicitDisputeStatement {
+	/// Produce the payload used for signing this type of statement.
+	pub fn signing_payload(&self) -> Vec<u8> {
+		const MAGIC: [u8; 4] = *b"DISP";
+
+		(MAGIC, self.valid, self.candidate_hash, self.session).encode()
+	}
+}
+
 /// A set of statements about a specific candidate.
 #[derive(Encode, Decode, Clone, PartialEq, RuntimeDebug)]
 pub struct DisputeStatementSet {
@@ -1124,7 +1154,7 @@ pub struct DisputeStatementSet {
 pub type MultiDisputeStatementSet = Vec<DisputeStatementSet>;
 
 /// The entire state of a dispute.
-#[derive(Encode, Decode, Clone, RuntimeDebug)]
+#[derive(Encode, Decode, Clone, RuntimeDebug, PartialEq)]
 pub struct DisputeState<N = BlockNumber> {
 	/// A bitfield indicating all validators for the candidate.
 	pub validators_for: BitVec<bitvec::order::Lsb0, u8>, // one bit per validator.
@@ -1149,6 +1179,19 @@ pub struct InherentData<HDR: HeaderT = Header> {
 	pub parent_header: HDR,
 }
 
+/// The maximum number of validators `f` which may safely be faulty.
+///
+/// The total number of validators is `n = 3f + e` where `e in { 1, 2, 3 }`.
+pub fn byzantine_threshold(n: usize) -> usize {
+	n.saturating_sub(1) / 3
+}
+
+/// The supermajority threshold of validators which represents a subset
+/// guaranteed to have at least f+1 honest validators.
+pub fn supermajority_threshold(n: usize) -> usize {
+	n - byzantine_threshold(n)
+}
+
 #[cfg(test)]
 mod tests {
 	use super::*;
@@ -1199,4 +1242,28 @@ mod tests {
 			&Hash::repeat_byte(4),
 		);
 	}
+
+	#[test]
+	fn test_byzantine_threshold() {
+		assert_eq!(byzantine_threshold(0), 0);
+		assert_eq!(byzantine_threshold(1), 0);
+		assert_eq!(byzantine_threshold(2), 0);
+		assert_eq!(byzantine_threshold(3), 0);
+		assert_eq!(byzantine_threshold(4), 1);
+		assert_eq!(byzantine_threshold(5), 1);
+		assert_eq!(byzantine_threshold(6), 1);
+		assert_eq!(byzantine_threshold(7), 2);
+	}
+
+	#[test]
+	fn test_supermajority_threshold() {
+		assert_eq!(supermajority_threshold(0), 0);
+		assert_eq!(supermajority_threshold(1), 1);
+		assert_eq!(supermajority_threshold(2), 2);
+		assert_eq!(supermajority_threshold(3), 3);
+		assert_eq!(supermajority_threshold(4), 3);
+		assert_eq!(supermajority_threshold(5), 4);
+		assert_eq!(supermajority_threshold(6), 5);
+		assert_eq!(supermajority_threshold(7), 5);
+	}
 }

roadmap/implementers-guide/src/runtime/disputes.md

@@ -42,11 +42,12 @@ Included: double_map (SessionIndex, CandidateHash) -> Option<BlockNumber>,
 // fewer than `byzantine_threshold + 1` validators.
 //
 // The i'th entry of the vector corresponds to the i'th validator in the session.
-SpamSlots: map SessionIndex -> Vec<u32>,
-// Whether the chain is frozen or not. Starts as `false`. When this is `true`,
-// the chain will not accept any new parachain blocks for backing or inclusion.
-// It can only be set back to `false` by governance intervention.
-Frozen: bool,
+SpamSlots: map SessionIndex -> Option<Vec<u32>>,
+// Whether the chain is frozen or not. Starts as `None`. When this is `Some`,
+// the chain will not accept any new parachain blocks for backing or inclusion,
+// and its value indicates the last valid block number in the chain.
+// It can only be set back to `None` by governance intervention.
+Frozen: Option<BlockNumber>,
 ```
 
 > `byzantine_threshold` refers to the maximum number `f` of validators which may be byzantine. The total number of validators is `n = 3f + e` where `e in { 1, 2, 3 }`.
@@ -65,7 +66,6 @@ Frozen: bool,
 ## Routines
 
 * `provide_multi_dispute_data(MultiDisputeStatementSet) -> Vec<(SessionIndex, Hash)>`:
-  1. Fail if any disputes in the set are duplicate or concluded before the `config.dispute_post_conclusion_acceptance_period` window relative to now.
   1. Pass on each dispute statement set to `provide_dispute_data`, propagating failure.
   1. Return a list of all candidates who just had disputes initiated.
 
@@ -75,18 +75,18 @@ Frozen: bool,
   1. If there is no dispute under `Disputes`, create a new `DisputeState` with blank bitfields.
   1. If `concluded_at` is `Some`, and is `concluded_at + config.post_conclusion_acceptance_period < now`, return false.
   1. If the overlap of the validators in the `DisputeStatementSet` and those already present in the `DisputeState` is fewer in number than `byzantine_threshold + 1` and the candidate is not present in the `Included` map
-    1. increment `SpamSlots` for each validator in the `DisputeStatementSet` which is not already in the `DisputeState`. Initialize the `SpamSlots` to a zeroed vector first, if necessary.
-    1. If the value for any spam slot exceeds `config.dispute_max_spam_slots`, return false.
+      1. increment `SpamSlots` for each validator in the `DisputeStatementSet` which is not already in the `DisputeState`. Initialize the `SpamSlots` to a zeroed vector first, if necessary. do not increment `SpamSlots` if the candidate is local.
+      1. If the value for any spam slot exceeds `config.dispute_max_spam_slots`, return false.
   1. If the overlap of the validators in the `DisputeStatementSet` and those already present in the `DisputeState` is at least `byzantine_threshold + 1`, the `DisputeState` has fewer than `byzantine_threshold + 1` validators, and the candidate is not present in the `Included` map, decrement `SpamSlots` for each validator in the `DisputeState`.
-  1. Import all statements into the dispute. This should fail if any statements are duplicate; if the corresponding bit for the corresponding validator is set in the dispute already.
-  1. If `concluded_at` is `None`, reward all statements slightly less.
+  1. Import all statements into the dispute. This should fail if any statements are duplicate or if the corresponding bit for the corresponding validator is set in the dispute already.
+  1. If `concluded_at` is `None`, reward all statements.
   1. If `concluded_at` is `Some`, reward all statements slightly less.
-  1. If either side now has supermajority, slash the other side. This may be both sides, and we support this possibility in code, but note that this requires validators to participate on both sides which has negative expected value. Set `concluded_at` to `Some(now)`.
+  1. If either side now has supermajority and did not previously, slash the other side. This may be both sides, and we support this possibility in code, but note that this requires validators to participate on both sides which has negative expected value. Set `concluded_at` to `Some(now)` if it was `None`.
   1. If just concluded against the candidate and the `Included` map contains `(session, candidate)`: invoke `revert_and_freeze` with the stored block number.
   1. Return true if just initiated, false otherwise.
 
 * `disputes() -> Vec<(SessionIndex, CandidateHash, DisputeState)>`: Get a list of all disputes and info about dispute state.
-  1. Iterate over all disputes in `Disputes`. Set the flag according to `concluded`.
+  1. Iterate over all disputes in `Disputes` and collect into a vector.
 
 * `note_included(SessionIndex, CandidateHash, included_in: BlockNumber)`:
   1. Add `(SessionIndex, CandidateHash)` to the `Included` map with `included_in - 1` as the value.
@@ -95,9 +95,10 @@ Frozen: bool,
 
 * `could_be_invalid(SessionIndex, CandidateHash) -> bool`: Returns whether a candidate has a live dispute ongoing or a dispute which has already concluded in the negative.
 
-* `is_frozen()`: Load the value of `Frozen` from storage.
+* `is_frozen()`: Load the value of `Frozen` from storage. Return true if `Some` and false if `None`.
 
-* `revert_and_freeze(BlockNumber):
+* `last_valid_block()`: Load the value of `Frozen` from storage and return. None indicates that all blocks in the chain are potentially valid.
+
+* `revert_and_freeze(BlockNumber)`:
   1. If `is_frozen()` return.
-  1. issue a digest in the block header which indicates the chain is to be abandoned back to the stored block number.
-  1. Set `Frozen` to true.
+  1. Set `Frozen` to `Some(BlockNumber)` to indicate a rollback to the given block number is necessary.

roadmap/implementers-guide/src/types/disputes.md

@@ -33,8 +33,8 @@ Kinds of dispute statements. Each of these can be combined with a candidate hash
 ```rust
 enum ValidDisputeStatementKind {
     Explicit,
-    BackingSeconded,
-    BackingValid,
+    BackingSeconded(Hash),
+    BackingValid(Hash),
     ApprovalChecking,
 }
 

runtime/kusama/src/lib.rs

@@ -52,6 +52,7 @@ use runtime_parachains::hrmp as parachains_hrmp;
 use runtime_parachains::scheduler as parachains_scheduler;
 use runtime_parachains::reward_points as parachains_reward_points;
 use runtime_parachains::runtime_api_impl::v1 as parachains_runtime_api_impl;
+use runtime_parachains::disputes as parachains_disputes;
 
 use xcm::v0::{MultiLocation::{self, Null, X1}, NetworkId, BodyId, Xcm, Junction::Parachain};
 use xcm::v0::MultiAsset::{self, AllConcreteFungible};
@@ -1085,7 +1086,15 @@ impl parachains_hrmp::Config for Runtime {
 	type Currency = Balances;
 }
 
-impl parachains_paras_inherent::Config for Runtime {}
+impl parachains_disputes::Config for Runtime {
+	type Event = Event;
+	type RewardValidators = ();
+	type PunishValidators = ();
+}
+
+impl parachains_paras_inherent::Config for Runtime {
+	type DisputesHandler = ();
+}
 
 impl parachains_scheduler::Config for Runtime {}
 
@@ -1462,6 +1471,7 @@ construct_runtime! {
 		ParasUmp: parachains_ump::{Pallet, Call, Storage, Event} = 59,
 		ParasHrmp: parachains_hrmp::{Pallet, Call, Storage, Event} = 60,
 		ParasSessionInfo: parachains_session_info::{Pallet, Call, Storage} = 61,
+		ParasDisputes: parachains_disputes::{Pallet, Call, Storage, Event<T>} = 62,
 
 		// Parachain Onboarding Pallets. Start indices at 70 to leave room.
 		Registrar: paras_registrar::{Pallet, Call, Storage, Event<T>} = 70,

runtime/parachains/Cargo.toml

@@ -11,6 +11,7 @@ log = { version = "0.4.14", default-features = false }
 rustc-hex = { version = "2.1.0", default-features = false }
 serde = { version = "1.0.123", features = [ "derive" ], optional = true }
 derive_more = "0.99.11"
+bitflags = "1"
 
 sp-api = { git = "https://github.com/paritytech/substrate", branch = "master", default-features = false }
 inherents = { package = "sp-inherents", git = "https://github.com/paritytech/substrate", branch = "master", default-features = false }