MaverickV2IncentiveMatcher

Inherits: IMaverickV2IncentiveMatcher, ReentrancyGuard, Multicall

IncentiveMatcher contract is deployed along with a ve token by the ve token factory. This contract allows protocols to provide matching incentives to Maverick BPs and allows ve holders to vote their token to increase the match in a BP. IncentiveMatcher has a concept of a matching epoch and the following actors:

• BP incentive adder

• Matching budget adder

• Voter

The lifecycle of an epoch is as follows:

• Anytime before or during an epoch, any party can permissionlessly add a matching and/or voting incentive budget to an epoch. These incentives will boost incentives added to any BPs during the epoch.

• During the epoch any party can permissionlessly add incentives to BPs. These incentives are eligible to be boosted through matching and voting.

• During the voting portion of the epoch, any ve holder can cast their ve vote for eligible BPs.

• At the end of the epoch, there is a vetoing period where any user who provided matching incentive budget can choose to veto a BP from being matched by their portion of the matching budget.

• At the end of the vetoing period, the matching rewards are elgible for distribution. Any user can permissionlessly call distribute for a given BP and epoch. This call will compute the matching boost for the BP and then send the BP reward contract the matching amount, which will in turn distribute the reward to the BP LPs.

State Variables

EPOCH_PERIOD

This function retrieves the epoch period length.

uint256 public constant EPOCH_PERIOD = 1 days;

PRE_VOTE_PERIOD

This function retrieves the period length of the epoch before voting starts. After an epoch begins, there is a window of time where voting is not possible which is the value this function returns.

uint256 public constant PRE_VOTE_PERIOD = 12 hours;

VETO_PERIOD

This function retrieves the vetoing period length.

uint256 public constant VETO_PERIOD = 5 hours;

NOTIFY_PERIOD

The function retrieves the notify period length, which is the amount of time in seconds during which the matching reward will be distributed through the rewards contract.

uint256 public constant NOTIFY_PERIOD = 14 days;

baseToken

This function retrieves the base token used by the IncentiveMatcher contract.

IERC20 public immutable baseToken;

factory

This function retrieves the address of the MaverickV2RewardFactory contract.

IMaverickV2RewardFactory public immutable factory;

veToken

This function retrieves the address of the veToken contract.

IMaverickV2VotingEscrow public immutable veToken;

hasVoted

This function checks if a specific user has voted in a particular epoch.

mapping(address user => mapping(uint256 epoch => bool)) public hasVoted;

hasDistributed

This function checks if incentives have been distributed for a specific reward contract in an epoch.

mapping(IMaverickV2Reward reward => mapping(uint256 epoch => bool)) public hasDistributed;

hasVetoed

This function checks if a specific matcher has cast a veto on a reward contract for an epoch.

mapping(address matcher => mapping(IMaverickV2Reward reward => mapping(uint256 epoch => bool))) public hasVetoed;

checkpoints

mapping(uint256 epoch => CheckpointData) private checkpoints;

Functions

constructor

constructor();

checkEpoch

Epoch Checkers and Helpers

modifier checkEpoch(uint256 epoch);

checkpointRewardData

This function retrieves checkpoint data for a specific reward contract within an epoch.

function checkpointRewardData(uint256 epoch, IMaverickV2Reward rewardContract)
    public
    view
    checkEpoch(epoch)
    returns (uint128 votesByReward, uint128 externalIncentivesByReward);

Parameters

Name	Type	Description
epoch	uint256	The epoch for which to retrieve checkpoint data.
rewardContract	IMaverickV2Reward	The address of the reward contract.

Returns

Name	Type	Description
votesByReward	uint128	The total number of votes cast for the reward contract in the epoch.
externalIncentivesByReward	uint128	The total amount of external incentives added for the reward contract in the epoch.

checkpointData

This function retrieves checkpoint data for a specific epoch.

function checkpointData(uint256 epoch)
    public
    view
    checkEpoch(epoch)
    returns (uint128 matchBudget, uint128 voteBudget, uint128 totalVote, uint128 totalExternalIncentivesAdded);

Parameters

Name	Type	Description
epoch	uint256	The epoch for which to retrieve checkpoint data.

Returns

Name	Type	Description
matchBudget	uint128	The amount of match tokens budgeted for the epoch.
voteBudget	uint128	The amount of vote tokens budgeted for the epoch.
totalVote	uint128	The total number of votes cast in the epoch.
totalExternalIncentivesAdded	uint128	The total amount of external incentives added for the epoch.

isEpoch

This function checks if a given epoch is valid.

function isEpoch(uint256 epoch) public pure returns (bool _isEpoch);

Parameters

Name	Type	Description
epoch	uint256	The epoch to check.

Returns

Name	Type	Description
_isEpoch	bool	True if the epoch input is a valid epoch, False otherwise.

epochIsOver

This function checks if a specific epoch has ended.

function epochIsOver(uint256 epoch) public view returns (bool isOver);

Parameters

Name	Type	Description
epoch	uint256	The epoch to check.

Returns

Name	Type	Description
isOver	bool	True if the epoch has ended, False otherwise.

vetoingIsActive

This function checks if the vetoing period is active for a specific epoch.

function vetoingIsActive(uint256 epoch) public view returns (bool isActive);

Parameters

Name	Type	Description
epoch	uint256	The epoch to check.

Returns

Name	Type	Description
isActive	bool	True if the vetoing period is active, False otherwise.

votingIsActive

This function checks if the voting period is active for a specific epoch.

function votingIsActive(uint256 epoch) public view returns (bool isActive);

Parameters

Name	Type	Description
epoch	uint256	The epoch to check.

Returns

Name	Type	Description
isActive	bool	True if the voting period is active, False otherwise.

vetoingIsOver

This function checks if the vetoing period is over for a specific epoch.

function vetoingIsOver(uint256 epoch) public view returns (bool isOver);

Parameters

Name	Type	Description
epoch	uint256	The epoch to check.

Returns

Name	Type	Description
isOver	bool	True if the vetoing period has ended for the given epoch, False otherwise.

votingStart

Returns the timestamp when voting starts. This is also the voting snapshot timestamp where the voting power for users is determined for that epoch.

function votingStart(uint256 epoch) public pure returns (uint256 start);

Parameters

Name	Type	Description
epoch	uint256	The epoch to check.

epochEnd

This function calculates the end timestamp for a specific epoch.

function epochEnd(uint256 epoch) public pure returns (uint256 end);

Parameters

Name	Type	Description
epoch	uint256	The epoch for which to calculate the end timestamp.

Returns

Name	Type	Description
end	uint256	The end timestamp of the epoch.

vetoingEnd

This function calculates the end timestamp for the vetoing period of a specific epoch.

function vetoingEnd(uint256 epoch) public pure returns (uint256 end);

Parameters

Name	Type	Description
epoch	uint256	The epoch for which to calculate the vetoing period end timestamp.

Returns

Name	Type	Description
end	uint256	The end timestamp of the vetoing period for the epoch.

currentEpoch

This function retrieves the current epoch number.

function currentEpoch() public view returns (uint256 epoch);

Returns

Name	Type	Description
epoch	uint256	The current epoch number.

lastEpoch

This function retrieves the number of the most recently completed epoch.

function lastEpoch() public view returns (uint256 epoch);

Returns

Name	Type	Description
epoch	uint256	The number of the last epoch.

rewardHasVe

This function checks if a specific reward contract has a veToken staking option.

function rewardHasVe(IMaverickV2Reward rewardContract) public view returns (bool);

Parameters

Name	Type	Description
rewardContract	IMaverickV2Reward	The address of the reward contract.

Returns

Name	Type	Description
<none>	bool	hasVe True if the reward contract has a veToken staking option, False otherwise.

_addBudget

User Actions

function _addBudget(uint128 matchBudget, uint128 voteBudget, uint256 epoch) private;

addMatchingBudget

This function allows adding a new budget to the matcher contract.

function addMatchingBudget(uint128 matchBudget, uint128 voteBudget, uint256 epoch)
    public
    checkEpoch(epoch)
    nonReentrant;

Parameters

Name	Type	Description
matchBudget	uint128	The amount of match tokens to add.
voteBudget	uint128	The amount of vote tokens to add.
epoch	uint256	The epoch for which the budget is added.

addIncentives

This function allows adding a new incentive to the system.

function addIncentives(IMaverickV2Reward rewardContract, uint256 amount, uint256 _duration)
    public
    nonReentrant
    returns (uint256 duration);

Parameters

Name	Type	Description
rewardContract	IMaverickV2Reward	The address of the reward contract for the incentive.
amount	uint256	The total amount of the incentive.
_duration	uint256	The duration (in epochs) for which this incentive will be active.

Returns

Name	Type	Description
duration	uint256	The duration (in epochs) for which this incentive was added.

_inVetoPeriodCheck

function _inVetoPeriodCheck(uint256 epoch) internal view;

_inVotePeriodCheck

function _inVotePeriodCheck(uint256 epoch) internal view;

vote

This function allows a user to cast a vote for specific reward contracts.

function vote(IMaverickV2Reward[] memory voteTargets, uint256[] memory weights) external nonReentrant;

Parameters

Name	Type	Description
voteTargets	IMaverickV2Reward[]	An array of addresses for the reward contracts to vote for.
weights	uint256[]	An array of weights for each vote target.

veto

This function allows casting a veto on a specific reward contract for an epoch.

function veto(IMaverickV2Reward rewardContract) public returns (uint128 vetoPower);

Parameters

Name	Type	Description
rewardContract	IMaverickV2Reward	The address of the reward contract to veto.

Returns

Name	Type	Description
vetoPower	uint128	The amount of veto power used (based on the user's epoch match contribution).

_checkVetoPeriodEnded

function _checkVetoPeriodEnded(uint256 epoch) internal view;

distribute

This function allows distributing incentives for a specific reward contract in a particular epoch.

function distribute(IMaverickV2Reward rewardContract, uint256 epoch)
    public
    checkEpoch(epoch)
    nonReentrant
    returns (uint256 matchAmount);

Parameters

Name	Type	Description
rewardContract	IMaverickV2Reward	The address of the reward contract to distribute incentives for.
epoch	uint256	The epoch for which to distribute incentives.

Returns

Name	Type	Description
matchAmount	uint256	The amount of matching tokens distributed.

rolloverExcessBudget

This function allows rolling over excess budget from a previous epoch to a new epoch.

Excess vote match budget amounts that have not been distributed will not rollover and will become permanently locked. To avoid this, a matcher should call distribute on all rewards contracts before calling rollover.

function rolloverExcessBudget(uint256 matchedEpoch, uint256 newEpoch)
    public
    checkEpoch(matchedEpoch)
    checkEpoch(newEpoch)
    returns (uint256 matchRolloverAmount, uint256 voteRolloverAmount);

Parameters

Name	Type	Description
matchedEpoch	uint256	The epoch from which to roll over the budget.
newEpoch	uint256	The epoch to which to roll over the budget.

Returns

Name	Type	Description
matchRolloverAmount	uint256	The amount of match tokens rolled over.
voteRolloverAmount	uint256	The amount of vote tokens rolled over.

Structs

MatchPair

struct MatchPair {
    uint128 matchBudget;
    uint128 voteBudget;
}

CheckpointData

struct CheckpointData {
    uint128 matchBudget;
    uint128 voteBudget;
    uint128 totalVote;
    uint128 totalExternalIncentivesAdded;
    uint128 voteRollover;
    mapping(IMaverickV2Reward => uint128) votesByReward;
    mapping(IMaverickV2Reward => uint128) externalIncentivesByReward;
    mapping(address => MatchPair) matcherAmounts;
}