RewardDistributor
Inherits: IRewardDistributor, RewardController
Author: webthethird
Abstract contract responsible for accruing and distributing rewards to users for providing liquidity to perpetual markets (handled by PerpRewardDistributor) or staking tokens (with the SafetyModule)
Inherits from RewardController, which defines the RewardInfo data structure and functions allowing governance to add/remove reward tokens or update their parameters, and implements IRewardContract, the interface used by the ClearingHouse to update user rewards any time a user's position is updated
State Variables
ecosystemReserve
Address of the reward token vault
_rewardsAccruedByUser
Rewards accrued and not yet claimed by user
First address is user, second is reward token
_totalUnclaimedRewards
Total rewards accrued and not claimed by all users
Address is reward token
_lpPositionsPerUser
Latest LP/staking positions per user and market
First address is user, second is the market
_cumulativeRewardPerLpToken
Reward accumulator for market rewards per reward token, as a number of reward tokens per LP/staked token
First address is reward token, second is the market
_cumulativeRewardPerLpTokenPerUser
Reward accumulator value per reward token when user rewards were last updated
First address is user, second is reward token, third is the market
_timeOfLastCumRewardUpdate
Timestamp of the most recent update to the per-market reward accumulator
_totalLiquidityPerMarket
Total LP/staked tokens registered for rewards per market
Functions
constructor
RewardDistributor constructor
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the EcosystemReserve contract, which holds the reward tokens |
rewardsAccruedByUser
Rewards accrued and not yet claimed by user
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the user |
|
| Address of the reward token |
Returns
Name | Type | Description |
---|---|---|
|
| Rewards accrued and not yet claimed by user |
totalUnclaimedRewards
Total rewards accrued and not claimed by all users
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the reward token |
Returns
Name | Type | Description |
---|---|---|
|
| Total rewards accrued and not claimed by all users |
lpPositionsPerUser
Latest LP/staking positions per user and market
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the user |
|
| Address of the market |
Returns
Name | Type | Description |
---|---|---|
|
| Stored position of the user in the market |
cumulativeRewardPerLpToken
Reward accumulator for market rewards per reward token, as a number of reward tokens per LP/staked token
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the reward token |
|
| Address of the market |
Returns
Name | Type | Description |
---|---|---|
|
| Number of reward tokens per LP/staking token |
cumulativeRewardPerLpTokenPerUser
Reward accumulator value per reward token when user rewards were last updated
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the user |
|
| Address of the reward token |
|
| Address of the market |
Returns
Name | Type | Description |
---|---|---|
|
| Number of reward tokens per Led token when user rewards were last updated |
timeOfLastCumRewardUpdate
Gets the timestamp of the most recent update to the per-market reward accumulator
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the market |
Returns
Name | Type | Description |
---|---|---|
|
| Timestamp of the most recent update to the per-market reward accumulator |
totalLiquidityPerMarket
Total LP/staked tokens registered for rewards per market
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the market |
Returns
Name | Type | Description |
---|---|---|
|
| Stored total number of tokens per market |
addRewardToken
Adds a new reward token
Can only be called by governance
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the reward token |
|
| Initial inflation rate for the new token |
|
| Initial reduction factor for the new token |
|
| Addresses of the markets to reward with the new token |
|
| Initial weights per market for the new token |
removeRewardToken
Removes a reward token from all markets for which it is registered
Can only be called by governance
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the reward token to remove |
registerPositions
Fetches and stores the caller's LP/stake positions and updates the total liquidity in each of the provided markets
Can only be called once per user, only necessary if user was an LP prior to this contract's deployment
Parameters
Name | Type | Description |
---|---|---|
|
| Addresses of the markets to sync with |
claimRewards
Accrues and then distributes rewards for all markets and reward tokens and returns the amount of rewards that were not distributed to the user
claimRewards
Accrues and then distributes rewards for all markets and reward tokens and returns the amount of rewards that were not distributed to the user
Non-reentrant because _distributeReward
transfers reward tokens to the user
_updateMarketRewards
Updates the reward accumulators for a given market
Executes when any of the following values are changed:
initial inflation rate per token,
reduction factor per token,
reward weights per market per token,
liquidity in the market
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the market |
_accrueRewards
Accrues rewards to a user for a given market
Assumes user's position hasn't changed since last accrual, since updating rewards due to changes in position is handled by updatePosition
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the market to accrue rewards for |
|
| Address of the user |
_distributeReward
Distributes accrued rewards from the ecosystem reserve to a user for a given reward token
Checks if there are enough rewards remaining in the ecosystem reserve to distribute, updates totalUnclaimedRewards
, and returns the amount of rewards that were not distributed
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the reward token |
|
| Address of the user to distribute rewards to |
|
| Amount of rewards to distribute |
Returns
Name | Type | Description |
---|---|---|
|
| Amount of rewards that were not distributed |
_rewardTokenBalance
Gets the current balance of a reward token in the ecosystem reserve
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the reward token |
Returns
Name | Type | Description |
---|---|---|
|
| Balance of the reward token in the ecosystem reserve |
_registerPosition
Registers a user's pre-existing position for a given market
User should have a position predating this contract's deployment, which can only be registered once
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the user to register |
|
| Address of the market for which to register the user's position |
_getNumMarkets
Gets the number of markets to be used for reward distribution
Markets are the perpetual markets (for the PerpRewardDistributor) or staked tokens (for the SafetyModule)
Returns
Name | Type | Description |
---|---|---|
|
| Number of markets |
_getMarketAddress
Gets the address of a market at a given index
Markets are the perpetual markets (for the PerpRewardDistributor) or staked tokens (for the SafetyModule)
Parameters
Name | Type | Description |
---|---|---|
|
| Index of the market |
Returns
Name | Type | Description |
---|---|---|
|
| Address of the market |
_getMarketIdx
Gets the index of an allowlisted market
Markets are the perpetual markets (for the PerpRewardDistributor) or staked tokens (for the SafetyModule)
Parameters
Name | Type | Description |
---|---|---|
|
| Index of the market in the allowlist |
Returns
Name | Type | Description |
---|---|---|
|
| Index of the market in the market list |
_getCurrentPosition
Returns the current position of the user in the market (i.e., perpetual market or staked token)
Parameters
Name | Type | Description |
---|---|---|
|
| Address of the user |
|
| Address of the market |
Returns
Name | Type | Description |
---|---|---|
|
| Current position of the user in the market |
Last updated