LM_PC_Staking_v1.sol

Git Source

Inherits: ILM_PC_Staking_v1, ERC20PaymentClientBase_v1, ReentrancyGuardUpgradeable

Author: Inverter Network

Provides a mechanism for users to stake tokens and earn rewards.

Extends {ERC20PaymentClientBase_v1} and integrates with the Payment Processor to enable the distribution of rewards to stakers.

State Variables

stakingToken

address of the token that can be staked here.

address internal stakingToken;

totalSupply

total supply of the token that is staked here.

uint internal totalSupply;

rewardRate

rate of how many reward tokens are distributed from the fundingmanager to the whole staking pool in seconds.

uint internal rewardRate;

rewardsEnd

timestamp of when the reward period will end.

uint internal rewardsEnd;

rewardValue

internal value that is needed to calculate the reward each user will receive.

uint internal rewardValue;

lastUpdate

timestamp of when the rewardValue was last updated.

uint internal lastUpdate;

balances

mapping of balances of each user in the staking token address => balance.

mapping(address => uint) internal balances;

userRewardValues

mapping of reward Values that are needed to calculate the rewards that a user should receive.

should change everytime the user stakes or unstakes funds address => rewardValue.

mapping(address => uint) internal userRewardValues;

userRewards

mapping of how many reward tokens the user accumulated address => earned.

mapping(address => uint) internal userRewards;

__gap

Storage gap for future upgrades.

uint[50] private __gap;

Functions

supportsInterface

See {IERC165-supportsInterface}.

function supportsInterface(bytes4 interfaceId)
    public
    view
    virtual
    override(ERC20PaymentClientBase_v1)
    returns (bool);

validDuration

modifier to check if the duration is valid.

modifier validDuration(uint duration);

Parameters

Name	Type	Description
duration	uint256	duration of the reward period.

init

function init(
    IOrchestrator_v1 orchestrator_,
    Metadata memory metadata,
    bytes memory configData
) external virtual override(Module_v1) initializer;

__LM_PC_Staking_v1_init

Initializes the staking contract.

function __LM_PC_Staking_v1_init(address _stakingToken)
    internal
    onlyInitializing;

Parameters

Name	Type	Description
_stakingToken	address	The address of the token that can be staked.

getBalance

Returns the amount of tokens a user staked in this contract.

function getBalance(address user) external view returns (uint);

Parameters

Name	Type	Description
user	address	The address of a user that staked.

getEarned

Returns the amount of tokens earned up until now by the current stake of a user.

function getEarned(address user) external view returns (uint);

Parameters

Name	Type	Description
user	address	The address of a user that staked.

Returns

Name	Type	Description
<none>	uint256	The amount of tokens earned.

getEstimatedReward

Returns a estimation of how much rewards will be earned with the current state of the staking contract.

This calculation uses the current reward rate and the current totalSupply to calculate the rewards.

function getEstimatedReward(uint amount, uint duration)
    external
    view
    validAmount(amount)
    validDuration(duration)
    returns (uint);

Parameters

Name	Type	Description
amount	uint256	How much token are staked.
duration	uint256	How long the tokens will be staked.

Returns

Name	Type	Description
<none>	uint256	The estimated amount of tokens earned.

getStakingToken

Returns address of the token users can stake.

function getStakingToken() external view returns (address);

Returns

Name	Type	Description
<none>	address	The address of the token.

getTotalSupply

Returns the total supply of staked tokens of this contract.

function getTotalSupply() external view returns (uint);

Returns

Name	Type	Description
<none>	uint256	The total supply of staked tokens.

getRewardRate

Returns how much Tokens will be distributed per second to all users that staked in this contract.

function getRewardRate() external view returns (uint);

Returns

Name	Type	Description
<none>	uint256	The reward rate.

getRewardsEnd

Returns when the rewards will not be distributed anymore.

function getRewardsEnd() external view returns (uint);

Returns

Name	Type	Description
<none>	uint256	The timestamp of when the rewards will end.

getRewardValue

Returns the reward value.

function getRewardValue() external view returns (uint);

Returns

Name	Type	Description
<none>	uint256	The reward value.

getLastUpdate

Returns the timestamp of last state change.

function getLastUpdate() external view returns (uint);

Returns

Name	Type	Description
<none>	uint256	The timestamp of last state change.

stake

Stake a specified amount of tokens to earn rewards.

Should tokens already be staked, then the sending address will collect the rewards up until this point.

function stake(uint amount) external virtual nonReentrant validAmount(amount);

Parameters

Name	Type	Description
amount	uint256	How much token should be staked.

unstake

Unstake a specified amount of tokens and collect rewards.

this function will revert with a Over/Underflow error in case amount is higher than balance.

function unstake(uint amount)
    external
    virtual
    nonReentrant
    validAmount(amount);

Parameters

Name	Type	Description
amount	uint256	How much token should be unstaked.

claimRewards

Collects the rewards that are earned up until now.

Reaps the rewards collected up to this point for the msg.Sender().

function claimRewards() external virtual nonReentrant;

setRewards

Sets the rewards that are to be distributed.

Equally distributes the reward amount over the given time period.

function setRewards(uint amount, uint duration)
    external
    onlyOrchestratorAdmin;

Parameters

Name	Type	Description
amount	uint256	How much token should be distributed.
duration	uint256	How much time it will take to distribute the token.

_stake

Stakes tokens.

function _stake(address depositFor, uint amount) internal virtual;

Parameters

Name	Type	Description
depositFor	address	The address of the user.
amount	uint256	The amount of tokens to stake.

_update

Updates the reward value and the timestamp of the last update.

This has to trigger on every major change of the state of the contract.

function _update(address triggerAddress) internal;

Parameters

Name	Type	Description
triggerAddress	address	The address of the user.

_calculateRewardValue

Calculates the reward value.

This is the heart of the algorithm. The reward Value is the accumulation of all the rewards a user would get for a single token if they had staked at the beginning of the lifetime of this contract. A "single" reward value or with the lack of a better word "reward period" is the rewardRate (so the rewards per second for the whole contract) multiplied by the time period it was active and dividing that with the total multiplied by the time period it was active and dividing that with the total supply. This "single" value is essentially what a single token would have earned in that time period.

function _calculateRewardValue() internal view returns (uint);

Returns

Name	Type	Description
<none>	uint256	The reward value.

_getRewardDistributionTimestamp

Calculates the timestamp where rewards will be distributed.

The function returns either the current timestamp or the last timestamp where rewards will be distributed, based on which one is earlier. Is necessary to calculate the exact rewardValue at the end of the reward lifespan. If not included rewards would be distributed forever.

function _getRewardDistributionTimestamp() internal view returns (uint);

Returns

Name	Type	Description
<none>	uint256	The timestamp where rewards will be distributed.

_earned

Calculates how much a user earned for their stake up to this point.

internal function to calculate how much a user earned for their stake up to this point. Uses the difference between the current Reward Value and the reward value when the user staked their tokens in combination with their current balance to calculate their earnings.

function _earned(address user, uint providedRewardValue)
    internal
    view
    returns (uint);

Parameters

Name	Type	Description
user	address	The address of the user.
providedRewardValue	uint256	The reward value.

Returns

Name	Type	Description
<none>	uint256	The amount of tokens the user earned.

_distributeRewards

Distributes earned rewards via the payment processor.

direct distribution of earned rewards via the payment processor.

function _distributeRewards(address recipient) internal;

Parameters

Name	Type	Description
recipient	address	The address of the user.

_setRewards

Sets the rewards.

for contracts that inherit.

function _setRewards(uint amount, uint duration)
    internal
    validAmount(amount)
    validDuration(duration);

Parameters

Name	Type	Description
amount	uint256	The amount of tokens to distribute.
duration	uint256	The duration of the reward period.

_setStakingToken

Sets the staking token.

function _setStakingToken(address _token) internal;

Parameters

Name	Type	Description
_token	address	The address of the token that can be staked.

_ensureValidDuration

Ensures that the duration in seconds is larger than 0.

function _ensureValidDuration(uint duration) internal view;

Parameters

Name	Type	Description
duration	uint256	The duration of the reward period.