Offences report system rework (#13425)

* Experiments with common equivocation trait

* Improved equivocation trait

* Fix grandpa equivocation implementation

* Remove some cruft

* Remove some more cruft

* More generic naming

* Simplification of offences manipilation

* More refactory

* Some prograss with the encapsulation of offence report system

* Finally unit type works as a universal null report system

* Align substrate node code

* Further simplification

* Fix test utils

* Remove not required associated type

* Fix benches

* Rollback to prev field name

* Box big params

* Fix typo

* Remove new tag computation

* Remove default implementations

* Better docs

* Return 'Result' instead of bool

* Change offence report system return types

* Some renaming and documentation

* Improve documentation

* More abstract offence report system

* Rename 'consume_evidence' to 'process_evidence'

* Further docs refinements

* Doc for dummy offence report

* Fix rustdoc

* Fix after master merge

* Apply code review suggestions

* Improve docs

substrate/primitives/staking/src/offence.rs

@@ -18,10 +18,10 @@
 //! Common traits and types that are useful for describing offences for usage in environments
 //! that use staking.
 
-use sp_std::vec::Vec;
-
 use codec::{Decode, Encode};
-use sp_runtime::Perbill;
+use sp_core::Get;
+use sp_runtime::{transaction_validity::TransactionValidityError, DispatchError, Perbill};
+use sp_std::vec::Vec;
 
 use crate::SessionIndex;
 
@@ -209,3 +209,68 @@ pub struct OffenceDetails<Reporter, Offender> {
 	/// particular reporters.
 	pub reporters: Vec<Reporter>,
 }
+
+/// An abstract system to publish, check and process offence evidences.
+///
+/// Implementation details are left opaque and we don't assume any specific usage
+/// scenario for this trait at this level. The main goal is to group together some
+/// common actions required during a typical offence report flow.
+///
+/// Even though this trait doesn't assume too much, this is a general guideline
+/// for a typical usage scenario:
+///
+/// 1. An offence is detected and an evidence is submitted on-chain via the
+///    [`OffenceReportSystem::publish_evidence`] method. This will construct
+///    and submit an extrinsic transaction containing the offence evidence.
+///
+/// 2. If the extrinsic is unsigned then the transaction receiver may want to
+///    perform some preliminary checks before further processing. This is a good
+///    place to call the [`OffenceReportSystem::check_evidence`] method.
+///
+/// 3. Finally the report extrinsic is executed on-chain. This is where the user
+///    calls the [`OffenceReportSystem::process_evidence`] to consume the offence
+///    report and enact any required action.
+pub trait OffenceReportSystem<Reporter, Evidence> {
+	/// Longevity, in blocks, for the evidence report validity.
+	///
+	/// For example, when using the staking pallet this should be set equal
+	/// to the bonding duration in blocks, not eras.
+	type Longevity: Get<u64>;
+
+	/// Publish an offence evidence.
+	///
+	/// Common usage: submit the evidence on-chain via some kind of extrinsic.
+	fn publish_evidence(evidence: Evidence) -> Result<(), ()>;
+
+	/// Check an offence evidence.
+	///
+	/// Common usage: preliminary validity check before execution
+	/// (e.g. for unsigned extrinsic quick checks).
+	fn check_evidence(evidence: Evidence) -> Result<(), TransactionValidityError>;
+
+	/// Process an offence evidence.
+	///
+	/// Common usage: enact some form of slashing directly or by forwarding
+	/// the evidence to a lower level specialized subsystem (e.g. a handler
+	/// implementing `ReportOffence` trait).
+	fn process_evidence(reporter: Reporter, evidence: Evidence) -> Result<(), DispatchError>;
+}
+
+/// Dummy offence report system.
+///
+/// Doesn't do anything special and returns `Ok(())` for all the actions.
+impl<Reporter, Evidence> OffenceReportSystem<Reporter, Evidence> for () {
+	type Longevity = ();
+
+	fn publish_evidence(_evidence: Evidence) -> Result<(), ()> {
+		Ok(())
+	}
+
+	fn check_evidence(_evidence: Evidence) -> Result<(), TransactionValidityError> {
+		Ok(())
+	}
+
+	fn process_evidence(_reporter: Reporter, _evidence: Evidence) -> Result<(), DispatchError> {
+		Ok(())
+	}
+}