Power Token Liquidity Mining for Developers
Using the Power Token concept for your own liquidity rewards
Last updated
Using the Power Token concept for your own liquidity rewards
Last updated
Below documentation and code it refers to; are provided under the BSD-3-Clause License.
The below documentation's goal is to give you an overview of how to work with the Power Tokens so that you can learn how they are used in the IPOR ecosystem and draw inspiration for your project. If something is unclear to you, contact the maintaining community via discord. Most current community links can be found on the project's website: https://www.ipor.io.
Power Token is built for modularity. The structure is based on the Power Token, which acts as a foundation and from where the user's Power Token balance can be delegated to modules built on top.
The first component described below is Liquidity Mining. It is a module allowing the distribution of the Power Token to the stakes of a platform's liquidity token (or any other token for that matter) and the Power Token. Abstracting the logic of Power Token use from the Power Token balance management allows for greater flexibility and future growth of Power Token applications within your protocol ecosystem.
Details about the implementation of the IPOR LIquidity mining example can be found in the Liquidity mining
Repository: https://github.com/IPOR-Labs/ipor-power-tokens
Until now, the Power Tokens and Liquidity Mining module have been audited by Zokyo and Ackee, and reports can be found in the audits section.
The model relies on a governance token staked into the Power Token contract. Once the user stakes his governance tokens (in the case of IPOR, that would be the IPOR token), he receives a balance of Power Tokens denominated to the underlying token at a 1:1 ratio.
FUNCTIONS used for staking
Once staked, Power Tokens, although not transferable, can be delegated. Delegating is assigning part of one's Power Token balance to a particular staking pool.
/contracts/tokens/PowerIpor.sol
or you can delegate and stake ipTokens in one function call:
When delegated, another contract can manage the delegated balance however it sees fit. In liquidity mining, delegated balance is used to calculate rewards in various staking pools.
Power Tokens are convertible to the Governance Tokens at a 1:1 ratio. However, there is a way to transfer additional tokens to the Power Token contract without minting any new Power Tokens. Such action will result in all current Power Tokens holders seeing a slightly higher Power Tokens balance as the additional underlying tokens would be distributed proportionally to all Power Tokens holders. This could be done if you would like to distribute Governance tokens to all holders of Power Tokens.
To make such action simple ERC20 transfer of the Governance Tokens has to be made to the address of the Power Token contract. Such transfer will automatically be reflected in the balances of Power Token holders.
In Power Token, the redemption fee (see below) is an example of using this functionality.
The Power Token contract allows for two kinds of redemption of Power Tokens for the underlying Governance Tokens, which can be tuned to the project's needs:
Immediate withdrawal with a fee
No-fee, 2-step redemption with a cool-down period.
If a staker redeems his Power Tokens for Governance Tokens with a fee, that fee is automatically redistributed to the remaining holders of Power Tokens.
Suppose they decide to go with the cool-down period. In that case, first, they need to request the redemption by calling the coolDown function and executing the final redemption function after a predefined cool-down period.
To redeem the tokens, they must be undelegated from any module they have previously delegated to.
Canceling the cooldown is possible by calling the function
Configuration
The admin can configure both the cool-down period and the immediate redemption fee. Fee can be set dynamically by calling a function:
The cooldown period can be set by changing the constant:
Fist component built on top of Power Tokens in the above repository is a LiquidityMining.sol contract. As an admin, you can appoint tokens that would be used for the pools in conjunction with the Power Token.
/contracts/mining/LiquidityMiningInternal.sol
If you would like to deactivate the pool, you to call the function:
After the pool has been deactivated, no user can stake liquidity tokens or delegate Power Tokens. From this point onwards, stakers can only remove their tokens from the pool. The administrator should also set rewards to 0 prior to deactivating the staking pool.
As a contract administrator, you can manage the rate at which the tokens are issued to the participants in the Liquidity Mining program. Rewards are calculated in Power Token (staked version of Governance Token) on every block when participants are staking their tokens. In case when there are no users, rewards are not issued.
/contracts/mining/LiquidityMiningInternas.sol
Changing rewards can be done at any time. Executing function setRewardsPerBlock will trigger rebalancing of the GlobalRewardsIndicators struct, which changes the rate of rewards issued.
To supply the rewards to the rewards contract, you have to make an ERC20 transfer of Governance token to the balance of the liquidityMining contract.
The power Token Liquidity Mining contract does not mandate setting a fixed duration of the rewards period. It is up to the administrator to keep issuing or stop issuing the rewards. It is important, however, to ensure enough governance tokens to cover the rewards that liquidity mining participants can claim. As the administrator, you can top up this balance when you see it appropriate. This approach allows you not to keep all the balance in the rewards contract but rather feed the tokens periodically from the cold wallet.
For example, if you're planning to run liquidity mining for 3 years and keep issuing 1 token per block for a given block, it will mean that you will issue 7.884.000 (assuming 12-second blocks). You can either deposit 7.884.000 tokens upfront or split them into tranches and deposit them every so often. If you decide to deposit quarterly (12*657.000), you could follow this schedule:
| time of deposit | amount |
|---|---|
at the beginning | 657.000 |
by the end of 1st quarter | 657.000 |
.... | .... |
by the end of last quarter | 657.000 |
As mentioned above, ensuring sufficient tokens to cover rewards is essential. If the administrator does not provide sufficient rewards, and all rewards are withdrawn to prevent the staked Power Tokens from being withdrawn as "rewards" by users, the Liquidity Mining contract would prevent any reward claiming. The stakers, at this point, would not be able to use standard ways to unstake their liquidity tokens. Instead, they would be able to use unstakeAndAllocatepwTokens. By doing that, stakers can retrieve their liquidity tokens, enable undelegating Power Tokens and set aside the calculated rewards until they can be claimed later when the contract administrator makes the overdue transfer.
Staker's power-up depends on the ratio between LP Tokens and Power Tokens they have in a particular staking pool. The exact value is drawn on the logarithmic curve defined in the "math section."
The function can be modified to suit particular project needs at inception but can also be modified when the project is running. It's important to note that the user's power-up will only be updated when it interacts with the mining contract, such as claim, stake, unstake etc.
Although the power-up function can be overridden completely, the logarithmic model has several advantages described in "Tokenomics." It can be easily adjusted by modifying horizontal and vertical shift constants:
Curve:
This function can be used by the user can rebalance their own position if they think that they could take advantage of a higher power-up, or other users can rebalance each other if they think that would lead to a particular user getting more adequate rewards hence freeing rewards for other users.
Admin-only functions
Power Token
appoint liquidity mining contract address
set PauseManager
transfer ownership (for example, time lock controller)
renounce ownership
Liquidity Mining
renounce ownership
transfer ownership (for example, time lock controller)
set PauseManager
Pause Manager
pause/unpause
When the Liquidity Mining contract is paused, the following functions are affected.
Staking and unstacking of liquidity tokens is not possible
Claiming rewards
Rewards are still calculated if, as a contract administrator, you wish to stop the issuance of the rewards, then before the pause, you should set rewards to 0
Delegating and undelegating of Power Tokens will not work on the Power Token contract.
When Power Token is paused, the following functionalities are affected:
delegating and undelegaing
invoking cooldown function
canceling cooldown
redeeming of Power Tokens for Governance Tokens
Stake and unstaking of Governance Tokens
Liquidity mining can not issue rewards, although the rewards are calculated.
