RewardController

Inherits: IRewardController, IncreAccessControl, Pausable, ReentrancyGuard

Author: webthethird

Base contract for storing and updating reward info for multiple reward tokens, each with

• a gradually decreasing emission rate, based on an initial inflation rate, reduction factor, and time elapsed

• a list of markets for which the reward token is distributed

• a list of weights representing the percentage of rewards that go to each market

State Variables

MAX_INFLATION_RATE

Maximum inflation rate, applies to all reward tokens

uint256 internal constant MAX_INFLATION_RATE = 5e24;

MIN_REDUCTION_FACTOR

Minimum reduction factor, applies to all reward tokens

uint256 internal constant MIN_REDUCTION_FACTOR = 1e18;

MAX_REWARD_TOKENS

Maximum number of reward tokens allowed

uint256 internal constant MAX_REWARD_TOKENS = 10;

rewardTokens

List of reward token addresses

Length must be <= MAX_REWARD_TOKENS

address[] public rewardTokens;

_rewardInfoByToken

Info for each registered reward token

mapping(address => RewardInfo) internal _rewardInfoByToken;

_marketWeightsByToken

Mapping from reward token to reward weights for each market

Market reward weights are basis points, i.e., 100 = 1%, 10000 = 100%

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

Functions

getMaxInflationRate

Gets the maximum allowed inflation rate for a reward token

function getMaxInflationRate() external pure returns (uint256);

Returns

Name	Type	Description
<none>	uint256	Maximum allowed inflation rate

getMinReductionFactor

Gets the minimum allowed reduction factor for a reward token

function getMinReductionFactor() external pure returns (uint256);

Returns

Name	Type	Description
<none>	uint256	Minimum allowed reduction factor

getMaxRewardTokens

Gets the maximum allowed number of reward tokens

function getMaxRewardTokens() external pure returns (uint256);

Returns

Name	Type	Description
<none>	uint256	Maximum allowed number of reward tokens

getRewardTokens

Returns the full list of reward tokens

function getRewardTokens() external view returns (address[] memory);

Returns

Name	Type	Description
<none>	address[]	Array of reward token addresses

getRewardTokenCount

Gets the number of reward tokens

function getRewardTokenCount() external view returns (uint256);

Returns

Name	Type	Description
<none>	uint256	Number of reward tokens

getInitialTimestamp

Gets the timestamp when a reward token was registered

function getInitialTimestamp(address rewardToken) external view returns (uint256);

Parameters

Name	Type	Description
rewardToken	address	Address of the reward token

Returns

Name	Type	Description
<none>	uint256	Timestamp when the reward token was registered

getInitialInflationRate

Gets the inflation rate of a reward token (w/o factoring in reduction factor)

function getInitialInflationRate(address rewardToken) external view returns (uint256);

Parameters

Name	Type	Description
rewardToken	address	Address of the reward token

Returns

Name	Type	Description
<none>	uint256	Initial inflation rate of the reward token

getInflationRate

Gets the current inflation rate of a reward token (factoring in reduction factor)

inflationRate = initialInflationRate / reductionFactor^((block.timestamp - initialTimestamp) / secondsPerYear)

function getInflationRate(address rewardToken) external view returns (uint256);

Parameters

Name	Type	Description
rewardToken	address	Address of the reward token

Returns

Name	Type	Description
<none>	uint256	Current inflation rate of the reward token

getReductionFactor

Gets the reduction factor of a reward token

function getReductionFactor(address rewardToken) external view returns (uint256);

Parameters

Name	Type	Description
rewardToken	address	Address of the reward token

Returns

Name	Type	Description
<none>	uint256	Reduction factor of the reward token

getRewardWeight

Gets the reward weight of a given market for a reward token

function getRewardWeight(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	The reward weight of the market in basis points

getRewardMarkets

Gets the list of all markets receiving a given reward token

function getRewardMarkets(address rewardToken) external view returns (address[] memory);

Parameters

Name	Type	Description
rewardToken	address	Address of the reward token

Returns

Name	Type	Description
<none>	address[]	Array of market addresses

isTokenPaused

Gets whether a reward token is paused

function isTokenPaused(address rewardToken) external view returns (bool);

Parameters

Name	Type	Description
rewardToken	address	Address of the reward token

Returns

Name	Type	Description
<none>	bool	True if the reward token is paused, false otherwise

updateRewardWeights

Sets the market addresses and reward weights for a reward token

Only callable by Governance

function updateRewardWeights(address rewardToken, address[] calldata markets, uint256[] calldata weights)
    external
    onlyRole(GOVERNANCE);

Parameters

Name	Type	Description
rewardToken	address	Address of the reward token
markets	address[]	List of market addresses to receive rewards
weights	uint256[]	List of weights for each market

updateInitialInflationRate

Sets the initial inflation rate used to calculate emissions over time for a given reward token

Only callable by Governance

function updateInitialInflationRate(address rewardToken, uint88 newInitialInflationRate)
    external
    onlyRole(GOVERNANCE);

Parameters

Name	Type	Description
rewardToken	address	Address of the reward token
newInitialInflationRate	uint88	The new inflation rate in tokens/year, scaled by 1e18

updateReductionFactor

Sets the reduction factor used to reduce emissions over time for a given reward token

Only callable by Governance

function updateReductionFactor(address rewardToken, uint88 newReductionFactor) external onlyRole(GOVERNANCE);

Parameters

Name	Type	Description
rewardToken	address	Address of the reward token
newReductionFactor	uint88	The new reduction factor, scaled by 1e18

pause

Pause the contract

Can only be called by Emergency Admin

function pause() external virtual override onlyRole(EMERGENCY_ADMIN);

unpause

Unpause the contract

Can only be called by Emergency Admin

function unpause() external virtual override onlyRole(EMERGENCY_ADMIN);

togglePausedReward

Pauses/unpauses the reward accrual for a particular reward token

Only callable by Emergency Admin

function togglePausedReward(address _rewardToken) external virtual onlyRole(EMERGENCY_ADMIN);

Parameters

Name	Type	Description
_rewardToken	address	Address of the reward token

_togglePausedReward

Pauses/unpauses the reward accrual for a particular reward token

Does not pause gradual reduction of inflation rate over time due to reduction factor

function _togglePausedReward(address _rewardToken) internal;

Parameters

Name	Type	Description
_rewardToken	address	Address of the reward token

_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 virtual;

Parameters

Name	Type	Description
market	address	Address of the market

_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 returns (uint256);

Returns

Name	Type	Description
<none>	uint256	Number of markets

_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 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

_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 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 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

Structs

RewardInfo

Data structure containing essential info for each reward token

struct RewardInfo {
    IERC20Metadata token;
    bool paused;
    uint80 initialTimestamp;
    uint88 initialInflationRate;
    uint88 reductionFactor;
    address[] marketAddresses;
}

Properties

Name	Type	Description
token	IERC20Metadata	Address of the reward token
paused	bool	Whether the reward token accrual is paused
initialTimestamp	uint80	Time when the reward token was added
initialInflationRate	uint88	Initial rate of reward token emission per year
reductionFactor	uint88	Factor by which the inflation rate is reduced each year
marketAddresses	address[]	List of markets for which the reward token is distributed