Crate pallet_proof_of_stake

Expand description

Proof of Stake Module

The goal of the Proof of Stake module is to reward people for providing liquidity to the Mangata DEX.

As described in Mangata tokenomics, during each session, some of the rewards are minted and distributed among promoted pools. The council decides which pool to promote, and each promoted pool has a weight assigned that determines how much of the rewards should be distributed to that pool.

The final amount of tokens that a user receives depends on:

the amount of activated liquidity - rewards are distributed proportionally to the amount of activated liquidity.
the liquidity token itself - the more weight is assigned to the pool, the more rewards it receives.
the time of liquidity activation - the longer a user stores liquidity, the more rewards they receive (based on an asymptotic curve).

Activated Liquidity cannot be transferred to another account; it is considered locked. The moment liquidity is unlocked, the user loses the ability to claim rewards for that liquidity.

Storage entries

TotalActivatedLiquidity - Stores information about the total amount of activated liquidity for each liquidity token.
PromotedPoolRewards - Stores information about the total amount of rewards for each liquidity token.
RewardsInfo - Stores information about rewards for liquidity mining.
ThirdPartyActivationKind - Wrapper over origin ActivateKind that is used in

Extrinsics

Pallet::activate_liquidity - Activates liquidity for liquidity mining rewards.
Pallet::deactivate_liquidity_for_native_rewards - Deactivates liquidity for liquidity mining rewards.
Pallet::claim_native_rewards - Claims all rewards for all liquidity tokens.
Pallet::update_pool_promotion - Enables/disables the pool for liquidity mining rewards.

3rd Party Rewards

Anyone can provide tokens to reward people who store a particular liquidity token. Any liquidity token can be rewarded with any other token provided by the user. Liquidity can be activated for multiple scheduled rewards related to that liquidity token. Tokens will remain locked (untransferable) as long as there is at least one schedule for which these rewards are activated.

Storage entries

RewardsInfoForScheduleRewards - Stores information about rewards for scheduled rewards.
ScheduleRewardsTotal - Stores the amount of rewards per single liquidity token.
RewardsSchedules - Stores information about scheduled rewards.
ScheduleId - Stores the unique id of the schedule.
RewardTokensPerPool - Stores information about which reward tokens are used for a particular liquidity token.
TotalActivatedLiquidityForSchedules - Stores information about the total amount of activated liquidity for each schedule.
ActivatedLiquidityForSchedules - Stores information about how much liquidity was activated for each schedule.
ActivatedLockedLiquidityForSchedules - Stores information about how much liquidity was activated for each schedule and not yet liquidity mining rewards.

Extrinsics

Pallet::reward_pool - Schedules rewards for the selected liquidity token.
Pallet::activate_liquidity_for_3rdparty_rewards - Activates liquidity for scheduled rewards.
Pallet::deactivate_liquidity_for_3rdparty_rewards - Deactivates liquidity for scheduled rewards.
Pallet::claim_3rdparty_rewards - Claims all scheduled rewards for all liquidity tokens.

Reusing a Single Liquidity Token for Multiple Rewards

It may happen that a single liquidity token is rewarded with:

Liquidity Mining Rewards - because the pool was promoted by the council.
Scheduled rewards with token X - because Alice decided to do so.
Scheduled rewards with token Y - because Bob decided to do so.

In that case, a single liquidity token can be used to obtain rewards from multiple sources. There are several options to do that:

The user can reuse liquidity used for liquidity mining rewards to claim scheduled rewards. In this case, Pallet::activate_liquidity_for_3rdparty_rewards should be used with [ActivateKind::LiquidityMining].
The user can reuse liquidity used for scheduled rewards (X) to sign up for rewards from other tokens (provided by Bob). In that case, Pallet::activate_liquidity_for_3rdparty_rewards should be used with [ActivateKind::ActivatedLiquidity(X)].
The user can’t directly provide liquidity activated for scheduled rewards to activate it for native rewards. Instead:
- Liquidity used for schedule rewards can be deactivated Pallet::deactivate_liquidity_for_3rdparty_rewards.
- Liquidity can be activated for liquidity mining rewards Pallet::activate_liquidity.
- Liquidity can be activated for scheduled rewards Pallet::activate_liquidity_for_3rdparty_rewards with [ThirdPartyActivationKind::Mining].

Unlocking tokens used for rewards

Once liquidity tokens are used to sign up for rewards they persist on user account but they become reserved/untransferable. In order to unlock them they need to be deactivated. Depending on rewards kind (native or 3rdparty) deactivation process differs.

Native rewards

If liq tokens are used only for native rewards they are locked/unlocked in the same moment liquidity is activated/deactivated.
If liq tokens are reactivated (see ThirdPartyActivationKind::NativeRewardsLiquidity) then:
- remaining( not reactivated) liq tokens that were not reactivated can be unlocked using Pallet::deactivate_liquidity_for_native_rewards
- reactivated liq tokens can be unlocked only after all of liquidity tokens ( not only reactivated part ) are deactivated from 3rdparty tokens and then Pallet::deactivate_liquidity_for_native_rewards is used

3rdparty rewards

If liq tokens are used for 3rdparty rewards they are locked in the moment of activation. To get them unlocked you need to unlock all of them(liq tokens) for every 3rdparty rewards schedule/token they were used/activated. Even if you want to deactivate only part of it, all of them needs to be deactivated, afterwards they can be reactivated with no penalty in terms of recevied rewards (you will get same amount of rewards as you would not be deactivating them)

3rdparty Rewards

It may happen that a single liquidity token is rewarded with:

Liquidity Mining Rewards - because the pool was promoted by the council.
Scheduled rewards with token X - because Alice decided to do so.
Scheduled rewards with token Y - because Bob decided to do so.

In that case, a single liquidity token can be used to obtain rewards from multiple sources. There are several options to do that:

The user can reuse liquidity used for liquidity mining rewards to claim scheduled rewards. In this case, Pallet::activate_liquidity_for_3rdparty_rewards should be used with [ActivateKind::LiquidityMining].
The user can reuse liquidity used for scheduled rewards (X) to sign up for rewards from other tokens (provided by Bob). In that case, Pallet::activate_liquidity_for_3rdparty_rewards should be used with [ActivateKind::ActivatedLiquidity(X)].
The user can’t directly provide liquidity activated for scheduled rewards to activate it for native rewards. Instead:
- Liquidity used for schedule rewards can be deactivated Pallet::deactivate_liquidity_for_3rdparty_rewards.
- Liquidity can be activated for liquidity mining rewards Pallet::activate_liquidity.
- Liquidity can be activated for scheduled rewards Pallet::activate_liquidity_for_3rdparty_rewards with [ThirdPartyActivationKind::Mining].

Re-exports

pub use weights::WeightInfo;
pub use pallet::*;

Modules

pallet
The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
weights
Autogenerated weights for pallet_proof_of_stake