From d1e3e3d7c5677e80acf6eb6331438785a799db4e Mon Sep 17 00:00:00 2001 From: Allen Pocket Date: Tue, 12 Oct 2021 11:01:06 +0800 Subject: [PATCH 1/3] :pencil: ($PALLET) Refactor docs of lm's error --- pallets/liquidity-mining/src/lib.rs | 32 ++++++++++++++--------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/pallets/liquidity-mining/src/lib.rs b/pallets/liquidity-mining/src/lib.rs index 6eab2f126..a9c38b5dc 100644 --- a/pallets/liquidity-mining/src/lib.rs +++ b/pallets/liquidity-mining/src/lib.rs @@ -359,15 +359,15 @@ pub mod pallet { #[pallet::constant] type RelayChainTokenSymbol: Get; - /// The amount deposited into a liquidity-pool should be less than the value + /// The deposit of a liquidity-pool should be less than the value #[pallet::constant] type MaximumDepositInPool: Get>; - /// The amount deposited by a user to a liquidity-pool should be greater than the value + /// The amount which be deposited to a liquidity-pool should be greater than the value #[pallet::constant] type MinimumDepositOfUser: Get>; - /// The amount of token to reward per block should be greater than the value + /// The amount of reward which will be released per block should be greater than the value #[pallet::constant] type MinimumRewardPerBlock: Get>; @@ -375,11 +375,11 @@ pub mod pallet { #[pallet::constant] type MinimumDuration: Get>; - /// The number of liquidity-pool charged should be less than the value + /// The count of liquidity-pool charged should be less than the value #[pallet::constant] type MaximumCharged: Get; - /// The number of option rewards should be less than the value + /// The count of option rewards should be less than the value #[pallet::constant] type MaximumOptionRewards: Get; @@ -399,27 +399,25 @@ pub mod pallet { InvalidPoolId, InvalidPoolState, InvalidPoolType, - /// Find duplicate reward when creating the liquidity-pool + /// Find duplicate rewards when creating the liquidity-pool DuplicateReward, - /// When the amount deposited in a liquidity-pool exceeds the `MaximumDepositInPool` + /// The deposit of a liquidity-pool exceeded the `MaximumDepositInPool` ExceedMaximumDeposit, - /// When the number of pool-charged exceeds the `MaximumCharged` + /// The number of pool which be charged exceeded the `MaximumCharged` ExceedMaximumCharged, - /// Not enough balance to deposit + /// User doesn't have enough balance of which be deposited to pool NotEnoughToDeposit, - /// Not enough balance to redeem(VERY SCARY ERR) + /// Keeper doesn't have enough balance to be redeemed by the user(VERY SCARY ERR) NotEnoughToRedeem, - /// Not enough balance of reward to unreserve - FailOnUnReserve, - /// Not enough deposit of the user in the liquidity-pool + /// User has nothing be deposited to the pool NoDepositOfUser, - /// Too low balance to deposit + /// The balance which was tried to deposit to the pool less than `MinimumDepositOfUser` TooLowToDeposit, - /// User doesnt have enough deposit to redeem + /// User doesn't have such amount deposit can be redeemed from the pool TooLowToRedeem, - /// The interval between two claims is short + /// Duplicate claim actions were at same block height TooShortBetweenTwoClaim, - /// The pool has been charged + /// The pool has been charged already PoolChargedAlready, /// __NOTE__: ERROR HAPPEN Unexpected, From 872180994d01010eae48193ef9be1a9bc6e17d31 Mon Sep 17 00:00:00 2001 From: Allen Pocket Date: Wed, 13 Oct 2021 12:14:47 +0800 Subject: [PATCH 2/3] :pencil: ($PALLET) Refactor the docs about all extrinsics --- pallets/liquidity-mining/src/lib.rs | 118 ++++++++++++++++------------ 1 file changed, 68 insertions(+), 50 deletions(-) diff --git a/pallets/liquidity-mining/src/lib.rs b/pallets/liquidity-mining/src/lib.rs index a9c38b5dc..28f652e5c 100644 --- a/pallets/liquidity-mining/src/lib.rs +++ b/pallets/liquidity-mining/src/lib.rs @@ -426,35 +426,35 @@ pub mod pallet { #[pallet::event] #[pallet::generate_deposit(pub (crate) fn deposit_event)] pub enum Event { - /// The liquidity-pool has been created + /// The liquidity-pool was created /// /// [pool_id, pool_type, trading_pair, keeper] PoolCreated(PoolId, PoolType, (CurrencyId, CurrencyId), AccountIdOf), - /// The liquidity-pool has been charged + /// The liquidity-pool was charged /// /// [pool_id, pool_type, trading_pair, investor] PoolCharged(PoolId, PoolType, (CurrencyId, CurrencyId), AccountIdOf), - /// The liquidity-pool has been started up + /// The liquidity-pool was started up /// /// [pool_id, pool_type, trading_pair] PoolStarted(PoolId, PoolType, (CurrencyId, CurrencyId)), - /// The liquidity-pool has been killed + /// The liquidity-pool was killed /// /// [pool_id, pool_type, trading_pair] PoolKilled(PoolId, PoolType, (CurrencyId, CurrencyId)), - /// The liquidity-pool has been retired forcefully + /// The liquidity-pool was retired forcefully /// /// [pool_id, pool_type, trading_pair] PoolRetiredForcefully(PoolId, PoolType, (CurrencyId, CurrencyId)), - /// User has deposited some trading-pair to a liquidity-pool + /// User deposited tokens to a liquidity-pool /// /// [pool_id, pool_type, trading_pair, amount_deposited, user] UserDeposited(PoolId, PoolType, (CurrencyId, CurrencyId), BalanceOf, AccountIdOf), - /// User has been redeemed some trading-pair from a liquidity-pool + /// User redeemed tokens from a liquidity-mining /// /// [pool_id, pool_type, trading_pair, amount_redeemed, user] UserRedeemed(PoolId, PoolType, (CurrencyId, CurrencyId), BalanceOf, AccountIdOf), - /// User has been claimed the rewards from a liquidity-pool + /// User withdrew the rewards whose deserved from a liquidity-pool /// /// [pool_id, pool_type, trading_pair, rewards, user] UserClaimed( @@ -494,6 +494,8 @@ pub mod pallet { #[pallet::call] impl Pallet { + /// Create a liquidity-pool which type is `PoolType::Mining`, Only accepts `lpToken` as + /// deposit. #[pallet::weight(( 0, DispatchClass::Normal, @@ -530,6 +532,8 @@ pub mod pallet { ) } + /// Create a liquidity-pool which type is `PoolType::Farming`, Only accepts free `vsToken` + /// and free `vsBond` as deposit. #[pallet::weight(( 0, DispatchClass::Normal, @@ -562,6 +566,8 @@ pub mod pallet { ) } + /// Create a liquidity-pool which type is `PoolType::Farming`, Only accepts reserved + /// `vsToken` and reserved `vsBond` as deposit. #[pallet::weight(( 0, DispatchClass::Normal, @@ -594,6 +600,11 @@ pub mod pallet { ) } + /// Transfer the rewards which are used to distribute to depositors to a liquidity-pool. + /// + /// _NOTE_: The extrinsic is only applied to the liquidity-pool at `PoolState::UnCharged`. + /// When the extrinsic was executed successfully, the liquidity-pool would be at + /// `PoolState::Charged`. #[pallet::weight(T::WeightInfo::charge())] pub fn charge(origin: OriginFor, pid: PoolId) -> DispatchResultWithPostInfo { let investor = ensure_signed(origin)?; @@ -628,6 +639,7 @@ pub mod pallet { Ok(().into()) } + /// Kill a liquidity-pool at `PoolState::Uncharged`. #[pallet::weight(( 0, DispatchClass::Normal, @@ -652,6 +664,13 @@ pub mod pallet { Ok(().into()) } + /// Make a liquidity-pool be at `PoolState::Retired` forcefully. + /// + /// __NOTE__: + /// 1. If the pool is at `PoolState::Charged` but doesn't have any deposit, the data about + /// the pool would be deleted and the rewards charged would be returned back. + /// 2. If the pool is at `PoolState::Charged` and has some deposit, or `PoolState::Ongoing`, + /// the field `block_retired` of the pool would be set to the current block height. #[pallet::weight(( 0, DispatchClass::Normal, @@ -691,15 +710,14 @@ pub mod pallet { Ok(().into()) } - /// User deposits some token to a liquidity-pool. + /// Caller deposits some token to a liquidity-pool. /// - /// The extrinsic will: - /// - Try to retire the liquidity-pool which has reached the end of life. - /// - Try to settle the rewards when the liquidity-pool in `Ongoing`. + /// __NOTE__: The unclaimed rewards of caller will be withdrawn automatically if there has. /// /// The conditions to deposit: - /// - User should deposit enough(greater than `T::MinimumDeposit`) token to liquidity-pool; - /// - The liquidity-pool should be in special state: `Charged`, `Ongoing`; + /// - The deposit caller was contributed to the pool should be bigger than + /// `T::MinimumDeposit`; + /// - The pool is at `PoolState::Charged` or `PoolState::Ongoing`; #[transactional] #[pallet::weight(T::WeightInfo::deposit())] pub fn deposit( @@ -774,25 +792,22 @@ pub mod pallet { Ok(().into()) } - /// User redeems some deposit from a liquidity-pool. - /// The deposit in the liquidity-pool should be greater than `T::MinimumDeposit` when the - /// liquidity-pool is on `Ongoing` state; So user may not be able to redeem completely - /// until the liquidity-pool is on `Retire` state. + /// Caller redeems some deposit owned by self from a pool. /// - /// The extrinsic will: - /// - Try to retire the liquidity-pool which has reached the end of life. - /// - Try to settle the rewards. - /// - Try to unreserve the remaining rewards to the pool investor when the deposit in the - /// liquidity-pool is clear. - /// - Try to delete the liquidity-pool in which the deposit becomes zero. - /// - Try to delete the deposit-data in which the deposit becomes zero. + /// __NOTE__: The unclaimed rewards of caller will be withdrawn automatically if there has. /// - /// The condition to redeem: - /// - User should have some deposit in the liquidity-pool; - /// - The liquidity-pool should be in special state: `Ongoing`, `Retired`; + /// __NOTE__: + /// 0. If the pool is at `PoolState::Ongoing`, the caller may not redeem successfully + /// because of the `reward algorithm`, which requires `pool-ongoing` must have deposit more + /// than `T::MinimumDeposit`. 1. If the pool is at `PoolState::Retired`, the extrinsic will + /// redeem all deposits owned by the caller, whatever the `value` is. + /// 2. If the pool is at `PoolState::Retired` and the deposit in the pool will become zero + /// after calling the extrinsic, the remaining rewards left in the pool will be returned + /// back to the charger. /// - /// NOTE: All deposit will be redeemed when the pool is being `Retired`, no matter the - /// `value` is. + /// The condition to redeem: + /// - There is enough deposit owned by the caller in the pool. + /// - The pool is at `PoolState::Ongoing` or `PoolState::Retired`. #[transactional] #[pallet::weight(T::WeightInfo::redeem())] pub fn redeem( @@ -809,22 +824,20 @@ pub mod pallet { Self::redeem_inner(user, pid, Some(value)) } - /// User redeems all deposit from a liquidity-pool. - /// The deposit in the liquidity-pool should be greater than `T::MinimumDeposit` when the - /// liquidity-pool is on `Ongoing` state; So user may not be able to redeem completely - /// until the liquidity-pool is on `Retire` state. + /// Caller redeems all deposit owned by self from a pool. /// - /// The extrinsic will: - /// - Try to retire the liquidity-pool which has reached the end of life. - /// - Try to settle the rewards. - /// - Try to unreserve the remaining rewards to the pool investor when the deposit in the - /// liquidity-pool is clear. - /// - Try to delete the liquidity-pool in which the deposit becomes zero. - /// - Try to delete the deposit-data in which the deposit becomes zero. + /// __NOTE__: The unclaimed rewards of caller will be withdrawn automatically if there has. + /// + /// __NOTE__: + /// 0. If the pool is at `PoolState::Ongoing`, the caller may not redeem successfully + /// because of the `reward algorithm`, which requires `pool-ongoing` must have deposit more + /// than `T::MinimumDeposit`. 1. If the pool is at `PoolState::Retired` and the deposit in + /// the pool will become zero after calling the extrinsic, the remaining rewards left in the + /// pool will be returned back to the charger. /// /// The condition to redeem: - /// - User should have some deposit in the liquidity-pool; - /// - The liquidity-pool should be in special state: `Ongoing`, `Retired`; + /// - There is enough deposit owned by the caller in the pool. + /// - The pool is at `PoolState::Ongoing` or `PoolState::Retired`. #[transactional] #[pallet::weight(T::WeightInfo::redeem_all())] pub fn redeem_all(origin: OriginFor, pid: PoolId) -> DispatchResultWithPostInfo { @@ -833,9 +846,15 @@ pub mod pallet { Self::redeem_inner(user, pid, None) } - /// Help someone to redeem the deposit whose deposited in a liquidity-pool. + /// A selfless man intimately helps depositors of the pool to redeem their deposit, + /// aaaaaaah, such a grateful!! + /// + /// If the `account` is `Option::None`, the extrinsic will give "freedom" for a lucky man + /// randomly; If the `account` is specific and a depositor of the pool indeed, who will be + /// given "freedom" by the extrinsic. /// - /// NOTE: The liquidity-pool should be in retired state. + /// The condition to redeem: + /// - The pool is at `PoolState::Retired`. #[transactional] #[pallet::weight(T::WeightInfo::volunteer_to_redeem())] pub fn volunteer_to_redeem( @@ -861,14 +880,13 @@ pub mod pallet { Self::redeem_inner(user, pid, None) } - /// User claims the rewards from a liquidity-pool. + /// Caller withdraw the unclaimed rewards owned by self from a pool. /// - /// The extrinsic will: - /// - Try to retire the liquidity-pool which has reached the end of life. + /// __NOTE__: The extrinsic will retire the pool, which is reached the end of life. /// /// The conditions to claim: - /// - User should have enough token deposited in the liquidity-pool; - /// - The liquidity-pool should be in special states: `Ongoing`; + /// - There is enough deposit owned by the caller in the pool. + /// - The pool is at `PoolState::Ongoing`. #[transactional] #[pallet::weight(T::WeightInfo::claim())] pub fn claim(origin: OriginFor, pid: PoolId) -> DispatchResultWithPostInfo { From 68cafbe82da564058df877d897a0f6ccdcf159a3 Mon Sep 17 00:00:00 2001 From: Allen Pocket Date: Wed, 13 Oct 2021 12:23:58 +0800 Subject: [PATCH 3/3] :art: ($PALLET) Format the docs --- pallets/liquidity-mining/src/lib.rs | 30 ++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/pallets/liquidity-mining/src/lib.rs b/pallets/liquidity-mining/src/lib.rs index 28f652e5c..a745cfe37 100644 --- a/pallets/liquidity-mining/src/lib.rs +++ b/pallets/liquidity-mining/src/lib.rs @@ -602,9 +602,9 @@ pub mod pallet { /// Transfer the rewards which are used to distribute to depositors to a liquidity-pool. /// - /// _NOTE_: The extrinsic is only applied to the liquidity-pool at `PoolState::UnCharged`. - /// When the extrinsic was executed successfully, the liquidity-pool would be at - /// `PoolState::Charged`. + /// _NOTE_: The extrinsic is only applied to the liquidity-pool at `PoolState::UnCharged`; + /// When the extrinsic was executed successfully, the liquidity-pool would be at + /// `PoolState::Charged`. #[pallet::weight(T::WeightInfo::charge())] pub fn charge(origin: OriginFor, pid: PoolId) -> DispatchResultWithPostInfo { let investor = ensure_signed(origin)?; @@ -669,6 +669,7 @@ pub mod pallet { /// __NOTE__: /// 1. If the pool is at `PoolState::Charged` but doesn't have any deposit, the data about /// the pool would be deleted and the rewards charged would be returned back. + /// /// 2. If the pool is at `PoolState::Charged` and has some deposit, or `PoolState::Ongoing`, /// the field `block_retired` of the pool would be set to the current block height. #[pallet::weight(( @@ -799,10 +800,13 @@ pub mod pallet { /// __NOTE__: /// 0. If the pool is at `PoolState::Ongoing`, the caller may not redeem successfully /// because of the `reward algorithm`, which requires `pool-ongoing` must have deposit more - /// than `T::MinimumDeposit`. 1. If the pool is at `PoolState::Retired`, the extrinsic will - /// redeem all deposits owned by the caller, whatever the `value` is. + /// than `T::MinimumDeposit`. + /// + /// 1. If the pool is at `PoolState::Retired`, the extrinsic will redeem all deposits + /// owned by the caller, whatever the `value` is. + /// /// 2. If the pool is at `PoolState::Retired` and the deposit in the pool will become zero - /// after calling the extrinsic, the remaining rewards left in the pool will be returned + /// after calling the extrinsic, the remaining rewards left in the pool will be returned /// back to the charger. /// /// The condition to redeem: @@ -831,9 +835,11 @@ pub mod pallet { /// __NOTE__: /// 0. If the pool is at `PoolState::Ongoing`, the caller may not redeem successfully /// because of the `reward algorithm`, which requires `pool-ongoing` must have deposit more - /// than `T::MinimumDeposit`. 1. If the pool is at `PoolState::Retired` and the deposit in - /// the pool will become zero after calling the extrinsic, the remaining rewards left in the - /// pool will be returned back to the charger. + /// than `T::MinimumDeposit`. + /// + /// 1. If the pool is at `PoolState::Retired` and the deposit in the pool will become zero + /// after calling the extrinsic, the remaining rewards left in the pool will be + /// returned back to the charger. /// /// The condition to redeem: /// - There is enough deposit owned by the caller in the pool. @@ -850,8 +856,10 @@ pub mod pallet { /// aaaaaaah, such a grateful!! /// /// If the `account` is `Option::None`, the extrinsic will give "freedom" for a lucky man - /// randomly; If the `account` is specific and a depositor of the pool indeed, who will be - /// given "freedom" by the extrinsic. + /// randomly; + /// + /// If the `account` is specific and a depositor of the pool indeed, who will be given + /// "freedom" by the extrinsic. /// /// The condition to redeem: /// - The pool is at `PoolState::Retired`.