Implementation of RFC-0097: Unbonding Queue for pallet-staking-async

prdoc/pr_8298.prdoc

@@ -0,0 +1,52 @@
+title: 'Implementation of RFC-0097: Unbonding Queue for pallet-staking-async'
+doc:
+- audience: [Runtime Dev, Runtime User]
+  description: |
+    # Description
+    This PR implements [RFC-0097](https://polkadot-fellows.github.io/RFCs/approved/0097-unbonding_queue.html) and its
+    [modification](https://hackmd.io/@vKfUEAWlRR2Ogaq8nYYknw/SyfioMGWgl), which introduces a variable unbonding time
+    mechanism to improve the security-liquidity trade-off in the staking system.
+
+    The unbonding queue allows for faster unbonding of staked tokens while maintaining network security by keeping a
+    minimum slashable share of stake locked for the full unbonding period.
+
+    ### Modified extrinsics:
+    - `unbond`: Enhanced to work with the unbonding queue mechanism, calculating variable unbonding times based on stake distribution.
+    - `withdraw_unbonded`: Modified to handle withdrawals from the unbonding queue with different unlock periods.
+    - `rebond`: Updated to work with the queue-based unbonding system.
+
+    ### Storage items:
+    - `ElectableStashes`: Added the stake backing up a given electable stash account.
+    - `UnbondingQueueParams`: New storage item containing configuration parameters:
+      - `min_slashable_share`: The minimum share of stake of the lowest backed validators that must remain slashable at any point in time.
+      - `lowest_ratio`: The proportion of the lowest-backed validator set.
+      - `unbond_period_lower_bound`: Minimum unbonding time in eras.
+    - `ErasLowestRatioTotalStake`: Tracks the lowest stake proportion among validators in each era.
+    - `TotalUnbondInEra`: Tracks the stake that started unbonding in a given era.
+    - `Ledger`: Added `previous_unbonded_stake` to track the accumulated stake to be unbonded at the time a given unlock chunk was created.
+
+    ### View functions:
+    - `unbonding_duration`: Used to obtain the list of funds that will be released at a given era.
+
+    ## Key features:
+    1. Variable unbonding time: Unbonding time varies based on the amount of stake in the system.
+    2. Security maintenance: Ensures a sufficient percentage of stake remains slashable at all times.
+    3. Unbonding queue management: Implements an efficient queue system for managing unbonding requests.
+
+    ### Migration v18:
+    Includes multi-block migration `LazyMigrationV17ToV18` that:
+      - Updates `StakingLedger` structure to include the new `previous_unbonded_stake` field in `UnlockChunk`.
+      - Migrates `ElectableStashes` from set-based to map-based storage (AccountId -> Balance mapping).
+      - Performs era adjustment for existing unlock chunks by subtracting the bonding duration.
+      - Uses stepped migration pattern to handle large datasets efficiently across multiple blocks.
+      - Includes comprehensive pre/post-upgrade checks for data integrity.
+
+crates:
+- name: pallet-staking-async-parachain-runtime
+  bump: minor
+- name: pallet-staking-async-runtime-api
+  bump: major
+- name: pallet-staking-async
+  bump: major
+- name: sp-staking
+  bump: patch

substrate/frame/staking-async/Cargo.toml

@@ -20,6 +20,7 @@ frame-election-provider-support = { workspace = true }
 frame-support = { workspace = true }
 frame-system = { workspace = true }
 log = { workspace = true }
+pallet-migrations = { workspace = true, default-features = false }
 pallet-staking-async-rc-client = { workspace = true }
 rand = { features = ["alloc"], workspace = true }
 rand_chacha = { workspace = true }
@@ -55,6 +56,7 @@ std = [
 	"log/std",
 	"pallet-bags-list/std",
 	"pallet-balances/std",
+	"pallet-migrations/std",
 	"pallet-staking-async-rc-client/std",
 	"rand/std",
 	"rand_chacha/std",
@@ -76,6 +78,7 @@ runtime-benchmarks = [
 	"frame-system/runtime-benchmarks",
 	"pallet-bags-list/runtime-benchmarks",
 	"pallet-balances/runtime-benchmarks",
+	"pallet-migrations/runtime-benchmarks",
 	"pallet-staking-async-rc-client/runtime-benchmarks",
 	"sp-runtime/runtime-benchmarks",
 	"sp-staking/runtime-benchmarks",
@@ -86,6 +89,7 @@ try-runtime = [
 	"frame-system/try-runtime",
 	"pallet-bags-list/try-runtime",
 	"pallet-balances/try-runtime",
+	"pallet-migrations/try-runtime",
 	"pallet-staking-async-rc-client/try-runtime",
 	"sp-runtime/try-runtime",
 ]

substrate/frame/staking-async/ahm-test/Cargo.toml

@@ -21,8 +21,6 @@ frame = { workspace = true, default-features = true }
 frame-support = { workspace = true, default-features = true }
 log = { workspace = true }
 scale-info = { features = ["derive"], workspace = true, default-features = true }
-sp-core = { workspace = true, default-features = true }
-sp-session = { workspace = true, default-features = true }
 sp-staking = { workspace = true, default-features = true }
 sp-tracing = { workspace = true, default-features = true }
 
@@ -66,3 +64,17 @@ try-runtime = [
 	"pallet-staking-async-ah-client/try-runtime",
 	"pallet-timestamp/try-runtime",
 ]
+runtime-benchmarks = [
+	"frame-election-provider-support/runtime-benchmarks",
+	"frame-support/runtime-benchmarks",
+	"frame/runtime-benchmarks",
+	"pallet-balances/runtime-benchmarks",
+	"pallet-election-provider-multi-block/runtime-benchmarks",
+	"pallet-root-offences/runtime-benchmarks",
+	"pallet-staking-async-ah-client/runtime-benchmarks",
+	"pallet-staking-async-rc-client/runtime-benchmarks",
+	"pallet-staking-async/runtime-benchmarks",
+	"pallet-staking/runtime-benchmarks",
+	"pallet-timestamp/runtime-benchmarks",
+	"sp-staking/runtime-benchmarks",
+]

substrate/frame/staking-async/ahm-test/src/ah/mock.rs

@@ -491,6 +491,11 @@ impl ExtBuilder {
 			validator_count: 4,
 			active_era: (0, 0, 0),
 			force_era: if self.pre_migration { Forcing::ForceNone } else { Forcing::default() },
+			unbonding_queue_config: Some(pallet_staking_async::UnbondingQueueConfig {
+				min_slashable_share: Perbill::from_percent(50),
+				lowest_ratio: Perbill::from_percent(34),
+				unbond_period_lower_bound: 2,
+			}),
 			..Default::default()
 		}
 		.assimilate_storage(&mut t)

substrate/frame/staking-async/ahm-test/src/ah/test.rs

@@ -21,7 +21,7 @@ use frame_support::assert_ok;
 use pallet_election_provider_multi_block::{Event as ElectionEvent, Phase};
 use pallet_staking_async::{
 	self as staking_async, session_rotation::Rotator, ActiveEra, ActiveEraInfo, CurrentEra,
-	Event as StakingEvent,
+	ErasLowestRatioTotalStake, Event as StakingEvent,
 };
 use pallet_staking_async_rc_client::{self as rc_client, UnexpectedKind, ValidatorSetReport};
 
@@ -102,6 +102,9 @@ fn on_receive_session_report() {
 			);
 		}
 
+		// The lowest stake proportion is zero before the election occurs.
+		assert_eq!(ErasLowestRatioTotalStake::<T>::iter().collect::<Vec<_>>(), vec![]);
+
 		// Next session we will begin election.
 		assert_ok!(rc_client::Pallet::<T>::relay_session_report(
 			RuntimeOrigin::root(),
@@ -196,6 +199,10 @@ fn on_receive_session_report() {
 				})
 			)]
 		);
+
+		// After the election, the stake backing the lowest third is composed of only one validator
+		// backed with 100.
+		assert_eq!(ErasLowestRatioTotalStake::<T>::iter().collect::<Vec<_>>(), vec![(1, 100)]);
 	})
 }
 

substrate/frame/staking-async/runtime-api/src/lib.rs

@@ -19,6 +19,9 @@
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
+extern crate alloc;
+
+use alloc::vec::Vec;
 use codec::Codec;
 
 sp_api::decl_runtime_apis! {
@@ -35,5 +38,8 @@ sp_api::decl_runtime_apis! {
 
 		/// Returns true if validator `account` has pages to be claimed for the given era.
 		fn pending_rewards(era: sp_staking::EraIndex, account: AccountId) -> bool;
+
+		/// Returns a list of (era, amount) that indices at which era unbonded funds will be unlocked.
+		fn unbonding_duration(account: AccountId) -> Vec<(sp_staking::EraIndex, Balance)>;
 	}
 }

substrate/frame/staking-async/runtimes/parachain/src/genesis_config_presets.rs

@@ -78,7 +78,16 @@ fn staking_async_parachain_genesis(params: GenesisParams) -> serde_json::Value {
 		},
 		polkadot_xcm: PolkadotXcmConfig { safe_xcm_version: Some(SAFE_XCM_VERSION) },
 		sudo: SudoConfig { key: Some(root) },
-		staking: StakingConfig { validator_count, dev_stakers, ..Default::default() }
+		staking: StakingConfig {
+			validator_count,
+			dev_stakers,
+			unbonding_queue_config: Some(pallet_staking_async::UnbondingQueueConfig {
+				min_slashable_share: Perbill::from_percent(50),
+				lowest_ratio: Perbill::from_percent(34),
+				unbond_period_lower_bound: 0,
+			}),
+			..Default::default()
+		}
 	})
 }
 

substrate/frame/staking-async/runtimes/parachain/src/lib.rs

@@ -1089,7 +1089,7 @@ parameter_types! {
 impl pallet_migrations::Config for Runtime {
 	type RuntimeEvent = RuntimeEvent;
 	#[cfg(not(feature = "runtime-benchmarks"))]
-	type Migrations = ();
+	type Migrations = (pallet_staking_async::migrations::v18::LazyMigrationV17ToV18<Runtime>,);
 	// Benchmarks need mocked migrations to guarantee that they succeed.
 	#[cfg(feature = "runtime-benchmarks")]
 	type Migrations = pallet_migrations::mock_helpers::MockedMigrations;
@@ -1794,6 +1794,10 @@ impl_runtime_apis! {
 		fn pending_rewards(era: sp_staking::EraIndex, account: AccountId) -> bool {
 			Staking::api_pending_rewards(era, account)
 		}
+
+		fn unbonding_duration(account: AccountId) -> Vec<(sp_staking::EraIndex, Balance)> {
+			Staking::unbonding_duration(account)
+		}
 	}
 
 	#[cfg(feature = "runtime-benchmarks")]

substrate/frame/staking-async/runtimes/parachain/src/weights/pallet_staking_async.rs

@@ -851,4 +851,16 @@ impl<T: frame_system::Config> pallet_staking_async::WeightInfo for WeightInfo<T>
 			.saturating_add(T::DbWeight::get().reads(7))
 			.saturating_add(T::DbWeight::get().writes(7))
 	}
+	/// Storage: `Staking::Ledger` (r:2 w:1)
+	/// Proof: `Staking::Ledger` (`max_values`: None, `max_size`: Some(1265), added: 3740, mode: `MaxEncodedLen`)
+	/// The range of component `c` is `[1, 32]`.
+	fn migration_from_v17_to_v18_migrate_staking_ledger_step(_c: u32, ) -> Weight {
+		// Proof Size summary in bytes:
+		//  Measured:  `698 + c * (3 ±0)`
+		//  Estimated: `8470`
+		// Minimum execution time: 45_000_000 picoseconds.
+		Weight::from_parts(60_791_228, 8470)
+			.saturating_add(T::DbWeight::get().reads(2_u64))
+			.saturating_add(T::DbWeight::get().writes(1_u64))
+	}
 }