BEEFY: implement equivocations detection, reporting and slashing (#13121)

* client/beefy: simplify self_vote logic * client/beefy: migrate to new state version * client/beefy: detect equivocated votes * fix typos * sp-beefy: add equivocation primitives * client/beefy: refactor vote processing * fix version migration for new rounds struct * client/beefy: track equivocations and create proofs * client/beefy: adjust tests for new voting logic * sp-beefy: fix commitment ordering and equality * client/beefy: simplify handle_vote() a bit * client/beefy: add simple equivocation test * client/beefy: submit equivocation proof - WIP * frame/beefy: add equivocation report runtime api - part 1 * frame/beefy: report equivocation logic - part 2 * frame/beefy: add pluggable Equivocation handler - part 3 * frame/beefy: impl ValidateUnsigned for equivocations reporting * client/beefy: submit report equivocation unsigned extrinsic * primitives/beefy: fix tests * frame/beefy: add default weights * frame/beefy: fix tests * client/beefy: fix tests * frame/beefy-mmr: fix tests * frame/beefy: cross-check session index with equivocation report * sp-beefy: make test Keyring useable in pallet * frame/beefy: add basic equivocation test * frame/beefy: test verify equivocation results in slashing * frame/beefy: test report_equivocation_old_set * frame/beefy: add more equivocation tests * sp-beefy: fix docs * beefy: simplify equivocations and fix tests * client/beefy: address review comments * frame/beefy: add ValidateUnsigned to test/mock runtime * client/beefy: fixes after merge master * fix missed merge damage * client/beefy: add test for reporting equivocations Also validated there's no unexpected equivocations reported in the other tests. Signed-off-by: acatangiu <adrian@parity.io> * sp-beefy: move test utils to their own file * client/beefy: add negative test for equivocation reports * sp-beefy: move back MmrRootProvider - used in polkadot-service * impl review suggestions * client/beefy: add equivocation metrics --------- Signed-off-by: acatangiu <adrian@parity.io> Co-authored-by: parity-processbot <>
2026-06-15 12:41:07 +00:00 · 2023-02-17 11:45:00 +02:00
parent 36480b158d
commit c21f292a02
22 changed files with 2141 additions and 214 deletions
@@ -0,0 +1,385 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2017-2023 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! An opt-in utility module for reporting equivocations.
+//!
+//! This module defines an offence type for BEEFY 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;
+//! - a way to get the current block author;
+//!
+//! These can be used in an offchain context in order to submit equivocation
+//! reporting extrinsics (from the client that's running the BEEFY protocol).
+//! And in a runtime context, so that the BEEFY pallet can validate the
+//! equivocation proofs in the extrinsic and report the offences.
+//!
+//! IMPORTANT:
+//! When using this module for enabling equivocation reporting it is required
+//! that the `ValidateUnsigned` for the BEEFY pallet is used in the runtime
+//! definition.
+
+use sp_std::prelude::*;
+
+use beefy_primitives::{EquivocationProof, ValidatorSetId};
+use codec::{self as codec, Decode, Encode};
+use frame_support::{
+	log,
+	traits::{Get, KeyOwnerProofSystem},
+};
+use frame_system::pallet_prelude::BlockNumberFor;
+use sp_runtime::{
+	transaction_validity::{
+		InvalidTransaction, TransactionPriority, TransactionSource, TransactionValidity,
+		TransactionValidityError, ValidTransaction,
+	},
+	DispatchResult, Perbill, RuntimeAppPublic,
+};
+use sp_staking::{
+	offence::{Kind, Offence, OffenceError, ReportOffence},
+	SessionIndex,
+};
+
+use super::{Call, Config, Pallet, LOG_TARGET};
+
+/// A trait with utility methods for handling equivocation reports in BEEFY.
+/// 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: Config> {
+	/// The offence type used for reporting offences on valid equivocation reports.
+	type Offence: BeefyOffence<BlockNumberFor<T>, T::KeyOwnerIdentification>;
+
+	/// The longevity, in blocks, that the equivocation report is valid for. When using the staking
+	/// pallet this should be equal to the bonding duration (in blocks, not eras).
+	type ReportLongevity: Get<u64>;
+
+	/// Report an offence proved by the given reporters.
+	fn report_offence(
+		reporters: Vec<T::AccountId>,
+		offence: Self::Offence,
+	) -> Result<(), OffenceError>;
+
+	/// Returns true if all of the offenders at the given time slot have already been reported.
+	fn is_known_offence(
+		offenders: &[T::KeyOwnerIdentification],
+		time_slot: &<Self::Offence as Offence<T::KeyOwnerIdentification>>::TimeSlot,
+	) -> bool;
+
+	/// Create and dispatch an equivocation report extrinsic.
+	fn submit_unsigned_equivocation_report(
+		equivocation_proof: EquivocationProof<
+			BlockNumberFor<T>,
+			T::BeefyId,
+			<T::BeefyId as RuntimeAppPublic>::Signature,
+		>,
+		key_owner_proof: T::KeyOwnerProof,
+	) -> DispatchResult;
+
+	/// Fetch the current block author id, if defined.
+	fn block_author() -> Option<T::AccountId>;
+}
+
+impl<T: Config> HandleEquivocation<T> for () {
+	type Offence = BeefyEquivocationOffence<BlockNumberFor<T>, T::KeyOwnerIdentification>;
+	type ReportLongevity = ();
+
+	fn report_offence(
+		_reporters: Vec<T::AccountId>,
+		_offence: BeefyEquivocationOffence<BlockNumberFor<T>, T::KeyOwnerIdentification>,
+	) -> Result<(), OffenceError> {
+		Ok(())
+	}
+
+	fn is_known_offence(
+		_offenders: &[T::KeyOwnerIdentification],
+		_time_slot: &BeefyTimeSlot<BlockNumberFor<T>>,
+	) -> bool {
+		true
+	}
+
+	fn submit_unsigned_equivocation_report(
+		_equivocation_proof: EquivocationProof<
+			BlockNumberFor<T>,
+			T::BeefyId,
+			<T::BeefyId as RuntimeAppPublic>::Signature,
+		>,
+		_key_owner_proof: T::KeyOwnerProof,
+	) -> DispatchResult {
+		Ok(())
+	}
+
+	fn block_author() -> Option<T::AccountId> {
+		None
+	}
+}
+
+/// 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<N, I, R, L, O = BeefyEquivocationOffence<N, I>> {
+	_phantom: sp_std::marker::PhantomData<(N, I, R, L, O)>,
+}
+
+impl<N, I, R, L, O> Default for EquivocationHandler<N, I, R, L, O> {
+	fn default() -> Self {
+		Self { _phantom: Default::default() }
+	}
+}
+
+impl<T, R, L, O> HandleEquivocation<T>
+	for EquivocationHandler<BlockNumberFor<T>, T::KeyOwnerIdentification, R, L, O>
+where
+	// We use the authorship pallet to fetch the current block author and use
+	// `offchain::SendTransactionTypes` for unsigned extrinsic creation and
+	// submission.
+	T: Config + pallet_authorship::Config + frame_system::offchain::SendTransactionTypes<Call<T>>,
+	// A system for reporting offences after valid equivocation reports are
+	// processed.
+	R: ReportOffence<T::AccountId, T::KeyOwnerIdentification, O>,
+	// The longevity (in blocks) that the equivocation report is valid for. When using the staking
+	// pallet this should be the bonding duration.
+	L: Get<u64>,
+	// The offence type that should be used when reporting.
+	O: BeefyOffence<BlockNumberFor<T>, T::KeyOwnerIdentification>,
+{
+	type Offence = O;
+	type ReportLongevity = L;
+
+	fn report_offence(reporters: Vec<T::AccountId>, offence: O) -> Result<(), OffenceError> {
+		R::report_offence(reporters, offence)
+	}
+
+	fn is_known_offence(offenders: &[T::KeyOwnerIdentification], time_slot: &O::TimeSlot) -> bool {
+		R::is_known_offence(offenders, time_slot)
+	}
+
+	fn submit_unsigned_equivocation_report(
+		equivocation_proof: EquivocationProof<
+			BlockNumberFor<T>,
+			T::BeefyId,
+			<T::BeefyId as RuntimeAppPublic>::Signature,
+		>,
+		key_owner_proof: T::KeyOwnerProof,
+	) -> DispatchResult {
+		use frame_system::offchain::SubmitTransaction;
+
+		let call = Call::report_equivocation_unsigned {
+			equivocation_proof: Box::new(equivocation_proof),
+			key_owner_proof,
+		};
+
+		match SubmitTransaction::<T, Call<T>>::submit_unsigned_transaction(call.into()) {
+			Ok(()) => log::info!(target: LOG_TARGET, "Submitted BEEFY equivocation report.",),
+			Err(e) =>
+				log::error!(target: LOG_TARGET, "Error submitting equivocation report: {:?}", e,),
+		}
+
+		Ok(())
+	}
+
+	fn block_author() -> Option<T::AccountId> {
+		<pallet_authorship::Pallet<T>>::author()
+	}
+}
+
+/// 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 BeefyTimeSlot<N: Copy + Clone + PartialOrd + Ord + Eq + PartialEq + Encode + Decode> {
+	// The order of these matters for `derive(Ord)`.
+	/// BEEFY Set ID.
+	pub set_id: ValidatorSetId,
+	/// Round number.
+	pub round: N,
+}
+
+/// Methods for the `ValidateUnsigned` implementation:
+/// It restricts calls to `report_equivocation_unsigned` to local calls (i.e. extrinsics generated
+/// on this node) or that already in a block. This guarantees that only block authors can include
+/// unsigned equivocation reports.
+impl<T: Config> Pallet<T> {
+	pub fn validate_unsigned(source: TransactionSource, call: &Call<T>) -> TransactionValidity {
+		if let Call::report_equivocation_unsigned { equivocation_proof, key_owner_proof } = call {
+			// discard equivocation report not coming from the local node
+			match source {
+				TransactionSource::Local | TransactionSource::InBlock => { /* allowed */ },
+				_ => {
+					log::warn!(
+						target: LOG_TARGET,
+						"rejecting unsigned report equivocation transaction because it is not local/in-block."
+					);
+					return InvalidTransaction::Call.into()
+				},
+			}
+
+			// check report staleness
+			is_known_offence::<T>(equivocation_proof, key_owner_proof)?;
+
+			let longevity =
+				<T::HandleEquivocation as HandleEquivocation<T>>::ReportLongevity::get();
+
+			ValidTransaction::with_tag_prefix("BeefyEquivocation")
+				// We assign the maximum priority for any equivocation report.
+				.priority(TransactionPriority::MAX)
+				// Only one equivocation report for the same offender at the same slot.
+				.and_provides((
+					equivocation_proof.offender_id().clone(),
+					equivocation_proof.set_id(),
+					*equivocation_proof.round_number(),
+				))
+				.longevity(longevity)
+				// We don't propagate this. This can never be included on a remote node.
+				.propagate(false)
+				.build()
+		} else {
+			InvalidTransaction::Call.into()
+		}
+	}
+
+	pub fn pre_dispatch(call: &Call<T>) -> Result<(), TransactionValidityError> {
+		if let Call::report_equivocation_unsigned { equivocation_proof, key_owner_proof } = call {
+			is_known_offence::<T>(equivocation_proof, key_owner_proof)
+		} else {
+			Err(InvalidTransaction::Call.into())
+		}
+	}
+}
+
+fn is_known_offence<T: Config>(
+	equivocation_proof: &EquivocationProof<
+		BlockNumberFor<T>,
+		T::BeefyId,
+		<T::BeefyId as RuntimeAppPublic>::Signature,
+	>,
+	key_owner_proof: &T::KeyOwnerProof,
+) -> Result<(), TransactionValidityError> {
+	// check the membership proof to extract the offender's id,
+	// equivocation validity will be fully checked during the call.
+	let key = (beefy_primitives::KEY_TYPE, equivocation_proof.offender_id().clone());
+
+	let offender = T::KeyOwnerProofSystem::check_proof(key, key_owner_proof.clone())
+		.ok_or(InvalidTransaction::BadProof)?;
+
+	// check if the offence has already been reported,
+	// and if so then we can discard the report.
+	let time_slot = <T::HandleEquivocation as HandleEquivocation<T>>::Offence::new_time_slot(
+		equivocation_proof.set_id(),
+		*equivocation_proof.round_number(),
+	);
+
+	let is_known_offence = T::HandleEquivocation::is_known_offence(&[offender], &time_slot);
+
+	if is_known_offence {
+		Err(InvalidTransaction::Stale.into())
+	} else {
+		Ok(())
+	}
+}
+
+/// A BEEFY equivocation offence report.
+pub struct BeefyEquivocationOffence<N, FullIdentification>
+where
+	N: Copy + Clone + PartialOrd + Ord + Eq + PartialEq + Encode + Decode,
+{
+	/// Time slot at which this incident happened.
+	pub time_slot: BeefyTimeSlot<N>,
+	/// 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 BEEFY offences and must also
+/// implement the `Offence` trait. This trait provides a constructor that is
+/// provided all available data during processing of BEEFY equivocations.
+pub trait BeefyOffence<N, FullIdentification>: Offence<FullIdentification>
+where
+	N: Copy + Clone + PartialOrd + Ord + Eq + PartialEq + Encode + Decode,
+{
+	/// Create a new BEEFY offence using the given equivocation details.
+	fn new(
+		session_index: SessionIndex,
+		validator_set_count: u32,
+		offender: FullIdentification,
+		set_id: ValidatorSetId,
+		round: N,
+	) -> Self;
+
+	/// Create a new BEEFY offence time slot.
+	fn new_time_slot(set_id: ValidatorSetId, round: N) -> Self::TimeSlot;
+}
+
+impl<N, FullIdentification: Clone> BeefyOffence<N, FullIdentification>
+	for BeefyEquivocationOffence<N, FullIdentification>
+where
+	N: Copy + Clone + PartialOrd + Ord + Eq + PartialEq + Encode + Decode,
+{
+	fn new(
+		session_index: SessionIndex,
+		validator_set_count: u32,
+		offender: FullIdentification,
+		set_id: ValidatorSetId,
+		round: N,
+	) -> Self {
+		BeefyEquivocationOffence {
+			session_index,
+			validator_set_count,
+			offender,
+			time_slot: BeefyTimeSlot { set_id, round },
+		}
+	}
+
+	fn new_time_slot(set_id: ValidatorSetId, round: N) -> Self::TimeSlot {
+		BeefyTimeSlot { set_id, round }
+	}
+}
+
+impl<N, FullIdentification: Clone> Offence<FullIdentification>
+	for BeefyEquivocationOffence<N, FullIdentification>
+where
+	N: Copy + Clone + PartialOrd + Ord + Eq + PartialEq + Encode + Decode,
+{
+	const ID: Kind = *b"beefy:equivocati";
+	type TimeSlot = BeefyTimeSlot<N>;
+
+	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(&self, offenders_count: u32) -> Perbill {
+		// the formula is min((3k / n)^2, 1)
+		let x = Perbill::from_rational(3 * offenders_count, self.validator_set_count);
+		// _ ^ 2
+		x.square()
+	}
+}