RewardController

Git Source

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;

MAX_BASIS_POINTS

100% in basis points

uint256 internal constant MAX_BASIS_POINTS = 10000;

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) public 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 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

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

Last updated