Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More docs to lm #346

Merged
merged 3 commits into from
Oct 13, 2021
Merged

More docs to lm #346

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d1e3e3d
:pencil: ($PALLET) Refactor docs of lm's error
AllenPocketGamer Oct 12, 2021
8721809
:pencil: ($PALLET) Refactor the docs about all extrinsics
AllenPocketGamer Oct 13, 2021
68cafbe
:art: ($PALLET) Format the docs
AllenPocketGamer Oct 13, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 91 additions & 67 deletions pallets/liquidity-mining/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,27 +359,27 @@ pub mod pallet {
#[pallet::constant]
type RelayChainTokenSymbol: Get<TokenSymbol>;

/// 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<BalanceOf<Self>>;

/// 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<BalanceOf<Self>>;

/// 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<BalanceOf<Self>>;

/// The duration of a liquidity-pool should be greater than the value
#[pallet::constant]
type MinimumDuration: Get<BlockNumberFor<Self>>;

/// 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<u32>;

/// 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<u32>;

Expand All @@ -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,
Expand All @@ -428,35 +426,35 @@ pub mod pallet {
#[pallet::event]
#[pallet::generate_deposit(pub (crate) fn deposit_event)]
pub enum Event<T: Config> {
/// The liquidity-pool has been created
/// The liquidity-pool was created
///
/// [pool_id, pool_type, trading_pair, keeper]
PoolCreated(PoolId, PoolType, (CurrencyId, CurrencyId), AccountIdOf<T>),
/// The liquidity-pool has been charged
/// The liquidity-pool was charged
///
/// [pool_id, pool_type, trading_pair, investor]
PoolCharged(PoolId, PoolType, (CurrencyId, CurrencyId), AccountIdOf<T>),
/// 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<T>, AccountIdOf<T>),
/// 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<T>, AccountIdOf<T>),
/// 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(
Expand Down Expand Up @@ -496,6 +494,8 @@ pub mod pallet {

#[pallet::call]
impl<T: Config> Pallet<T> {
/// Create a liquidity-pool which type is `PoolType::Mining`, Only accepts `lpToken` as
/// deposit.
#[pallet::weight((
0,
DispatchClass::Normal,
Expand Down Expand Up @@ -532,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,
Expand Down Expand Up @@ -564,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,
Expand Down Expand Up @@ -596,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<T>, pid: PoolId) -> DispatchResultWithPostInfo {
let investor = ensure_signed(origin)?;
Expand Down Expand Up @@ -630,6 +639,7 @@ pub mod pallet {
Ok(().into())
}

/// Kill a liquidity-pool at `PoolState::Uncharged`.
#[pallet::weight((
0,
DispatchClass::Normal,
Expand All @@ -654,6 +664,14 @@ 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,
Expand Down Expand Up @@ -693,15 +711,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(
Expand Down Expand Up @@ -776,25 +793,25 @@ 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(
Expand All @@ -811,22 +828,22 @@ 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.
///
/// __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`.
///
/// 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.
/// 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<T>, pid: PoolId) -> DispatchResultWithPostInfo {
Expand All @@ -835,9 +852,17 @@ 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!!
///
/// NOTE: The liquidity-pool should be in retired state.
/// 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.
///
/// The condition to redeem:
/// - The pool is at `PoolState::Retired`.
#[transactional]
#[pallet::weight(T::WeightInfo::volunteer_to_redeem())]
pub fn volunteer_to_redeem(
Expand All @@ -863,14 +888,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<T>, pid: PoolId) -> DispatchResultWithPostInfo {
Expand Down