Redesign Slash/SlashReport types with a function to calculate the penalty

substrate/validator-sets/primitives/src/slash_points.rs

@@ -0,0 +1,258 @@
+use core::{num::NonZero, time::Duration};
+
+#[cfg(feature = "std")]
+use zeroize::Zeroize;
+
+use scale::{Encode, Decode, MaxEncodedLen};
+use scale_info::TypeInfo;
+
+#[cfg(feature = "borsh")]
+use borsh::{BorshSerialize, BorshDeserialize};
+#[cfg(feature = "serde")]
+use serde::{Serialize, Deserialize};
+
+use sp_core::{ConstU32, bounded::BoundedVec};
+#[cfg(not(feature = "std"))]
+use sp_std::vec::Vec;
+
+use serai_primitives::{TARGET_BLOCK_TIME, Amount};
+
+use crate::{SESSION_LENGTH, MAX_KEY_SHARES_PER_SET_U32};
+
+/// Each slash point is equivalent to the downtime implied by missing a block proposal.
+// Takes a NonZero<u16> so that the result is never 0.
+fn downtime_per_slash_point(validators: NonZero<u16>) -> Duration {
+  Duration::from_secs(TARGET_BLOCK_TIME) * u32::from(u16::from(validators))
+}
+
+/// A slash for a validator.
+#[derive(Clone, Copy, PartialEq, Eq, Debug, Encode, Decode, MaxEncodedLen, TypeInfo)]
+#[cfg_attr(feature = "std", derive(Zeroize))]
+#[cfg_attr(feature = "borsh", derive(BorshSerialize, BorshDeserialize))]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub enum Slash {
+  /// The slash points accumulated by this validator.
+  ///
+  /// Each point is considered as `downtime_per_slash_point(validators)` downtime, where
+  /// `validators` is the amount of validators present in the set.
+  Points(u32),
+  /// A fatal slash due to fundamentally faulty behavior.
+  ///
+  /// This should only be used for misbehavior with explicit evidence of impropriety. This should
+  /// not be used for liveness failures. The validator will be penalized all allocated stake.
+  Fatal,
+}
+
+impl Slash {
+  /// Calculate the penalty which should be applied to the validator.
+  ///
+  /// Does not panic, even due to overflows, if `allocated_stake + session_rewards <= u64::MAX`.
+  pub fn penalty(
+    self,
+    validators: NonZero<u16>,
+    allocated_stake: Amount,
+    session_rewards: Amount,
+  ) -> Amount {
+    match self {
+      Self::Points(slash_points) => {
+        let mut slash_points = u64::from(slash_points);
+        // Do the logic with the stake in u128 to prevent overflow from multiplying u64s
+        let allocated_stake = u128::from(allocated_stake.0);
+        let session_rewards = u128::from(session_rewards.0);
+
+        // A Serai validator is allowed to be offline for an average of one day every two weeks
+        // with no additional penalty. They'll solely not earn rewards for the time they were
+        // offline.
+        const GRACE_WINDOW: Duration = Duration::from_secs(2 * 7 * 24 * 60 * 60);
+        const GRACE: Duration = Duration::from_secs(24 * 60 * 60);
+
+        // GRACE / GRACE_WINDOW is the fraction of the time a validator is allowed to be offline
+        // This means we want SESSION_LENGTH * (GRACE / GRACE_WINDOW), but with the parentheses
+        // moved so we don't incur the floordiv and hit 0
+        const PENALTY_FREE_DOWNTIME: Duration = Duration::from_secs(
+          (SESSION_LENGTH.as_secs() * GRACE.as_secs()) / GRACE_WINDOW.as_secs(),
+        );
+
+        let downtime_per_slash_point = downtime_per_slash_point(validators);
+        let penalty_free_slash_points =
+          PENALTY_FREE_DOWNTIME.as_secs() / downtime_per_slash_point.as_secs();
+
+        /*
+          In practice, the following means:
+
+          - Hours 0-12 are penalized as if they're hours 0-12.
+          - Hours 12-24 are penalized as if they're hours 12-36.
+          - Hours 24-36 are penalized as if they're hours 36-96.
+          - Hours 36-48 are penalized as if they're hours 96-168.
+          - Hours 48-168 are penalized for 0-2% of stake.
+          - 168-336 hours of slashes, for a session only lasting 168 hours, is penalized for 2-10%
+            of stake.
+
+          This means a validator offline has to be offline for more than two days to start having
+          their stake slashed.
+        */
+
+        const MULTIPLIERS: [u64; 4] = [1, 2, 5, 6];
+        let reward_slash = {
+          // In intervals of the penalty-free slash points, weight the slash points accrued
+          // The multiplier for the first interval is 1 as it's penalty-free
+          let mut weighted_slash_points_for_reward_slash = 0;
+          let mut total_possible_slash_points_for_rewards_slash = 0;
+          for mult in MULTIPLIERS {
+            let slash_points_in_interval = slash_points.min(penalty_free_slash_points);
+            weighted_slash_points_for_reward_slash += slash_points_in_interval * mult;
+            total_possible_slash_points_for_rewards_slash += penalty_free_slash_points * mult;
+            slash_points -= slash_points_in_interval;
+          }
+          // If there are no penalty-free slash points, and the validator was slashed, slash the
+          // entire reward
+          (u128::from(weighted_slash_points_for_reward_slash) * session_rewards)
+            .checked_div(u128::from(total_possible_slash_points_for_rewards_slash))
+            .unwrap_or({
+              if weighted_slash_points_for_reward_slash == 0 {
+                0
+              } else {
+                session_rewards
+              }
+            })
+        };
+
+        let slash_points_for_entire_session =
+          SESSION_LENGTH.as_secs() / downtime_per_slash_point.as_secs();
+
+        let offline_slash = {
+          // The amount of stake to slash for being offline
+          const MAX_STAKE_SLASH_PERCENTAGE_OFFLINE: u64 = 2;
+
+          let stake_to_slash_for_being_offline =
+            (allocated_stake * u128::from(MAX_STAKE_SLASH_PERCENTAGE_OFFLINE)) / 100;
+
+          // We already removed the slash points for `intervals * penalty_free_slash_points`
+          let slash_points_for_reward_slash =
+            penalty_free_slash_points * u64::try_from(MULTIPLIERS.len()).unwrap();
+          let slash_points_for_offline_stake_slash =
+            slash_points_for_entire_session.saturating_sub(slash_points_for_reward_slash);
+
+          let slash_points_in_interval = slash_points.min(slash_points_for_offline_stake_slash);
+          slash_points -= slash_points_in_interval;
+          // If there are no slash points for the entire session, don't slash stake
+          // That's an extreme edge case which shouldn't start penalizing validators
+          (u128::from(slash_points_in_interval) * stake_to_slash_for_being_offline)
+            .checked_div(u128::from(slash_points_for_offline_stake_slash))
+            .unwrap_or(0)
+        };
+
+        let disruptive_slash = {
+          /*
+            A validator may have more slash points than `slash_points_for_stake_slash` if they
+            didn't just accrue slashes for missing block proposals, yet also accrued slashes for
+            being disruptive. In that case, we still want to bound their slash points so they can't
+            somehow be slashed for 100% of their stake (which should only happen on a fatal slash).
+          */
+          const MAX_STAKE_SLASH_PERCENTAGE_DISRUPTIVE: u64 = 8;
+
+          let stake_to_slash_for_being_disruptive =
+            (allocated_stake * u128::from(MAX_STAKE_SLASH_PERCENTAGE_DISRUPTIVE)) / 100;
+          // Follows the offline slash for `unwrap_or` policy
+          (u128::from(slash_points.min(slash_points_for_entire_session)) *
+            stake_to_slash_for_being_disruptive)
+            .checked_div(u128::from(slash_points_for_entire_session))
+            .unwrap_or(0)
+        };
+
+        // The penalty is all slashes, but never more than the validator's balance
+        // (handles any rounding errors which may or may not exist)
+        let penalty_u128 =
+          (reward_slash + offline_slash + disruptive_slash).min(allocated_stake + session_rewards);
+        // saturating_into
+        Amount(u64::try_from(penalty_u128).unwrap_or(u64::MAX))
+      }
+      // On fatal slash, their entire stake is removed
+      Self::Fatal => Amount(allocated_stake.0 + session_rewards.0),
+    }
+  }
+}
+
+#[derive(Clone, PartialEq, Eq, Debug, Encode, Decode, TypeInfo, MaxEncodedLen)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct SlashReport(pub BoundedVec<Slash, ConstU32<{ MAX_KEY_SHARES_PER_SET_U32 }>>);
+
+// This is assumed binding to the ValidatorSet via the key signed with
+pub fn report_slashes_message(slashes: &SlashReport) -> Vec<u8> {
+  (b"ValidatorSets-report_slashes", slashes).encode()
+}
+
+#[test]
+fn test_penalty() {
+  for validators in [1, 50, 100, crate::MAX_KEY_SHARES_PER_SET] {
+    let validators = NonZero::new(validators).unwrap();
+    // 12 hours of slash points should only decrease the rewards proportionately
+    let twelve_hours_of_slash_points =
+      u32::try_from((12 * 60 * 60) / downtime_per_slash_point(validators).as_secs()).unwrap();
+    assert_eq!(
+      Slash::Points(twelve_hours_of_slash_points).penalty(
+        validators,
+        Amount(u64::MAX),
+        Amount(168)
+      ),
+      Amount(12)
+    );
+    // 24 hours of slash points should be counted as 36 hours
+    assert_eq!(
+      Slash::Points(2 * twelve_hours_of_slash_points).penalty(
+        validators,
+        Amount(u64::MAX),
+        Amount(168)
+      ),
+      Amount(36)
+    );
+    // 36 hours of slash points should be counted as 96 hours
+    assert_eq!(
+      Slash::Points(3 * twelve_hours_of_slash_points).penalty(
+        validators,
+        Amount(u64::MAX),
+        Amount(168)
+      ),
+      Amount(96)
+    );
+    // 48 hours of slash points should be counted as 168 hours
+    assert_eq!(
+      Slash::Points(4 * twelve_hours_of_slash_points).penalty(
+        validators,
+        Amount(u64::MAX),
+        Amount(168)
+      ),
+      Amount(168)
+    );
+
+    // A full week of slash points should slash 2%
+    let week_of_slash_points = 14 * twelve_hours_of_slash_points;
+    assert_eq!(
+      Slash::Points(week_of_slash_points).penalty(validators, Amount(1000), Amount(168)),
+      Amount(20 + 168)
+    );
+
+    // Two weeks of slash points should slash 10%
+    assert_eq!(
+      Slash::Points(2 * week_of_slash_points).penalty(validators, Amount(1000), Amount(168)),
+      Amount(100 + 168)
+    );
+
+    // Anything greater should still only slash 10%
+    assert_eq!(
+      Slash::Points(u32::MAX).penalty(validators, Amount(1000), Amount(168)),
+      Amount(100 + 168)
+    );
+  }
+}
+
+#[test]
+fn no_overflow() {
+  Slash::Points(u32::MAX).penalty(
+    NonZero::new(u16::MAX).unwrap(),
+    Amount(u64::MAX),
+    Amount(u64::MAX),
+  );
+
+  Slash::Points(u32::MAX).penalty(NonZero::new(1).unwrap(), Amount(u64::MAX), Amount(u64::MAX));
+}