> ## Documentation Index
> Fetch the complete documentation index at: https://tech.ramses.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```solidity theme={null}
  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

```solidity theme={null}
  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

```solidity theme={null}
  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

```solidity theme={null}
  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)

```solidity theme={null}
  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

```solidity theme={null}
  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

```solidity theme={null}
  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

```solidity theme={null}
  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

```solidity theme={null}
  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

```solidity theme={null}
  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

```solidity theme={null}
  function getRewardTokens() external view returns (address[])
```

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

### positionHash

```solidity theme={null}
  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

```solidity theme={null}
  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

```solidity theme={null}
  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

```solidity theme={null}
  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