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
constructor(address _stake, address _bribe, address __ve, address _voter)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
function getPriorBalanceIndex(address account, uint timestamp) public view returns (uint)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
function getPriorSupplyIndex(uint timestamp) public view returns (uint)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
function getPriorRewardPerToken(address token, uint timestamp) public view returns (uint, uint)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
function rewardsListLength() external view returns (uint)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
function lastTimeRewardApplicable(address token) public view returns (uint)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
function getReward(address account, address[] memory tokens) external lockDescription:
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
function rewardPerToken(address token) public view returns (uint)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
function derivedBalance(address account) public view returns (uint)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
function batchRewardPerToken(address token, uint maxRuns) externalDescription:
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
function earned(address token, address account) public view returns (uint)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
function deposit(address user, uint amount, uint tokenId) public lockDescription:
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
function withdrawAll() externalDescription:
A convenience function for the caller (msg.sender) to withdraw their entire staked balanceOf. Calls the withdraw function internally.
withdraw
function withdraw(uint amount) publicDescription:
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
function withdrawToken(uint amount, uint tokenId) public lockDescription:
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
function left(address token) external view returns (uint)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
function notifyRewardAmount(address token, uint amount) external lockDescription:
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