Bribe
Description:
This contract manages and distributes external rewards (bribes) for a specific gauge/pool within the ecosystem. Users who vote for the associated gauge using their veNFTs (managed by the _ve
contract) deposit their voting weight into this contract via the factory
(typically the Voter
contract). Deposited rewards (notifyRewardAmount
) are then distributed proportionally over a 7-day period (DURATION
) based on the amount of voting weight each user has contributed (balanceOf
) relative to the total voting weight (totalSupply
) directed towards this bribe contract. It uses a checkpointing system similar to Synthetix staking contracts to track balances, supply, and rewards per token over time, allowing users to claim accrued bribes (getReward
).
Constructor
Description:
Initializes the Bribe
contract upon deployment. It sets the factory
address, which is expected to be the Voter
contract responsible for managing deposits and withdrawals of voting weight (_deposit
, _withdraw
) and triggering reward claims (getRewardForOwner
). It also retrieves and stores the associated VotingEscrow
(_ve
) address from the factory.
Input Parameters:
_factory
address
The address of the contract (typically Voter
) authorized to modify balances and trigger owner claims.
getPriorBalanceIndex
Description:
Helper function to find the index of the latest user balance checkpoint (checkpoints
) for a given tokenId
that occurred at or before the specified timestamp
. Uses binary search. Returns 0 if no checkpoint is found at or before the timestamp.
Input Parameters:
tokenId
uint
The ID of the veNFT representing the user's vote.
timestamp
uint
The timestamp to find the checkpoint index for.
Return Value:
uint
The index of the relevant user balance checkpoint.
getPriorSupplyIndex
Description:
Helper function to find the index of the latest total supply checkpoint (supplyCheckpoints
) that occurred at or before the specified timestamp
. Uses binary search. Returns 0 if no checkpoint is found at or before the timestamp.
Input Parameters:
timestamp
uint
The timestamp to find the supply checkpoint for.
Return Value:
uint
The index of the relevant total supply checkpoint.
getPriorRewardPerToken
Description:
Helper function to find the reward per token and timestamp of the latest checkpoint (rewardPerTokenCheckpoints
) for a specific reward token
that occurred at or before the specified timestamp
. Uses binary search. Returns (0, 0) if no checkpoint is found.
Input Parameters:
token
address
The address of the reward token to query for.
timestamp
uint
The timestamp to find the checkpoint for.
Return Value:
uint reward
The reward per token stored at the checkpoint.
uint timestamp
The timestamp of the checkpoint.
rewardsListLength
Description:
Returns the number of distinct reward tokens that have been added to this bribe contract via notifyRewardAmount
.
Return Value:
uint
The number of reward tokens registered.
lastTimeRewardApplicable
Description:
Calculates the effective timestamp up to which rewards for a given token
should be calculated. This is the earlier of the current block timestamp and the periodFinish
for that reward token.
Input Parameters:
token
address
The address of the reward token to query for.
Return Value:
uint
The timestamp until which the current reward rate for the token is applicable.
getReward
Description:
Allows a user (msg.sender
) to claim their accrued bribe rewards for a specific veNFT (tokenId
) across one or more specified reward tokens
. Requires the caller to be the owner or approved for the tokenId
. It updates reward calculations and transfers the earned amounts.
Input Parameters:
tokenId
uint
The ID of the veNFT representing the user's vote that earned the rewards.
tokens
address[] memory
An array of reward token addresses for which to claim rewards.
Events Emitted:
ClaimRewards(address indexed from, address indexed reward, uint amount)
for each token claimed.
getRewardForOwner
Description:
Allows the designated factory
(the Voter contract) to trigger a reward claim for a specific veNFT (tokenId
) across multiple reward tokens
. The claimed rewards are sent directly to the actual owner of the tokenId
. This is used for batch claiming operations initiated by the Voter.
Input Parameters:
tokenId
uint
The ID of the veNFT whose owner should receive the rewards.
tokens
address[] memory
An array of reward token addresses for which to claim rewards.
Events Emitted:
ClaimRewards(address indexed from, address indexed reward, uint amount)
for each token claimed.
rewardPerToken
Description:
Calculates the current cumulative reward per unit of voting weight (totalSupply
) for a specific reward token
. This value increases over time as rewards are distributed.
Input Parameters:
token
address
The address of the reward token to query for.
Return Value:
uint
The current reward accrued per unit of total voting weight (scaled by PRECISION
).
batchRewardPerToken
Description:
Updates the rewardPerTokenCheckpoints
for a given reward token
by processing past supply checkpoints. This function can be called permissionlessly to advance the reward calculation state, potentially processing up to maxRuns
supply checkpoints in one call.
Input Parameters:
token
address
The address of the reward token whose checkpoints need updating.
maxRuns
uint
The maximum number of supply checkpoints to process in this call.
earned
Description:
Calculates the amount of a specific reward token
that is currently claimable by a user for their specific veNFT (tokenId
), based on their historical voting weight (balanceOf
checkpoints) and the change in rewardPerToken
over time.
Input Parameters:
token
address
The address of the reward token to calculate earnings for.
tokenId
uint
The ID of the veNFT representing the user's vote.
Return Value:
uint
The amount of token
earned and currently claimable by the NFT.
_deposit
Description:
Internal use function callable only by the factory
(Voter) address. Increases the voting weight (balanceOf
) associated with a specific veNFT (tokenId
) by amount
, and increases the totalSupply
. Updates user balance and total supply checkpoints. Called when votes are cast or increased for the associated gauge.
Input Parameters:
amount
uint
The amount of voting weight to deposit.
tokenId
uint
The ID of the veNFT representing the vote.
Events Emitted:
Deposit(address indexed from, uint tokenId, uint amount)
_withdraw
Description:
Internal use function callable only by the factory
(Voter) address. Decreases the voting weight (balanceOf
) associated with a specific veNFT (tokenId
) by amount
, and decreases the totalSupply
. Updates user balance and total supply checkpoints. Called when votes are removed or reset for the associated gauge.
Input Parameters:
amount
uint
The amount of voting weight to withdraw.
tokenId
uint
The ID of the veNFT representing the vote.
Events Emitted:
Withdraw(address indexed from, uint tokenId, uint amount)
left
Description:
Calculates the amount of a specific reward token
that is remaining to be distributed within the current reward period, based on the rewardRate
and time until periodFinish
. Returns 0 if the period has finished.
Input Parameters:
token
address
The address of the reward token to query.
Return Value:
uint
The amount of token
left to be distributed.
notifyRewardAmount
Description:
Allows anyone to add bribe rewards (amount
) for a specific reward token
. It transfers the tokens from the caller (msg.sender
) to this contract. It updates the rewardRate
based on the new amount plus any remaining amount from the previous period, distributing the total over a new 7-day DURATION
. Registers the token in the rewards
list if it's new.
Input Parameters:
token
address
The address of the reward token being added.
amount
uint
The amount of the reward token to add.
Events Emitted:
NotifyReward(address indexed from, address indexed reward, uint amount)
Last updated