IncentivesManager
Description:
This contract manages the time-released distribution of incentives (typically the base reward token) to the associated Voter contract. It acts as an intermediary, holding the total incentive amount and releasing it periodically (weekly) based on current conditions. Key features include:
Dilution Control: Introduces a
poolCapon the total veToken supply (_ve.totalSupply()). The actual weekly incentive amount (WeeklyIncentives) distributed is scaled down if the current veToken supply exceeds this cap, preventing excessive dilution of rewards for existing lockers.Dynamic End Time: While a
minimumDistributionEndTimeis set, the actualdistributionEndTimeadjusts dynamically based on the ratio of current veToken supply to thepoolCap. If supply is below the cap, the distribution period effectively extends; if it's at or above the cap, it matches the minimum duration.Periodic Distribution: The
update_periodfunction, callable weekly by authorized providers, calculates the appropriate incentive amount for the past week and sends it to theVotervianotifyRewardAmount. It interacts withVoteEscrowDistributionto ensure token balances are checkpointed before distribution.Access Control: Uses an
adminrole and anincentiveWhitelistto control who can deposit/update incentives and triggerupdate_period.
Constructor
Description:
Initializes the IncentivesManager contract upon deployment. Sets the immutable addresses of the core interacting contracts: _voter (Voter), _ve (VoteEscrow), and _ve_dist (VoteEscrowDistribution). It also identifies the underlying reward token (_token) from the VoteEscrow contract and sets the initial admin address.
Input Parameters:
__voter
address
Address of the Voter contract that receives incentives.
__ve
address
Address of the VoteEscrow contract managing veNFT supply.
__ve_dist
address
Address of the VoteEscrowDistribution contract.
__admin
address
Address designated as the administrator for this contract.
addToWhitelist
Description:
Allows the admin to add an address (_addr) to the incentiveWhitelist. Whitelisted addresses, along with the admin, can deposit/update incentives and trigger the weekly update_period.
Input Parameters:
_addr
address
The address to add to the incentive provider whitelist.
removeFromWhitelist
Description:
Allows the admin to remove an address (_addr) from the incentiveWhitelist.
Input Parameters:
_addr
address
The address to remove from the incentive provider whitelist.
update_period
Description:
Calculates and distributes the incentives accrued since the lastDistributionTime. Callable only by the admin or a whitelisted provider, and only if at least one week (week) has passed. It calculates the WeeklyIncentives based on the current _ve.totalSupply() relative to the poolCap, determines the amount to distribute for the elapsed time, checkpoints the VoteEscrowDistribution, approves the Voter contract, and calls _voter.notifyRewardAmount() to send the calculated incentives. Updates internal tracking (distributedSoFar, totalIncentives, lastDistributionTime).
Return Value:
distributedThisCall
uint256
The amount of incentives distributed in this function call.
deposit_incentives
Description:
Used to deposit the initial batch of incentives into the contract and configure the distribution parameters. Callable only by the admin or a whitelisted provider. Requires the start time to be in the future and duration to be at least one week. Transfers _incentives from the caller, sets totalIncentives, poolCap, distributionStartTime, calculates the initial maxWeeklyIncentives and WeeklyIncentivesPerLockedToken, sets the minimumDistributionEndTime, and calculates the initial dynamic distributionEndTime.
Input Parameters:
_incentives
uint
The total amount of incentive tokens being deposited for this period.
_pool_cap
uint
The maximum veToken supply (_ve.totalSupply()) to consider for full emission rate calculation.
_distribution_start_time
uint
The Unix timestamp when the incentive distribution should begin. Must be in the future.
_distribution_end_time
uint
The minimum Unix timestamp when the distribution should end (used to calculate initial duration).
Events Emitted:
DepositIncentives(...)
update_incentives
Description:
Allows adding more incentives (_incentives) to the current distribution period, potentially updating the _pool_cap and extending the minimum duration via _distribution_end_time. Callable only by the admin or a whitelisted provider during an active distribution period. Transfers additional _incentives from the caller, recalculates rates (maxWeeklyIncentives, WeeklyIncentivesPerLockedToken), updates totalIncentives, potentially updates poolCap, sets the new minimumDistributionEndTime, and recalculates the dynamic distributionEndTime.
Input Parameters:
_incentives
uint
The additional amount of incentive tokens being deposited (can be 0 if only updating cap/duration).
_pool_cap
uint
The new maximum veToken supply to consider. Must be >= current _ve.totalSupply().
_distribution_end_time
uint
The new minimum Unix timestamp when the distribution should end. Must be in the future.
Events Emitted:
UpdateIncentives(...)
sweepLeftovers
Description:
Allows the admin to withdraw any remaining balance of the incentive token (_token) held by this contract after the dynamic distributionEndTime has passed. This is useful if rounding or other factors leave dust amounts after the intended distribution period.
incentives_balance
Description:
Returns the current balance of the incentive token (_token) held by this IncentivesManager contract.
Return Value:
uint256
The contract's current balance of the incentive token.
updateWeeklyIncentives
Description:
Recalculates and updates the WeeklyIncentives state variable based on the current _ve.totalSupply(), the stored poolCap, and the maxWeeklyIncentives. This function can be called externally to refresh the rate if needed, although update_period also performs this update internally before distribution.
Last updated