improve documentation of fast-unstake pallet

frame/fast-unstake/Cargo.toml

@@ -27,14 +27,13 @@ frame-election-provider-support = { default-features = false, path = "../electio
 
 frame-benchmarking = { version = "4.0.0-dev", default-features = false, optional = true, path = "../benchmarking" }
 
-[dev-dependencies]
-pallet-staking-reward-curve = { version = "4.0.0-dev", path = "../staking/reward-curve" }
-sp-core = { version = "7.0.0", default-features = false, path = "../../primitives/core" }
-substrate-test-utils = { version = "4.0.0-dev", path = "../../test-utils" }
-sp-tracing = { version = "6.0.0", path = "../../primitives/tracing" }
-pallet-staking = { path = "../staking" }
-pallet-balances = { path = "../balances" }
-pallet-timestamp = { path = "../timestamp" }
+pallet-staking-reward-curve = { version = "4.0.0-dev", path = "../staking/reward-curve", optional = true }
+sp-core = { version = "7.0.0", default-features = false, path = "../../primitives/core", optional = true }
+substrate-test-utils = { version = "4.0.0-dev", path = "../../test-utils", optional = true }
+sp-tracing = { version = "6.0.0", path = "../../primitives/tracing", optional = true }
+pallet-staking = { path = "../staking", optional = true }
+pallet-balances = { path = "../balances", optional = true }
+pallet-timestamp = { path = "../timestamp", optional = true }
 
 [features]
 default = ["std"]
@@ -54,6 +53,14 @@ std = [
 	"frame-election-provider-support/std",
 
 	"frame-benchmarking/std",
+
+	"pallet-staking-reward-curve",
+	"sp-core",
+	"substrate-test-utils",
+	"sp-tracing",
+	"pallet-staking",
+	"pallet-balances",
+	"pallet-timestamp"
 ]
 runtime-benchmarks = [
 	"frame-benchmarking/runtime-benchmarks",

frame/fast-unstake/src/lib.rs

@@ -15,6 +15,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! # Fast Unstake Pallet
+//!
+//! ## Overview
+//!
 //! A pallet that's designed to JUST do the following:
 //!
 //! If a nominator is not exposed in any `ErasStakers` (i.e. "has not actively backed any
@@ -27,16 +31,16 @@
 //! Nominator" role explained in the
 //! [February Staking Update](https://polkadot.network/blog/staking-update-february-2022/).
 //!
-//! This pallet works off the basis of `on_idle`, meaning that it provides no guarantee about when
-//! it will succeed, if at all. Moreover, the queue implementation is unordered. In case of
-//! congestion, no FIFO ordering is provided.
+//! This pallet works off the basis of `on_idle`, meaning that it
+//! provides no guarantee about when it will succeed, if at all. Moreover, the queue implementation
+//! is unordered. In case of congestion, no FIFO ordering is provided.
 //!
 //! Stakers who are certain about NOT being exposed can register themselves with
-//! [`Call::register_fast_unstake`]. This will chill, and fully unbond the staker, and place them in
-//! the queue to be checked.
+//! [`Pallet::register_fast_unstake`]. This will chill, and fully unbond the staker, and place them
+//! in the queue to be checked.
 //!
 //! Once queued, but not being actively processed, stakers can withdraw their request via
-//! [`Call::deregister`].
+//! [`Pallet::deregister`].
 //!
 //! Once queued, a staker wishing to unbond can perform no further action in pallet-staking. This is
 //! to prevent them from accidentally exposing themselves behind a validator etc.
@@ -46,16 +50,44 @@
 //!
 //! If unsuccessful, meaning that the staker was exposed sometime in the last `BondingDuration` eras
 //! they will end up being slashed for the amount of wasted work they have inflicted on the chian.
+//!
+//! ## Details
+//!
+//! The main components of this pallet are:
+//! - [`pallet::Pallet`], which implements all of the dispatchable extrinsics of the pallet, among
+//!   other public functions.
+//! 	- The subset of the functions that are dispatchable can be identified either in
+//!    [`pallet::dispatchables`] module or in [`pallet::Call`] enum.
+//! - [`pallet::storage_types`], which contains the list of all types that are representing a
+//!   storage item. Otherwise, all storage items are listed among [`pallet::types`].
+//! - [`pallet::Config`], which contains the configuration trait of this pallet.
+//! - [`pallet::Event`].
+//! - [`pallet::Error`].
+//!
+//! All of which can be seen in more detail in [`pallet`] module.
+//!
+//! ## Examples
+//!
+//! Fast-unstake with multiple participants in the queue.
+//!
+//! ```
+#![doc = include_str!("../examples/fast_unstake_success_multi.rs")]
+//! ```
+//! 
+//! Fast unstake failing because a nominator is exposed.
+//! ```
+#![doc = include_str!("../examples/exposed_nominator_cannot_unstake.rs")]
+//! ```
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
 pub use pallet::*;
 
-#[cfg(test)]
-mod mock;
+#[cfg(any(test, feature = "std"))]
+pub mod mock;
 
 #[cfg(test)]
-mod tests;
+pub mod tests;
 
 // NOTE: enable benchmarking in tests as well.
 #[cfg(feature = "runtime-benchmarks")]
@@ -77,6 +109,7 @@ macro_rules! log {
 	};
 }
 
+/// Foo
 #[frame_support::pallet]
 pub mod pallet {
 	use super::*;

frame/fast-unstake/src/mock.rs

@@ -215,7 +215,7 @@ parameter_types! {
 	static FastUnstakeEvents: u32 = 0;
 }
 
-pub(crate) fn fast_unstake_events_since_last_call() -> Vec<super::Event<Runtime>> {
+pub fn fast_unstake_events_since_last_call() -> Vec<super::Event<Runtime>> {
 	let events = System::events()
 		.into_iter()
 		.map(|r| r.event)
@@ -270,7 +270,7 @@ impl ExtBuilder {
 			});
 	}
 
-	pub(crate) fn batch(self, size: u32) -> Self {
+	pub fn batch(self, size: u32) -> Self {
 		BatchSize::set(size);
 		self
 	}
@@ -338,7 +338,7 @@ impl ExtBuilder {
 	}
 }
 
-pub(crate) fn run_to_block(n: u64, on_idle: bool) {
+pub fn run_to_block(n: u64, on_idle: bool) {
 	let current_block = System::block_number();
 	assert!(n > current_block);
 	while System::block_number() < n {
@@ -357,7 +357,7 @@ pub(crate) fn run_to_block(n: u64, on_idle: bool) {
 	}
 }
 
-pub(crate) fn next_block(on_idle: bool) {
+pub fn next_block(on_idle: bool) {
 	let current = System::block_number();
 	run_to_block(current + 1, on_idle);
 }

frame/fast-unstake/src/tests.rs

@@ -303,59 +303,6 @@ mod on_idle {
 		});
 	}
 
-	#[test]
-	fn successful_multi_queue() {
-		ExtBuilder::default().build_and_execute(|| {
-			ErasToCheckPerBlock::<T>::put(BondingDuration::get() + 1);
-			CurrentEra::<T>::put(BondingDuration::get());
-
-			// register multi accounts for fast unstake
-			assert_ok!(FastUnstake::register_fast_unstake(RuntimeOrigin::signed(2)));
-			assert_eq!(Queue::<T>::get(1), Some(Deposit::get()));
-			assert_ok!(FastUnstake::register_fast_unstake(RuntimeOrigin::signed(4)));
-			assert_eq!(Queue::<T>::get(3), Some(Deposit::get()));
-
-			// assert 2 queue items are in Queue & None in Head to start with
-			assert_eq!(Queue::<T>::count(), 2);
-			assert_eq!(Head::<T>::get(), None);
-
-			// process on idle and check eras for next Queue item
-			next_block(true);
-
-			// process on idle & let go of current Head
-			next_block(true);
-
-			// confirm Head / Queue items remaining
-			assert_eq!(Queue::<T>::count(), 1);
-			assert_eq!(Head::<T>::get(), None);
-
-			// process on idle and check eras for next Queue item
-			next_block(true);
-
-			// process on idle & let go of current Head
-			next_block(true);
-
-			// Head & Queue should now be empty
-			assert_eq!(Head::<T>::get(), None);
-			assert_eq!(Queue::<T>::count(), 0);
-
-			assert_eq!(
-				fast_unstake_events_since_last_call(),
-				vec![
-					Event::BatchChecked { eras: vec![3, 2, 1, 0] },
-					Event::Unstaked { stash: 1, result: Ok(()) },
-					Event::BatchFinished { size: 1 },
-					Event::BatchChecked { eras: vec![3, 2, 1, 0] },
-					Event::Unstaked { stash: 3, result: Ok(()) },
-					Event::BatchFinished { size: 1 },
-				]
-			);
-
-			assert_unstaked(&1);
-			assert_unstaked(&3);
-		});
-	}
-
 	#[test]
 	fn successful_unstake() {
 		ExtBuilder::default().build_and_execute(|| {
@@ -693,48 +640,6 @@ mod on_idle {
 		});
 	}
 
-	#[test]
-	fn exposed_nominator_cannot_unstake() {
-		ExtBuilder::default().build_and_execute(|| {
-			ErasToCheckPerBlock::<T>::put(1);
-			CurrentEra::<T>::put(BondingDuration::get());
-
-			// create an exposed nominator in era 1
-			let exposed = 666;
-			create_exposed_nominator(exposed, 1);
-
-			// a few blocks later, we realize they are slashed
-			next_block(true);
-			assert_eq!(
-				Head::<T>::get(),
-				Some(UnstakeRequest {
-					stashes: bounded_vec![(exposed, Deposit::get())],
-					checked: bounded_vec![3]
-				})
-			);
-			next_block(true);
-			assert_eq!(
-				Head::<T>::get(),
-				Some(UnstakeRequest {
-					stashes: bounded_vec![(exposed, Deposit::get())],
-					checked: bounded_vec![3, 2]
-				})
-			);
-			next_block(true);
-			assert_eq!(Head::<T>::get(), None);
-
-			assert_eq!(
-				fast_unstake_events_since_last_call(),
-				vec![
-					Event::BatchChecked { eras: vec![3] },
-					Event::BatchChecked { eras: vec![2] },
-					Event::Slashed { stash: exposed, amount: Deposit::get() },
-					Event::BatchFinished { size: 0 }
-				]
-			);
-		});
-	}
-
 	#[test]
 	fn exposed_nominator_cannot_unstake_multi_check() {
 		ExtBuilder::default().build_and_execute(|| {

frame/fast-unstake/src/types.rs

@@ -35,7 +35,7 @@ pub type BalanceOf<T> =
 #[scale_info(skip_type_params(T))]
 pub struct UnstakeRequest<T: Config> {
 	/// This list of stashes being processed in this request, and their corresponding deposit.
-	pub(crate) stashes: BoundedVec<(T::AccountId, BalanceOf<T>), T::BatchSize>,
+	pub stashes: BoundedVec<(T::AccountId, BalanceOf<T>), T::BatchSize>,
 	/// The list of eras for which they have been checked.
-	pub(crate) checked: BoundedVec<EraIndex, MaxChecking<T>>,
+	pub checked: BoundedVec<EraIndex, MaxChecking<T>>,
 }

frame/support/src/lib.rs

@@ -1520,6 +1520,17 @@ pub mod tests {
 	}
 }
 
+/// Prelude to be used for pallet testing, for ease of use.
+#[cfg(feature = "std")]
+pub mod testing_prelude {
+	pub use super::{
+		assert_err, assert_err_ignore_postinfo, assert_err_with_weight, assert_error_encoded_size,
+		assert_noop, assert_ok, assert_storage_noop, bounded_btree_map, bounded_vec, parameter_types
+	};
+	pub use sp_arithmetic::assert_eq_error_rate;
+	pub use super::traits::Get;
+}
+
 /// Prelude to be used alongside pallet macro, for ease of use.
 pub mod pallet_prelude {
 	#[cfg(feature = "std")]