# MaverickV2IncentiveMatcher

**Inherits:** [IMaverickV2IncentiveMatcher](/technical-reference/maverick-v2/v2-contracts/maverick-v2-reward-contracts/interfaces/imaverickv2incentivematcher.md), ReentrancyGuard, [Multicall](/technical-reference/maverick-v2/v2-contracts/maverick-v2-common-contracts/base/multicall.md)

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 <a href="#state-variables" id="state-variables"></a>

#### EPOCH\_PERIOD <a href="#epoch_period" id="epoch_period"></a>

This function retrieves the epoch period length.

```solidity
uint256 public constant EPOCH_PERIOD = 1 days;
```

#### PRE\_VOTE\_PERIOD <a href="#pre_vote_period" id="pre_vote_period"></a>

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.

```solidity
uint256 public constant PRE_VOTE_PERIOD = 12 hours;
```

#### VETO\_PERIOD <a href="#veto_period" id="veto_period"></a>

This function retrieves the vetoing period length.

```solidity
uint256 public constant VETO_PERIOD = 5 hours;
```

#### NOTIFY\_PERIOD <a href="#notify_period" id="notify_period"></a>

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.

```solidity
uint256 public constant NOTIFY_PERIOD = 14 days;
```

#### baseToken <a href="#basetoken" id="basetoken"></a>

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

```solidity
IERC20 public immutable baseToken;
```

#### factory <a href="#factory" id="factory"></a>

This function retrieves the address of the MaverickV2RewardFactory contract.

```solidity
IMaverickV2RewardFactory public immutable factory;
```

#### veToken <a href="#vetoken" id="vetoken"></a>

This function retrieves the address of the veToken contract.

```solidity
IMaverickV2VotingEscrow public immutable veToken;
```

#### hasVoted <a href="#hasvoted" id="hasvoted"></a>

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

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

#### hasDistributed <a href="#hasdistributed" id="hasdistributed"></a>

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

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

#### hasVetoed <a href="#hasvetoed" id="hasvetoed"></a>

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

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

#### checkpoints <a href="#checkpoints" id="checkpoints"></a>

```solidity
mapping(uint256 epoch => CheckpointData) private checkpoints;
```

### Functions <a href="#functions" id="functions"></a>

#### constructor <a href="#constructor" id="constructor"></a>

```solidity
constructor();
```

#### checkEpoch <a href="#checkepoch" id="checkepoch"></a>

Epoch Checkers and Helpers

```solidity
modifier checkEpoch(uint256 epoch);
```

#### checkpointRewardData <a href="#checkpointrewarddata" id="checkpointrewarddata"></a>

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

```solidity
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 <a href="#checkpointdata" id="checkpointdata"></a>

This function retrieves checkpoint data for a specific epoch.

```solidity
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 <a href="#isepoch" id="isepoch"></a>

This function checks if a given epoch is valid.

```solidity
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 <a href="#epochisover" id="epochisover"></a>

This function checks if a specific epoch has ended.

```solidity
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 <a href="#vetoingisactive" id="vetoingisactive"></a>

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

```solidity
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 <a href="#votingisactive" id="votingisactive"></a>

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

```solidity
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 <a href="#vetoingisover" id="vetoingisover"></a>

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

```solidity
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 <a href="#votingstart" id="votingstart"></a>

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

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

**Parameters**

| Name    | Type      | Description         |
| ------- | --------- | ------------------- |
| `epoch` | `uint256` | The epoch to check. |

#### epochEnd <a href="#epochend" id="epochend"></a>

This function calculates the end timestamp for a specific epoch.

```solidity
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 <a href="#vetoingend" id="vetoingend"></a>

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

```solidity
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 <a href="#currentepoch" id="currentepoch"></a>

This function retrieves the current epoch number.

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

**Returns**

| Name    | Type      | Description               |
| ------- | --------- | ------------------------- |
| `epoch` | `uint256` | The current epoch number. |

#### lastEpoch <a href="#lastepoch" id="lastepoch"></a>

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

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

**Returns**

| Name    | Type      | Description                   |
| ------- | --------- | ----------------------------- |
| `epoch` | `uint256` | The number of the last epoch. |

#### rewardHasVe <a href="#rewardhasve" id="rewardhasve"></a>

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

```solidity
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 <a href="#addbudget" id="addbudget"></a>

User Actions

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

#### addMatchingBudget <a href="#addmatchingbudget" id="addmatchingbudget"></a>

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

```solidity
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 <a href="#addincentives" id="addincentives"></a>

This function allows adding a new incentive to the system.

```solidity
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 <a href="#invetoperiodcheck" id="invetoperiodcheck"></a>

```solidity
function _inVetoPeriodCheck(uint256 epoch) internal view;
```

#### \_inVotePeriodCheck <a href="#invoteperiodcheck" id="invoteperiodcheck"></a>

```solidity
function _inVotePeriodCheck(uint256 epoch) internal view;
```

#### vote <a href="#vote" id="vote"></a>

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

```solidity
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 <a href="#veto" id="veto"></a>

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

```solidity
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 <a href="#checkvetoperiodended" id="checkvetoperiodended"></a>

```solidity
function _checkVetoPeriodEnded(uint256 epoch) internal view;
```

#### distribute <a href="#distribute" id="distribute"></a>

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

```solidity
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 <a href="#rolloverexcessbudget" id="rolloverexcessbudget"></a>

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.

```solidity
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 <a href="#structs" id="structs"></a>

#### MatchPair <a href="#matchpair" id="matchpair"></a>

```solidity
struct MatchPair {
    uint128 matchBudget;
    uint128 voteBudget;
}
```

#### CheckpointData <a href="#checkpointdata-1" id="checkpointdata-1"></a>

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mav.xyz/technical-reference/maverick-v2/v2-contracts/maverick-v2-reward-contracts/maverickv2incentivematcher.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.