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

address public immutable ecosystemReserve;

_rewardsAccruedByUser

Rewards accrued and not yet claimed by user

First address is user, second is reward token

mapping(address => mapping(address => uint256)) internal _rewardsAccruedByUser;

_totalUnclaimedRewards

Total rewards accrued and not claimed by all users

Address is reward token

mapping(address => uint256) internal _totalUnclaimedRewards;

_lpPositionsPerUser

Latest LP/staking positions per user and market

First address is user, second is the market

mapping(address => mapping(address => uint256)) internal _lpPositionsPerUser;

_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

mapping(address => mapping(address => uint256)) internal _cumulativeRewardPerLpToken;

_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

mapping(address => mapping(address => mapping(address => uint256))) internal _cumulativeRewardPerLpTokenPerUser;

_timeOfLastCumRewardUpdate

Timestamp of the most recent update to the per-market reward accumulator

mapping(address => uint256) internal _timeOfLastCumRewardUpdate;

_totalLiquidityPerMarket

Total LP/staked tokens registered for rewards per market

mapping(address => uint256) internal _totalLiquidityPerMarket;

Functions

constructor

RewardDistributor constructor

constructor(address _ecosystemReserve) payable;

Parameters

Name	Type	Description
_ecosystemReserve	address	Address of the EcosystemReserve contract, which holds the reward tokens

rewardsAccruedByUser

Rewards accrued and not yet claimed by user

function rewardsAccruedByUser(address _user, address _rewardToken) external view returns (uint256);

Parameters

Name	Type	Description
_user	address	Address of the user
_rewardToken	address	Address of the reward token

Returns

Name	Type	Description
<none>	uint256	Rewards accrued and not yet claimed by user

totalUnclaimedRewards

Total rewards accrued and not claimed by all users

function totalUnclaimedRewards(address _rewardToken) external view returns (uint256);

Parameters

Name	Type	Description
_rewardToken	address	Address of the reward token

Returns

Name	Type	Description
<none>	uint256	Total rewards accrued and not claimed by all users

lpPositionsPerUser

Latest LP/staking positions per user and market

function lpPositionsPerUser(address _user, address _market) external view returns (uint256);

Parameters

Name	Type	Description
_user	address	Address of the user
_market	address	Address of the market

Returns

Name	Type	Description
<none>	uint256	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

function cumulativeRewardPerLpToken(address _rewardToken, address _market) external view returns (uint256);

Parameters

Name	Type	Description
_rewardToken	address	Address of the reward token
_market	address	Address of the market

Returns

Name	Type	Description
<none>	uint256	Number of reward tokens per LP/staking token

cumulativeRewardPerLpTokenPerUser

Reward accumulator value per reward token when user rewards were last updated

function cumulativeRewardPerLpTokenPerUser(address _user, address _rewardToken, address _market)
    external
    view
    returns (uint256);

Parameters

Name	Type	Description
_user	address	Address of the user
_rewardToken	address	Address of the reward token
_market	address	Address of the market

Returns

Name	Type	Description
<none>	uint256	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

function timeOfLastCumRewardUpdate(address _market) external view returns (uint256);

Parameters

Name	Type	Description
_market	address	Address of the market

Returns

Name	Type	Description
<none>	uint256	Timestamp of the most recent update to the per-market reward accumulator

totalLiquidityPerMarket

Total LP/staked tokens registered for rewards per market

function totalLiquidityPerMarket(address _market) external view returns (uint256);

Parameters

Name	Type	Description
_market	address	Address of the market

Returns

Name	Type	Description
<none>	uint256	Stored total number of tokens per market

initMarketStartTime

Sets the start time for accruing rewards to a market which has not been initialized yet

Can only be called by governance

function initMarketStartTime(address _market) external virtual onlyRole(GOVERNANCE);

Parameters

Name	Type	Description
_market	address	Address of the market (i.e., perpetual market or staking token)

addRewardToken

Adds a new reward token

Can only be called by governance

function addRewardToken(
    address _rewardToken,
    uint88 _initialInflationRate,
    uint88 _initialReductionFactor,
    address[] calldata _markets,
    uint256[] calldata _marketWeights
) external onlyRole(GOVERNANCE);

Parameters

Name	Type	Description
_rewardToken	address	Address of the reward token
_initialInflationRate	uint88	Initial inflation rate for the new token
_initialReductionFactor	uint88	Initial reduction factor for the new token
_markets	address[]	Addresses of the markets to reward with the new token
_marketWeights	uint256[]	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

function removeRewardToken(address _rewardToken) external onlyRole(GOVERNANCE);

Parameters

Name	Type	Description
_rewardToken	address	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

function registerPositions(address[] calldata _markets) external;

Parameters

Name	Type	Description
_markets	address[]	Addresses of the markets to sync with

claimRewardsFor

Accrues and then distributes rewards for all markets and reward tokens and returns the amount of rewards that were not distributed to the given user

function claimRewardsFor(address _user) public override;

Parameters

Name	Type	Description
_user	address	Address of the user to claim rewards for

claimRewardsFor

Accrues and then distributes rewards for all markets and reward tokens and returns the amount of rewards that were not distributed to the given user

function claimRewardsFor(address _user, address[] memory _rewardTokens) public override nonReentrant whenNotPaused;

Parameters

Name	Type	Description
_user	address	Address of the user to claim rewards for
_rewardTokens	address[]	Addresses of the reward tokens to claim rewards for

_updateMarketRewards

Updates the reward accumulator for a given market

Executes when any of the following variables are changed: inflationRate, marketWeights, liquidity

function _updateMarketRewards(address market) internal override;

Parameters

Name	Type	Description
market	address	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

function _accrueRewards(address market, address user) internal virtual;

Parameters

Name	Type	Description
market	address	Address of the market to accrue rewards for
user	address	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

function _distributeReward(address _token, address _to, uint256 _amount) internal returns (uint256);

Parameters

Name	Type	Description
_token	address	Address of the reward token
_to	address	Address of the user to distribute rewards to
_amount	uint256	Amount of rewards to distribute

Returns

Name	Type	Description
<none>	uint256	Amount of rewards that were not distributed

_rewardTokenBalance

Gets the current balance of a reward token in the ecosystem reserve

function _rewardTokenBalance(address _token) internal view returns (uint256);

Parameters

Name	Type	Description
_token	address	Address of the reward token

Returns

Name	Type	Description
<none>	uint256	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

function _registerPosition(address _user, address _market) internal virtual;

Parameters

Name	Type	Description
_user	address	Address of the user to register
_market	address	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)

function _getNumMarkets() internal view virtual override returns (uint256);

Returns

Name	Type	Description
<none>	uint256	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)

function _getMarketAddress(uint256 idx) internal view virtual override returns (address);

Parameters

Name	Type	Description
idx	uint256	Index of the market

Returns

Name	Type	Description
<none>	address	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)

function _getMarketIdx(uint256 i) internal view virtual override returns (uint256);

Parameters

Name	Type	Description
i	uint256	Index of the market in the allowlist ClearingHouse.ids (for the PerpRewardDistributor) or stakingTokens (for the SafetyModule)

Returns

Name	Type	Description
<none>	uint256	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)

function _getCurrentPosition(address user, address market) internal view virtual override returns (uint256);

Parameters

Name	Type	Description
user	address	Address of the user
market	address	Address of the market

Returns

Name	Type	Description
<none>	uint256	Current position of the user in the market