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