Gauge
Description:
This contract serves as a staking pool for a specific LP token (stake). Users deposit their LP tokens into the gauge to earn rewards. Rewards typically include base emission tokens distributed via the associated Voter contract and potentially other tokens added directly as incentives (notifyRewardAmount). The gauge implements a boosting mechanism where a user's reward share (derivedBalance) is calculated based on both their staked LP amount and the voting power of an associated veNFT (_ve) they may link to their stake. The contract interacts with the Voter to manage veNFT attachments/detachments and to receive base token emissions. It uses a checkpointing system, similar to the Bribe contract, to track balances and calculate rewards based on the derived (boosted) supply and balances over time.
Constructor
Description:
Initializes the Gauge contract upon deployment. Sets the immutable addresses for the LP token to be staked (_stake), the associated bribe contract (_bribe, likely for fee distribution or additional incentives), the VotingEscrow contract (__ve) managing veNFTs used for boosting, and the Voter contract (_voter) responsible for distributing base rewards and managing veNFT attachments.
Input Parameters:
_stake
address
The address of the LP token users will stake.
_bribe
address
The address of the associated Bribe contract.
__ve
address
The address of the VotingEscrow contract managing veNFTs.
_voter
address
The address of the Voter contract managing emissions and attachments.
getPriorBalanceIndex
Description:
Helper function to find the index of the latest derived balance checkpoint (checkpoints) for a given account 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:
account
address
The address of the user account to check.
timestamp
uint
The timestamp to find the checkpoint index for.
Return Value:
uint
The index of the relevant derived balance checkpoint for the user.
getPriorSupplyIndex
Description:
Helper function to find the index of the latest derived 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 index for.
Return Value:
uint
The index of the relevant derived 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 (excluding the base emission from the Voter, unless also added via notifyRewardAmount) that have been added to this gauge contract.
Return Value:
uint
The number of reward tokens registered.
lastTimeRewardApplicable
Description:
Calculates the effective timestamp up to which rewards for a given token (added via notifyRewardAmount) 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:
Claims accrued rewards for a specified account across one or more reward tokens. Can be called by the account owner or the voter contract. It first triggers the Voter to distribute any pending base emissions to this gauge (IVoter(voter).distribute(address(this))). Then, it calculates and transfers the earned amounts for the specified tokens. Finally, it recalculates and checkpoints the user's derivedBalance and the derivedSupply.
Input Parameters:
account
address
The address of the user for whom to claim 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 derived voting weight (derivedSupply) 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 derived voting weight (scaled by PRECISION).
derivedBalance
Description:
Calculates the user's "derived" or "boosted" balance used for reward calculations. It's a combination of their raw staked LP balance (balanceOf) and a portion potentially boosted by their veNFT balance (IVoteEscrow(_ve).balanceOfNFT), weighted relative to the total veNFT supply. The formula applies a 40% weight to the raw LP balance and a 60% weight to the veNFT-boosted portion, capped by the user's raw LP balance.
Input Parameters:
account
address
The user account address to calculate for.
Return Value:
uint
The calculated derived (boosted) balance for the specified account.
batchRewardPerToken
Description:
Updates the rewardPerTokenCheckpoints for a given reward token by processing past derived 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 (account), based on their historical derived balance (checkpoints) and the change in rewardPerToken over time.
Input Parameters:
token
address
The address of the reward token to calculate earnings for.
account
address
The user account address.
Return Value:
uint
The amount of token earned and currently claimable by the user.
deposit
Description:
Allows a caller (msg.sender) to deposit amount of the stake token into the gauge on behalf of a specified user. Transfers tokens from msg.sender. Increases the totalSupply (raw LP) and balanceOf[user]. If a tokenId (veNFT) is provided and belongs to the user, it links this tokenId to the user's stake within the gauge (if not already linked) and calls attachTokenToGauge on the Voter. Updates the user's derivedBalance and the total derivedSupply, writing necessary checkpoints. Emits deposit events locally and via the Voter.
Input Parameters:
user
address
The address of the user for whom the deposit is being made.
amount
uint
The amount of stake token to deposit.
tokenId
uint
The ID of the user's veNFT to link for boosting (optional, can be 0).
Events Emitted:
Deposit (local), also triggers Voter.emitDeposit.
withdrawAll
Description:
A convenience function for the caller (msg.sender) to withdraw their entire staked balanceOf. Calls the withdraw function internally.
withdraw
Description:
Allows the caller (msg.sender) to withdraw a specified amount of their staked LP tokens. If the amount being withdrawn is their entire balance, it implicitly assumes the linked tokenId (if any) should be detached. Calls withdrawToken internally.
Input Parameters:
amount
uint
The amount of stake token to withdraw.
withdrawToken
Description:
Allows the caller (msg.sender) to withdraw a specified amount of staked LP tokens. Decreases totalSupply and balanceOf[msg.sender]. Transfers the tokens back to the caller. If a tokenId is provided and matches the currently linked tokenId for the user, it detaches the veNFT by calling detachTokenFromGauge on the Voter and clears the link (tokenIds[msg.sender] = 0). Updates the user's derivedBalance and the total derivedSupply, writing necessary checkpoints. Emits withdraw events locally and via the Voter.
Input Parameters:
amount
uint
The amount of stake token to withdraw.
tokenId
uint
The ID of the veNFT to explicitly detach (must match linked ID if provided).
Events Emitted:
Withdraw (local), also triggers Voter.emitWithdraw.
left
Description:
Calculates the amount of a specific reward token (added via notifyRewardAmount) 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 extra reward incentives (amount) for a specific reward token (cannot be the same as the stake token). Transfers the tokens from the caller (msg.sender) to this gauge. Updates the rewardRate based on the new amount plus any remaining amount, 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