GaugeV3

Distributes weekly RAM emissions to Ramses V3 concentrated liquidity positions. Rewards are allocated based on periodSecondsInsideX96, which tracks each position’s time-weighted in-range contribution during each weekly period.

Functions

notifyRewardAmount

  function notifyRewardAmount(
    address token,
    uint256 amount
  ) external

Notifies the gauge of newly deposited reward tokens for distribution in the current period. Collects protocol fees from the pool before processing. The token must be a whitelisted reward token.

Parameters:

Name	Type	Description
`token`	address	The reward token address
`amount`	uint256	The amount of reward tokens to distribute

notifyRewardAmountNextPeriod

  function notifyRewardAmountNextPeriod(
    address token,
    uint256 amount
  ) external

Queues reward tokens for distribution in the next period rather than the current one.

Parameters:

Name	Type	Description
`token`	address	The reward token address
`amount`	uint256	The amount of reward tokens to distribute

notifyRewardAmountForPeriod

  function notifyRewardAmountForPeriod(
    address token,
    uint256 amount,
    uint256 period
  ) external

Queues reward tokens for distribution in a specific future period. The period must be strictly in the future.

Parameters:

Name	Type	Description
`token`	address	The reward token address
`amount`	uint256	The amount of reward tokens to distribute
`period`	uint256	The future period to distribute rewards in

getReward

  function getReward(
    uint256 tokenId,
    address[] tokens
  ) external

Claims accrued rewards for a position. Calculates rewards based on the position’s periodSecondsInsideX96 relative to total in-range liquidity during each period. The caller must be the position owner, operator, or approved for all. Only callable by authorized claimers.

Parameters:

Name	Type	Description
`tokenId`	uint256	The ID of the position NFT to claim for
`tokens`	address[]	The reward token addresses to claim

getReward (batch)

  function getReward(
    uint256[] tokenIds,
    address[] tokens
  ) external

Claims accrued rewards for multiple positions in a single call.

Parameters:

Name	Type	Description
`tokenIds`	uint256[]	The IDs of the position NFTs to claim for
`tokens`	address[]	The reward token addresses to claim

getRewardForOwner

  function getRewardForOwner(
    uint256 tokenId,
    address[] tokens
  ) external

Claims rewards on behalf of the position owner, sending them to the owner’s address. Callable by the voter contract or authorized claimers.

Parameters:

Name	Type	Description
`tokenId`	uint256	The ID of the position NFT to claim for
`tokens`	address[]	The reward token addresses to claim

earned

  function earned(
    address token,
    uint256 tokenId
  ) external view returns (uint256)

Returns the amount of a reward token earned by a position but not yet claimed.

Parameters:

Name	Type	Description
`token`	address	The reward token address
`tokenId`	uint256	The ID of the position NFT

Return Values:

Type	Description
uint256	Amount of earned rewards

periodEarned

  function periodEarned(
    uint256 period,
    address token,
    uint256 tokenId
  ) external view returns (uint256)

Returns the amount earned by a position for a specific period.

Parameters:

Name	Type	Description
`period`	uint256	The period to query
`token`	address	The reward token address
`tokenId`	uint256	The ID of the position NFT

left

  function left(
    address token
  ) external view returns (uint256)

Returns the approximate amount of a reward token remaining for distribution in the current period, based on the time remaining.

Parameters:

Name	Type	Description
`token`	address	The reward token address

Return Values:

Type	Description
uint256	Approximate remaining reward amount

rewardRate

  function rewardRate(
    address token
  ) external view returns (uint256)

Returns the per-second reward rate for a token in the current period.

Parameters:

Name	Type	Description
`token`	address	The reward token address

Return Values:

Type	Description
uint256	Reward amount per second

getRewardTokens

  function getRewardTokens() external view returns (address[])

Returns the list of all reward token addresses registered on this gauge.

positionHash

  function positionHash(
    address owner,
    uint256 index,
    int24 tickLower,
    int24 tickUpper
  ) external pure returns (bytes32)

Computes the unique identifier for a position based on its owner, index, and tick range.

Parameters:

Name	Type	Description
`owner`	address	The position owner address
`index`	uint256	The position index (token ID)
`tickLower`	int24	The lower tick of the position range
`tickUpper`	int24	The upper tick of the position range

addRewards

  function addRewards(
    address reward
  ) external

Adds a new reward token to the gauge. Only callable by AccessHub.

Parameters:

Name	Type	Description
`reward`	address	The reward token address to add

removeRewards

  function removeRewards(
    address reward
  ) external

Removes a reward token from the gauge. Only callable by AccessHub.

Parameters:

Name	Type	Description
`reward`	address	The reward token address to remove

syncCache

  function syncCache() external

Syncs cached values from the Voter and AccessHub contracts, including the reward validator, R33 address, fee collector, and authorized claimers list.

Key Concepts

Rewards are distributed per weekly period (epoch), aligned with the Ramses voting cycle
A position earns rewards proportional to its secondsInsideX96 during each period relative to the total
Only authorized claimers (registered through the Voter contract) can call reward-claiming functions
The gauge supports a reward validator for anti-sybil checks; flagged claims are redirected to the R33 address
notifyRewardAmount collects protocol fees from the pool before processing new rewards

Overview

Guides

Reference

Functions

notifyRewardAmount

Parameters:

notifyRewardAmountNextPeriod

Parameters:

notifyRewardAmountForPeriod

Parameters:

getReward

Parameters:

getReward (batch)

Parameters:

getRewardForOwner

Parameters:

earned

Parameters:

Return Values:

periodEarned

Parameters:

left

Parameters:

Return Values:

rewardRate

Parameters:

Return Values:

getRewardTokens

positionHash

Parameters:

addRewards

Parameters:

removeRewards

Parameters:

syncCache

Key Concepts

​Functions

​notifyRewardAmount

​Parameters:

​notifyRewardAmountNextPeriod

​Parameters:

​notifyRewardAmountForPeriod

​Parameters:

​getReward

​Parameters:

​getReward (batch)

​Parameters:

​getRewardForOwner

​Parameters:

​earned

​Parameters:

​Return Values:

​periodEarned

​Parameters:

​left

​Parameters:

​Return Values:

​rewardRate

​Parameters:

​Return Values:

​getRewardTokens

​positionHash

​Parameters:

​addRewards

​Parameters:

​removeRewards

​Parameters:

​syncCache

​Key Concepts

Functions

notifyRewardAmount

Parameters:

notifyRewardAmountNextPeriod

Parameters:

notifyRewardAmountForPeriod

Parameters:

getReward

Parameters:

getReward (batch)

Parameters:

getRewardForOwner

Parameters:

earned

Parameters:

Return Values:

periodEarned

Parameters:

left

Parameters:

Return Values:

rewardRate

Parameters:

Return Values:

getRewardTokens

positionHash

Parameters:

addRewards

Parameters:

removeRewards

Parameters:

syncCache

Key Concepts