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

cumulus/parachains/runtimes/assets/asset-hub-westend/src/lib.rs

@@ -1199,7 +1199,10 @@ parameter_types! {
 impl pallet_migrations::Config for Runtime {
 	type RuntimeEvent = RuntimeEvent;
 	#[cfg(not(feature = "runtime-benchmarks"))]
-	type Migrations = pallet_revive::migrations::v1::Migration<Runtime>;
+	type Migrations = (
+		pallet_revive::migrations::v1::Migration<Runtime>,
+		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;

cumulus/parachains/runtimes/assets/asset-hub-westend/src/staking.rs

@@ -256,7 +256,7 @@ parameter_types! {
 	/// Duration of a relay session in our blocks. Needs to be hardcoded per-runtime.
 	pub const RelaySessionDuration: BlockNumber = 1 * HOURS;
 	// 2 eras for unbonding (12 hours).
-	pub const BondingDuration: sp_staking::EraIndex = 2;
+	pub const MaxUnbondingDuration: sp_staking::EraIndex = 2;
 	// 1 era in which slashes can be cancelled (6 hours).
 	pub const SlashDeferDuration: sp_staking::EraIndex = 1;
 	pub const MaxControllersInDeprecationBatch: u32 = 751;
@@ -276,7 +276,7 @@ impl pallet_staking_async::Config for Runtime {
 	type Slash = ();
 	type Reward = ();
 	type SessionsPerEra = SessionsPerEra;
-	type BondingDuration = BondingDuration;
+	type MaxUnbondingDuration = MaxUnbondingDuration;
 	type SlashDeferDuration = SlashDeferDuration;
 	type AdminOrigin = EitherOf<EnsureRoot<AccountId>, StakingAdmin>;
 	type EraPayout = EraPayout;

cumulus/parachains/runtimes/assets/asset-hub-westend/src/weights/pallet_staking_async.rs

@@ -917,4 +917,17 @@ impl<T: frame_system::Config> pallet_staking_async::WeightInfo for WeightInfo<T>
 			.saturating_add(T::DbWeight::get().writes((4_u64).saturating_mul(v.into())))
 			.saturating_add(Weight::from_parts(0, 2749).saturating_mul(v.into()))
 	}
+
+	/// 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))
+	}
 }

prdoc/pr_8298.prdoc

@@ -0,0 +1,54 @@
+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.
+    - `ErasTotalUnbond`: 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: minor
+- name: pallet-staking-async
+  bump: major
+- name: sp-staking
+  bump: patch
+- name: asset-hub-westend-runtime
+  bump: major

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 }
@@ -59,6 +60,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",
@@ -80,6 +82,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",
@@ -90,6 +93,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 }
 

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

@@ -121,7 +121,7 @@ pub(crate) fn roll_until_next_active(mut end_index: SessionIndex) -> Vec<Account
 							leftover: false,
 							// arbitrary, feel free to change if test setup updates
 							new_validator_set: vec![3, 5, 6, 8],
-							prune_up_to: active_era.checked_sub(BondingDuration::get()),
+							prune_up_to: active_era.checked_sub(MaxUnbondingDuration::get()),
 						})
 					)
 				);
@@ -312,7 +312,7 @@ impl multi_block::signed::Config for Runtime {
 }
 
 parameter_types! {
-	pub static BondingDuration: u32 = 3;
+	pub static MaxUnbondingDuration: u32 = 3;
 	pub static SlashDeferredDuration: u32 = 2;
 	pub static SessionsPerEra: u32 = 6;
 	pub static PlanningEraOffset: u32 = 2;
@@ -323,7 +323,7 @@ impl pallet_staking_async::Config for Runtime {
 	type RuntimeHoldReason = RuntimeHoldReason;
 
 	type AdminOrigin = EnsureRoot<AccountId>;
-	type BondingDuration = BondingDuration;
+	type MaxUnbondingDuration = MaxUnbondingDuration;
 	type SessionsPerEra = SessionsPerEra;
 	type PlanningEraOffset = PlanningEraOffset;
 
@@ -490,6 +490,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,11 @@ 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)>;
+
+		/// Returns the estimated number of eras for unbonding a given amount.
+		fn estimate_unbonding_duration(amount: Balance) -> sp_staking::EraIndex;
 	}
 }

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

@@ -90,6 +90,11 @@ fn staking_async_parachain_genesis(params: GenesisParams, preset: String) -> ser
 				.into_iter()
 				.map(|acc| (acc, endowment / 2, StakerStatus::Validator))
 				.collect(),
+			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

@@ -1792,6 +1792,14 @@ 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)
+		}
+
+		fn estimate_unbonding_duration(amount: Balance) -> sp_staking::EraIndex {
+			Staking::estimate_unbonding_duration(amount)
+		}
 	}
 
 	#[cfg(feature = "runtime-benchmarks")]

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

@@ -410,7 +410,7 @@ parameter_types! {
 	/// Duration of a relay session in our blocks. Needs to be hardcoded per-runtime.
 	pub const RelaySessionDuration: BlockNumber = 10;
 	// 2 eras for unbonding (12 hours).
-	pub const BondingDuration: sp_staking::EraIndex = 2;
+	pub const MaxUnbondingDuration: sp_staking::EraIndex = 2;
 	// 1 era in which slashes can be cancelled (6 hours).
 	pub const SlashDeferDuration: sp_staking::EraIndex = 1;
 	// Note: this is not really correct as Max Nominators is (MaxExposurePageSize * page_count) but
@@ -435,7 +435,7 @@ impl pallet_staking_async::Config for Runtime {
 	type Slash = ();
 	type Reward = ();
 	type SessionsPerEra = SessionsPerEra;
-	type BondingDuration = BondingDuration;
+	type MaxUnbondingDuration = MaxUnbondingDuration;
 	type SlashDeferDuration = SlashDeferDuration;
 	type AdminOrigin = EitherOf<EnsureRoot<AccountId>, StakingAdmin>;
 	type EraPayout = EraPayout;

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

@@ -900,4 +900,16 @@ impl<T: frame_system::Config> pallet_staking_async::WeightInfo for WeightInfo<T>
 			.saturating_add(T::DbWeight::get().writes((4_u64).saturating_mul(v.into())))
 			.saturating_add(Weight::from_parts(0, 3937).saturating_mul(v.into()))
 	}
+	/// 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))
+	}
 }