From fb9baeb70bf4bf4310b93235ea7b4af6c25fc789 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Wed, 7 Jul 2021 07:31:20 +0200 Subject: [PATCH] clean up staking docs, remove EraElectionStatus references (#9287) --- substrate/frame/staking/src/lib.rs | 97 +++--------------------------- 1 file changed, 7 insertions(+), 90 deletions(-) diff --git a/substrate/frame/staking/src/lib.rs b/substrate/frame/staking/src/lib.rs index 595255a40e..5fe02212c6 100644 --- a/substrate/frame/staking/src/lib.rs +++ b/substrate/frame/staking/src/lib.rs @@ -1447,7 +1447,6 @@ pub mod pallet { /// The dispatch origin for this call must be _Signed_ by the stash account. /// /// Emits `Bonded`. - /// /// # /// - Independent of the arguments. Moderate complexity. /// - O(1). @@ -1456,10 +1455,6 @@ pub mod pallet { /// NOTE: Two of the storage writes (`Self::bonded`, `Self::payee`) are _never_ cleaned /// unless the `origin` falls below _existential deposit_ and gets removed as dust. /// ------------------ - /// Weight: O(1) - /// DB Weight: - /// - Read: Bonded, Ledger, [Origin Account], Current Era, History Depth, Locks - /// - Write: Bonded, Payee, [Origin Account], Locks, Ledger /// # #[pallet::weight(T::WeightInfo::bond())] pub fn bond( @@ -1513,23 +1508,17 @@ pub mod pallet { /// Add some extra amount that have appeared in the stash `free_balance` into the balance up /// for staking. /// + /// The dispatch origin for this call must be _Signed_ by the stash, not the controller. + /// /// Use this if there are additional funds in your stash account that you wish to bond. /// Unlike [`bond`] or [`unbond`] this function does not impose any limitation on the amount /// that can be added. /// - /// The dispatch origin for this call must be _Signed_ by the stash, not the controller and - /// it can be only called when [`EraElectionStatus`] is `Closed`. - /// /// Emits `Bonded`. /// /// # /// - Independent of the arguments. Insignificant complexity. /// - O(1). - /// - One DB entry. - /// ------------ - /// DB Weight: - /// - Read: Era Election Status, Bonded, Ledger, [Origin Account], Locks - /// - Write: [Origin Account], Locks, Ledger /// # #[pallet::weight(T::WeightInfo::bond_extra())] pub fn bond_extra( @@ -1559,6 +1548,8 @@ pub mod pallet { /// period ends. If this leaves an amount actively bonded less than /// T::Currency::minimum_balance(), then it is increased to the full amount. /// + /// The dispatch origin for this call must be _Signed_ by the controller, not the stash. + /// /// Once the unlock period is done, you can call `withdraw_unbonded` to actually move /// the funds out of management ready for transfer. /// @@ -1569,27 +1560,9 @@ pub mod pallet { /// If a user encounters the `InsufficientBond` error when calling this extrinsic, /// they should call `chill` first in order to free up their bonded funds. /// - /// The dispatch origin for this call must be _Signed_ by the controller, not the stash. - /// And, it can be only called when [`EraElectionStatus`] is `Closed`. - /// /// Emits `Unbonded`. /// /// See also [`Call::withdraw_unbonded`]. - /// - /// # - /// - Independent of the arguments. Limited but potentially exploitable complexity. - /// - Contains a limited number of reads. - /// - Each call (requires the remainder of the bonded balance to be above `minimum_balance`) - /// will cause a new entry to be inserted into a vector (`Ledger.unlocking`) kept in storage. - /// The only way to clean the aforementioned storage item is also user-controlled via - /// `withdraw_unbonded`. - /// - One DB entry. - /// ---------- - /// Weight: O(1) - /// DB Weight: - /// - Read: EraElectionStatus, Ledger, CurrentEra, Locks, BalanceOf Stash, - /// - Write: Locks, Ledger, BalanceOf Stash, - /// #[pallet::weight(T::WeightInfo::unbond())] pub fn unbond(origin: OriginFor, #[pallet::compact] value: BalanceOf) -> DispatchResult { let controller = ensure_signed(origin)?; @@ -1636,30 +1609,14 @@ pub mod pallet { /// This essentially frees up that balance to be used by the stash account to do /// whatever it wants. /// - /// The dispatch origin for this call must be _Signed_ by the controller, not the stash. - /// And, it can be only called when [`EraElectionStatus`] is `Closed`. + /// The dispatch origin for this call must be _Signed_ by the controller. /// /// Emits `Withdrawn`. /// /// See also [`Call::unbond`]. /// /// # - /// - Could be dependent on the `origin` argument and how much `unlocking` chunks exist. - /// It implies `consolidate_unlocked` which loops over `Ledger.unlocking`, which is - /// indirectly user-controlled. See [`unbond`] for more detail. - /// - Contains a limited number of reads, yet the size of which could be large based on `ledger`. - /// - Writes are limited to the `origin` account key. - /// --------------- /// Complexity O(S) where S is the number of slashing spans to remove - /// Update: - /// - Reads: EraElectionStatus, Ledger, Current Era, Locks, [Origin Account] - /// - Writes: [Origin Account], Locks, Ledger - /// Kill: - /// - Reads: EraElectionStatus, Ledger, Current Era, Bonded, Slashing Spans, [Origin - /// Account], Locks, BalanceOf stash - /// - Writes: Bonded, Slashing Spans (if S > 0), Ledger, Payee, Validators, Nominators, - /// [Origin Account], Locks, BalanceOf stash. - /// - Writes Each: SpanSlash * S /// NOTE: Weight annotation is the kill scenario, we refund otherwise. /// # #[pallet::weight(T::WeightInfo::withdraw_unbonded_kill(*num_slashing_spans))] @@ -1707,18 +1664,6 @@ pub mod pallet { /// Effects will be felt at the beginning of the next era. /// /// The dispatch origin for this call must be _Signed_ by the controller, not the stash. - /// And, it can be only called when [`EraElectionStatus`] is `Closed`. - /// - /// # - /// - Independent of the arguments. Insignificant complexity. - /// - Contains a limited number of reads. - /// - Writes are limited to the `origin` account key. - /// ----------- - /// Weight: O(1) - /// DB Weight: - /// - Read: Era Election Status, Ledger - /// - Write: Nominators, Validators - /// # #[pallet::weight(T::WeightInfo::validate())] pub fn validate(origin: OriginFor, prefs: ValidatorPrefs) -> DispatchResult { let controller = ensure_signed(origin)?; @@ -1743,22 +1688,14 @@ pub mod pallet { /// Declare the desire to nominate `targets` for the origin controller. /// - /// Effects will be felt at the beginning of the next era. This can only be called when - /// [`EraElectionStatus`] is `Closed`. + /// Effects will be felt at the beginning of the next era. /// /// The dispatch origin for this call must be _Signed_ by the controller, not the stash. - /// And, it can be only called when [`EraElectionStatus`] is `Closed`. /// /// # /// - The transaction's complexity is proportional to the size of `targets` (N) /// which is capped at CompactAssignments::LIMIT (MAX_NOMINATIONS). /// - Both the reads and writes follow a similar pattern. - /// --------- - /// Weight: O(N) - /// where N is the number of targets - /// DB Weight: - /// - Reads: Era Election Status, Ledger, Current Era - /// - Writes: Validators, Nominators /// # #[pallet::weight(T::WeightInfo::nominate(targets.len() as u32))] pub fn nominate( @@ -1811,17 +1748,11 @@ pub mod pallet { /// Effects will be felt at the beginning of the next era. /// /// The dispatch origin for this call must be _Signed_ by the controller, not the stash. - /// And, it can be only called when [`EraElectionStatus`] is `Closed`. /// /// # /// - Independent of the arguments. Insignificant complexity. /// - Contains one read. /// - Writes are limited to the `origin` account key. - /// -------- - /// Weight: O(1) - /// DB Weight: - /// - Read: EraElectionStatus, Ledger - /// - Write: Validators, Nominators /// # #[pallet::weight(T::WeightInfo::chill())] pub fn chill(origin: OriginFor) -> DispatchResult { @@ -2100,8 +2031,6 @@ pub mod pallet { /// The origin of this call must be _Signed_. Any account can call this function, even if /// it is not one of the stakers. /// - /// This can only be called when [`EraElectionStatus`] is `Closed`. - /// /// # /// - Time complexity: at most O(MaxNominatorRewardedPerValidator). /// - Contains a limited number of reads and writes. @@ -2110,11 +2039,6 @@ pub mod pallet { /// Weight: /// - Reward Destination Staked: O(N) /// - Reward Destination Controller (Creating): O(N) - /// DB Weight: - /// - Read: EraElectionStatus, CurrentEra, HistoryDepth, ErasValidatorReward, - /// ErasStakersClipped, ErasRewardPoints, ErasValidatorPrefs (8 items) - /// - Read Each: Bonded, Ledger, Payee, Locks, System Account (5 items) - /// - Write Each: System Account, Locks, Ledger (3 items) /// /// NOTE: weights are assuming that payouts are made to alive stash account (Staked). /// Paying even a dead controller is cheaper weight-wise. We don't do any refunds here. @@ -2131,17 +2055,12 @@ pub mod pallet { /// Rebond a portion of the stash scheduled to be unlocked. /// - /// The dispatch origin must be signed by the controller, and it can be only called when - /// [`EraElectionStatus`] is `Closed`. + /// The dispatch origin must be signed by the controller. /// /// # /// - Time complexity: O(L), where L is unlocking chunks /// - Bounded by `MAX_UNLOCKING_CHUNKS`. /// - Storage changes: Can't increase storage, only decrease it. - /// --------------- - /// - DB Weight: - /// - Reads: EraElectionStatus, Ledger, Locks, [Origin Account] - /// - Writes: [Origin Account], Locks, Ledger /// # #[pallet::weight(T::WeightInfo::rebond(MAX_UNLOCKING_CHUNKS as u32))] pub fn rebond( @@ -2238,8 +2157,6 @@ pub mod pallet { /// Effects will be felt at the beginning of the next era. /// /// The dispatch origin for this call must be _Signed_ by the controller, not the stash. - /// And, it can be only called when [`EraElectionStatus`] is `Closed`. The controller - /// account should represent a validator. /// /// - `who`: A list of nominator stash accounts who are nominating this validator which /// should no longer be nominating this validator.