diff --git a/frame/balances/README.adoc b/frame/balances/README.adoc index db294462e..dcfe5a2fb 100644 --- a/frame/balances/README.adoc +++ b/frame/balances/README.adoc @@ -72,22 +72,11 @@ it will reset the account nonce (`frame_system::AccountNonce`). The dispatch origin for this call is `root`. -## Weight - -### Weight in Balances - -| Call | Origin | weight | -|-------------------------------|--------|-----------| -| fn force\_transfer(...) | S | 1,000,000 | -| fn transfer(...) | S | 1,000,000 | -| fn transfer\_keep\_alive(...) | S | 1,000,000 | -| fn set\_balance(...) | R | 50,000 | - -### Weight in Substrate's Balances - -| Call | Origin | weight | -|-------------------------------|--------|-----------| -| fn force\_transfer(...) | S | 1,000,000 | -| fn transfer(...) | S | 1,000,000 | -| fn transfer\_keep\_alive(...) | S | 1,000,000 | -| fn set\_balance(...) | R | 50,000 | +## Weights + +| Call | Origin | Darwinia | Substrate | +|-------------------------------|--------|-----------|-----------| +| fn force\_transfer(...) | S | 1,000,000 | 1,000,000 | +| fn transfer(...) | S | 1,000,000 | 1,000,000 | +| fn transfer\_keep\_alive(...) | S | 1,000,000 | 1,000,000 | +| fn set\_balance(...) | R | 50,000 | 50,000 | diff --git a/frame/chainrelay/eth/backing/README.md b/frame/chainrelay/eth/backing/README.md new file mode 100644 index 000000000..31a34f6fc --- /dev/null +++ b/frame/chainrelay/eth/backing/README.md @@ -0,0 +1,7 @@ +# darwinia-eth-backing + +## Weights + +| Call | Origin | darwinia | +|----------------|--------|----------| +| fn redeem(...) | S | 10,000 | diff --git a/frame/chainrelay/eth/backing/src/lib.rs b/frame/chainrelay/eth/backing/src/lib.rs index d5d10c47b..f86b1f66d 100644 --- a/frame/chainrelay/eth/backing/src/lib.rs +++ b/frame/chainrelay/eth/backing/src/lib.rs @@ -36,6 +36,7 @@ use ethabi::{Event as EthEvent, EventParam as EthEventParam, ParamType, RawLog}; use frame_support::{ decl_error, decl_event, decl_module, decl_storage, ensure, traits::{Currency, OnUnbalanced, Time}, + weights::SimpleDispatchInfo, }; use frame_system::{self as system, ensure_signed}; use sp_runtime::{ @@ -152,6 +153,12 @@ decl_module! { fn deposit_event() = default; + /// Redeem balances + /// + /// # + /// - `O(1)` + /// # + #[weight = SimpleDispatchInfo::FixedNormal(10_000)] pub fn redeem(origin, r#for: RedeemFor) { let _relayer = ensure_signed(origin)?; diff --git a/frame/chainrelay/eth/relay/README.md b/frame/chainrelay/eth/relay/README.md new file mode 100644 index 000000000..2b3a75584 --- /dev/null +++ b/frame/chainrelay/eth/relay/README.md @@ -0,0 +1,12 @@ +# darwinia-eth-relay + +## Weights + +| Call | Origin | Darwinia | +|-------------------------------------------|--------|----------| +| fn relay\_header(...) | S | 100,000 | +| fn check\_receipt(...) | S | 100,000 | +| fn add\_authority(...) | R | 50,000 | +| fn remove\_authority(...) | R | 50,000 | +| fn toggle\_check\_authorities(...) | R | 10,000 | +| fn set\_number\_of\_blocks\_finality(...) | R | 10,000 | diff --git a/frame/chainrelay/eth/relay/src/lib.rs b/frame/chainrelay/eth/relay/src/lib.rs index 41b6e2585..5ef687f80 100644 --- a/frame/chainrelay/eth/relay/src/lib.rs +++ b/frame/chainrelay/eth/relay/src/lib.rs @@ -171,6 +171,17 @@ decl_module! { >::deposit_event(RawEvent::SetGenesisHeader(relayer, header, genesis_difficulty)); } + /// Relay header of eth block, store the passing header + /// to darwinia Storage if it is verified. + /// + /// # + /// - `O(1)`. + /// - Limited Storage reads + /// - One storage read + /// - One storage write + /// - Up to one event + /// # + #[weight = SimpleDispatchInfo::FixedNormal(100_000)] pub fn relay_header(origin, header: EthHeader) { let relayer = ensure_signed(origin)?; if Self::check_authorities() { @@ -192,6 +203,14 @@ decl_module! { >::deposit_event(RawEvent::RelayHeader(relayer, header)); } + /// Check receipt + /// + /// # + /// - `O(1)`. + /// - Limited Storage reads + /// - Up to one event + /// # + #[weight = SimpleDispatchInfo::FixedNormal(100_000)] pub fn check_receipt(origin, proof_record: EthReceiptProof) { let relayer = ensure_signed(origin)?; if Self::check_authorities() { @@ -205,6 +224,14 @@ decl_module! { // --- root call --- + /// Add authority + /// + /// # + /// - `O(A)` where `A` length of `authorities` + /// - One storage mutation (codec `O(A)`). + /// - Up to one event + /// # + #[weight = SimpleDispatchInfo::FixedNormal(50_000)] pub fn add_authority(origin, who: T::AccountId) { ensure_root(origin)?; @@ -215,6 +242,14 @@ decl_module! { } } + /// Remove authority + /// + /// # + /// - `O(A)` where `A` length of `authorities` + /// - One storage mutation (codec `O(A)`). + /// - Up to one event + /// # + #[weight = SimpleDispatchInfo::FixedNormal(50_000)] pub fn remove_authority(origin, who: T::AccountId) { ensure_root(origin)?; @@ -227,6 +262,14 @@ decl_module! { } } + /// Check authorities + /// + /// # + /// - `O(1)`. + /// - One storage write + /// - Up to one event + /// # + #[weight = SimpleDispatchInfo::FixedNormal(10_000)] pub fn toggle_check_authorities(origin) { ensure_root(origin)?; @@ -235,13 +278,25 @@ decl_module! { >::deposit_event(RawEvent::ToggleCheckAuthorities(Self::check_authorities())); } - #[weight = SimpleDispatchInfo::FixedNormal(5_000)] + /// Set number of blocks finality + /// + /// # + /// - `O(1)`. + /// - One storage write + /// # + #[weight = SimpleDispatchInfo::FixedNormal(10_000)] pub fn set_number_of_blocks_finality(origin, #[compact] new: u64) { ensure_root(origin)?; NumberOfBlocksFinality::put(new); } - #[weight = SimpleDispatchInfo::FixedNormal(5_000)] + /// Set number of blocks finality + /// + /// # + /// - `O(1)`. + /// - One storage write + /// # + #[weight = SimpleDispatchInfo::FixedNormal(10_000)] pub fn set_number_of_blocks_safe(origin, #[compact] new: u64) { ensure_root(origin)?; NumberOfBlocksSafe::put(new); diff --git a/frame/elections-phragmen/README.md b/frame/elections-phragmen/README.md new file mode 100644 index 000000000..ff5126998 --- /dev/null +++ b/frame/elections-phragmen/README.md @@ -0,0 +1,12 @@ +# elections-phragmen + +## Weights + +| Call | Origin | darwinia | substrate | +|--------------------------------|--------|-----------|-----------| +| fn remove\_member(...) | S | 2,000,000 | 2,000,000 | +| fn renounce\_candidacy(...) | S | 2,000,000 | 2,000,000 | +| fn report\_defunct\_voter(...) | S | 1,000,000 | 1,000,000 | +| fn submit\_candidacy(...) | S | 500,000 | 500,000 | +| fn vote(...) | S | 100,000 | 100,000 | +| fn remove\_voter(...) | S | 10,000 | 10,000 | diff --git a/frame/staking/CHANGELOG.md b/frame/staking/CHANGELOG.md index 17c71efc8..c651d0074 100644 --- a/frame/staking/CHANGELOG.md +++ b/frame/staking/CHANGELOG.md @@ -8,13 +8,14 @@ Some concepts should have some explaination for the changing from substrate power is a mixture of ring and kton. -+ For *RING*: `power = ring_ratio * POWER_COUNT / 2` -+ For *KTON*: `power = kton_ratio * POWER_COUNT / 2` ++ *RING*: `power = ring_ratio * POWER_COUNT / 2` ++ *KTON*: `power = kton_ratio * POWER_COUNT / 2` -### rebond +We use `currency_to_power` and `power_of` to calculcate `power`. -The darwinia style `rebond` implementation. +### rebond +We doesn't support `rebond` currently now. ### withdraw @@ -22,10 +23,30 @@ What should happen after all balances being unbonded?(the locked balance) ## Moudle -+ delete `withdraw_unbond` -+ delete `slashable_balance_of` -+ use `power_of` -+ use `stake_of` +### delete `withdraw_unbond` + ++ **withdraw_unbond**: Remove all associated data of a stash account from the staking system. + +Darwinia has `active_balance` and `active_deposit_balance`, we calculate `normal_balance` by `active_balance - active_deposit_balance`, the `normal_balance` is **free to transfer**, so we don't need the `withdraw_unbond` function actually. + +### delete `slashable_balance_of` + ++ **slashable_balance_of**: The total balance that can be slashed from a stash account as of right now. + +We use `power_of` and `stake_of` instead of `slashable_balance_of`: + ++ **power_of**: The total power that can be slashed from a stash account as of right now. ++ **stake_of**: The `active_ring` and `active_kton` from a stash account. + +**For if an account is slashale:** + +Just use `power_of`, if the return `power` is zero, the target account is not slashable. + +**For the amount of slashable balances:** + +The slashable balances actually mean `active-ring` and `active-kton` in darwinia's staking +process, we can use `Staking::ledger(controller)` to get a `StakingLedger` which contains +the `active-ring` and `active-kton` the `controller` have. ## Structs diff --git a/frame/staking/README.md b/frame/staking/README.md new file mode 100644 index 000000000..12d504ebf --- /dev/null +++ b/frame/staking/README.md @@ -0,0 +1,104 @@ +# Staking + +The Staking module is the means by which a set of network maintainers (known as _authorities_ +in some contexts and _validators_ in others) are chosen based upon those who voluntarily place +funds under deposit. Under deposit, those funds are rewarded under normal operation but are +held at pain of _slash_ (expropriation) should the staked maintainer be found not to be +discharging its duties properly. + +## Terminology + +- **Staking**: The process of locking up funds for some time, placing them at risk of slashing +(loss) in order to become a rewarded maintainer of the network. +- **Validating**: The process of running a node to actively maintain the network, either by +producing blocks or guaranteeing finality of the chain. +- **Nominating**: The process of placing staked funds behind one or more validators in order to +share in any reward, and punishment, they take. +- **Stash account**: The account holding an owner's funds used for staking. +- **Controller account**: The account that controls an owner's funds for staking. +- **Era**: A (whole) number of sessions, which is the period that the validator set (and each +validator's active nominator set) is recalculated and where rewards are paid out. +- **Slash**: The punishment of a staker by reducing its funds. + +## Weights + +| Call | Origin | darwinia | substrate | +|---------------------------------------|--------|-----------|-----------| +| fn cancel\_deferred\_slash | R | 1,000,000 | 1,000,000 | +| fn validate(...) | S | 750,000 | 750,000 | +| fn nominate(...) | S | 750,000 | 750,000 | +| fn set\_controller(...) | S | 750,000 | 750,000 | +| fn try\_claim\_deposits\_with\_punish | S | 750,000 | - | +| fn deposit\_extra(...) | S | 500,000 | - | +| fn bond(...) | S | 500,000 | 500,000 | +| fn bond\_extra(...) | S | 500,000 | 500,000 | +| fn chill(...) | S | 500,000 | 500,000 | +| fn set\_payee(...) | S | 500,000 | 500,000 | +| fn payout\_nominator | R | 500,000 | 500,000 | +| fn set\_history\_depth | R | 500,000 | 500,000 | +| fn unbond(...) | S | 500,000 | 400,000 | +| fn clain\_mature\_deposits | S | 100,000 | 10,000 | +| fn set\_invulnerables | R | 10,000 | 10,000 | +| fn force\_unstake | R | 10,000 | 10,000 | +| fn force\_new\_era_\always | R | 10,000 | 10,000 | +| fn set\_validator\_count(...) | R | 10,000 | 5,000 | +| fn force\_no\_eras | R | 10,000 | 5,000 | +| fn reap\_stash | R | 10,000 | - | + +## FAQ + +### Q1: What is the relationship between stash and controller? + +Stash account holding an owner's funds used for staking, controller account controls an owner's funds for staking. + +### Q2: What does staker mean? + +Almost any interaction with the Staking module requires a process of **bonding** (also known +as being a *staker*). To become *bonded*, a fund-holding account known as the *stash account*, +which holds some or all of the funds that become frozen in place as part of the staking process, +is paired with an active **controller** account, which issues instructions on how they shall be +used. + +### Q3: What are the differents from BlockNumber, Era, Session and TimeStamp? + +We config the relationships manually, for example: + +```rust +pub fn start_session(session_index: SessionIndex) { + for i in Session::current_index()..session_index { + Staking::on_finalize(System::block_number()); + System::set_block_number((i + 1).into()); + Timestamp::set_timestamp(System::block_number() * 1000); + Session::on_initialize(System::block_number()); + } + assert_eq!(Session::current_index(), session_index); +} +``` + +| Unit | Value | +|-------------|----------| +| BlockNumber | 4 | +| Session | 3 | +| Timestamp | 3 * 1000 | +| Era | 1 | + +### Q4: What is the process of rewrad? + +```rust +// 1. Insert stash account into Payment map. +Payee::::insert(11, RewardDestination::Controller); +// 2. Add reward points to validators using their stash account ID. +Staking::reward_by_ids(vec![(11, 50)]); +// 3. Make all validator and nominator request their payment +make_all_reward_payment(0); // 0 means 0 era. +``` + +**What happend exactly?** + +`make_all_reward_payment` triggers reward process: + ++ `make_all_reward_payment` + + reward nominators + + payout from nominators to controller + + reward validators + + payout from validators to controller diff --git a/frame/staking/src/lib.rs b/frame/staking/src/lib.rs index 4d46fa0ea..a0f9679b3 100644 --- a/frame/staking/src/lib.rs +++ b/frame/staking/src/lib.rs @@ -1232,7 +1232,16 @@ decl_module! { } } - // TODO: doc + /// Deposit some extra amount ring, and return kton to the controller. + /// + /// The dispatch origin for this call must be _Signed_ by the stash, not the controller. + /// + /// # + /// - Independent of the arguments. Insignificant complexity. + /// - O(1). + /// - One DB entry. + /// # + #[weight = SimpleDispatchInfo::FixedNormal(500_000)] fn deposit_extra(origin, value: RingBalance, promise_month: Moment) { let stash = ensure_signed(origin)?; let controller = Self::bonded(&stash).ok_or(>::NotStash)?; @@ -1290,7 +1299,7 @@ decl_module! { /// /// /// Only active normal ring can be unbond - #[weight = SimpleDispatchInfo::FixedNormal(400_000)] + #[weight = SimpleDispatchInfo::FixedNormal(500_000)] fn unbond(origin, value: StakingBalanceT) { let controller = ensure_signed(origin)?; let mut ledger = Self::clear_mature_deposits(Self::ledger(&controller).ok_or(>::NotController)?); @@ -1386,7 +1395,16 @@ decl_module! { } } - // TODO: doc + /// Stash accounts can get their ring back after the depositing time exceeded, + /// and the ring getting back is still in staking status. + /// + /// # + /// - Independent of the arguments. Insignificant complexity. + /// - One storage read. + /// - One storage write. + /// - Writes are limited to the `origin` account key. + /// # + #[weight = SimpleDispatchInfo::FixedNormal(500_000)] fn claim_mature_deposits(origin) { let controller = ensure_signed(origin)?; let ledger = Self::clear_mature_deposits(Self::ledger(&controller).ok_or(>::NotController)?); @@ -1394,7 +1412,18 @@ decl_module! { >::insert(controller, ledger); } - // TODO: doc + /// Claim deposits while the depositing time has not been exceeded, the ring + /// will not be slashed, but the account is required to pay KTON as punish. + /// + /// Refer to https://talk.darwinia.network/topics/55 + /// + /// # + /// - Independent of the arguments. Insignificant complexity. + /// - One storage read. + /// - One storage write. + /// - Writes are limited to the `origin` account key. + /// # + #[weight = SimpleDispatchInfo::FixedNormal(750_000)] fn try_claim_deposits_with_punish(origin, expire_time: MomentT) { let controller = ensure_signed(origin)?; let mut ledger = Self::ledger(&controller).ok_or(>::NotController)?; diff --git a/frame/treasury/README.adoc b/frame/treasury/README.adoc index e82fb7e84..7200e0e6c 100644 --- a/frame/treasury/README.adoc +++ b/frame/treasury/README.adoc @@ -35,6 +35,15 @@ respectively. - `reject_proposal` - Reject a proposal, slashing the deposit. - `approve_proposal` - Accept the proposal, returning the deposit. -## GenesisConfig - -The Treasury module depends on the `GenesisConfig`. +## Weights + +| Call | Origin | Darwinia | Substrate | +|---------------------------|--------|----------|-----------| +| fn propose\_spend(...) | S | 500,000 | 500,000 | +| fn tip\_new(...) | S | 150,000 | 150,000 | +| fn reject\_proposal(...) | - | 100,000 | 100,000 | +| fn approve\_proposal(...) | - | 100,000 | 100,000 | +| fn report\_awesome(...) | S | 100,000 | 100,000 | +| fn retract\_tip(...) | S | 50,000 | 50,000 | +| fn tip(...) | S | 50,000 | 50,000 | +| fn close\_tip(...) | S | 50,000 | 50,000 |