From dbf2572b86c6f5ecad3d74b3b67d150ed428efc3 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Sun, 7 May 2023 15:31:42 +0200 Subject: [PATCH 01/32] improve documentation of fast-unstake pallet --- frame/fast-unstake/Cargo.toml | 23 +++++--- frame/fast-unstake/src/lib.rs | 51 ++++++++++++++---- frame/fast-unstake/src/mock.rs | 8 +-- frame/fast-unstake/src/tests.rs | 95 --------------------------------- frame/fast-unstake/src/types.rs | 4 +- frame/support/src/lib.rs | 11 ++++ 6 files changed, 74 insertions(+), 118 deletions(-) diff --git a/frame/fast-unstake/Cargo.toml b/frame/fast-unstake/Cargo.toml index 93fceefa2de51..ede1713afd952 100644 --- a/frame/fast-unstake/Cargo.toml +++ b/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", diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 3e79bf4077d20..c385bcecca3be 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/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::*; diff --git a/frame/fast-unstake/src/mock.rs b/frame/fast-unstake/src/mock.rs index fbe6c4592bf67..fdc04f654d3ea 100644 --- a/frame/fast-unstake/src/mock.rs +++ b/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> { +pub fn fast_unstake_events_since_last_call() -> Vec> { 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); } diff --git a/frame/fast-unstake/src/tests.rs b/frame/fast-unstake/src/tests.rs index b4bf1f1cb994a..e803f1b83bf3f 100644 --- a/frame/fast-unstake/src/tests.rs +++ b/frame/fast-unstake/src/tests.rs @@ -303,59 +303,6 @@ mod on_idle { }); } - #[test] - fn successful_multi_queue() { - ExtBuilder::default().build_and_execute(|| { - ErasToCheckPerBlock::::put(BondingDuration::get() + 1); - CurrentEra::::put(BondingDuration::get()); - - // register multi accounts for fast unstake - assert_ok!(FastUnstake::register_fast_unstake(RuntimeOrigin::signed(2))); - assert_eq!(Queue::::get(1), Some(Deposit::get())); - assert_ok!(FastUnstake::register_fast_unstake(RuntimeOrigin::signed(4))); - assert_eq!(Queue::::get(3), Some(Deposit::get())); - - // assert 2 queue items are in Queue & None in Head to start with - assert_eq!(Queue::::count(), 2); - assert_eq!(Head::::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::::count(), 1); - assert_eq!(Head::::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::::get(), None); - assert_eq!(Queue::::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::::put(1); - CurrentEra::::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::::get(), - Some(UnstakeRequest { - stashes: bounded_vec![(exposed, Deposit::get())], - checked: bounded_vec![3] - }) - ); - next_block(true); - assert_eq!( - Head::::get(), - Some(UnstakeRequest { - stashes: bounded_vec![(exposed, Deposit::get())], - checked: bounded_vec![3, 2] - }) - ); - next_block(true); - assert_eq!(Head::::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(|| { diff --git a/frame/fast-unstake/src/types.rs b/frame/fast-unstake/src/types.rs index 3ec4b3a9b4d6e..e909dc1b6224a 100644 --- a/frame/fast-unstake/src/types.rs +++ b/frame/fast-unstake/src/types.rs @@ -35,7 +35,7 @@ pub type BalanceOf = #[scale_info(skip_type_params(T))] pub struct UnstakeRequest { /// This list of stashes being processed in this request, and their corresponding deposit. - pub(crate) stashes: BoundedVec<(T::AccountId, BalanceOf), T::BatchSize>, + pub stashes: BoundedVec<(T::AccountId, BalanceOf), T::BatchSize>, /// The list of eras for which they have been checked. - pub(crate) checked: BoundedVec>, + pub checked: BoundedVec>, } diff --git a/frame/support/src/lib.rs b/frame/support/src/lib.rs index 138b7b55bf0eb..7910b9ff5e62e 100644 --- a/frame/support/src/lib.rs +++ b/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")] From 9d2a9a21a034634a6816ca845e3fe94339f77146 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Tue, 9 May 2023 12:25:53 +0200 Subject: [PATCH 02/32] using Sam's crate now --- Cargo.lock | 35 ++++++- frame/fast-unstake/Cargo.toml | 2 + frame/fast-unstake/src/lib.rs | 99 ++++++++++++------- frame/fast-unstake/src/mock.rs | 8 +- frame/fast-unstake/src/tests.rs | 2 + frame/fast-unstake/src/types.rs | 26 ++++- .../procedural/src/pallet/expand/call.rs | 15 ++- .../procedural/src/pallet/expand/config.rs | 20 ++-- .../procedural/src/pallet/expand/doc_only.rs | 60 +++++++---- .../procedural/src/pallet/expand/mod.rs | 28 ++++-- .../src/pallet/expand/pallet_struct.rs | 4 +- .../procedural/src/pallet/expand/storage.rs | 83 ++++++++++++++-- frame/support/src/lib.rs | 11 +++ 13 files changed, 298 insertions(+), 95 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index b8e42c10316eb..9448eb386b371 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1894,6 +1894,28 @@ version = "0.3.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10" +[[package]] +name = "docify" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00b469cf6e58cc46d7f038c7f9a9c2ed85ae05e3bb65ad165b2b941f41758e57" +dependencies = [ + "docify_macros", +] + +[[package]] +name = "docify_macros" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "58fd5476bf7e08fb686a7ec8c8f4d0cfb0baa2ab66b151fd6328981b101153da" +dependencies = [ + "derive-syn-parse", + "prettyplease 0.2.4", + "proc-macro2", + "quote", + "syn 2.0.14", +] + [[package]] name = "downcast" version = "0.11.0" @@ -6277,6 +6299,7 @@ dependencies = [ name = "pallet-fast-unstake" version = "4.0.0-dev" dependencies = [ + "docify", "frame-benchmarking", "frame-election-provider-support", "frame-support", @@ -7738,6 +7761,16 @@ dependencies = [ "syn 1.0.109", ] +[[package]] +name = "prettyplease" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ceca8aaf45b5c46ec7ed39fff75f57290368c1846d33d24a122ca81416ab058" +dependencies = [ + "proc-macro2", + "syn 2.0.14", +] + [[package]] name = "primitive-types" version = "0.12.1" @@ -7865,7 +7898,7 @@ dependencies = [ "log", "multimap", "petgraph", - "prettyplease", + "prettyplease 0.1.23", "prost", "prost-types", "regex", diff --git a/frame/fast-unstake/Cargo.toml b/frame/fast-unstake/Cargo.toml index 93fceefa2de51..87c4e4a9f929f 100644 --- a/frame/fast-unstake/Cargo.toml +++ b/frame/fast-unstake/Cargo.toml @@ -27,6 +27,8 @@ frame-election-provider-support = { default-features = false, path = "../electio frame-benchmarking = { version = "4.0.0-dev", default-features = false, optional = true, path = "../benchmarking" } +docify = "0.1.1" + [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" } diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 3e79bf4077d20..d03c6d44c8a8a 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/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,29 @@ //! //! 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 +//! +//! See [`pallet`] module for more information. +//! +//! ## Examples +//! +//! 1. Fast-unstake with multiple participants in the queue. +#![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", successful_multi_queue)] +//! +//! 2. Fast unstake failing because a nominator is exposed. +#![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", exposed_nominator_cannot_unstake)] +//! #![cfg_attr(not(feature = "std"), no_std)] pub use pallet::*; #[cfg(test)] -mod mock; +pub mod mock; #[cfg(test)] -mod tests; +pub mod tests; // NOTE: enable benchmarking in tests as well. #[cfg(feature = "runtime-benchmarks")] @@ -91,23 +108,15 @@ pub mod pallet { use sp_std::{prelude::*, vec::Vec}; pub use weights::WeightInfo; - #[derive(scale_info::TypeInfo, codec::Encode, codec::Decode, codec::MaxEncodedLen)] - #[codec(mel_bound(T: Config))] - #[scale_info(skip_type_params(T))] - pub struct MaxChecking(sp_std::marker::PhantomData); - impl frame_support::traits::Get for MaxChecking { - fn get() -> u32 { - T::Staking::bonding_duration() + 1 - } - } - const STORAGE_VERSION: StorageVersion = StorageVersion::new(1); #[pallet::pallet] #[pallet::storage_version(STORAGE_VERSION)] + #[doc(alias = "FastUnstakePallet")] // TODO: expand in macro, although it is not super useful. https://github.com/paritytech/substrate/issues/13818 pub struct Pallet(_); #[pallet::config] + #[doc(alias = "FastUnstakeConfig")] pub trait Config: frame_system::Config { /// The overarching event type. type RuntimeEvent: From> @@ -122,7 +131,7 @@ pub mod pallet { #[pallet::constant] type Deposit: Get>; - /// The origin that can control this pallet. + /// The origin that can control this pallet, in other words invoke [`Pallet::control`]. type ControlOrigin: frame_support::traits::EnsureOrigin; /// Batch size. @@ -133,40 +142,44 @@ pub mod pallet { /// The access to staking functionality. type Staking: StakingInterface, AccountId = Self::AccountId>; + /// Maximum value for `ErasToCheckPerBlock`, checked in [`Pallet::control`]. + /// + /// This should be as close as possible, but more than the actual value, in order to have + /// accurate benchmarks. + type MaxErasToCheckPerBlock: Get; + /// The weight information of this pallet. type WeightInfo: WeightInfo; - /// Maximum value for `ErasToCheckPerBlock`. This should be as close as possible, but more - /// than the actual value, in order to have accurate benchmarks. - type MaxErasToCheckPerBlock: Get; - /// Use only for benchmarking. #[cfg(feature = "runtime-benchmarks")] type MaxBackersPerValidator: Get; } /// The current "head of the queue" being unstaked. + /// + /// The head in itself can be a batch of up to [`Config::BatchSize`] stakers. #[pallet::storage] pub type Head = StorageValue<_, UnstakeRequest, OptionQuery>; /// The map of all accounts wishing to be unstaked. /// /// Keeps track of `AccountId` wishing to unstake and it's corresponding deposit. - /// - /// TWOX-NOTE: SAFE since `AccountId` is a secure hash. + // Hasher: Twox safe since `AccountId` is a secure hash. #[pallet::storage] pub type Queue = CountedStorageMap<_, Twox64Concat, T::AccountId, BalanceOf>; /// Number of eras to check per block. /// - /// If set to 0, this pallet does absolutely nothing. + /// If set to 0, this pallet does absolutely nothing. Cannot be set to more than + /// [`Config::MaxErasToCheckPerBlock`]. /// - /// Based on the amount of weight available at `on_idle`, up to this many eras of a single - /// nominator might be checked. + /// Based on the amount of weight available at [`Pallet::on_idle`], up to this many eras of a + /// [`UnstakeRequest`], stored in [`Head`] might be checked. #[pallet::storage] + #[pallet::getter(fn eras_to_check_per_block)] pub type ErasToCheckPerBlock = StorageValue<_, u32, ValueQuery>; - /// The events of this pallet. #[pallet::event] #[pallet::generate_deposit(pub(super) fn deposit_event)] pub enum Event { @@ -244,8 +257,13 @@ pub mod pallet { impl Pallet { /// Register oneself for fast-unstake. /// - /// The dispatch origin of this call must be signed by the controller account, similar to - /// `staking::unbond`. + /// + /// ## Dispatch Origin + /// + /// The dispatch origin of this call must be *signed* by the whoever is permitted by to call + /// unbond funds by the staking system. See [`Config::Staking`]. + /// + /// ## Details /// /// The stash associated with the origin must have no ongoing unlocking chunks. If /// successful, this will fully unbond and chill the stash. Then, it will enqueue the stash @@ -285,11 +303,18 @@ pub mod pallet { /// Deregister oneself from the fast-unstake. /// + /// ## Dispatch Origin + /// + /// The dispatch origin of this call must be *signed* by the whoever is permitted by to call + /// unbond funds by the staking system. See [`Config::Staking`]. + /// + /// ## Details + /// /// This is useful if one is registered, they are still waiting, and they change their mind. /// /// Note that the associated stash is still fully unbonded and chilled as a consequence of - /// calling `register_fast_unstake`. This should probably be followed by a call to - /// `Staking::rebond`. + /// calling [`Pallet::register_fast_unstake`]. THerefore, this should probably be followed + /// by a call to `rebond` in the staking system. #[pallet::call_index(1)] #[pallet::weight(::WeightInfo::deregister())] pub fn deregister(origin: OriginFor) -> DispatchResult { @@ -315,7 +340,13 @@ pub mod pallet { /// Control the operation of this pallet. /// - /// Dispatch origin must be signed by the [`Config::ControlOrigin`]. + /// ## Dispatch Origin + /// + /// The dispatch origin of this call must be [`Config::ControlOrigin`]. + /// + /// ## Details + /// + /// Can set the number of eras to check per block, and potentially other admin work. #[pallet::call_index(2)] #[pallet::weight(::WeightInfo::control())] pub fn control(origin: OriginFor, eras_to_check: EraIndex) -> DispatchResult { diff --git a/frame/fast-unstake/src/mock.rs b/frame/fast-unstake/src/mock.rs index fbe6c4592bf67..fdc04f654d3ea 100644 --- a/frame/fast-unstake/src/mock.rs +++ b/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> { +pub fn fast_unstake_events_since_last_call() -> Vec> { 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); } diff --git a/frame/fast-unstake/src/tests.rs b/frame/fast-unstake/src/tests.rs index b4bf1f1cb994a..2ba9a9343645d 100644 --- a/frame/fast-unstake/src/tests.rs +++ b/frame/fast-unstake/src/tests.rs @@ -303,6 +303,7 @@ mod on_idle { }); } + #[docify::export] #[test] fn successful_multi_queue() { ExtBuilder::default().build_and_execute(|| { @@ -694,6 +695,7 @@ mod on_idle { } #[test] + #[docify::export] fn exposed_nominator_cannot_unstake() { ExtBuilder::default().build_and_execute(|| { ErasToCheckPerBlock::::put(1); diff --git a/frame/fast-unstake/src/types.rs b/frame/fast-unstake/src/types.rs index 3ec4b3a9b4d6e..0edbcdba10999 100644 --- a/frame/fast-unstake/src/types.rs +++ b/frame/fast-unstake/src/types.rs @@ -17,7 +17,7 @@ //! Types used in the Fast Unstake pallet. -use crate::{Config, MaxChecking}; +use crate::Config; use codec::{Decode, Encode, MaxEncodedLen}; use frame_support::{ traits::Currency, BoundedVec, EqNoBound, PartialEqNoBound, RuntimeDebugNoBound, @@ -26,16 +26,32 @@ use scale_info::TypeInfo; use sp_staking::EraIndex; use sp_std::prelude::*; -pub type BalanceOf = +/// Maximum number of eras that we might check for a single staker. +/// +/// In effect, it is the bonding duration, coming from [`Config::Staking`], plus one. +#[derive(scale_info::TypeInfo, codec::Encode, codec::Decode, codec::MaxEncodedLen)] +#[codec(mel_bound(T: Config))] +#[scale_info(skip_type_params(T))] +pub struct MaxChecking(sp_std::marker::PhantomData); +impl frame_support::traits::Get for MaxChecking { + fn get() -> u32 { + T::Staking::bonding_duration() + 1 + } +} + +pub(crate) type BalanceOf = <::Currency as Currency<::AccountId>>::Balance; /// An unstake request. +/// +/// This is stored in [`crate::Head`] storage item and points to the current unstake request that is +/// being processed. #[derive( Encode, Decode, EqNoBound, PartialEqNoBound, Clone, TypeInfo, RuntimeDebugNoBound, MaxEncodedLen, )] #[scale_info(skip_type_params(T))] pub struct UnstakeRequest { - /// This list of stashes being processed in this request, and their corresponding deposit. - pub(crate) stashes: BoundedVec<(T::AccountId, BalanceOf), T::BatchSize>, + /// This list of stashes are being processed in this request, and their corresponding deposit. + pub stashes: BoundedVec<(T::AccountId, BalanceOf), T::BatchSize>, /// The list of eras for which they have been checked. - pub(crate) checked: BoundedVec>, + pub checked: BoundedVec>, } diff --git a/frame/support/procedural/src/pallet/expand/call.rs b/frame/support/procedural/src/pallet/expand/call.rs index f17fdc81a647c..e7b80faa0b7ed 100644 --- a/frame/support/procedural/src/pallet/expand/call.rs +++ b/frame/support/procedural/src/pallet/expand/call.rs @@ -113,7 +113,13 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream { } debug_assert_eq!(fn_weight.len(), methods.len()); - let fn_doc = methods.iter().map(|method| &method.docs).collect::>(); + let fn_doc = methods + .iter() + .map(|method| { + let reference = format!("See [`Pallet::{}`].", method.name); + quote!(#reference) + }) + .collect::>(); let args_name = methods .iter() @@ -175,9 +181,8 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream { .collect::>() }); - let default_docs = [syn::parse_quote!( - r"Contains one variant per dispatchable that can be called by an extrinsic." - )]; + let default_docs = + [syn::parse_quote!(r"Contains a variant per dispatchable extrinsic that this pallet has.")]; let docs = if docs.is_empty() { &default_docs[..] } else { &docs[..] }; let maybe_compile_error = if def.call.is_none() { @@ -274,7 +279,7 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream { #frame_support::Never, ), #( - #( #[doc = #fn_doc] )* + #[doc = #fn_doc] #[codec(index = #call_index)] #fn_name { #( diff --git a/frame/support/procedural/src/pallet/expand/config.rs b/frame/support/procedural/src/pallet/expand/config.rs index c70f6eb80422a..7d7949de5d3cb 100644 --- a/frame/support/procedural/src/pallet/expand/config.rs +++ b/frame/support/procedural/src/pallet/expand/config.rs @@ -16,7 +16,6 @@ // limitations under the License. use crate::pallet::Def; -use frame_support_procedural_tools::get_doc_literals; /// /// * Generate default rust doc @@ -31,15 +30,22 @@ pub fn expand_config(def: &mut Def) -> proc_macro2::TokenStream { } }; - if get_doc_literals(&config_item.attrs).is_empty() { - config_item.attrs.push(syn::parse_quote!( + config_item.attrs.insert( + 0, + syn::parse_quote!( #[doc = r" - Configuration trait of this pallet. + Configuration trait of this pallet. - Implement this type for a runtime in order to customize this pallet. + The main purpose of this trait is to act as an interface between this + pallet, and the runtime in which it is embedded in. A type, function, + or constant in this trait is essentially left to be configured by the + runtime that includes this pallet. + + Consequently, a runtime that wants to include this pallet must + implement this trait. "] - )); - } + ), + ); Default::default() } diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 32c9329f29498..b023974e6c211 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -20,8 +20,6 @@ use proc_macro2::Span; use crate::pallet::Def; pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { - let storage_names = def.storages.iter().map(|storage| &storage.ident); - let storage_docs = def.storages.iter().map(|storage| &storage.docs); let dispatchables = if let Some(call_def) = &def.call { let type_impl_generics = def.type_impl_generics(Span::call_site()); call_def @@ -35,17 +33,16 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { .map(|(_, arg_name, arg_type)| quote::quote!( #arg_name: #arg_type, )) .collect::(); let docs = &method.docs; - let line_2 = - format!(" designed to document the [`{}`][`Call::{}`] variant of", name, name); + + let real = format!(" [`Pallet::{}`].", name); quote::quote!( #( #[doc = #docs] )* /// - /// --- + /// # Warning: Doc-Only /// - /// NOTE: This function is an automatically generated, doc only, uncallable stub. - #[ doc = #line_2 ] - /// the pallet [`Call`] enum. You should not attempt to call this function - /// directly. + /// This function is an automatically generated, and is doc-only, uncallable + /// stub. See the real version in + #[ doc = #real ] pub fn #name<#type_impl_generics>(#args) { unreachable!(); } ) }) @@ -54,22 +51,49 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { quote::quote!() }; + let storage_types = def + .storages + .iter() + .map(|storage| { + let storage_name = &storage.ident; + let storage_type_docs = &storage.docs; + let real = format!("[`pallet::{}`].", storage_name); + quote::quote!( + #( #[doc = #storage_type_docs] )* + /// + /// # Warning: Doc-Only + /// + /// This type is an automatically generated, and is doc-only. See the real version in + #[ doc = #real ] + pub struct #storage_name(); + ) + }) + .collect::(); + quote::quote!( - /// Auto-generated docs-only module listing all defined storage types for this pallet. - /// Note that members of this module cannot be used directly and are only provided for - /// documentation purposes. + /// Auto-generated docs-only module listing all defined storage types for this pallet, + /// public or non-public. + /// + /// # Warning: Doc-Only + /// + /// Members of this module cannot be used directly and are only provided for documentation + /// purposes. + /// + /// To see the actual storage type, find the a struct with the same name at the root of the + /// pallet, in the list of [*Type Definitions*](../index.html#types). #[cfg(doc)] pub mod storage_types { use super::*; - #( - #( #[doc = #storage_docs] )* - pub struct #storage_names(); - )* + #storage_types } /// Auto-generated docs-only module listing all defined dispatchables for this pallet. - /// Note that members of this module cannot be used directly and are only provided for - /// documentation purposes. + /// + /// # Warning: Doc-Only + /// + /// Members of this module cannot be used directly and are only provided for documentation + /// purposes. To see the real version of each dispatchable, look for them in [`Pallet`] or + /// [`Call`]. #[cfg(doc)] pub mod dispatchables { use super::*; diff --git a/frame/support/procedural/src/pallet/expand/mod.rs b/frame/support/procedural/src/pallet/expand/mod.rs index 926ab0ec82d73..ab37474dfb39f 100644 --- a/frame/support/procedural/src/pallet/expand/mod.rs +++ b/frame/support/procedural/src/pallet/expand/mod.rs @@ -36,7 +36,6 @@ mod type_value; mod validate_unsigned; use crate::pallet::Def; -use frame_support_procedural_tools::get_doc_literals; use quote::ToTokens; /// Merge where clause together, `where` token span is taken from the first not none one. @@ -75,16 +74,25 @@ pub fn expand(mut def: Def) -> proc_macro2::TokenStream { let tt_default_parts = tt_default_parts::expand_tt_default_parts(&mut def); let doc_only = doc_only::expand_doc_only(&mut def); - if get_doc_literals(&def.item.attrs).is_empty() { - def.item.attrs.push(syn::parse_quote!( + def.item.attrs.insert( + 0, + syn::parse_quote!( #[doc = r" - The module that hosts all the - [FRAME](https://docs.substrate.io/main-docs/build/events-errors/) - types needed to add this pallet to a - runtime. - "] - )); - } + The `pallet` module in each FRAME pallet hosts the most important items needed to + construct this pallet. + + The main components of this pallet are: + - [`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 + [`dispatchables`] module or in the [`Call`] enum. + - [`storage_types`], which contains the list of all types that are representing a + storage item. Otherwise, all storage items are listed among [*Type Definitions*](#types). + - [`Config`], which contains the configuration trait of this pallet. + - [`Event`] and [`Error`], which are listed among the [*Enums*](#enums). + "] + ), + ); let new_items = quote::quote!( #metadata_docs diff --git a/frame/support/procedural/src/pallet/expand/pallet_struct.rs b/frame/support/procedural/src/pallet/expand/pallet_struct.rs index 99d2d79f231d9..800e23388c1af 100644 --- a/frame/support/procedural/src/pallet/expand/pallet_struct.rs +++ b/frame/support/procedural/src/pallet/expand/pallet_struct.rs @@ -62,8 +62,8 @@ pub fn expand_pallet_struct(def: &mut Def) -> proc_macro2::TokenStream { if get_doc_literals(&pallet_item.attrs).is_empty() { pallet_item.attrs.push(syn::parse_quote!( #[doc = r" - The [pallet](https://docs.substrate.io/reference/frame-pallets/#pallets) implementing - the on-chain logic. + The `Pallet` struct, the main type that implements traits and standalone + functions within the pallet. "] )); } diff --git a/frame/support/procedural/src/pallet/expand/storage.rs b/frame/support/procedural/src/pallet/expand/storage.rs index c742ddcd25fbc..28fb08c096a69 100644 --- a/frame/support/procedural/src/pallet/expand/storage.rs +++ b/frame/support/procedural/src/pallet/expand/storage.rs @@ -22,6 +22,7 @@ use crate::{ Def, }, }; +use itertools::Itertools; use quote::ToTokens; use std::{collections::HashMap, ops::IndexMut}; use syn::spanned::Spanned; @@ -310,6 +311,65 @@ pub fn process_generics(def: &mut Def) -> syn::Result t, + _ => unreachable!("Checked by def"), + }; + typ_item.attrs.push(syn::parse_quote!(#[doc = ""])); + typ_item.attrs.push(syn::parse_quote!(#[doc = #doc_line])); + }; + def.storages.iter_mut().for_each(|storage| match &storage.metadata { + Metadata::Value { value } => { + let doc_line = format!( + "Storage type is [`StorageValue`] with value type `{}`.", + value.to_token_stream() + ); + push_string_literal(&doc_line, storage); + }, + Metadata::Map { key, value } => { + let doc_line = format!( + "Storage type is [`StorageMap`] with key type `{}` and value type `{}`.", + key.to_token_stream(), + value.to_token_stream() + ); + push_string_literal(&doc_line, storage); + }, + Metadata::DoubleMap { key1, key2, value } => { + let doc_line = format!( + "Storage type is [`StorageDoubleMap`] with key1 type {}, key2 type {} and value type {}.", + key1.to_token_stream(), + key2.to_token_stream(), + value.to_token_stream() + ); + push_string_literal(&doc_line, storage); + }, + Metadata::NMap { keys, value, .. } => { + let doc_line = format!( + "Storage type is [`StorageNMap`] with keys type ({}) and value type {}.", + keys.iter() + .map(|k| k.to_token_stream().to_string()) + .collect::>() + .join(", "), + value.to_token_stream() + ); + push_string_literal(&doc_line, storage); + }, + Metadata::CountedMap { key, value } => { + let doc_line = format!( + "Storage type is [`CountedStorageMap`] with key type {} and value type {}.", + key.to_token_stream(), + value.to_token_stream() + ); + push_string_literal(&doc_line, storage); + }, + }); +} + /// /// * generate StoragePrefix structs (e.g. for a storage `MyStorage` a struct with the name /// `_GeneratedPrefixForStorage$NameOfStorage` is generated) and implements StorageInstance trait. @@ -323,6 +383,8 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream { Err(e) => return e.into_compile_error(), }; + augment_final_docs(def); + // Check for duplicate prefixes let mut prefix_set = HashMap::new(); let mut errors = def @@ -365,10 +427,6 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream { if let Some(getter) = &storage.getter { let completed_where_clause = super::merge_where_clauses(&[&storage.where_clause, &def.config.where_clause]); - let docs = storage - .docs - .iter() - .map(|d| quote::quote_spanned!(storage.attr_span => #[doc = #d])); let ident = &storage.ident; let gen = &def.type_use_generics(storage.attr_span); @@ -378,6 +436,13 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream { let cfg_attrs = &storage.cfg_attrs; + // If the storage item is public, just link to it, rather than + let getter_doc_line = if matches!(storage.vis, syn::Visibility::Public(_)) { + format!("An auto-generated getter for [`{}`].", storage.ident) + } else { + storage.docs.iter().map(|d| d.into_token_stream().to_string()).join("\n") + }; + match &storage.metadata { Metadata::Value { value } => { let query = match storage.query_kind.as_ref().expect("Checked by def") { @@ -394,7 +459,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream { quote::quote_spanned!(storage.attr_span => #(#cfg_attrs)* impl<#type_impl_gen> #pallet_ident<#type_use_gen> #completed_where_clause { - #( #docs )* + #[doc = #getter_doc_line] pub fn #getter() -> #query { < #full_ident as #frame_support::storage::StorageValue<#value> @@ -418,7 +483,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream { quote::quote_spanned!(storage.attr_span => #(#cfg_attrs)* impl<#type_impl_gen> #pallet_ident<#type_use_gen> #completed_where_clause { - #( #docs )* + #[doc = #getter_doc_line] pub fn #getter(k: KArg) -> #query where KArg: #frame_support::codec::EncodeLike<#key>, { @@ -444,7 +509,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream { quote::quote_spanned!(storage.attr_span => #(#cfg_attrs)* impl<#type_impl_gen> #pallet_ident<#type_use_gen> #completed_where_clause { - #( #docs )* + #[doc = #getter_doc_line] pub fn #getter(k: KArg) -> #query where KArg: #frame_support::codec::EncodeLike<#key>, { @@ -470,7 +535,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream { quote::quote_spanned!(storage.attr_span => #(#cfg_attrs)* impl<#type_impl_gen> #pallet_ident<#type_use_gen> #completed_where_clause { - #( #docs )* + #[doc = #getter_doc_line] pub fn #getter(k1: KArg1, k2: KArg2) -> #query where KArg1: #frame_support::codec::EncodeLike<#key1>, KArg2: #frame_support::codec::EncodeLike<#key2>, @@ -498,7 +563,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream { quote::quote_spanned!(storage.attr_span => #(#cfg_attrs)* impl<#type_impl_gen> #pallet_ident<#type_use_gen> #completed_where_clause { - #( #docs )* + #[doc = #getter_doc_line] pub fn #getter(key: KArg) -> #query where KArg: #frame_support::storage::types::EncodeLikeTuple< diff --git a/frame/support/src/lib.rs b/frame/support/src/lib.rs index 138b7b55bf0eb..7910b9ff5e62e 100644 --- a/frame/support/src/lib.rs +++ b/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")] From 91e811b495c15fbd96d9a0afbf59d2ddf1860650 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Tue, 9 May 2023 12:28:55 +0200 Subject: [PATCH 03/32] fix --- frame/support/procedural/src/pallet/expand/error.rs | 5 +---- frame/support/procedural/src/pallet/expand/event.rs | 9 +++------ 2 files changed, 4 insertions(+), 10 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/error.rs b/frame/support/procedural/src/pallet/expand/error.rs index 70f9fdfc71112..376a6a9f51c6d 100644 --- a/frame/support/procedural/src/pallet/expand/error.rs +++ b/frame/support/procedural/src/pallet/expand/error.rs @@ -110,10 +110,7 @@ pub fn expand_error(def: &mut Def) -> proc_macro2::TokenStream { if get_doc_literals(&error_item.attrs).is_empty() { error_item.attrs.push(syn::parse_quote!( - #[doc = r" - Custom [dispatch errors](https://docs.substrate.io/main-docs/build/events-errors/) - of this pallet. - "] + #[doc = "The `Error` enum of this pallet."] )); } diff --git a/frame/support/procedural/src/pallet/expand/event.rs b/frame/support/procedural/src/pallet/expand/event.rs index 2f0cefb8b9fc3..f94bdef332d9d 100644 --- a/frame/support/procedural/src/pallet/expand/event.rs +++ b/frame/support/procedural/src/pallet/expand/event.rs @@ -97,12 +97,9 @@ pub fn expand_event(def: &mut Def) -> proc_macro2::TokenStream { } if get_doc_literals(&event_item.attrs).is_empty() { - event_item.attrs.push(syn::parse_quote!( - #[doc = r" - The [event](https://docs.substrate.io/main-docs/build/events-errors/) emitted - by this pallet. - "] - )); + event_item + .attrs + .push(syn::parse_quote!(#[doc = "The `Event` enum of this pallet"])); } // derive some traits because system event require Clone, FullCodec, Eq, PartialEq and Debug From 85f4390fbfbf409b82f0b2a88c0bc57754f9ef37 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Tue, 9 May 2023 12:29:53 +0200 Subject: [PATCH 04/32] remove stuff not needed --- frame/fast-unstake/src/lib.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 5d6958b54bed8..dce321b0ad860 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -113,11 +113,9 @@ pub mod pallet { #[pallet::pallet] #[pallet::storage_version(STORAGE_VERSION)] - #[doc(alias = "FastUnstakePallet")] // TODO: expand in macro, although it is not super useful. https://github.com/paritytech/substrate/issues/13818 pub struct Pallet(_); #[pallet::config] - #[doc(alias = "FastUnstakeConfig")] pub trait Config: frame_system::Config { /// The overarching event type. type RuntimeEvent: From> From 1a6c63d1a917da9500079311548e14f879f0bcad Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Tue, 9 May 2023 12:42:17 +0200 Subject: [PATCH 05/32] Some updates --- frame/fast-unstake/Cargo.toml | 8 ----- frame/fast-unstake/src/lib.rs | 1 - frame/fast-unstake/src/mock.rs | 8 ++--- frame/fast-unstake/src/tests.rs | 54 +++++++++++++++++++++++++++++++++ 4 files changed, 58 insertions(+), 13 deletions(-) diff --git a/frame/fast-unstake/Cargo.toml b/frame/fast-unstake/Cargo.toml index b7fc95918f547..87c4e4a9f929f 100644 --- a/frame/fast-unstake/Cargo.toml +++ b/frame/fast-unstake/Cargo.toml @@ -56,14 +56,6 @@ 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", diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index dce321b0ad860..10b55bfcc4b43 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -94,7 +94,6 @@ macro_rules! log { }; } -/// Foo #[frame_support::pallet] pub mod pallet { use super::*; diff --git a/frame/fast-unstake/src/mock.rs b/frame/fast-unstake/src/mock.rs index fdc04f654d3ea..fbe6c4592bf67 100644 --- a/frame/fast-unstake/src/mock.rs +++ b/frame/fast-unstake/src/mock.rs @@ -215,7 +215,7 @@ parameter_types! { static FastUnstakeEvents: u32 = 0; } -pub fn fast_unstake_events_since_last_call() -> Vec> { +pub(crate) fn fast_unstake_events_since_last_call() -> Vec> { let events = System::events() .into_iter() .map(|r| r.event) @@ -270,7 +270,7 @@ impl ExtBuilder { }); } - pub fn batch(self, size: u32) -> Self { + pub(crate) fn batch(self, size: u32) -> Self { BatchSize::set(size); self } @@ -338,7 +338,7 @@ impl ExtBuilder { } } -pub fn run_to_block(n: u64, on_idle: bool) { +pub(crate) 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 fn run_to_block(n: u64, on_idle: bool) { } } -pub fn next_block(on_idle: bool) { +pub(crate) fn next_block(on_idle: bool) { let current = System::block_number(); run_to_block(current + 1, on_idle); } diff --git a/frame/fast-unstake/src/tests.rs b/frame/fast-unstake/src/tests.rs index 194ee4fb6cf8c..ff31eed527cf5 100644 --- a/frame/fast-unstake/src/tests.rs +++ b/frame/fast-unstake/src/tests.rs @@ -303,6 +303,60 @@ mod on_idle { }); } + #[docify::export] + #[test] + fn successful_multi_queue() { + ExtBuilder::default().build_and_execute(|| { + ErasToCheckPerBlock::::put(BondingDuration::get() + 1); + CurrentEra::::put(BondingDuration::get()); + + // register multi accounts for fast unstake + assert_ok!(FastUnstake::register_fast_unstake(RuntimeOrigin::signed(2))); + assert_eq!(Queue::::get(1), Some(Deposit::get())); + assert_ok!(FastUnstake::register_fast_unstake(RuntimeOrigin::signed(4))); + assert_eq!(Queue::::get(3), Some(Deposit::get())); + + // assert 2 queue items are in Queue & None in Head to start with + assert_eq!(Queue::::count(), 2); + assert_eq!(Head::::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::::count(), 1); + assert_eq!(Head::::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::::get(), None); + assert_eq!(Queue::::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); + }); + } + #[docify::export] #[test] fn successful_unstake() { From dc82e480a2282071faae91e2680d549d2ae8e9fb Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Tue, 9 May 2023 12:45:49 +0200 Subject: [PATCH 06/32] use new prelude. --- frame/fast-unstake/src/tests.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/fast-unstake/src/tests.rs b/frame/fast-unstake/src/tests.rs index ff31eed527cf5..4cb69d82d672e 100644 --- a/frame/fast-unstake/src/tests.rs +++ b/frame/fast-unstake/src/tests.rs @@ -19,7 +19,7 @@ use super::*; use crate::{mock::*, types::*, Event}; -use frame_support::{assert_noop, assert_ok, bounded_vec, pallet_prelude::*, traits::Currency}; +use frame_support::{pallet_prelude::*, traits::Currency, testing_prelude::*}; use pallet_staking::{CurrentEra, RewardDestination}; use sp_runtime::traits::BadOrigin; From 4973a3266042462824cfc1c3b104f48ec0e669dc Mon Sep 17 00:00:00 2001 From: kianenigma Date: Wed, 10 May 2023 10:19:33 +0200 Subject: [PATCH 07/32] update --- frame/fast-unstake/src/lib.rs | 86 +++++++++++++++++++++++++---------- 1 file changed, 61 insertions(+), 25 deletions(-) diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 10b55bfcc4b43..4065b4155572c 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -17,45 +17,49 @@ //! # Fast Unstake Pallet //! -//! ## Overview +//! A pallet to allow participants of the staking system (represented by [`Config::Staking`]) to +//! unstake quicker, if and only if they meed the condition of not being exposed to any slashes. //! -//! A pallet that's designed to JUST do the following: +//! ## High Level / End-User Details //! -//! If a nominator is not exposed in any `ErasStakers` (i.e. "has not actively backed any -//! validators in the last `BondingDuration` days"), then they can register themselves in this -//! pallet, unstake faster than having to wait an entire bonding duration. +//! This pallet that's designed to JUST do the following: //! -//! Appearing in the exposure of a validator means being exposed equal to that validator from the -//! point of view of the staking system. This usually means earning rewards with the validator, and -//! also being at the risk of slashing with the validator. This is equivalent to the "Active -//! Nominator" role explained in the -//! [February Staking Update](https://polkadot.network/blog/staking-update-february-2022/). +//! If a nominator is not exposed anywhere in the staking system, checked via +//! [`T::Staking::is_exposed_in_era`] (i.e. "has not actively backed any validators in the last +//! [`T::Staking::bonding_duration`] days"), then they can register themselves in this pallet, +//! unstake faster than having to wait an entire bonding duration. //! -//! 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. +//! *Being exposed with validator* from the point of view of the staking system means earning +//! rewards with the validator, and also being at the risk of slashing with the validator. This is +//! equivalent to the "Active Nominator" role explained in +//! [here](https://polkadot.network/blog/staking-update-february-2022/). //! //! Stakers who are certain about NOT being exposed can register themselves with //! [`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 -//! [`Pallet::deregister`]. +//! A successful registration implies being fully unbonded and chilled in the staking system. These +//! effects persis, even if the fast-unstake registration is retracted (see [`Pallet::deregister`] +//! and further). //! -//! 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. +//! Once registered as a fast-unstaker, the staker will be queued and checked by the system. This +//! can take a variable number of blocks based on demand, but will almost certainly be "faster" (as +//! the name suggest) than waiting the standard bonding duration. //! -//! Once processed, if successful, no additional fee for the checking process is taken, and the -//! staker is instantly unbonded. +//! A fast-unstaker is either in [`Queue`], or actively being checked, at which point it lives in +//! [`Head`]. Once in [`Head`], the request cannot retracted anymore. But, once in [`Queue`], it +//! can, via [`Pallet::deregister`]. //! -//! 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. +//! A deposit, equal to [`Config::Deposit`] is collected for this process, and is returned in case a +//! successful unstake occurs (`Event::Unstaked` signals that). //! -//! ## Details +//! Once processed, if successful, no additional fee for the checking process is taken, and the +//! staker is instantly unbonded. //! -//! See [`pallet`] module for more information. +//! If unsuccessful, meaning that the staker was exposed, the aforementioned deposit will be +//! slashed for the amount of wasted work they have inflicted on the chian. //! -//! ## Examples +//! ### Example //! //! 1. Fast-unstake with multiple participants in the queue. #![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", successful_multi_queue)] @@ -63,6 +67,38 @@ //! 2. Fast unstake failing because a nominator is exposed. #![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", exposed_nominator_cannot_unstake)] //! +//! ## Code Details +//! +//! See [`pallet`] module for more information. +//! +//! ## Low Level / Implementation Details +//! +//! 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. +//! +//! A few important considerations can be concluded based on the `on_idle`-based implementation: +//! +//! * It is crucial for the weights of this pallet to be correct. The code inside +//! [`Pallet::on_idle`] MUST be able to measure itself and report the remaining weight correctly +//! after execution. +//! +//! * If the weight measurement is incorrect, it can lead to perpetual overweight (consequently +//! slow) blocks. +//! +//! * The amount of weight that `on_idle` consumes is a direct function of [`ErasToCheckPerBlock`]. +//! +//! * Thus, a correct value of [`ErasToCheckPerBlock`] (which can be set via [`Pallet::control`]) +//! should be chosen, such that a reasonable amount of weight is used `on_idle`. If +//! [`ErasToCheckPerBlock`] is too large, `on_idle` will always conclude that it has not enough +//! weight to proceed, and will early-return. Nonetheless, this should also be *safe* as long as +//! the benchmarking/weights are *accurate*. +//! +//! * See the inline code-comments on `do_on_idle` (private) for more details. +//! +//! * For further safety, in case of any unforeseen errors, the pallet will emit +//! [`Event::InternalError`] and set [`ErasToCheckPerBlock`] back to 0, which essentially means +//! the pallet will halt/disable itself. #![cfg_attr(not(feature = "std"), no_std)] @@ -81,9 +117,9 @@ pub mod migrations; pub mod types; pub mod weights; +/// The logging target of this pallet. pub const LOG_TARGET: &'static str = "runtime::fast-unstake"; -// syntactic sugar for logging. #[macro_export] macro_rules! log { ($level:tt, $patter:expr $(, $values:expr)* $(,)?) => { From 8d0c523c540cfe86afe6c756999d5d32158633d7 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Wed, 10 May 2023 10:59:36 +0200 Subject: [PATCH 08/32] some other fancy docs --- frame/fast-unstake/src/lib.rs | 46 +++++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 10 deletions(-) diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 4065b4155572c..88424f6bfa121 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -15,19 +15,28 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! > Made with *Substrate*, for *Polkadot*. +//! +//! [![github]](https://github.com/paritytech/substrate/frame/fast-unstake) - +//! [![polkadot]](https://polkadot.network) +//! +//! [polkadot]: https://img.shields.io/badge/polkadot-E6007A?style=for-the-badge&logo=polkadot&logoColor=white +//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github +//! //! # Fast Unstake Pallet //! -//! A pallet to allow participants of the staking system (represented by [`Config::Staking`]) to -//! unstake quicker, if and only if they meed the condition of not being exposed to any slashes. +//! A pallet to allow participants of the staking system (represented by [`Config::Staking`], being +//! [`StakingInterface`]) to unstake quicker, if and only if they meed the condition of not being +//! exposed to any slashes. //! //! ## High Level / End-User Details //! //! This pallet that's designed to JUST do the following: //! //! If a nominator is not exposed anywhere in the staking system, checked via -//! [`T::Staking::is_exposed_in_era`] (i.e. "has not actively backed any validators in the last -//! [`T::Staking::bonding_duration`] days"), then they can register themselves in this pallet, -//! unstake faster than having to wait an entire bonding duration. +//! [`StakingInterface::is_exposed_in_era`] (i.e. "has not actively backed any validators in the +//! last [`StakingInterface::bonding_duration`] days"), then they can register themselves in this +//! pallet, unstake faster than having to wait an entire bonding duration. //! //! *Being exposed with validator* from the point of view of the staking system means earning //! rewards with the validator, and also being at the risk of slashing with the validator. This is @@ -56,8 +65,8 @@ //! Once processed, if successful, no additional fee for the checking process is taken, and the //! staker is instantly unbonded. //! -//! If unsuccessful, meaning that the staker was exposed, the aforementioned deposit will be -//! slashed for the amount of wasted work they have inflicted on the chian. +//! If unsuccessful, meaning that the staker was exposed, the aforementioned deposit will be slashed +//! for the amount of wasted work they have inflicted on the chian. //! //! ### Example //! @@ -117,6 +126,12 @@ pub mod migrations; pub mod types; pub mod weights; +// some extra imports for docs to link properly. +#[cfg(doc)] +pub use frame_support::traits::Hooks; +#[cfg(doc)] +pub use sp_staking::StakingInterface; + /// The logging target of this pallet. pub const LOG_TARGET: &'static str = "runtime::fast-unstake"; @@ -221,8 +236,6 @@ pub mod pallet { Unstaked { stash: T::AccountId, result: DispatchResult }, /// A staker was slashed for requesting fast-unstake whilst being exposed. Slashed { stash: T::AccountId, amount: BalanceOf }, - /// An internal error happened. Operations will be paused now. - InternalError, /// A batch was partially checked for the given eras, but the process did not finish. BatchChecked { eras: Vec }, /// A batch of a given size was terminated. @@ -230,6 +243,8 @@ pub mod pallet { /// This is always follows by a number of `Unstaked` or `Slashed` events, marking the end /// of the batch. A new batch will be created upon next block. BatchFinished { size: u32 }, + /// An internal error happened. Operations will be paused now. + InternalError, } #[pallet::error] @@ -291,7 +306,6 @@ pub mod pallet { impl Pallet { /// Register oneself for fast-unstake. /// - /// /// ## Dispatch Origin /// /// The dispatch origin of this call must be *signed* by the whoever is permitted by to call @@ -312,6 +326,10 @@ pub mod pallet { /// If the check fails, the stash remains chilled and waiting for being unbonded as in with /// the normal staking system, but they lose part of their unbonding chunks due to consuming /// the chain's resources. + /// + /// ## Events + /// + /// Some events from the staking and currency system might be emitted. #[pallet::call_index(0)] #[pallet::weight(::WeightInfo::register_fast_unstake())] pub fn register_fast_unstake(origin: OriginFor) -> DispatchResult { @@ -349,6 +367,10 @@ pub mod pallet { /// Note that the associated stash is still fully unbonded and chilled as a consequence of /// calling [`Pallet::register_fast_unstake`]. THerefore, this should probably be followed /// by a call to `rebond` in the staking system. + /// + /// ## Events + /// + /// Some events from the staking and currency system might be emitted. #[pallet::call_index(1)] #[pallet::weight(::WeightInfo::deregister())] pub fn deregister(origin: OriginFor) -> DispatchResult { @@ -381,6 +403,10 @@ pub mod pallet { /// ## Details /// /// Can set the number of eras to check per block, and potentially other admin work. + /// + /// ## Events + /// + /// No events are emitted from this dispatch. #[pallet::call_index(2)] #[pallet::weight(::WeightInfo::control())] pub fn control(origin: OriginFor, eras_to_check: EraIndex) -> DispatchResult { From 1572dd8b06f93a1067acb096d3b0e578d9cf9da5 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Wed, 10 May 2023 11:02:38 +0200 Subject: [PATCH 09/32] Update frame/fast-unstake/src/lib.rs Co-authored-by: Liam Aharon --- frame/fast-unstake/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 88424f6bfa121..7f13aad988b8e 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -48,7 +48,7 @@ //! in the queue to be checked. //! //! A successful registration implies being fully unbonded and chilled in the staking system. These -//! effects persis, even if the fast-unstake registration is retracted (see [`Pallet::deregister`] +//! effects persist, even if the fast-unstake registration is retracted (see [`Pallet::deregister`] //! and further). //! //! Once registered as a fast-unstaker, the staker will be queued and checked by the system. This From 9aa4edef22ba759bb0e16b9186e1583e7643074d Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Wed, 10 May 2023 11:02:44 +0200 Subject: [PATCH 10/32] Update frame/support/procedural/src/pallet/expand/mod.rs Co-authored-by: Liam Aharon --- frame/support/procedural/src/pallet/expand/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/mod.rs b/frame/support/procedural/src/pallet/expand/mod.rs index ab37474dfb39f..561ff8937cdeb 100644 --- a/frame/support/procedural/src/pallet/expand/mod.rs +++ b/frame/support/procedural/src/pallet/expand/mod.rs @@ -85,7 +85,7 @@ pub fn expand(mut def: Def) -> proc_macro2::TokenStream { - [`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 - [`dispatchables`] module or in the [`Call`] enum. + the [`dispatchables`] module or in the [`Call`] enum. - [`storage_types`], which contains the list of all types that are representing a storage item. Otherwise, all storage items are listed among [*Type Definitions*](#types). - [`Config`], which contains the configuration trait of this pallet. From f24ac3c77f9ae4ccbac4640ee102f8c63a2a2ef7 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Wed, 10 May 2023 11:13:05 +0200 Subject: [PATCH 11/32] update --- frame/fast-unstake/src/lib.rs | 6 ++++-- frame/support/procedural/src/pallet/expand/storage.rs | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 88424f6bfa121..90d879bd1a604 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -68,6 +68,8 @@ //! If unsuccessful, meaning that the staker was exposed, the aforementioned deposit will be slashed //! for the amount of wasted work they have inflicted on the chian. //! +//! All in all, this pallet is meant to provide an easy off-ramp for some stakers. +//! //! ### Example //! //! 1. Fast-unstake with multiple participants in the queue. @@ -114,10 +116,10 @@ pub use pallet::*; #[cfg(test)] -pub mod mock; +mod mock; #[cfg(test)] -pub mod tests; +mod tests; // NOTE: enable benchmarking in tests as well. #[cfg(feature = "runtime-benchmarks")] diff --git a/frame/support/procedural/src/pallet/expand/storage.rs b/frame/support/procedural/src/pallet/expand/storage.rs index 28fb08c096a69..f106d5c308da5 100644 --- a/frame/support/procedural/src/pallet/expand/storage.rs +++ b/frame/support/procedural/src/pallet/expand/storage.rs @@ -436,7 +436,7 @@ pub fn expand_storages(def: &mut Def) -> proc_macro2::TokenStream { let cfg_attrs = &storage.cfg_attrs; - // If the storage item is public, just link to it, rather than + // If the storage item is public, just link to it, rather than copy-pasting the docs. let getter_doc_line = if matches!(storage.vis, syn::Visibility::Public(_)) { format!("An auto-generated getter for [`{}`].", storage.ident) } else { From 91846b98ef62a5006f4e185d60ebb0cce46fd6a7 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Wed, 10 May 2023 19:24:06 +0200 Subject: [PATCH 12/32] Update frame/fast-unstake/src/lib.rs Co-authored-by: Keith Yeung --- frame/fast-unstake/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 614e4ab85e325..61321b0afaa54 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -26,7 +26,7 @@ //! # Fast Unstake Pallet //! //! A pallet to allow participants of the staking system (represented by [`Config::Staking`], being -//! [`StakingInterface`]) to unstake quicker, if and only if they meed the condition of not being +//! [`StakingInterface`]) to unstake quicker, if and only if they meet the condition of not being //! exposed to any slashes. //! //! ## High Level / End-User Details From 6b7804a55384b34312d396c95db821882a31271a Mon Sep 17 00:00:00 2001 From: kianenigma Date: Tue, 23 May 2023 10:37:43 +0200 Subject: [PATCH 13/32] update --- Cargo.lock | 31 ++++++++++++++++++++++++++----- frame/fast-unstake/Cargo.toml | 2 +- frame/fast-unstake/src/lib.rs | 2 +- frame/fast-unstake/src/tests.rs | 4 ++-- 4 files changed, 30 insertions(+), 9 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 504a47be9c357..9500d5306105d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1287,6 +1287,17 @@ version = "1.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "acbf1af155f9b9ef647e42cdc158db4b64a1b61f743629225fde6f3e0be2a7c7" +[[package]] +name = "colored" +version = "2.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b3616f750b84d8f0de8a58bda93e08e2a81ad3f523089b05f1dffecab48c6cbd" +dependencies = [ + "atty", + "lazy_static", + "winapi", +] + [[package]] name = "comfy-table" version = "6.1.4" @@ -1298,6 +1309,12 @@ dependencies = [ "unicode-width", ] +[[package]] +name = "common-path" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2382f75942f4b3be3690fe4f86365e9c853c1587d6ee58212cebf6e2a9ccd101" + [[package]] name = "concurrent-queue" version = "2.2.0" @@ -2040,24 +2057,28 @@ checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10" [[package]] name = "docify" -version = "0.1.1" +version = "0.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "00b469cf6e58cc46d7f038c7f9a9c2ed85ae05e3bb65ad165b2b941f41758e57" +checksum = "a1955ad3f17ac98c900db08d539b838e22db36de79e6dc5b91d0bd7023a11d7e" dependencies = [ "docify_macros", ] [[package]] name = "docify_macros" -version = "0.1.1" +version = "0.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "58fd5476bf7e08fb686a7ec8c8f4d0cfb0baa2ab66b151fd6328981b101153da" +checksum = "7e42a4bfcc0d24888181bf02b5ddf90f7f0c5d1246223dbb8d7a565a92e0e4bd" dependencies = [ + "colored", + "common-path", "derive-syn-parse", - "prettyplease 0.2.4", + "lazy_static", "proc-macro2", "quote", + "regex", "syn 2.0.15", + "walkdir", ] [[package]] diff --git a/frame/fast-unstake/Cargo.toml b/frame/fast-unstake/Cargo.toml index 87c4e4a9f929f..0bcdbcd276561 100644 --- a/frame/fast-unstake/Cargo.toml +++ b/frame/fast-unstake/Cargo.toml @@ -27,7 +27,7 @@ frame-election-provider-support = { default-features = false, path = "../electio frame-benchmarking = { version = "4.0.0-dev", default-features = false, optional = true, path = "../benchmarking" } -docify = "0.1.1" +docify = "0.1.5" [dev-dependencies] pallet-staking-reward-curve = { version = "4.0.0-dev", path = "../staking/reward-curve" } diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 5d8cf04e350ff..9d71bd2204fa9 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -76,7 +76,7 @@ #![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", successful_multi_queue)] //! //! 2. Fast unstake failing because a nominator is exposed. -#![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", exposed_nominator_cannot_unstake)] +#![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", exposed_nominator_cannot_unstake_fail)] //! //! ## Pallet API //! diff --git a/frame/fast-unstake/src/tests.rs b/frame/fast-unstake/src/tests.rs index 479708ba80d77..94ad6a84b85a1 100644 --- a/frame/fast-unstake/src/tests.rs +++ b/frame/fast-unstake/src/tests.rs @@ -19,7 +19,7 @@ use super::*; use crate::{mock::*, types::*, Event}; -use frame_support::{pallet_prelude::*, traits::Currency, testing_prelude::*}; +use frame_support::{pallet_prelude::*, testing_prelude::*, traits::Currency}; use pallet_staking::{CurrentEra, RewardDestination}; use sp_runtime::traits::BadOrigin; @@ -695,8 +695,8 @@ mod on_idle { }); } - #[test] #[docify::export] + #[test] fn exposed_nominator_cannot_unstake() { ExtBuilder::default().build_and_execute(|| { ErasToCheckPerBlock::::put(1); From c6a9dc7f6c3b6c0b518cd9d54ae1871f4b17bdeb Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 24 May 2023 23:34:57 -0400 Subject: [PATCH 14/32] fix no_std issue by updating to latest version of docify --- Cargo.lock | 9 +++++---- frame/fast-unstake/Cargo.toml | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 9500d5306105d..f97e5890944ee 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2057,23 +2057,24 @@ checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10" [[package]] name = "docify" -version = "0.1.5" +version = "0.1.7" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a1955ad3f17ac98c900db08d539b838e22db36de79e6dc5b91d0bd7023a11d7e" +checksum = "fd42b99df89dcc00ff3d62361e02d8a91320f25bafde59d66f0be5d87a906f0f" dependencies = [ "docify_macros", ] [[package]] name = "docify_macros" -version = "0.1.5" +version = "0.1.7" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7e42a4bfcc0d24888181bf02b5ddf90f7f0c5d1246223dbb8d7a565a92e0e4bd" +checksum = "22ee41bab3ace62c9e2ba2960003219b57b5b2203a93b5e08ce8fb2ab7aa05be" dependencies = [ "colored", "common-path", "derive-syn-parse", "lazy_static", + "prettyplease 0.2.4", "proc-macro2", "quote", "regex", diff --git a/frame/fast-unstake/Cargo.toml b/frame/fast-unstake/Cargo.toml index 0bcdbcd276561..82bc4b772d976 100644 --- a/frame/fast-unstake/Cargo.toml +++ b/frame/fast-unstake/Cargo.toml @@ -27,7 +27,7 @@ frame-election-provider-support = { default-features = false, path = "../electio frame-benchmarking = { version = "4.0.0-dev", default-features = false, optional = true, path = "../benchmarking" } -docify = "0.1.5" +docify = "0.1.7" [dev-dependencies] pallet-staking-reward-curve = { version = "4.0.0-dev", path = "../staking/reward-curve" } From 6fda39769b15f407716806176cf5a6f311665f3e Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 24 May 2023 23:35:42 -0400 Subject: [PATCH 15/32] get things compiling by adding a use for StakingInterface --- frame/fast-unstake/src/types.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/fast-unstake/src/types.rs b/frame/fast-unstake/src/types.rs index 0edbcdba10999..15d0a327e917e 100644 --- a/frame/fast-unstake/src/types.rs +++ b/frame/fast-unstake/src/types.rs @@ -23,7 +23,7 @@ use frame_support::{ traits::Currency, BoundedVec, EqNoBound, PartialEqNoBound, RuntimeDebugNoBound, }; use scale_info::TypeInfo; -use sp_staking::EraIndex; +use sp_staking::{EraIndex, StakingInterface}; use sp_std::prelude::*; /// Maximum number of eras that we might check for a single staker. From 372f14e8f718a18b290d732e6e69cb14a130f255 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Wed, 24 May 2023 23:36:43 -0400 Subject: [PATCH 16/32] fix docify paths to their proper values, still not working because bug --- frame/fast-unstake/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 9d71bd2204fa9..4252d32a8e9ad 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -73,10 +73,10 @@ //! ### Example //! //! 1. Fast-unstake with multiple participants in the queue. -#![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", successful_multi_queue)] +#![doc = docify::embed!("frame/fast-unstake/src/tests.rs", successful_multi_queue)] //! //! 2. Fast unstake failing because a nominator is exposed. -#![doc = docify::embed!("./frame/fast-unstake/src/tests.rs", exposed_nominator_cannot_unstake_fail)] +#![doc = docify::embed!("frame/fast-unstake/src/tests.rs", exposed_nominator_cannot_unstake)] //! //! ## Pallet API //! From f68b1bb658fb96a242020a2e378457a4198a6f26 Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Thu, 25 May 2023 14:30:52 -0400 Subject: [PATCH 17/32] embed working :tada: --- Cargo.lock | 8 ++++---- frame/fast-unstake/Cargo.toml | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index f97e5890944ee..57944e066b97f 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2057,18 +2057,18 @@ checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10" [[package]] name = "docify" -version = "0.1.7" +version = "0.1.8" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fd42b99df89dcc00ff3d62361e02d8a91320f25bafde59d66f0be5d87a906f0f" +checksum = "00e374affbf735d7a344f4ae5b623fb988cde5b1f9bbf2dff260c9d360796f44" dependencies = [ "docify_macros", ] [[package]] name = "docify_macros" -version = "0.1.7" +version = "0.1.8" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "22ee41bab3ace62c9e2ba2960003219b57b5b2203a93b5e08ce8fb2ab7aa05be" +checksum = "998f7260ad879a4060e05ca21ea66432cd3811103549e85f66144bd5345e8afc" dependencies = [ "colored", "common-path", diff --git a/frame/fast-unstake/Cargo.toml b/frame/fast-unstake/Cargo.toml index 82bc4b772d976..a09bdfdc3cbae 100644 --- a/frame/fast-unstake/Cargo.toml +++ b/frame/fast-unstake/Cargo.toml @@ -27,7 +27,7 @@ frame-election-provider-support = { default-features = false, path = "../electio frame-benchmarking = { version = "4.0.0-dev", default-features = false, optional = true, path = "../benchmarking" } -docify = "0.1.7" +docify = "0.1.8" [dev-dependencies] pallet-staking-reward-curve = { version = "4.0.0-dev", path = "../staking/reward-curve" } From 99ab3142a05b8d757bad71e9b14ca933310c6ada Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Thu, 25 May 2023 20:06:09 -0400 Subject: [PATCH 18/32] update syn --- Cargo.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.lock b/Cargo.lock index d981066e192fb..ca505151b012a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2068,7 +2068,7 @@ dependencies = [ "proc-macro2", "quote", "regex", - "syn 2.0.15", + "syn 2.0.16", "walkdir", ] From acd122b2d474ecbce6ea8563b03bfda5f218774a Mon Sep 17 00:00:00 2001 From: Sam Johnson Date: Thu, 25 May 2023 22:20:20 -0400 Subject: [PATCH 19/32] upgrade to docify v0.1.10 for some fixes --- Cargo.lock | 21 +++++---------------- frame/fast-unstake/Cargo.toml | 2 +- 2 files changed, 6 insertions(+), 17 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index ca505151b012a..dea0e4c373ad9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1278,17 +1278,6 @@ version = "1.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "acbf1af155f9b9ef647e42cdc158db4b64a1b61f743629225fde6f3e0be2a7c7" -[[package]] -name = "colored" -version = "2.0.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b3616f750b84d8f0de8a58bda93e08e2a81ad3f523089b05f1dffecab48c6cbd" -dependencies = [ - "atty", - "lazy_static", - "winapi", -] - [[package]] name = "comfy-table" version = "6.1.4" @@ -2047,20 +2036,19 @@ checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10" [[package]] name = "docify" -version = "0.1.8" +version = "0.1.10" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "00e374affbf735d7a344f4ae5b623fb988cde5b1f9bbf2dff260c9d360796f44" +checksum = "7767ccc3eb4cd952984251db536253f3b37447b00d5d700c12a3fa59e2116f01" dependencies = [ "docify_macros", ] [[package]] name = "docify_macros" -version = "0.1.8" +version = "0.1.10" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "998f7260ad879a4060e05ca21ea66432cd3811103549e85f66144bd5345e8afc" +checksum = "cbaa8797736720f7df8d70318fc09e4ce5c5a897111a60ddce414713ea391043" dependencies = [ - "colored", "common-path", "derive-syn-parse", "lazy_static", @@ -2069,6 +2057,7 @@ dependencies = [ "quote", "regex", "syn 2.0.16", + "termcolor", "walkdir", ] diff --git a/frame/fast-unstake/Cargo.toml b/frame/fast-unstake/Cargo.toml index a09bdfdc3cbae..b18274775e39b 100644 --- a/frame/fast-unstake/Cargo.toml +++ b/frame/fast-unstake/Cargo.toml @@ -27,7 +27,7 @@ frame-election-provider-support = { default-features = false, path = "../electio frame-benchmarking = { version = "4.0.0-dev", default-features = false, optional = true, path = "../benchmarking" } -docify = "0.1.8" +docify = "0.1.10" [dev-dependencies] pallet-staking-reward-curve = { version = "4.0.0-dev", path = "../staking/reward-curve" } From 44e34e47d6cfcba33b73e6f9c32ee034c795687a Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Fri, 26 May 2023 14:45:25 +0200 Subject: [PATCH 20/32] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Juan Co-authored-by: Gonçalo Pestana --- frame/fast-unstake/src/lib.rs | 24 +++++++++---------- .../procedural/src/pallet/expand/config.rs | 2 +- .../procedural/src/pallet/expand/doc_only.rs | 2 +- .../procedural/src/pallet/expand/storage.rs | 4 ++-- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 4252d32a8e9ad..9a9506d413af4 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -36,7 +36,7 @@ //! If a nominator is not exposed anywhere in the staking system, checked via //! [`StakingInterface::is_exposed_in_era`] (i.e. "has not actively backed any validators in the //! last [`StakingInterface::bonding_duration`] days"), then they can register themselves in this -//! pallet, unstake faster than having to wait an entire bonding duration. +//! pallet and unstake faster than having to wait an entire bonding duration. //! //! *Being exposed with validator* from the point of view of the staking system means earning //! rewards with the validator, and also being at the risk of slashing with the validator. This is @@ -44,29 +44,29 @@ //! [here](https://polkadot.network/blog/staking-update-february-2022/). //! //! Stakers who are certain about NOT being exposed can register themselves with -//! [`Pallet::register_fast_unstake`]. This will chill, and fully unbond the staker, and place them +//! [`Pallet::register_fast_unstake`]. This will chill, fully unbond the staker and place them //! in the queue to be checked. //! //! A successful registration implies being fully unbonded and chilled in the staking system. These -//! effects persist, even if the fast-unstake registration is retracted (see [`Pallet::deregister`] +//! effects persist even if the fast-unstake registration is retracted (see [`Pallet::deregister`] //! and further). //! //! Once registered as a fast-unstaker, the staker will be queued and checked by the system. This //! can take a variable number of blocks based on demand, but will almost certainly be "faster" (as //! the name suggest) than waiting the standard bonding duration. //! -//! A fast-unstaker is either in [`Queue`], or actively being checked, at which point it lives in -//! [`Head`]. Once in [`Head`], the request cannot retracted anymore. But, once in [`Queue`], it +//! A fast-unstaker is either in [`Queue`] or actively being checked, at which point it lives in +//! [`Head`]. Once in [`Head`], the request cannot be retracted anymore. But, once in [`Queue`], it //! can, via [`Pallet::deregister`]. //! -//! A deposit, equal to [`Config::Deposit`] is collected for this process, and is returned in case a +//! A deposit equal to [`Config::Deposit`] is collected for this process, and is returned in case a //! successful unstake occurs (`Event::Unstaked` signals that). //! //! Once processed, if successful, no additional fee for the checking process is taken, and the //! staker is instantly unbonded. //! //! If unsuccessful, meaning that the staker was exposed, the aforementioned deposit will be slashed -//! for the amount of wasted work they have inflicted on the chian. +//! for the amount of wasted work they have inflicted on the chain. //! //! All in all, this pallet is meant to provide an easy off-ramp for some stakers. //! @@ -199,8 +199,8 @@ pub mod pallet { /// Maximum value for `ErasToCheckPerBlock`, checked in [`Pallet::control`]. /// - /// This should be as close as possible, but more than the actual value, in order to have - /// accurate benchmarks. + /// This should be slightly bigger than the actual value in order to have accurate + /// benchmarks. type MaxErasToCheckPerBlock: Get; /// The weight information of this pallet. @@ -314,7 +314,7 @@ pub mod pallet { /// /// ## Dispatch Origin /// - /// The dispatch origin of this call must be *signed* by the whoever is permitted by to call + /// The dispatch origin of this call must be *signed* by whoever is permitted to call /// unbond funds by the staking system. See [`Config::Staking`]. /// /// ## Details @@ -363,7 +363,7 @@ pub mod pallet { /// /// ## Dispatch Origin /// - /// The dispatch origin of this call must be *signed* by the whoever is permitted by to call + /// The dispatch origin of this call must be *signed* by whoever is permitted to call /// unbond funds by the staking system. See [`Config::Staking`]. /// /// ## Details @@ -371,7 +371,7 @@ pub mod pallet { /// This is useful if one is registered, they are still waiting, and they change their mind. /// /// Note that the associated stash is still fully unbonded and chilled as a consequence of - /// calling [`Pallet::register_fast_unstake`]. THerefore, this should probably be followed + /// calling [`Pallet::register_fast_unstake`]. Therefore, this should probably be followed /// by a call to `rebond` in the staking system. /// /// ## Events diff --git a/frame/support/procedural/src/pallet/expand/config.rs b/frame/support/procedural/src/pallet/expand/config.rs index 7d7949de5d3cb..f6078c4181997 100644 --- a/frame/support/procedural/src/pallet/expand/config.rs +++ b/frame/support/procedural/src/pallet/expand/config.rs @@ -37,7 +37,7 @@ pub fn expand_config(def: &mut Def) -> proc_macro2::TokenStream { Configuration trait of this pallet. The main purpose of this trait is to act as an interface between this - pallet, and the runtime in which it is embedded in. A type, function, + pallet and the runtime in which it is embedded in. A type, function, or constant in this trait is essentially left to be configured by the runtime that includes this pallet. diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index b023974e6c211..5252da5fcea39 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -63,7 +63,7 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { /// /// # Warning: Doc-Only /// - /// This type is an automatically generated, and is doc-only. See the real version in + /// This type is automatically generated, and is doc-only. See the real version in #[ doc = #real ] pub struct #storage_name(); ) diff --git a/frame/support/procedural/src/pallet/expand/storage.rs b/frame/support/procedural/src/pallet/expand/storage.rs index f106d5c308da5..253b429bb6eb3 100644 --- a/frame/support/procedural/src/pallet/expand/storage.rs +++ b/frame/support/procedural/src/pallet/expand/storage.rs @@ -312,7 +312,7 @@ pub fn process_generics(def: &mut Def) -> syn::Result proc_macro2::TokenStream { let cfg_attrs = &storage.cfg_attrs; - // If the storage item is public, just link to it, rather than copy-pasting the docs. + // If the storage item is public, just link to it rather than copy-pasting the docs. let getter_doc_line = if matches!(storage.vis, syn::Visibility::Public(_)) { format!("An auto-generated getter for [`{}`].", storage.ident) } else { From 7cb1db4b89ddc6bfbaae661b2b77213f012f743d Mon Sep 17 00:00:00 2001 From: kianenigma Date: Fri, 26 May 2023 14:59:57 +0200 Subject: [PATCH 21/32] improve docs --- frame/fast-unstake/src/lib.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index 9a9506d413af4..ed3b6fce6dc41 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -229,8 +229,9 @@ pub mod pallet { /// If set to 0, this pallet does absolutely nothing. Cannot be set to more than /// [`Config::MaxErasToCheckPerBlock`]. /// - /// Based on the amount of weight available at [`Pallet::on_idle`], up to this many eras of a - /// [`UnstakeRequest`], stored in [`Head`] might be checked. + /// Based on the amount of weight available at [`Pallet::on_idle`], up to this many eras are + /// checked. The checking is represented by updating [`UnstakeRequest::checked`], which is + /// stored in [`Head`]. #[pallet::storage] #[pallet::getter(fn eras_to_check_per_block)] pub type ErasToCheckPerBlock = StorageValue<_, u32, ValueQuery>; From 52449528c0e1c1be72a4c142f5f8193b2a217572 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Fri, 26 May 2023 15:00:36 +0200 Subject: [PATCH 22/32] Update frame/support/procedural/src/pallet/expand/doc_only.rs Co-authored-by: Juan --- frame/support/procedural/src/pallet/expand/doc_only.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 5252da5fcea39..9ca17c70626ae 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -71,8 +71,8 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { .collect::(); quote::quote!( - /// Auto-generated docs-only module listing all defined storage types for this pallet, - /// public or non-public. + /// Auto-generated docs-only module listing all (public and private) defined storage types + /// for this pallet. /// /// # Warning: Doc-Only /// From 9c9ab282bad04c549da37d69684cdc8e15dd8ed8 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Fri, 26 May 2023 15:11:20 +0200 Subject: [PATCH 23/32] fmt --- frame/support/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frame/support/src/lib.rs b/frame/support/src/lib.rs index 1a17ef132c79f..80629b9425cef 100644 --- a/frame/support/src/lib.rs +++ b/frame/support/src/lib.rs @@ -1525,10 +1525,10 @@ pub mod tests { 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 + assert_noop, assert_ok, assert_storage_noop, bounded_btree_map, bounded_vec, + parameter_types, traits::Get, }; pub use sp_arithmetic::assert_eq_error_rate; - pub use super::traits::Get; } /// Prelude to be used alongside pallet macro, for ease of use. From 396cec245c109070f0bfa53d894750d65b05bf73 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Fri, 26 May 2023 15:33:04 +0200 Subject: [PATCH 24/32] fix --- .../procedural/src/pallet/expand/config.rs | 15 +++++------- .../procedural/src/pallet/expand/mod.rs | 23 +++++++++---------- frame/support/test/src/lib.rs | 2 +- 3 files changed, 18 insertions(+), 22 deletions(-) diff --git a/frame/support/procedural/src/pallet/expand/config.rs b/frame/support/procedural/src/pallet/expand/config.rs index f6078c4181997..1f593d6089d71 100644 --- a/frame/support/procedural/src/pallet/expand/config.rs +++ b/frame/support/procedural/src/pallet/expand/config.rs @@ -33,17 +33,14 @@ pub fn expand_config(def: &mut Def) -> proc_macro2::TokenStream { config_item.attrs.insert( 0, syn::parse_quote!( - #[doc = r" - Configuration trait of this pallet. + #[doc = r"Configuration trait of this pallet. - The main purpose of this trait is to act as an interface between this - pallet and the runtime in which it is embedded in. A type, function, - or constant in this trait is essentially left to be configured by the - runtime that includes this pallet. +The main purpose of this trait is to act as an interface between this pallet and the runtime in +which it is embedded in. A type, function, or constant in this trait is essentially left to be +configured by the runtime that includes this pallet. - Consequently, a runtime that wants to include this pallet must - implement this trait. - "] +Consequently, a runtime that wants to include this pallet mustimplement this trait." + ] ), ); diff --git a/frame/support/procedural/src/pallet/expand/mod.rs b/frame/support/procedural/src/pallet/expand/mod.rs index 561ff8937cdeb..76bcb5443955d 100644 --- a/frame/support/procedural/src/pallet/expand/mod.rs +++ b/frame/support/procedural/src/pallet/expand/mod.rs @@ -77,19 +77,18 @@ pub fn expand(mut def: Def) -> proc_macro2::TokenStream { def.item.attrs.insert( 0, syn::parse_quote!( - #[doc = r" - The `pallet` module in each FRAME pallet hosts the most important items needed to - construct this pallet. + #[doc = r"The `pallet` module in each FRAME pallet hosts the most important items needed +to construct this pallet. - The main components of this pallet are: - - [`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 - the [`dispatchables`] module or in the [`Call`] enum. - - [`storage_types`], which contains the list of all types that are representing a - storage item. Otherwise, all storage items are listed among [*Type Definitions*](#types). - - [`Config`], which contains the configuration trait of this pallet. - - [`Event`] and [`Error`], which are listed among the [*Enums*](#enums). +The main components of this pallet are: +- [`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 +the [`dispatchables`] module or in the [`Call`] enum. +- [`storage_types`], which contains the list of all types that are representing a +storage item. Otherwise, all storage items are listed among [*Type Definitions*](#types). +- [`Config`], which contains the configuration trait of this pallet. +- [`Event`] and [`Error`], which are listed among the [*Enums*](#enums). "] ), ); diff --git a/frame/support/test/src/lib.rs b/frame/support/test/src/lib.rs index 5dccc88471a7b..2a3cf13d4dac7 100644 --- a/frame/support/test/src/lib.rs +++ b/frame/support/test/src/lib.rs @@ -34,7 +34,7 @@ pub mod pallet { #[pallet::pallet] pub struct Pallet(_); - /// The configuration trait + /// The configuration trait. #[pallet::config] #[pallet::disable_frame_system_supertrait_check] pub trait Config: 'static + Eq + Clone { From 21fc4df41834e3e54365780133f462dcb6078879 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Sun, 28 May 2023 10:40:07 +0200 Subject: [PATCH 25/32] Update frame/support/procedural/src/pallet/expand/doc_only.rs Co-authored-by: Muharem Ismailov --- frame/support/procedural/src/pallet/expand/doc_only.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/doc_only.rs b/frame/support/procedural/src/pallet/expand/doc_only.rs index 9ca17c70626ae..50afeb3ca88cf 100644 --- a/frame/support/procedural/src/pallet/expand/doc_only.rs +++ b/frame/support/procedural/src/pallet/expand/doc_only.rs @@ -79,7 +79,7 @@ pub fn expand_doc_only(def: &mut Def) -> proc_macro2::TokenStream { /// Members of this module cannot be used directly and are only provided for documentation /// purposes. /// - /// To see the actual storage type, find the a struct with the same name at the root of the + /// To see the actual storage type, find a struct with the same name at the root of the /// pallet, in the list of [*Type Definitions*](../index.html#types). #[cfg(doc)] pub mod storage_types { From e4939dc64ba6792a9a1af992362e130305f8ec51 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Sun, 28 May 2023 10:40:16 +0200 Subject: [PATCH 26/32] Update frame/support/procedural/src/pallet/expand/config.rs Co-authored-by: Muharem Ismailov --- frame/support/procedural/src/pallet/expand/config.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/config.rs b/frame/support/procedural/src/pallet/expand/config.rs index 1f593d6089d71..4c8fb167abc53 100644 --- a/frame/support/procedural/src/pallet/expand/config.rs +++ b/frame/support/procedural/src/pallet/expand/config.rs @@ -36,7 +36,7 @@ pub fn expand_config(def: &mut Def) -> proc_macro2::TokenStream { #[doc = r"Configuration trait of this pallet. The main purpose of this trait is to act as an interface between this pallet and the runtime in -which it is embedded in. A type, function, or constant in this trait is essentially left to be +which it is embedded in. A type, function, or constant in this trait is essentially left to be configured by the runtime that includes this pallet. Consequently, a runtime that wants to include this pallet mustimplement this trait." From ffe579f85a93f72c6aeb1bf90ff3827c7ed3ea92 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Sun, 28 May 2023 10:40:24 +0200 Subject: [PATCH 27/32] Update frame/support/procedural/src/pallet/expand/config.rs Co-authored-by: Muharem Ismailov --- frame/support/procedural/src/pallet/expand/config.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/support/procedural/src/pallet/expand/config.rs b/frame/support/procedural/src/pallet/expand/config.rs index 4c8fb167abc53..dd7471aa767cb 100644 --- a/frame/support/procedural/src/pallet/expand/config.rs +++ b/frame/support/procedural/src/pallet/expand/config.rs @@ -39,7 +39,7 @@ The main purpose of this trait is to act as an interface between this pallet and which it is embedded in. A type, function, or constant in this trait is essentially left to be configured by the runtime that includes this pallet. -Consequently, a runtime that wants to include this pallet mustimplement this trait." +Consequently, a runtime that wants to include this pallet must implement this trait." ] ), ); From 04a5affc0fac0aad2a9f56d9c49281589f2bb7f8 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Sun, 28 May 2023 10:40:43 +0200 Subject: [PATCH 28/32] remove redundant --- frame/fast-unstake/src/lib.rs | 2 -- frame/support/procedural/src/pallet/expand/mod.rs | 4 ++-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/frame/fast-unstake/src/lib.rs b/frame/fast-unstake/src/lib.rs index ed3b6fce6dc41..9be5878f2e199 100644 --- a/frame/fast-unstake/src/lib.rs +++ b/frame/fast-unstake/src/lib.rs @@ -31,8 +31,6 @@ //! //! ## Overview //! -//! This pallet that's designed to JUST do the following: -//! //! If a nominator is not exposed anywhere in the staking system, checked via //! [`StakingInterface::is_exposed_in_era`] (i.e. "has not actively backed any validators in the //! last [`StakingInterface::bonding_duration`] days"), then they can register themselves in this diff --git a/frame/support/procedural/src/pallet/expand/mod.rs b/frame/support/procedural/src/pallet/expand/mod.rs index 76bcb5443955d..2b998227c1d84 100644 --- a/frame/support/procedural/src/pallet/expand/mod.rs +++ b/frame/support/procedural/src/pallet/expand/mod.rs @@ -83,8 +83,8 @@ to construct this pallet. The main components of this pallet are: - [`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 -the [`dispatchables`] module or in the [`Call`] enum. + - The subset of the functions that are dispatchable can be identified either in the + [`dispatchables`] module or in the [`Call`] enum. - [`storage_types`], which contains the list of all types that are representing a storage item. Otherwise, all storage items are listed among [*Type Definitions*](#types). - [`Config`], which contains the configuration trait of this pallet. From ff780177274b22e81b3997128015c4bb9c1f7138 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Mon, 29 May 2023 11:18:14 +0200 Subject: [PATCH 29/32] update docify rev --- Cargo.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 54a76a96eb225..9a7b07db3c39d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2036,18 +2036,18 @@ checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10" [[package]] name = "docify" -version = "0.1.10" +version = "0.1.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7767ccc3eb4cd952984251db536253f3b37447b00d5d700c12a3fa59e2116f01" +checksum = "5ce509bc276b9b3a9ceeafafd4d9f09c80fe99aac0a1111159b4403503a473aa" dependencies = [ "docify_macros", ] [[package]] name = "docify_macros" -version = "0.1.10" +version = "0.1.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "cbaa8797736720f7df8d70318fc09e4ce5c5a897111a60ddce414713ea391043" +checksum = "ad111835b124405b045223eba48ab631a22e7ffa1f232279780b4aafa1c65380" dependencies = [ "common-path", "derive-syn-parse", From 9602902e91a6b0a5e19f433ce925c847286b8de3 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Mon, 29 May 2023 12:44:28 +0200 Subject: [PATCH 30/32] update. --- frame/fast-unstake/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/fast-unstake/Cargo.toml b/frame/fast-unstake/Cargo.toml index b18274775e39b..8ddd4d4628b36 100644 --- a/frame/fast-unstake/Cargo.toml +++ b/frame/fast-unstake/Cargo.toml @@ -27,7 +27,7 @@ frame-election-provider-support = { default-features = false, path = "../electio frame-benchmarking = { version = "4.0.0-dev", default-features = false, optional = true, path = "../benchmarking" } -docify = "0.1.10" +docify = "0.1.11" [dev-dependencies] pallet-staking-reward-curve = { version = "4.0.0-dev", path = "../staking/reward-curve" } From 93aca7a0a8c5f70f366780d5aa904db4d9e21539 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Mon, 29 May 2023 16:43:06 +0200 Subject: [PATCH 31/32] update. --- frame/fast-unstake/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frame/fast-unstake/Cargo.toml b/frame/fast-unstake/Cargo.toml index 8ddd4d4628b36..41b2df3c7c6fa 100644 --- a/frame/fast-unstake/Cargo.toml +++ b/frame/fast-unstake/Cargo.toml @@ -27,7 +27,7 @@ frame-election-provider-support = { default-features = false, path = "../electio frame-benchmarking = { version = "4.0.0-dev", default-features = false, optional = true, path = "../benchmarking" } -docify = "0.1.11" +docify = "0.1.13" [dev-dependencies] pallet-staking-reward-curve = { version = "4.0.0-dev", path = "../staking/reward-curve" } From 55fc00176c14a819a56303960f57deed0bbc27c1 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Mon, 29 May 2023 17:00:13 +0200 Subject: [PATCH 32/32] update lock file --- Cargo.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 2bcd2787dcee6..56754e432c7c8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2036,18 +2036,18 @@ checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10" [[package]] name = "docify" -version = "0.1.11" +version = "0.1.13" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5ce509bc276b9b3a9ceeafafd4d9f09c80fe99aac0a1111159b4403503a473aa" +checksum = "18b972b74c30cbe838fc6a07665132ff94f257350e26fd01d80bc59ee7fcf129" dependencies = [ "docify_macros", ] [[package]] name = "docify_macros" -version = "0.1.11" +version = "0.1.13" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ad111835b124405b045223eba48ab631a22e7ffa1f232279780b4aafa1c65380" +checksum = "c93004d1011191c56df9e853dca42f2012e7488638bcd5078935f5ce43e06cf3" dependencies = [ "common-path", "derive-syn-parse",