Key takeaways:
Liquidity Deposit and Locking: Users provide liquidity by calling addLiquidityAndLock, which adds their specified token amounts to the pool and locks their LP tokens.
Reward Accumulation and Claiming: Rewards accumulate over time based on the user’s stake size and duration. Users can claim rewards through the claim function, provided they meet lockup conditions and the pool allows withdrawals.
NFT Reward Multipliers: Users holding eligible NFTs can boost their rewards, with the multiplier applied when they claim.
Withdrawal of LP Tokens: Users can exit the liquidity pool by withdrawing their LP tokens via unlockAndRemoveLP, but only after meeting any required lock period. If the pool has a withdrawal lock, they must wait until the lock is lifted or expires.
Reward Calculation: Rewards are based on the duration of the stake, the staked LP token amount, and the pool’s reward rate. The calculation adjusts based on the lock period, user activity, and any NFT multiplier, giving a personalized reward amount per user. For liquidity pools (LPs), the lock period cannot be 0 because rewards are only calculated for locked tokens.
___________________________________________________________________________
User Interaction Flow:
Deposit Liquidity:
The user decides to participate in the liquidity locking program and provides liquidity to one of the supported pools.
They call the addLiquidityAndLock function, specifying the pool ID (_pid) and the amount of each token they want to add as liquidity (_token0Amt and _token1Amt).
The contract adds liquidity to the Uniswap pair and locks the LP tokens for the specified pool.
Claim Rewards:
Over time, the user accumulates rewards based on their stake in the pool.
They can claim their accumulated rewards by calling the claim function, specifying the pool ID (_pid) they want to claim rewards from.
Before processing the claim, the contract checks two conditions:
If withdrawal is locked for the specified pool (_pid), and
If the user is eligible to claim rewards based on the lockup period.
If either condition fails, the claim function will return false, and the user won't be able to claim rewards.
If both conditions pass, the contract calculates the amount of rewards the user is entitled to based on their stake duration and the reward rate.
If the user owns the correct NFT multiplier for the pool, the reward amount is adjusted accordingly.
The contract transfers the claimed rewards to the user's address.
Withdraw LP Tokens:
At any time, the user may decide to withdraw their LP tokens and exit the liquidity locking program.
They call the unlockAndRemoveLP function, specifying the pool ID (_pid) and the number of LP tokens they want to withdraw (_amount).
Before withdrawing, the contract checks if the user meets any lockup period requirements and if the withdrawal is locked for the specified pool (_pid).
If withdrawal is locked, the contract will prevent the user from withdrawing LP tokens until the lock period expires or the withdrawal lock is lifted by the owner.
If the conditions are met, the contract removes the LP tokens from the liquidity pool and transfers them back to the user.
The contract updates the user's total invested and withdrawn amounts, as well as the total invested amount in the pool.
Reward Calculation
Variables Initialization:
Initialize variables pool and user to store information about the specified pool and user, respectively.
Define variables from and to represent the start and end timestamps for the reward calculation period.
Calculate Reward:
Calculate the duration of the reward calculation period. If the user's last payout time is greater than or equal to their deposit time, set from as the last payout time. Otherwise, set from as the user's deposit time.
Calculate to as the minimum of the current timestamp and the time when the user's deposit period ends.
If to is greater than from, calculate the reward amount using the following formula:
reward = ((to - from) * amount * rewardRate) / (1000 * 365 days)
where:
to - from represents the duration in seconds.
amount represents the number of tokens staked by the user.
rewardRate represents the rate of reward distribution per LP token.
Apply the multiplier to the calculated reward amount if the user owns the correct NFT multiplier for the pool.
Return Reward Amount:
Return the calculated reward amount.
NB: amount here is the number of LP tokens they received after adding liquidity