feat: Rebrand Polkadot/Substrate references to PezkuwiChain

This commit systematically rebrands various references from Parity Technologies'
Polkadot/Substrate ecosystem to PezkuwiChain within the kurdistan-sdk.

Key changes include:
- Updated external repository URLs (zombienet-sdk, parity-db, parity-scale-codec, wasm-instrument) to point to pezkuwichain forks.
- Modified internal documentation and code comments to reflect PezkuwiChain naming and structure.
- Replaced direct references to  with  or specific paths within the  for XCM, Pezkuwi, and other modules.
- Cleaned up deprecated  issue and PR references in various  and  files, particularly in  and  modules.
- Adjusted image and logo URLs in documentation to point to PezkuwiChain assets.
- Removed or rephrased comments related to external Polkadot/Substrate PRs and issues.

This is a significant step towards fully customizing the SDK for the PezkuwiChain ecosystem.

bizinikiwi/primitives/staking/Cargo.toml

@@ -0,0 +1,36 @@
+[package]
+name = "pezsp-staking"
+version = "26.0.0"
+authors.workspace = true
+edition.workspace = true
+license = "Apache-2.0"
+homepage.workspace = true
+repository.workspace = true
+description = "A crate which contains primitives that are useful for implementation that uses staking approaches in general. Definitions related to sessions, slashing, etc go here."
+readme = "README.md"
+
+[lints]
+workspace = true
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu"]
+
+[dependencies]
+codec = { features = ["derive"], workspace = true }
+impl-trait-for-tuples = { workspace = true }
+scale-info = { features = ["derive"], workspace = true }
+serde = { features = ["alloc", "derive"], optional = true, workspace = true }
+
+pezsp-core = { workspace = true }
+pezsp-runtime = { workspace = true }
+
+[features]
+default = ["std"]
+std = [
+	"codec/std",
+	"scale-info/std",
+	"serde/std",
+	"pezsp-core/std",
+	"pezsp-runtime/std",
+]
+runtime-benchmarks = ["pezsp-runtime/runtime-benchmarks"]

bizinikiwi/primitives/staking/README.md

@@ -0,0 +1,4 @@
+A crate which contains primitives that are useful for implementation that uses staking
+approaches in general. Definitions related to sessions, slashing, etc go here.
+
+License: Apache-2.0

bizinikiwi/primitives/staking/src/currency_to_vote.rs

@@ -0,0 +1,122 @@
+// This file is part of Bizinikiwi.
+
+// Copyright (C) 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.
+
+use pezsp_runtime::{
+	traits::{UniqueSaturatedFrom, UniqueSaturatedInto},
+	SaturatedConversion,
+};
+
+/// A trait similar to `Convert` to convert values from `B` an abstract balance type
+/// into u64 and back from u128. (This conversion is used in election and other places where complex
+/// calculation over balance type is needed)
+///
+/// Total issuance of the currency is passed in, but an implementation of this trait may or may not
+/// use it.
+///
+/// # WARNING
+///
+/// the total issuance being passed in implies that the implementation must be aware of the fact
+/// that its values can affect the outcome. This implies that if the vote value is dependent on the
+/// total issuance, it should never ber written to storage for later re-use.
+pub trait CurrencyToVote<B> {
+	/// Convert balance to u64.
+	fn to_vote(value: B, issuance: B) -> u64;
+
+	/// Convert u128 to balance.
+	fn to_currency(value: u128, issuance: B) -> B;
+
+	/// Send a signal whether you are going to downscale the `B` when converting to `u64` given the
+	/// current issuance.
+	///
+	/// This is useful for automated checks in place to signal maintainers that the total issuance
+	/// has reached a point where downscaling will happen.
+	///
+	/// `None` means we don't know. `Some(_)` means we know with certainty.
+	fn will_downscale(issuance: B) -> Option<bool>;
+}
+
+/// An implementation of `CurrencyToVote` tailored for chain's that have a balance type of u128.
+///
+/// The factor is the `(total_issuance / u64::MAX).max(1)`, represented as u64. Let's look at the
+/// important cases:
+///
+/// If the chain's total issuance is less than u64::MAX, this will always be 1, which means that
+/// the factor will not have any effect. In this case, any account's balance is also less. Thus,
+/// both of the conversions are basically an `as`; Any balance can fit in u64.
+///
+/// If the chain's total issuance is more than 2*u64::MAX, then a factor might be multiplied and
+/// divided upon conversion.
+pub struct U128CurrencyToVote;
+
+impl U128CurrencyToVote {
+	fn factor(issuance: u128) -> u128 {
+		(issuance / u64::MAX as u128).max(1)
+	}
+}
+
+impl CurrencyToVote<u128> for U128CurrencyToVote {
+	fn to_vote(value: u128, issuance: u128) -> u64 {
+		(value / Self::factor(issuance)).saturated_into()
+	}
+
+	fn to_currency(value: u128, issuance: u128) -> u128 {
+		value.saturating_mul(Self::factor(issuance))
+	}
+
+	fn will_downscale(issuance: u128) -> Option<bool> {
+		Some(issuance > u64::MAX as u128)
+	}
+}
+
+/// A naive implementation of `CurrencyConvert` that simply saturates all conversions.
+///
+/// # Warning
+///
+/// This is designed to be used mostly for testing. Use with care, and think about the consequences.
+pub struct SaturatingCurrencyToVote;
+
+impl<B: UniqueSaturatedInto<u64> + UniqueSaturatedFrom<u128>> CurrencyToVote<B>
+	for SaturatingCurrencyToVote
+{
+	fn to_vote(value: B, _: B) -> u64 {
+		value.unique_saturated_into()
+	}
+
+	fn to_currency(value: u128, _: B) -> B {
+		B::unique_saturated_from(value)
+	}
+
+	fn will_downscale(_issuance: B) -> Option<bool> {
+		None
+	}
+}
+
+#[cfg(feature = "std")]
+impl<B: UniqueSaturatedInto<u64> + UniqueSaturatedFrom<u128>> CurrencyToVote<B> for () {
+	fn to_vote(value: B, issuance: B) -> u64 {
+		SaturatingCurrencyToVote::to_vote(value, issuance)
+	}
+
+	/// Convert u128 to balance.
+	fn to_currency(value: u128, issuance: B) -> B {
+		SaturatingCurrencyToVote::to_currency(value, issuance)
+	}
+
+	fn will_downscale(_issuance: B) -> Option<bool> {
+		None
+	}
+}

bizinikiwi/primitives/staking/src/lib.rs

@@ -0,0 +1,832 @@
+// This file is part of Bizinikiwi.
+
+// Copyright (C) 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.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+//! A crate which contains primitives that are useful for implementation that uses staking
+//! approaches in general. Definitions related to sessions, slashing, etc go here.
+
+extern crate alloc;
+
+use crate::currency_to_vote::CurrencyToVote;
+use alloc::{collections::btree_map::BTreeMap, vec, vec::Vec};
+use codec::{Decode, DecodeWithMemTracking, Encode, FullCodec, HasCompact, MaxEncodedLen};
+use core::ops::{Add, AddAssign, Sub, SubAssign};
+use scale_info::TypeInfo;
+use pezsp_runtime::{
+	traits::{AtLeast32BitUnsigned, Zero},
+	DispatchError, DispatchResult, Perbill, RuntimeDebug, Saturating,
+};
+
+pub mod offence;
+
+pub mod currency_to_vote;
+
+/// Simple index type with which we can count sessions.
+pub type SessionIndex = u32;
+
+/// Counter for the number of eras that have passed.
+pub type EraIndex = u32;
+
+/// Type for identifying a page.
+pub type Page = u32;
+/// Representation of a staking account, which may be a stash or controller account.
+///
+/// Note: once the controller is completely deprecated, this enum can also be deprecated in favor of
+/// the stash account. Tracking issue: <https://github.com/pezkuwichain/kurdistan-sdk/issues/28>.
+#[derive(Clone, Debug)]
+pub enum StakingAccount<AccountId> {
+	Stash(AccountId),
+	Controller(AccountId),
+}
+
+#[cfg(feature = "std")]
+impl<AccountId> From<AccountId> for StakingAccount<AccountId> {
+	fn from(account: AccountId) -> Self {
+		StakingAccount::Stash(account)
+	}
+}
+
+/// Representation of the status of a staker.
+#[derive(RuntimeDebug, TypeInfo)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize, PartialEq, Eq, Clone))]
+pub enum StakerStatus<AccountId> {
+	/// Chilling.
+	Idle,
+	/// Declaring desire in validate, i.e author blocks.
+	Validator,
+	/// Declaring desire to nominate, delegate, or generally approve of the given set of others.
+	Nominator(Vec<AccountId>),
+}
+
+/// A struct that reflects stake that an account has in the staking system. Provides a set of
+/// methods to operate on it's properties. Aimed at making `StakingInterface` more concise.
+#[derive(RuntimeDebug, Clone, Copy, Eq, PartialEq, Default)]
+pub struct Stake<Balance> {
+	/// The total stake that `stash` has in the staking system. This includes the
+	/// `active` stake, and any funds currently in the process of unbonding via
+	/// [`StakingInterface::unbond`].
+	///
+	/// # Note
+	///
+	/// This is only guaranteed to reflect the amount locked by the staking system. If there are
+	/// non-staking locks on the bonded pair's balance this amount is going to be larger in
+	/// reality.
+	pub total: Balance,
+	/// The total amount of the stash's balance that will be at stake in any forthcoming
+	/// rounds.
+	pub active: Balance,
+}
+
+/// A generic staking event listener.
+///
+/// Note that the interface is designed in a way that the events are fired post-action, so any
+/// pre-action data that is needed needs to be passed to interface methods. The rest of the data can
+/// be retrieved by using `StakingInterface`.
+#[impl_trait_for_tuples::impl_for_tuples(10)]
+pub trait OnStakingUpdate<AccountId, Balance> {
+	/// Fired when the stake amount of someone updates.
+	///
+	/// This is effectively any changes to the bond amount, such as bonding more funds, and
+	/// unbonding.
+	fn on_stake_update(_who: &AccountId, _prev_stake: Option<Stake<Balance>>) {}
+
+	/// Fired when someone sets their intention to nominate.
+	///
+	/// This should never be fired for existing nominators.
+	fn on_nominator_add(_who: &AccountId) {}
+
+	/// Fired when an existing nominator updates their nominations.
+	///
+	/// Note that this is not fired when a nominator changes their stake. For that,
+	/// `on_stake_update` should be used, followed by querying whether `who` was a validator or a
+	/// nominator.
+	fn on_nominator_update(_who: &AccountId, _prev_nominations: Vec<AccountId>) {}
+
+	/// Fired when someone removes their intention to nominate, either due to chill or validating.
+	///
+	/// The set of nominations at the time of removal is provided as it can no longer be fetched in
+	/// any way.
+	fn on_nominator_remove(_who: &AccountId, _nominations: Vec<AccountId>) {}
+
+	/// Fired when someone sets their intention to validate.
+	///
+	/// Note validator preference changes are not communicated, but could be added if needed.
+	fn on_validator_add(_who: &AccountId) {}
+
+	/// Fired when an existing validator updates their preferences.
+	///
+	/// Note validator preference changes are not communicated, but could be added if needed.
+	fn on_validator_update(_who: &AccountId) {}
+
+	/// Fired when someone removes their intention to validate, either due to chill or nominating.
+	fn on_validator_remove(_who: &AccountId) {}
+
+	/// Fired when someone is fully unstaked.
+	fn on_unstake(_who: &AccountId) {}
+
+	/// Fired when a staker is slashed.
+	///
+	/// * `stash` - The stash of the staker whom the slash was applied to.
+	/// * `slashed_active` - The new bonded balance of the staker after the slash was applied.
+	/// * `slashed_unlocking` - A map of slashed eras, and the balance of that unlocking chunk after
+	///   the slash is applied. Any era not present in the map is not affected at all.
+	/// * `slashed_total` - The aggregated balance that was lost due to the slash.
+	fn on_slash(
+		_stash: &AccountId,
+		_slashed_active: Balance,
+		_slashed_unlocking: &BTreeMap<EraIndex, Balance>,
+		_slashed_total: Balance,
+	) {
+	}
+
+	/// Fired when a portion of a staker's balance has been withdrawn.
+	fn on_withdraw(_stash: &AccountId, _amount: Balance) {}
+}
+
+/// A generic representation of a staking implementation.
+///
+/// This interface uses the terminology of NPoS, but it is aims to be generic enough to cover other
+/// implementations as well.
+pub trait StakingInterface {
+	/// Balance type used by the staking system.
+	type Balance: Sub<Output = Self::Balance>
+		+ Ord
+		+ PartialEq
+		+ Default
+		+ Copy
+		+ MaxEncodedLen
+		+ FullCodec
+		+ TypeInfo
+		+ Saturating;
+
+	/// AccountId type used by the staking system.
+	type AccountId: Clone + core::fmt::Debug;
+
+	/// Means of converting Currency to VoteWeight.
+	type CurrencyToVote: CurrencyToVote<Self::Balance>;
+
+	/// The minimum amount required to bond in order to set nomination intentions. This does not
+	/// necessarily mean the nomination will be counted in an election, but instead just enough to
+	/// be stored as a nominator. In other words, this is the minimum amount to register the
+	/// intention to nominate.
+	fn minimum_nominator_bond() -> Self::Balance;
+
+	/// The minimum amount required to bond in order to set validation intentions.
+	fn minimum_validator_bond() -> Self::Balance;
+
+	/// Return a stash account that is controlled by a `controller`.
+	///
+	/// ## Note
+	///
+	/// The controller abstraction is not permanent and might go away. Avoid using this as much as
+	/// possible.
+	fn stash_by_ctrl(controller: &Self::AccountId) -> Result<Self::AccountId, DispatchError>;
+
+	/// Number of eras that staked funds must remain bonded for.
+	fn bonding_duration() -> EraIndex;
+
+	/// The current era index.
+	///
+	/// This should be the latest planned era that the staking system knows about.
+	fn current_era() -> EraIndex;
+
+	/// Returns the [`Stake`] of `who`.
+	fn stake(who: &Self::AccountId) -> Result<Stake<Self::Balance>, DispatchError>;
+
+	/// Total stake of a staker, `Err` if not a staker.
+	fn total_stake(who: &Self::AccountId) -> Result<Self::Balance, DispatchError> {
+		Self::stake(who).map(|s| s.total)
+	}
+
+	/// Total active portion of a staker's [`Stake`], `Err` if not a staker.
+	fn active_stake(who: &Self::AccountId) -> Result<Self::Balance, DispatchError> {
+		Self::stake(who).map(|s| s.active)
+	}
+
+	/// Returns whether a staker is unbonding, `Err` if not a staker at all.
+	fn is_unbonding(who: &Self::AccountId) -> Result<bool, DispatchError> {
+		Self::stake(who).map(|s| s.active != s.total)
+	}
+
+	/// Returns whether a staker is FULLY unbonding, `Err` if not a staker at all.
+	fn fully_unbond(who: &Self::AccountId) -> DispatchResult {
+		Self::unbond(who, Self::stake(who)?.active)
+	}
+
+	/// Bond (lock) `value` of `who`'s balance, while forwarding any rewards to `payee`.
+	fn bond(who: &Self::AccountId, value: Self::Balance, payee: &Self::AccountId)
+		-> DispatchResult;
+
+	/// Have `who` nominate `validators`.
+	fn nominate(who: &Self::AccountId, validators: Vec<Self::AccountId>) -> DispatchResult;
+
+	/// Chill `who`.
+	fn chill(who: &Self::AccountId) -> DispatchResult;
+
+	/// Bond some extra amount in `who`'s free balance against the active bonded balance of
+	/// the account. The amount extra actually bonded will never be more than `who`'s free
+	/// balance.
+	fn bond_extra(who: &Self::AccountId, extra: Self::Balance) -> DispatchResult;
+
+	/// Schedule a portion of the active bonded balance to be unlocked at era
+	/// [Self::current_era] + [`Self::bonding_duration`].
+	///
+	/// Once the unlock era has been reached, [`Self::withdraw_unbonded`] can be called to unlock
+	/// the funds.
+	///
+	/// The amount of times this can be successfully called is limited based on how many distinct
+	/// eras funds are schedule to unlock in. Calling [`Self::withdraw_unbonded`] after some unlock
+	/// schedules have reached their unlocking era should allow more calls to this function.
+	fn unbond(stash: &Self::AccountId, value: Self::Balance) -> DispatchResult;
+
+	/// Set the reward destination for the ledger associated with the stash.
+	fn set_payee(stash: &Self::AccountId, reward_acc: &Self::AccountId) -> DispatchResult;
+
+	/// Unlock any funds schedule to unlock before or at the current era.
+	///
+	/// Returns whether the stash was killed because of this withdraw or not.
+	fn withdraw_unbonded(
+		stash: Self::AccountId,
+		num_slashing_spans: u32,
+	) -> Result<bool, DispatchError>;
+
+	/// The ideal number of active validators.
+	fn desired_validator_count() -> u32;
+
+	/// Whether or not there is an ongoing election.
+	fn election_ongoing() -> bool;
+
+	/// Force a current staker to become completely unstaked, immediately.
+	fn force_unstake(who: Self::AccountId) -> DispatchResult;
+
+	/// Checks whether an account `staker` has been exposed in an era.
+	fn is_exposed_in_era(who: &Self::AccountId, era: &EraIndex) -> bool;
+
+	/// Return the status of the given staker, `Err` if not staked at all.
+	fn status(who: &Self::AccountId) -> Result<StakerStatus<Self::AccountId>, DispatchError>;
+
+	/// Checks whether or not this is a validator account.
+	fn is_validator(who: &Self::AccountId) -> bool {
+		Self::status(who).map(|s| matches!(s, StakerStatus::Validator)).unwrap_or(false)
+	}
+
+	/// Checks whether the staker is a virtual account.
+	///
+	/// A virtual staker is an account whose locks are not managed by the [`StakingInterface`]
+	/// implementation but by an external pallet. See [`StakingUnchecked::virtual_bond`] for more
+	/// details.
+	fn is_virtual_staker(who: &Self::AccountId) -> bool;
+
+	/// Get the nominations of a stash, if they are a nominator, `None` otherwise.
+	fn nominations(who: &Self::AccountId) -> Option<Vec<Self::AccountId>> {
+		match Self::status(who) {
+			Ok(StakerStatus::Nominator(t)) => Some(t),
+			_ => None,
+		}
+	}
+
+	/// Returns the fraction of the slash to be rewarded to reporter.
+	fn slash_reward_fraction() -> Perbill;
+
+	#[cfg(feature = "runtime-benchmarks")]
+	fn max_exposure_page_size() -> Page;
+
+	#[cfg(feature = "runtime-benchmarks")]
+	fn add_era_stakers(
+		current_era: &EraIndex,
+		stash: &Self::AccountId,
+		exposures: Vec<(Self::AccountId, Self::Balance)>,
+	);
+
+	#[cfg(feature = "runtime-benchmarks")]
+	fn set_current_era(era: EraIndex);
+}
+
+/// Set of low level apis to manipulate staking ledger.
+///
+/// These apis bypass some or all safety checks and should only be used if you know what you are
+/// doing.
+pub trait StakingUnchecked: StakingInterface {
+	/// Migrate an existing staker to a virtual staker.
+	///
+	/// It would release all funds held by the implementation pallet.
+	fn migrate_to_virtual_staker(who: &Self::AccountId) -> DispatchResult;
+
+	/// Book-keep a new bond for `keyless_who` without applying any locks (hence virtual).
+	///
+	/// It is important that `keyless_who` is a keyless account and therefore cannot interact with
+	/// staking pallet directly. Caller is responsible for ensuring the passed amount is locked and
+	/// valid.
+	fn virtual_bond(
+		keyless_who: &Self::AccountId,
+		value: Self::Balance,
+		payee: &Self::AccountId,
+	) -> DispatchResult;
+
+	/// Migrate a virtual staker to a direct staker.
+	///
+	/// Only used for testing.
+	#[cfg(feature = "runtime-benchmarks")]
+	fn migrate_to_direct_staker(who: &Self::AccountId);
+}
+
+/// The amount of exposure for an era that an individual nominator has (susceptible to slashing).
+#[derive(
+	PartialEq,
+	Eq,
+	PartialOrd,
+	Ord,
+	Clone,
+	Encode,
+	Decode,
+	DecodeWithMemTracking,
+	RuntimeDebug,
+	TypeInfo,
+	Copy,
+)]
+pub struct IndividualExposure<AccountId, Balance: HasCompact> {
+	/// The stash account of the nominator in question.
+	pub who: AccountId,
+	/// Amount of funds exposed.
+	#[codec(compact)]
+	pub value: Balance,
+}
+
+/// A snapshot of the stake backing a single validator in the system.
+#[derive(
+	PartialEq,
+	Eq,
+	PartialOrd,
+	Ord,
+	Clone,
+	Encode,
+	Decode,
+	DecodeWithMemTracking,
+	RuntimeDebug,
+	TypeInfo,
+)]
+pub struct Exposure<AccountId, Balance: HasCompact> {
+	/// The total balance backing this validator.
+	#[codec(compact)]
+	pub total: Balance,
+	/// The validator's own stash that is exposed.
+	#[codec(compact)]
+	pub own: Balance,
+	/// The portions of nominators stashes that are exposed.
+	pub others: Vec<IndividualExposure<AccountId, Balance>>,
+}
+
+impl<AccountId, Balance: Default + HasCompact> Default for Exposure<AccountId, Balance> {
+	fn default() -> Self {
+		Self { total: Default::default(), own: Default::default(), others: vec![] }
+	}
+}
+
+impl<
+		AccountId: Clone,
+		Balance: HasCompact + AtLeast32BitUnsigned + Copy + codec::MaxEncodedLen,
+	> Exposure<AccountId, Balance>
+{
+	/// Splits self into two instances of exposures.
+	///
+	/// `n_others` individual exposures are consumed from self and returned as part of the new
+	/// exposure.
+	///
+	/// Since this method splits `others` of a single exposure, `total.own` will be the same for
+	/// both `self` and the returned exposure.
+	pub fn split_others(&mut self, n_others: u32) -> Self {
+		let head_others: Vec<_> =
+			self.others.drain(..(n_others as usize).min(self.others.len())).collect();
+
+		let total_others_head: Balance = head_others
+			.iter()
+			.fold(Zero::zero(), |acc: Balance, o| acc.saturating_add(o.value));
+
+		self.total = self.total.saturating_sub(total_others_head);
+
+		Self {
+			total: total_others_head.saturating_add(self.own),
+			own: self.own,
+			others: head_others,
+		}
+	}
+
+	/// Converts an `Exposure` into `PagedExposureMetadata` and multiple chunks of
+	/// `IndividualExposure` with each chunk having maximum of `page_size` elements.
+	pub fn into_pages(
+		self,
+		page_size: Page,
+	) -> (PagedExposureMetadata<Balance>, Vec<ExposurePage<AccountId, Balance>>) {
+		let individual_chunks = self.others.chunks(page_size as usize);
+		let mut exposure_pages: Vec<ExposurePage<AccountId, Balance>> =
+			Vec::with_capacity(individual_chunks.len());
+
+		for chunk in individual_chunks {
+			let mut page_total: Balance = Zero::zero();
+			let mut others: Vec<IndividualExposure<AccountId, Balance>> =
+				Vec::with_capacity(chunk.len());
+			for individual in chunk.iter() {
+				page_total.saturating_accrue(individual.value);
+				others.push(IndividualExposure {
+					who: individual.who.clone(),
+					value: individual.value,
+				})
+			}
+			exposure_pages.push(ExposurePage { page_total, others });
+		}
+
+		(
+			PagedExposureMetadata {
+				total: self.total,
+				own: self.own,
+				nominator_count: self.others.len() as u32,
+				page_count: exposure_pages.len() as Page,
+			},
+			exposure_pages,
+		)
+	}
+}
+
+/// A snapshot of the stake backing a single validator in the system.
+#[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Encode, Decode, RuntimeDebug, TypeInfo)]
+pub struct ExposurePage<AccountId, Balance: HasCompact> {
+	/// The total balance of this chunk/page.
+	#[codec(compact)]
+	pub page_total: Balance,
+	/// The portions of nominators stashes that are exposed.
+	pub others: Vec<IndividualExposure<AccountId, Balance>>,
+}
+
+impl<A, B: Default + HasCompact> Default for ExposurePage<A, B> {
+	fn default() -> Self {
+		ExposurePage { page_total: Default::default(), others: vec![] }
+	}
+}
+
+/// Returns an exposure page from a set of individual exposures.
+impl<A, B: HasCompact + Default + AddAssign + SubAssign + Clone> From<Vec<IndividualExposure<A, B>>>
+	for ExposurePage<A, B>
+{
+	fn from(exposures: Vec<IndividualExposure<A, B>>) -> Self {
+		exposures.into_iter().fold(ExposurePage::default(), |mut page, e| {
+			page.page_total += e.value.clone();
+			page.others.push(e);
+			page
+		})
+	}
+}
+
+/// Metadata for Paged Exposure of a validator such as total stake across pages and page count.
+///
+/// In combination with the associated `ExposurePage`s, it can be used to reconstruct a full
+/// `Exposure` set of a validator. This is useful for cases where we want to query full set of
+/// `Exposure` as one page (for backward compatibility).
+#[derive(
+	PartialEq,
+	Eq,
+	PartialOrd,
+	Ord,
+	Clone,
+	Encode,
+	Decode,
+	RuntimeDebug,
+	TypeInfo,
+	Default,
+	MaxEncodedLen,
+	Copy,
+)]
+pub struct PagedExposureMetadata<Balance: HasCompact + codec::MaxEncodedLen> {
+	/// The total balance backing this validator.
+	#[codec(compact)]
+	pub total: Balance,
+	/// The validator's own stash that is exposed.
+	#[codec(compact)]
+	pub own: Balance,
+	/// Number of nominators backing this validator.
+	pub nominator_count: u32,
+	/// Number of pages of nominators.
+	pub page_count: Page,
+}
+
+impl<Balance> PagedExposureMetadata<Balance>
+where
+	Balance: HasCompact
+		+ codec::MaxEncodedLen
+		+ Add<Output = Balance>
+		+ Sub<Output = Balance>
+		+ pezsp_runtime::Saturating
+		+ PartialEq
+		+ Copy
+		+ pezsp_runtime::traits::Debug,
+{
+	/// Consumes self and returns the result of the metadata updated with `other_balances` and
+	/// of adding `other_num` nominators to the metadata.
+	///
+	/// `Max` is a getter of the maximum number of nominators per page.
+	pub fn update_with<Max: pezsp_core::Get<u32>>(
+		self,
+		others_balance: Balance,
+		others_num: u32,
+	) -> Self {
+		let page_limit = Max::get().max(1);
+		let new_nominator_count = self.nominator_count.saturating_add(others_num);
+		let new_page_count = new_nominator_count
+			.saturating_add(page_limit)
+			.saturating_sub(1)
+			.saturating_div(page_limit);
+
+		Self {
+			total: self.total.saturating_add(others_balance),
+			own: self.own,
+			nominator_count: new_nominator_count,
+			page_count: new_page_count,
+		}
+	}
+}
+
+/// A type that belongs only in the context of an `Agent`.
+///
+/// `Agent` is someone that manages delegated funds from [`Delegator`] accounts. It can
+/// then use these funds to participate in the staking system. It can never use its own funds to
+/// stake. They instead (virtually bond)[`StakingUnchecked::virtual_bond`] into the staking system
+/// and are also called `Virtual Stakers`.
+///
+/// The `Agent` is also responsible for managing rewards and slashing for all the `Delegators` that
+/// have delegated funds to it.
+#[derive(Clone, Debug)]
+pub struct Agent<T>(T);
+impl<T> From<T> for Agent<T> {
+	fn from(acc: T) -> Self {
+		Agent(acc)
+	}
+}
+
+impl<T> Agent<T> {
+	pub fn get(self) -> T {
+		self.0
+	}
+}
+
+/// A type that belongs only in the context of a `Delegator`.
+///
+/// `Delegator` is someone that delegates funds to an `Agent`, allowing them to pool funds
+/// along with other delegators and participate in the staking system.
+#[derive(Clone, Debug)]
+pub struct Delegator<T>(T);
+impl<T> From<T> for Delegator<T> {
+	fn from(acc: T) -> Self {
+		Delegator(acc)
+	}
+}
+
+impl<T> Delegator<T> {
+	pub fn get(self) -> T {
+		self.0
+	}
+}
+
+/// Trait to provide delegation functionality for stakers.
+pub trait DelegationInterface {
+	/// Balance type used by the staking system.
+	type Balance: Sub<Output = Self::Balance>
+		+ Ord
+		+ PartialEq
+		+ Default
+		+ Copy
+		+ MaxEncodedLen
+		+ FullCodec
+		+ TypeInfo
+		+ Saturating;
+
+	/// AccountId type used by the staking system.
+	type AccountId: Clone + core::fmt::Debug;
+
+	/// Returns effective balance of the `Agent` account. `None` if not an `Agent`.
+	///
+	/// This takes into account any pending slashes to `Agent` against the delegated balance.
+	fn agent_balance(agent: Agent<Self::AccountId>) -> Option<Self::Balance>;
+
+	/// Returns the total amount of funds that is unbonded and can be withdrawn from the `Agent`
+	/// account. `None` if not an `Agent`.
+	fn agent_transferable_balance(agent: Agent<Self::AccountId>) -> Option<Self::Balance>;
+
+	/// Returns the total amount of funds delegated. `None` if not a `Delegator`.
+	fn delegator_balance(delegator: Delegator<Self::AccountId>) -> Option<Self::Balance>;
+
+	/// Register `Agent` such that it can accept delegation.
+	fn register_agent(
+		agent: Agent<Self::AccountId>,
+		reward_account: &Self::AccountId,
+	) -> DispatchResult;
+
+	/// Removes `Agent` registration.
+	///
+	/// This should only be allowed if the agent has no staked funds.
+	fn remove_agent(agent: Agent<Self::AccountId>) -> DispatchResult;
+
+	/// Add delegation to the `Agent`.
+	fn delegate(
+		delegator: Delegator<Self::AccountId>,
+		agent: Agent<Self::AccountId>,
+		amount: Self::Balance,
+	) -> DispatchResult;
+
+	/// Withdraw or revoke delegation to `Agent`.
+	///
+	/// If there are `Agent` funds upto `amount` available to withdraw, then those funds would
+	/// be released to the `delegator`
+	fn withdraw_delegation(
+		delegator: Delegator<Self::AccountId>,
+		agent: Agent<Self::AccountId>,
+		amount: Self::Balance,
+		num_slashing_spans: u32,
+	) -> DispatchResult;
+
+	/// Returns pending slashes posted to the `Agent` account. None if not an `Agent`.
+	///
+	/// Slashes to `Agent` account are not immediate and are applied lazily. Since `Agent`
+	/// has an unbounded number of delegators, immediate slashing is not possible.
+	fn pending_slash(agent: Agent<Self::AccountId>) -> Option<Self::Balance>;
+
+	/// Apply a pending slash to an `Agent` by slashing `value` from `delegator`.
+	///
+	/// A reporter may be provided (if one exists) in order for the implementor to reward them,
+	/// if applicable.
+	fn delegator_slash(
+		agent: Agent<Self::AccountId>,
+		delegator: Delegator<Self::AccountId>,
+		value: Self::Balance,
+		maybe_reporter: Option<Self::AccountId>,
+	) -> DispatchResult;
+}
+
+/// Trait to provide functionality for direct stakers to migrate to delegation agents.
+/// See [`DelegationInterface`] for more details on delegation.
+pub trait DelegationMigrator {
+	/// Balance type used by the staking system.
+	type Balance: Sub<Output = Self::Balance>
+		+ Ord
+		+ PartialEq
+		+ Default
+		+ Copy
+		+ MaxEncodedLen
+		+ FullCodec
+		+ TypeInfo
+		+ Saturating;
+
+	/// AccountId type used by the staking system.
+	type AccountId: Clone + core::fmt::Debug;
+
+	/// Migrate an existing `Nominator` to `Agent` account.
+	///
+	/// The implementation should ensure the `Nominator` account funds are moved to an escrow
+	/// from which `Agents` can later release funds to its `Delegators`.
+	fn migrate_nominator_to_agent(
+		agent: Agent<Self::AccountId>,
+		reward_account: &Self::AccountId,
+	) -> DispatchResult;
+
+	/// Migrate `value` of delegation to `delegator` from a migrating agent.
+	///
+	/// When a direct `Nominator` migrates to `Agent`, the funds are kept in escrow. This function
+	/// allows the `Agent` to release the funds to the `delegator`.
+	fn migrate_delegation(
+		agent: Agent<Self::AccountId>,
+		delegator: Delegator<Self::AccountId>,
+		value: Self::Balance,
+	) -> DispatchResult;
+
+	/// Drop the `Agent` account and its associated delegators.
+	///
+	/// Also removed from [`StakingUnchecked`] as a Virtual Staker. Useful for testing.
+	#[cfg(feature = "runtime-benchmarks")]
+	fn force_kill_agent(agent: Agent<Self::AccountId>);
+}
+
+pezsp_core::generate_feature_enabled_macro!(runtime_benchmarks_enabled, feature = "runtime-benchmarks", $);
+
+#[cfg(test)]
+mod tests {
+	use pezsp_core::ConstU32;
+
+	use super::*;
+
+	#[test]
+	fn update_with_works() {
+		let metadata = PagedExposureMetadata::<u32> {
+			total: 1000,
+			own: 0, // don't care
+			nominator_count: 10,
+			page_count: 1,
+		};
+
+		assert_eq!(
+			metadata.update_with::<ConstU32<10>>(1, 1),
+			PagedExposureMetadata { total: 1001, own: 0, nominator_count: 11, page_count: 2 },
+		);
+
+		assert_eq!(
+			metadata.update_with::<ConstU32<5>>(1, 1),
+			PagedExposureMetadata { total: 1001, own: 0, nominator_count: 11, page_count: 3 },
+		);
+
+		assert_eq!(
+			metadata.update_with::<ConstU32<4>>(1, 1),
+			PagedExposureMetadata { total: 1001, own: 0, nominator_count: 11, page_count: 3 },
+		);
+
+		assert_eq!(
+			metadata.update_with::<ConstU32<1>>(1, 1),
+			PagedExposureMetadata { total: 1001, own: 0, nominator_count: 11, page_count: 11 },
+		);
+	}
+
+	#[test]
+	fn individual_exposures_to_exposure_works() {
+		let exposure_1 = IndividualExposure { who: 1, value: 10u32 };
+		let exposure_2 = IndividualExposure { who: 2, value: 20 };
+		let exposure_3 = IndividualExposure { who: 3, value: 30 };
+
+		let exposure_page: ExposurePage<u32, u32> = vec![exposure_1, exposure_2, exposure_3].into();
+
+		assert_eq!(
+			exposure_page,
+			ExposurePage { page_total: 60, others: vec![exposure_1, exposure_2, exposure_3] },
+		);
+	}
+
+	#[test]
+	fn empty_individual_exposures_to_exposure_works() {
+		let empty_exposures: Vec<IndividualExposure<u32, u32>> = vec![];
+
+		let exposure_page: ExposurePage<u32, u32> = empty_exposures.into();
+		assert_eq!(exposure_page, ExposurePage { page_total: 0, others: vec![] });
+	}
+
+	#[test]
+	fn exposure_split_others_works() {
+		let exposure = Exposure {
+			total: 100,
+			own: 20,
+			others: vec![
+				IndividualExposure { who: 1, value: 20u32 },
+				IndividualExposure { who: 2, value: 20 },
+				IndividualExposure { who: 3, value: 20 },
+				IndividualExposure { who: 4, value: 20 },
+			],
+		};
+
+		let mut exposure_0 = exposure.clone();
+		// split others with with 0 `n_others` is a noop and returns an empty exposure (with `own`
+		// only).
+		let split_exposure = exposure_0.split_others(0);
+		assert_eq!(exposure_0, exposure);
+		assert_eq!(split_exposure, Exposure { total: 20, own: 20, others: vec![] });
+
+		let mut exposure_1 = exposure.clone();
+		// split individual exposures so that the returned exposure has 1 individual exposure.
+		let split_exposure = exposure_1.split_others(1);
+		assert_eq!(exposure_1.own, 20);
+		assert_eq!(exposure_1.total, 20 + 3 * 20);
+		assert_eq!(exposure_1.others.len(), 3);
+
+		assert_eq!(split_exposure.own, 20);
+		assert_eq!(split_exposure.total, 20 + 1 * 20);
+		assert_eq!(split_exposure.others.len(), 1);
+
+		let mut exposure_3 = exposure.clone();
+		// split individual exposures so that the returned exposure has 3 individual exposures,
+		// which are consumed from the original exposure.
+		let split_exposure = exposure_3.split_others(3);
+		assert_eq!(exposure_3.own, 20);
+		assert_eq!(exposure_3.total, 20 + 1 * 20);
+		assert_eq!(exposure_3.others.len(), 1);
+
+		assert_eq!(split_exposure.own, 20);
+		assert_eq!(split_exposure.total, 20 + 3 * 20);
+		assert_eq!(split_exposure.others.len(), 3);
+
+		let mut exposure_max = exposure.clone();
+		// split others with with more `n_others` than the number of others in the exposure
+		// consumes all the individual exposures of the original Exposure and returns them in the
+		// new exposure.
+		let split_exposure = exposure_max.split_others(u32::MAX);
+		assert_eq!(split_exposure, exposure);
+		assert_eq!(exposure_max, Exposure { total: 20, own: 20, others: vec![] });
+	}
+}

bizinikiwi/primitives/staking/src/offence.rs

@@ -0,0 +1,297 @@
+// This file is part of Bizinikiwi.
+
+// Copyright (C) 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.
+
+//! Common traits and types that are useful for describing offences for usage in environments
+//! that use staking.
+
+use alloc::vec::Vec;
+use codec::{Decode, Encode, MaxEncodedLen};
+use pezsp_core::Get;
+use pezsp_runtime::{transaction_validity::TransactionValidityError, DispatchError, Perbill};
+
+use crate::SessionIndex;
+
+/// The kind of an offence, is a byte string representing some kind identifier
+/// e.g. `b"im-online:offlin"`, `b"babe:equivocatio"`
+pub type Kind = [u8; 16];
+
+/// Number of times the offence of this authority was already reported in the past.
+///
+/// Note that we don't buffer offence reporting, so every time we see a new offence
+/// of the same kind, we will report past authorities again.
+/// This counter keeps track of how many times the authority was already reported in the past,
+/// so that we can slash it accordingly.
+pub type OffenceCount = u32;
+
+/// A trait implemented by an offence report.
+///
+/// This trait assumes that the offence is legitimate and was validated already.
+///
+/// Examples of offences include: a BABE equivocation or a GRANDPA unjustified vote.
+pub trait Offence<Offender> {
+	/// Identifier which is unique for this kind of an offence.
+	const ID: Kind;
+
+	/// A type that represents a point in time on an abstract timescale.
+	///
+	/// See `Offence::time_slot` for details. The only requirement is that such timescale could be
+	/// represented by a single `u128` value.
+	type TimeSlot: Clone + codec::Codec + Ord;
+
+	/// The list of all offenders involved in this incident.
+	///
+	/// The list has no duplicates, so it is rather a set.
+	fn offenders(&self) -> Vec<Offender>;
+
+	/// The session index that is used for querying the validator set for the `slash_fraction`
+	/// function.
+	///
+	/// This is used for filtering historical sessions.
+	fn session_index(&self) -> SessionIndex;
+
+	/// Return a validator set count at the time when the offence took place.
+	fn validator_set_count(&self) -> u32;
+
+	/// A point in time when this offence happened.
+	///
+	/// This is used for looking up offences that happened at the "same time".
+	///
+	/// The timescale is abstract and doesn't have to be the same across different implementations
+	/// of this trait. The value doesn't represent absolute timescale though since it is interpreted
+	/// along with the `session_index`. Two offences are considered to happen at the same time iff
+	/// both `session_index` and `time_slot` are equal.
+	///
+	/// As an example, for GRANDPA timescale could be a round number and for BABE it could be a slot
+	/// number. Note that for GRANDPA the round number is reset each epoch.
+	fn time_slot(&self) -> Self::TimeSlot;
+
+	/// A slash fraction of the total exposure that should be slashed for this
+	/// particular offence for the `offenders_count` that happened at a singular `TimeSlot`.
+	///
+	/// `offenders_count` - the count of unique offending authorities for this `TimeSlot`. It is >0.
+	fn slash_fraction(&self, offenders_count: u32) -> Perbill;
+}
+
+/// Errors that may happen on offence reports.
+#[derive(PartialEq, pezsp_runtime::RuntimeDebug)]
+pub enum OffenceError {
+	/// The report has already been submitted.
+	DuplicateReport,
+
+	/// Other error has happened.
+	Other(u8),
+}
+
+impl pezsp_runtime::traits::Printable for OffenceError {
+	fn print(&self) {
+		"OffenceError".print();
+		match self {
+			Self::DuplicateReport => "DuplicateReport".print(),
+			Self::Other(e) => {
+				"Other".print();
+				e.print();
+			},
+		}
+	}
+}
+
+/// A trait for decoupling offence reporters from the actual handling of offence reports.
+pub trait ReportOffence<Reporter, Offender, O: Offence<Offender>> {
+	/// Report an `offence` and reward given `reporters`.
+	fn report_offence(reporters: Vec<Reporter>, offence: O) -> Result<(), OffenceError>;
+
+	/// Returns true iff all of the given offenders have been previously reported
+	/// at the given time slot. This function is useful to prevent the sending of
+	/// duplicate offence reports.
+	fn is_known_offence(offenders: &[Offender], time_slot: &O::TimeSlot) -> bool;
+}
+
+impl<Reporter, Offender, O: Offence<Offender>> ReportOffence<Reporter, Offender, O> for () {
+	fn report_offence(_reporters: Vec<Reporter>, _offence: O) -> Result<(), OffenceError> {
+		Ok(())
+	}
+
+	fn is_known_offence(_offenders: &[Offender], _time_slot: &O::TimeSlot) -> bool {
+		true
+	}
+}
+
+/// A trait to take action on an offence.
+///
+/// Used to decouple the module that handles offences and
+/// the one that should punish for those offences.
+pub trait OnOffenceHandler<Reporter, Offender, Res> {
+	/// A handler for an offence of a particular kind.
+	///
+	/// Note that this contains a list of all previous offenders
+	/// as well. The implementer should cater for a case, where
+	/// the same authorities were reported for the same offence
+	/// in the past (see `OffenceCount`).
+	///
+	/// The vector of `slash_fraction` contains `Perbill`s
+	/// the authorities should be slashed and is computed
+	/// according to the `OffenceCount` already. This is of the same length as `offenders.`
+	/// Zero is a valid value for a fraction.
+	///
+	/// The `session` parameter is the session index of the offence.
+	///
+	/// The receiver might decide to not accept this offence. In this case, the call site is
+	/// responsible for queuing the report and re-submitting again.
+	fn on_offence(
+		offenders: &[OffenceDetails<Reporter, Offender>],
+		slash_fraction: &[Perbill],
+		session: SessionIndex,
+	) -> Res;
+}
+
+impl<Reporter, Offender, Res: Default> OnOffenceHandler<Reporter, Offender, Res> for () {
+	fn on_offence(
+		_offenders: &[OffenceDetails<Reporter, Offender>],
+		_slash_fraction: &[Perbill],
+		_session: SessionIndex,
+	) -> Res {
+		Default::default()
+	}
+}
+
+/// A details about an offending authority for a particular kind of offence.
+#[derive(Clone, PartialEq, Eq, Encode, Decode, pezsp_runtime::RuntimeDebug, scale_info::TypeInfo)]
+pub struct OffenceDetails<Reporter, Offender> {
+	/// The offending authority id
+	pub offender: Offender,
+	/// A list of reporters of offences of this authority ID. Possibly empty where there are no
+	/// 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(())
+	}
+}
+
+/// Wrapper type representing the severity of an offence.
+///
+/// As of now the only meaningful value taken into account
+/// when deciding the severity of an offence is the associated
+/// slash amount `Perbill`.
+///
+/// For instance used for the purposes of distinguishing who should be
+/// prioritized for disablement.
+#[derive(
+	Clone,
+	Copy,
+	PartialEq,
+	Eq,
+	Encode,
+	Decode,
+	MaxEncodedLen,
+	core::fmt::Debug,
+	scale_info::TypeInfo,
+)]
+pub struct OffenceSeverity(pub Perbill);
+
+impl OffenceSeverity {
+	/// Returns the maximum severity.
+	pub fn max_severity() -> Self {
+		Self(Perbill::from_percent(100))
+	}
+
+	/// Returns the minimum severity.
+	pub fn min_severity() -> Self {
+		Self(Perbill::from_percent(0))
+	}
+}
+
+impl Default for OffenceSeverity {
+	/// Default is the maximum severity.
+	/// When severity is unclear it is best to assume the worst.
+	fn default() -> Self {
+		Self::max_severity()
+	}
+}
+
+impl PartialOrd for OffenceSeverity {
+	fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
+		self.0.partial_cmp(&other.0)
+	}
+}
+
+impl Ord for OffenceSeverity {
+	fn cmp(&self, other: &Self) -> core::cmp::Ordering {
+		self.0.cmp(&other.0)
+	}
+}