grandpa: report equivocations (#3868)

* session: runtime api for generating session membership proofs * grandpa: add runtime api for creating equivocation report txs * grandpa: submit signed equivocation report transactions * grandpa: use proper equivocation report type * grandpa: report equivocations * grandpa: validate equivocation proof * grandpa: update to finality-grandpa 0.9.1 * grandpa: fix encoding of session membership proof * grandpa: initialize set id session mapping for genesis session * grandpa: fix bug in set_id session validation * fix compilation * cleanup from merge conflicts * cleanup crate tomls * grandpa: refactor equivocation handling to separate trait * node-template: fix compilation * fix test compilation * bump finality-grandpa to v0.10.2 * rpc: fix runtime version test * CHERRY-PICK #4200: Add documentation to SubmitSignedTransaction and actually make it work Squashed commit of the following: commit 4f2cb0b1c588a06f2f3b478bb4b28b5cb29d54b9 Author: Tomasz Drwięga <tomasz@parity.io> Date: Tue Dec 3 16:29:33 2019 +0100 Split the method to avoid confusing type error message. commit c5bf24eeaaf902add89ed1b046b22c4a4aaeb2cd Author: Tomasz Drwięga <tomasz@parity.io> Date: Tue Dec 3 16:19:55 2019 +0100 Make accounts optional, fix logic. commit 97db1ef556e023cf6847e5ffdb036c0e3ea6fb0a Author: Tomasz Drwięga <tomasz@parity.io> Date: Tue Dec 3 10:06:20 2019 +0100 Remove warning. commit 535f5c116d1a2e826eaf90c3f7e6798e443d61d8 Merge: 516257217 0f1a5f651 Author: Tomasz Drwięga <tomasz@parity.io> Date: Tue Dec 3 07:08:05 2019 +0100 Merge branch 'master' into td-signed-transactions commit 516257217bac89fcebd083712f4ea68b7b23b55a Merge: ac98248c6 2e68c80c2 Author: Tomasz Drwięga <tomasz@parity.io> Date: Mon Dec 2 13:57:25 2019 +0100 Merge branch 'master' into td-signed-transactions commit ac98248c6c56cff381130645a82a13d29933cf83 Author: Tomasz Drwięga <tomasz@parity.io> Date: Mon Nov 25 17:34:52 2019 +0100 Forgotten import. commit 67a3c19031506c28e31c6bc4a90fff62d467dd58 Author: Tomasz Drwięga <tomasz@parity.io> Date: Mon Nov 25 17:32:10 2019 +0100 Fix naming and bounds. commit 93e768ea9df97a4629fca1f9bc4b108fdb33f876 Author: Tomasz Drwięga <tomasz@parity.io> Date: Mon Nov 25 17:01:05 2019 +0100 Add documentation to signed transactions and actually make them work. * grandpa: skip block initialization on report submission method * primitives: allow transaction pool access by default for offchain calls * grandpa: unused parameters * grandpa: remove unused method * grandpa: enable equivocation reporting * grandpa: add workaround for parameter encoding * grandpa: fix localized_payload calls in tests * fix submit_report_equivocation_extrinsic in runtimes * node: fix submit transaction test compilation * node: bump spec_version * rpc: fix api version test * grandpa: allow custom equivocation offence type * grandpa: add test for authorities::next_change_height * grandpa: cleanup report_equivocation function * node: move reporting app crypto to node-primitives * grandpa: move equivocation traits to own module * grandpa: rename app-crypto crate import * grandpa: export equivocation types * node: bump spec_version * grandpa: rename EquivocationReport to EquivocationProof * grandpa: add missing docs to primitives * grandpa: add missing docs to equivocation * node: fix compilation * grandpa: add missing docs to pallet * node: bump spec_version * fix whitespace * grandpa: return error on offence reporting * grandpa: expose session and validator count in proofs through traits * grandpa: use strong key in module KeyOwnerProofSystem * grandpa: move key ownership proof to grandpa runtime api * grandpa: remove unnecessary cloning when checking equivocation proof * grandpa: make report_equivocation a method in Environment * support: implement KeyOwnerProofSystem for () * grandpa: move KeyOwnerProofSystem to module trait * test-utils: fix runtime compilation * grandpa: fix test compilation * grandpa: fix test compilation after merge * grandpa: simplify transaction submission types * grandpa: validate equivocation report in signed extension * client: fix test * node: use ValidateEquivocationReport signed extension * grandpa: expose key ownership proof under opaque type * grandpa: better docs on key ownership proofs * grandpa: add note about signed extension * grandpa: add ValidateEquivocationReport::new * grandpa: remove skip_initialize_block from runtime api * grandpa: use new offchain transaction submission API * grandpa: take set_id in generate_key_ownership_proof * grandpa: update to finality-grandpa v0.12.2 * grandpa: cleanup usages of AuthoritySet::current * grandpa: fix test * grandpa: add mocking utilities for equivocation reporting * grandpa: add test for equivocation reporting * grandpa: move SetIdSession initialization * grandpa: add more tests * node: enable historical session manager * node: bump spec_version * node: use strong key types in KeyOwnerProofSystem definitions * grandpa: export GrandpaEquivocationOffence type
2026-05-30 09:21:04 +00:00 · 2020-05-06 17:25:51 +01:00
parent a1127f8f9d
commit fbd2ac8f3b
38 changed files with 2249 additions and 296 deletions
@@ -0,0 +1,406 @@
+// Copyright 2017-2020 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Substrate is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+//!
+//! An opt-in utility module for reporting equivocations.
+//!
+//! This module defines an offence type for GRANDPA equivocations
+//! and some utility traits to wire together:
+//! - a key ownership proof system (e.g. to prove that a given authority was
+//! part of a session);
+//! - a system for reporting offences;
+//! - a system for signing and submitting transactions;
+//!
+//! These can be used in an offchain context in order to submit equivocation
+//! reporting extrinsics (from the client that's running the GRANDPA protocol).
+//! And in a runtime context, so that the GRANDPA module can validate the
+//! equivocation proofs in the extrinsic and report the offences.
+//!
+
+use sp_std::prelude::*;
+
+use codec::{self as codec, Decode, Encode};
+use frame_support::{debug, dispatch::IsSubType, traits::KeyOwnerProofSystem};
+use frame_system::offchain::{AppCrypto, CreateSignedTransaction, Signer};
+use sp_finality_grandpa::{EquivocationProof, RoundNumber, SetId};
+use sp_runtime::{
+	traits::{DispatchInfoOf, SignedExtension},
+	transaction_validity::{
+		InvalidTransaction, TransactionValidity, TransactionValidityError, ValidTransaction,
+	},
+	DispatchResult, Perbill,
+};
+use sp_staking::{
+	offence::{Kind, Offence, OffenceError, ReportOffence},
+	SessionIndex,
+};
+
+/// Ensure that equivocation reports are only processed if valid.
+#[derive(Encode, Decode, Clone, Eq, PartialEq)]
+pub struct ValidateEquivocationReport<T>(sp_std::marker::PhantomData<T>);
+
+impl<T> Default for ValidateEquivocationReport<T> {
+	fn default() -> ValidateEquivocationReport<T> {
+		ValidateEquivocationReport::new()
+	}
+}
+
+impl<T> ValidateEquivocationReport<T> {
+	pub fn new() -> ValidateEquivocationReport<T> {
+		ValidateEquivocationReport(Default::default())
+	}
+}
+
+impl<T> sp_std::fmt::Debug for ValidateEquivocationReport<T> {
+	fn fmt(&self, f: &mut sp_std::fmt::Formatter) -> sp_std::fmt::Result {
+		write!(f, "ValidateEquivocationReport<T>")
+	}
+}
+
+/// Custom validity error used when validating equivocation reports.
+#[derive(Debug)]
+#[repr(u8)]
+pub enum ReportEquivocationValidityError {
+	/// The proof provided in the report is not valid.
+	InvalidEquivocationProof = 1,
+	/// The proof provided in the report is not valid.
+	InvalidKeyOwnershipProof = 2,
+	/// The set id provided in the report is not valid.
+	InvalidSetId = 3,
+	/// The session index provided in the report is not valid.
+	InvalidSession = 4,
+}
+
+impl From<ReportEquivocationValidityError> for TransactionValidityError {
+	fn from(e: ReportEquivocationValidityError) -> TransactionValidityError {
+		TransactionValidityError::from(InvalidTransaction::Custom(e as u8))
+	}
+}
+
+impl<T: super::Trait + Send + Sync> SignedExtension for ValidateEquivocationReport<T>
+where
+	<T as frame_system::Trait>::Call: IsSubType<super::Module<T>, T>,
+{
+	const IDENTIFIER: &'static str = "ValidateEquivocationReport";
+	type AccountId = T::AccountId;
+	type Call = <T as frame_system::Trait>::Call;
+	type AdditionalSigned = ();
+	type Pre = ();
+
+	fn additional_signed(
+		&self,
+	) -> sp_std::result::Result<Self::AdditionalSigned, TransactionValidityError> {
+		Ok(())
+	}
+
+	fn validate(
+		&self,
+		_who: &Self::AccountId,
+		call: &Self::Call,
+		_info: &DispatchInfoOf<Self::Call>,
+		_len: usize,
+	) -> TransactionValidity {
+		let (equivocation_proof, key_owner_proof) = match call.is_sub_type() {
+			Some(super::Call::report_equivocation(equivocation_proof, key_owner_proof)) => {
+				(equivocation_proof, key_owner_proof)
+			}
+			_ => return Ok(ValidTransaction::default()),
+		};
+
+		// validate the key ownership proof extracting the id of the offender.
+		if let None = T::KeyOwnerProofSystem::check_proof(
+			(
+				sp_finality_grandpa::KEY_TYPE,
+				equivocation_proof.offender().clone(),
+			),
+			key_owner_proof.clone(),
+		) {
+			return Err(ReportEquivocationValidityError::InvalidKeyOwnershipProof.into());
+		}
+
+		// we check the equivocation within the context of its set id (and
+		// associated session).
+		let set_id = equivocation_proof.set_id();
+		let session_index = key_owner_proof.session();
+
+		// validate equivocation proof (check votes are different and
+		// signatures are valid).
+		if let Err(_) = sp_finality_grandpa::check_equivocation_proof(equivocation_proof.clone()) {
+			return Err(ReportEquivocationValidityError::InvalidEquivocationProof.into());
+		}
+
+		// fetch the current and previous sets last session index. on the
+		// genesis set there's no previous set.
+		let previous_set_id_session_index = if set_id == 0 {
+			None
+		} else {
+			let session_index =
+				if let Some(session_id) = <super::Module<T>>::session_for_set(set_id - 1) {
+					session_id
+				} else {
+					return Err(ReportEquivocationValidityError::InvalidSetId.into());
+				};
+
+			Some(session_index)
+		};
+
+		let set_id_session_index =
+			if let Some(session_id) = <super::Module<T>>::session_for_set(set_id) {
+				session_id
+			} else {
+				return Err(ReportEquivocationValidityError::InvalidSetId.into());
+			};
+
+		// check that the session id for the membership proof is within the
+		// bounds of the set id reported in the equivocation.
+		if session_index > set_id_session_index ||
+			previous_set_id_session_index
+				.map(|previous_index| session_index <= previous_index)
+				.unwrap_or(false)
+		{
+			return Err(ReportEquivocationValidityError::InvalidSession.into());
+		}
+
+		Ok(ValidTransaction::default())
+	}
+}
+
+/// A trait with utility methods for handling equivocation reports in GRANDPA.
+/// The offence type is generic, and the trait provides , reporting an offence
+/// triggered by a valid equivocation report, and also for creating and
+/// submitting equivocation report extrinsics (useful only in offchain context).
+pub trait HandleEquivocation<T: super::Trait> {
+	/// The offence type used for reporting offences on valid equivocation reports.
+	type Offence: GrandpaOffence<T::KeyOwnerIdentification>;
+
+	/// Report an offence proved by the given reporters.
+	fn report_offence(
+		reporters: Vec<T::AccountId>,
+		offence: Self::Offence,
+	) -> Result<(), OffenceError>;
+
+	/// Create and dispatch an equivocation report extrinsic.
+	fn submit_equivocation_report(
+		equivocation_proof: EquivocationProof<T::Hash, T::BlockNumber>,
+		key_owner_proof: T::KeyOwnerProof,
+	) -> DispatchResult;
+}
+
+impl<T: super::Trait> HandleEquivocation<T> for () {
+	type Offence = GrandpaEquivocationOffence<T::KeyOwnerIdentification>;
+
+	fn report_offence(
+		_reporters: Vec<T::AccountId>,
+		_offence: GrandpaEquivocationOffence<T::KeyOwnerIdentification>,
+	) -> Result<(), OffenceError> {
+		Ok(())
+	}
+
+	fn submit_equivocation_report(
+		_equivocation_proof: EquivocationProof<T::Hash, T::BlockNumber>,
+		_key_owner_proof: T::KeyOwnerProof,
+	) -> DispatchResult {
+		Ok(())
+	}
+}
+
+/// Generic equivocation handler. This type implements `HandleEquivocation`
+/// using existing subsystems that are part of frame (type bounds described
+/// below) and will dispatch to them directly, it's only purpose is to wire all
+/// subsystems together.
+pub struct EquivocationHandler<I, C, S, R, O = GrandpaEquivocationOffence<I>> {
+	_phantom: sp_std::marker::PhantomData<(I, C, S, R, O)>,
+}
+
+impl<I, C, S, R, O> Default for EquivocationHandler<I, C, S, R, O> {
+	fn default() -> Self {
+		Self {
+			_phantom: Default::default(),
+		}
+	}
+}
+
+impl<T, C, S, R, O> HandleEquivocation<T>
+	for EquivocationHandler<T::KeyOwnerIdentification, C, S, R, O>
+where
+	// A signed transaction creator. Used for signing and submitting equivocation reports.
+	T: super::Trait + CreateSignedTransaction<super::Call<T>>,
+	// Application-specific crypto bindings.
+	C: AppCrypto<T::Public, T::Signature>,
+	// The offence type that should be used when reporting.
+	O: GrandpaOffence<T::KeyOwnerIdentification>,
+	// A system for reporting offences after valid equivocation reports are
+	// processed.
+	R: ReportOffence<T::AccountId, T::KeyOwnerIdentification, O>,
+{
+	type Offence = O;
+
+	fn report_offence(reporters: Vec<T::AccountId>, offence: O) -> Result<(), OffenceError> {
+		R::report_offence(reporters, offence)
+	}
+
+	fn submit_equivocation_report(
+		equivocation_proof: EquivocationProof<T::Hash, T::BlockNumber>,
+		key_owner_proof: T::KeyOwnerProof,
+	) -> DispatchResult {
+		use frame_system::offchain::SendSignedTransaction;
+
+		let signer = Signer::<T, C>::all_accounts();
+		if !signer.can_sign() {
+			return Err(
+				"No local accounts available. Consider adding one via `author_insertKey` RPC.",
+			)?;
+		}
+
+		let results = signer.send_signed_transaction(|_account| {
+			super::Call::report_equivocation(equivocation_proof.clone(), key_owner_proof.clone())
+		});
+
+		for (acc, res) in &results {
+			match res {
+				Ok(()) => debug::info!("[{:?}] Submitted GRANDPA equivocation report.", acc.id),
+				Err(e) => debug::error!(
+					"[{:?}] Error submitting equivocation report: {:?}",
+					acc.id,
+					e
+				),
+			}
+		}
+
+		Ok(())
+	}
+}
+
+/// A round number and set id which point on the time of an offence.
+#[derive(Copy, Clone, PartialOrd, Ord, Eq, PartialEq, Encode, Decode)]
+pub struct GrandpaTimeSlot {
+	// The order of these matters for `derive(Ord)`.
+	/// Grandpa Set ID.
+	pub set_id: SetId,
+	/// Round number.
+	pub round: RoundNumber,
+}
+
+/// A grandpa equivocation offence report.
+#[allow(dead_code)]
+pub struct GrandpaEquivocationOffence<FullIdentification> {
+	/// Time slot at which this incident happened.
+	pub time_slot: GrandpaTimeSlot,
+	/// The session index in which the incident happened.
+	pub session_index: SessionIndex,
+	/// The size of the validator set at the time of the offence.
+	pub validator_set_count: u32,
+	/// The authority which produced this equivocation.
+	pub offender: FullIdentification,
+}
+
+/// An interface for types that will be used as GRANDPA offences and must also
+/// implement the `Offence` trait. This trait provides a constructor that is
+/// provided all available data during processing of GRANDPA equivocations.
+pub trait GrandpaOffence<FullIdentification>: Offence<FullIdentification> {
+	/// Create a new GRANDPA offence using the given equivocation details.
+	fn new(
+		session_index: SessionIndex,
+		validator_set_count: u32,
+		offender: FullIdentification,
+		set_id: SetId,
+		round: RoundNumber,
+	) -> Self;
+}
+
+impl<FullIdentification: Clone> GrandpaOffence<FullIdentification>
+	for GrandpaEquivocationOffence<FullIdentification>
+{
+	fn new(
+		session_index: SessionIndex,
+		validator_set_count: u32,
+		offender: FullIdentification,
+		set_id: SetId,
+		round: RoundNumber,
+	) -> Self {
+		GrandpaEquivocationOffence {
+			session_index,
+			validator_set_count,
+			offender,
+			time_slot: GrandpaTimeSlot { set_id, round },
+		}
+	}
+}
+
+impl<FullIdentification: Clone> Offence<FullIdentification>
+	for GrandpaEquivocationOffence<FullIdentification>
+{
+	const ID: Kind = *b"grandpa:equivoca";
+	type TimeSlot = GrandpaTimeSlot;
+
+	fn offenders(&self) -> Vec<FullIdentification> {
+		vec![self.offender.clone()]
+	}
+
+	fn session_index(&self) -> SessionIndex {
+		self.session_index
+	}
+
+	fn validator_set_count(&self) -> u32 {
+		self.validator_set_count
+	}
+
+	fn time_slot(&self) -> Self::TimeSlot {
+		self.time_slot
+	}
+
+	fn slash_fraction(offenders_count: u32, validator_set_count: u32) -> Perbill {
+		// the formula is min((3k / n)^2, 1)
+		let x = Perbill::from_rational_approximation(3 * offenders_count, validator_set_count);
+		// _ ^ 2
+		x.square()
+	}
+}
+
+/// A trait to get a session number the `MembershipProof` belongs to.
+pub trait GetSessionNumber {
+	fn session(&self) -> SessionIndex;
+}
+
+/// A trait to get the validator count at the session the `MembershipProof`
+/// belongs to.
+pub trait GetValidatorCount {
+	fn validator_count(&self) -> sp_session::ValidatorCount;
+}
+
+impl GetSessionNumber for frame_support::Void {
+	fn session(&self) -> SessionIndex {
+		Default::default()
+	}
+}
+
+impl GetValidatorCount for frame_support::Void {
+	fn validator_count(&self) -> sp_session::ValidatorCount {
+		Default::default()
+	}
+}
+
+impl GetSessionNumber for sp_session::MembershipProof {
+	fn session(&self) -> SessionIndex {
+		self.session()
+	}
+}
+
+impl GetValidatorCount for sp_session::MembershipProof {
+	fn validator_count(&self) -> sp_session::ValidatorCount {
+		self.validator_count()
+	}
+}