IMaverickV2IncentiveMatcher

Functions

checkpointData

This function retrieves checkpoint data for a specific epoch.

function checkpointData(uint256 epoch)
    external
    view
    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.

checkpointRewardData

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

function checkpointRewardData(uint256 epoch, IMaverickV2Reward rewardContract)
    external
    view
    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.

isEpoch

This function checks if a given epoch is valid.

function isEpoch(uint256 epoch) external 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.

lastEpoch

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

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

Returns

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

epochIsOver

This function checks if a specific epoch has ended.

function epochIsOver(uint256 epoch) external 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) external 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) external 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.

currentEpoch

This function retrieves the current epoch number.

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

Returns

Name	Type	Description
epoch	uint256	The current epoch number.

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) external pure returns (uint256 start);

Parameters

Name	Type	Description
epoch	uint256	The epoch to check.

addMatchingBudget

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

called by protocol to add base token budget to an epoch that will be used for matching incentives. Can be called anytime before or during the epoch.

function addMatchingBudget(uint128 matchBudget, uint128 voteBudget, uint256 epoch) external;

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.

rewardHasVe

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

For a rewards contract to be eligible for matching, the rewards contract must have the baseToken's ve contract as a locking option.

function rewardHasVe(IMaverickV2Reward rewardContract) external view returns (bool hasVe);

Parameters

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

Returns

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

addIncentives

This function allows adding a new incentive to the system.

Called by protocol to add incentives to a given rewards contract.

function addIncentives(IMaverickV2Reward rewardContract, uint256 amount, uint256 _duration)
    external
    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.

vote

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

Called by ve token holders to vote for rewards contracts in a given epoch. voteTargets have to be passed in ascending sort order as a unique set of values. weights are relative values that are scales by the user's voting power.

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

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.

Veto a given rewards contract. If a rewards contract is vetoed, it will not receive any matching incentives. Rewards contracts can only be vetoed in the VETO_PERIOD seconds after the end of the epoch.

function veto(IMaverickV2Reward rewardContract) external 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).

distribute

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

Called by any user to distribute matching incentives to a given reward contract for a given epoch. Call is only functional after the vetoing period for the epoch is over.

function distribute(IMaverickV2Reward rewardContract, uint256 epoch) external 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)
    external
    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.

EPOCH_PERIOD

This function retrieves the epoch period length.

function EPOCH_PERIOD() external returns (uint256);

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.

function PRE_VOTE_PERIOD() external returns (uint256);

VETO_PERIOD

This function retrieves the vetoing period length.

function VETO_PERIOD() external returns (uint256);

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.

function NOTIFY_PERIOD() external returns (uint256);

baseToken

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

function baseToken() external returns (IERC20);

Returns

Name	Type	Description
<none>	IERC20	The address of the base token.

factory

This function retrieves the address of the MaverickV2RewardFactory contract.

function factory() external returns (IMaverickV2RewardFactory);

Returns

Name	Type	Description
<none>	IMaverickV2RewardFactory	The address of the MaverickV2RewardFactory contract.

veToken

This function retrieves the address of the veToken contract.

function veToken() external returns (IMaverickV2VotingEscrow);

Returns

Name	Type	Description
<none>	IMaverickV2VotingEscrow	The address of the veToken contract.

hasVoted

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

function hasVoted(address user, uint256 epoch) external returns (bool);

Parameters

Name	Type	Description
user	address	The address of the user.
epoch	uint256	The epoch to check.

Returns

Name	Type	Description
<none>	bool	True if the user has voted, False otherwise.

hasVetoed

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

function hasVetoed(address matcher, IMaverickV2Reward rewardContract, uint256 epoch) external returns (bool);

Parameters

Name	Type	Description
matcher	address	The address of the IncentiveMatcher contract.
rewardContract	IMaverickV2Reward	The address of the reward contract.
epoch	uint256	The epoch to check.

Returns

Name	Type	Description
<none>	bool	True if the matcher has cast a veto, False otherwise.

hasDistributed

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

function hasDistributed(IMaverickV2Reward rewardContract, uint256 epoch) external returns (bool);

Parameters

Name	Type	Description
rewardContract	IMaverickV2Reward	The address of the reward contract.
epoch	uint256	The epoch to check.

Returns

Name	Type	Description
<none>	bool	True if incentives have been distributed, False otherwise.

epochEnd

This function calculates the end timestamp for a specific epoch.

function epochEnd(uint256 epoch) external 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) external 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.

vetoingIsOver

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

function vetoingIsOver(uint256 epoch) external 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.

Events

BudgetAdded

event BudgetAdded(address matcher, uint256 matchRolloverAmount, uint256 voteRolloverAmount, uint256 epoch);

BudgetRolledOver

event BudgetRolledOver(
    address matcher, uint256 matchRolloverAmount, uint256 voteRolloverAmount, uint256 matchedEpoch, uint256 newEpoch
);

IncentiveAdded

event IncentiveAdded(uint256 amount, uint256 epoch, IMaverickV2Reward rewardContract, uint256 duration);

Vote

event Vote(address voter, uint256 epoch, IMaverickV2Reward rewardContract, uint256 vote);

Distribute

event Distribute(uint256 epoch, IMaverickV2Reward rewardContract, IERC20 _baseToken, uint256 matchAmount);

Veto

event Veto(address matcher, uint256 epoch, IMaverickV2Reward rewardContract, uint256 amount, uint256 vetoPower);

Errors

IncentiveMatcherInvalidEpoch

error IncentiveMatcherInvalidEpoch(uint256 epoch);

IncentiveMatcherNotRewardFactoryContract

error IncentiveMatcherNotRewardFactoryContract(IMaverickV2Reward rewardContract);

IncentiveMatcherEpochHasNotEnded

error IncentiveMatcherEpochHasNotEnded(uint256 currentTime, uint256 epochEnd);

IncentiveMatcherVotePeriodNotActive

error IncentiveMatcherVotePeriodNotActive(uint256 currentTime, uint256 voteStart, uint256 voteEnd);

IncentiveMatcherVetoPeriodNotActive

error IncentiveMatcherVetoPeriodNotActive(uint256 currentTime, uint256 vetoStart, uint256 vetoEnd);

IncentiveMatcherVetoPeriodHasNotEnded

error IncentiveMatcherVetoPeriodHasNotEnded(uint256 currentTime, uint256 voteEnd);

IncentiveMatcherSenderHasAlreadyVoted

error IncentiveMatcherSenderHasAlreadyVoted();

IncentiveMatcherSenderHasNoVotingPower

error IncentiveMatcherSenderHasNoVotingPower(address voter, uint256 voteSnapshotTimestamp);

IncentiveMatcherInvalidTargetOrder

error IncentiveMatcherInvalidTargetOrder(IMaverickV2Reward lastReward, IMaverickV2Reward voteReward);

IncentiveMatcherInvalidVote

error IncentiveMatcherInvalidVote(
    IMaverickV2Reward rewardContract, uint256 voteWeights, uint256 totalVoteWeight, uint256 vote
);

IncentiveMatcherNoExternalIncentivesToDistributed

error IncentiveMatcherNoExternalIncentivesToDistributed(IMaverickV2Reward rewardContract, uint256 epoch);

IncentiveMatcherEpochAlreadyDistributed

error IncentiveMatcherEpochAlreadyDistributed(uint256 epoch, IMaverickV2Reward rewardContract);

IncentiveMatcherEpochHasPassed

error IncentiveMatcherEpochHasPassed(uint256 epoch);

IncentiveMatcherRewardDoesNotHaveVeStakingOption

error IncentiveMatcherRewardDoesNotHaveVeStakingOption();

IncentiveMatcherMatcherAlreadyVetoed

error IncentiveMatcherMatcherAlreadyVetoed(address matcher, IMaverickV2Reward rewardContract, uint256 epoch);

IncentiveMatcherNothingToRollover

error IncentiveMatcherNothingToRollover(address matcher, uint256 matchedEpoch);