# CCIP v1.6.1 RateLimiter Library API Reference
Source: https://docs.chain.link/ccip/api-reference/evm/v1.6.1/rate-limiter

> For the complete documentation index, see [llms.txt](/llms.txt).

<Aside type="note" title="Integrate Chainlink CCIP v1.6.1 into your project">
  <Tabs sharedStore="ccip-v1-6-1-package" client:visible>
    <Fragment slot="tab.1">npm</Fragment>
    <Fragment slot="tab.2">yarn</Fragment>
    <Fragment slot="tab.3">foundry</Fragment>

    <Fragment slot="panel.1">
      If you use [NPM](https://www.npmjs.com/), install the [@chainlink/contracts-ccip NPM package](https://www.npmjs.com/package/@chainlink/contracts-ccip):

      ```shell
      npm install @chainlink/contracts-ccip@1.6.1
      ```
    </Fragment>

    <Fragment slot="panel.2">
      If you use [Yarn](https://yarnpkg.com/), install the [@chainlink/contracts-ccip NPM package](https://www.npmjs.com/package/@chainlink/contracts-ccip):

      ```shell
      yarn add @chainlink/contracts-ccip@1.6.1
      ```
    </Fragment>

    <Fragment slot="panel.3">
      If you use [Foundry](https://book.getfoundry.sh/), install the package:

      ```shell
      forge install smartcontractkit/chainlink-ccip@bbab0601244ce58e2ffac0dbc178a80aab1fa4a3
      ```
    </Fragment>
  </Tabs>
</Aside>

## RateLimiter

A library implementing the Token Bucket algorithm for rate limiting cross-chain operations.

[Git Source](https://github.com/smartcontractkit/chainlink-ccip/tree/contracts-ccip-v1.6.1/chains/evm/contracts/libraries/RateLimiter.sol)

> \*\*NOTE\*\*
>
>
>
> This library provides rate limiting functionality with the following features:
>
> - Uses uint128 for safe state management
> - Supports USD value rate limiting with 18 decimals precision
> - Handles ERC20 token amount rate limiting
> - Implements automatic token bucket refill
> - Provides configuration validation and safety checks through [`Config`](#config)
> - Includes overflow protection for exceptional scenarios

## Events

### TokensConsumed

```solidity
event TokensConsumed(uint256 tokens);
```

<Aside>Emitted when tokens are successfully consumed from the [`TokenBucket`](#tokenbucket).</Aside>

**Parameters**

| Name     | Type      | Description                   |
| -------- | --------- | ----------------------------- |
| `tokens` | `uint256` | The number of tokens consumed |

### ConfigChanged

```solidity
event ConfigChanged(Config config);
```

<Aside>Emitted when the rate limiter [`Config`](#config) is updated.</Aside>

**Parameters**

| Name     | Type                | Description                   |
| -------- | ------------------- | ----------------------------- |
| `config` | [`Config`](#config) | The new configuration applied |

## Errors

### BucketOverfilled

```solidity
error BucketOverfilled();
```

<Aside>Thrown when the [`TokenBucket`](#tokenbucket) contains more tokens than its capacity.</Aside>

### OnlyCallableByAdminOrOwner

```solidity
error OnlyCallableByAdminOrOwner();
```

<Aside>Thrown when a restricted function is called by an unauthorized address.</Aside>

### TokenMaxCapacityExceeded

```solidity
error TokenMaxCapacityExceeded(uint256 capacity, uint256 requested, address tokenAddress);
```

<Aside>Thrown when attempting to consume more tokens than the [`TokenBucket`](#tokenbucket)'s capacity.</Aside>

### TokenRateLimitReached

```solidity
error TokenRateLimitReached(uint256 minWaitInSeconds, uint256 available, address tokenAddress);
```

> \*\*NOTE\*\*
>
>
>
> Thrown when attempting to consume more tokens than currently available in the [`TokenBucket`](#tokenbucket).

### AggregateValueMaxCapacityExceeded

```solidity
error AggregateValueMaxCapacityExceeded(uint256 capacity, uint256 requested);
```

<Aside>Thrown when attempting to consume more aggregate value than the [`TokenBucket`](#tokenbucket)'s capacity.</Aside>

### AggregateValueRateLimitReached

```solidity
error AggregateValueRateLimitReached(uint256 minWaitInSeconds, uint256 available);
```

> \*\*NOTE\*\*
>
>
>
> Thrown when attempting to consume more aggregate value than currently available in the [`TokenBucket`](#tokenbucket).

### InvalidRateLimitRate

```solidity
error InvalidRateLimitRate(Config rateLimiterConfig);
```

<Aside>Thrown when the rate limit [`Config`](#config) is invalid (rate is zero or exceeds capacity).</Aside>

### DisabledNonZeroRateLimit

```solidity
error DisabledNonZeroRateLimit(Config config);
```

<Aside>Thrown when a disabled [`Config`](#config) has non-zero rate or capacity values.</Aside>

### RateLimitMustBeDisabled

```solidity
error RateLimitMustBeDisabled();
```

<Aside>Thrown when attempting to enable rate limiting in a context where it must be disabled.</Aside>

## Structs

### TokenBucket

Represents the state and configuration of a token bucket rate limiter.

```solidity
struct TokenBucket {
  uint128 tokens;
  uint32 lastUpdated;
  bool isEnabled;
  uint128 capacity;
  uint128 rate;
}
```

> \*\*NOTE\*\*
>
>
>
> State management structure:
>
> - `tokens`: Current token balance in the bucket
> - `lastUpdated`: Timestamp of the last refill (in seconds, supports 100+ years)
> - `isEnabled`: Whether rate limiting is active
> - `capacity`: Maximum token capacity
> - `rate`: Tokens added per second during refill
>
> This struct uses the configuration parameters defined in [`Config`](#config).

### Config

Configuration parameters for the rate limiter.

```solidity
struct Config {
  bool isEnabled;
  uint128 capacity;
  uint128 rate;
}
```

> \*\*NOTE\*\*
>
>
>
> Configuration structure used to configure [`TokenBucket`](#tokenbucket):
>
> - `isEnabled`: Activation state of the rate limiter
> - `capacity`: Maximum token capacity
> - `rate`: Token refill rate per second

## Functions

### \_consume

Removes tokens from the pool, reducing the available rate capacity for subsequent calls.

```solidity
function _consume(TokenBucket storage s_bucket, uint256 requestTokens, address tokenAddress) internal;
```

> \*\*NOTE\*\*
>
>
>
> Key behaviors:
>
> - Skips execution if rate limiting is disabled or requestTokens is zero
> - Automatically refills tokens based on elapsed time
> - Enforces capacity and rate limits
> - Emits [`TokensConsumed`](#tokensconsumed) event for non-zero consumption
> - Reverts with [`TokenMaxCapacityExceeded`](#tokenmaxcapacityexceeded) or [`TokenRateLimitReached`](#tokenratelimitreached) on violations

**Parameters**

| Name            | Type                          | Description                                                     |
| --------------- | ----------------------------- | --------------------------------------------------------------- |
| `s_bucket`      | [`TokenBucket`](#tokenbucket) | The token bucket to consume from                                |
| `requestTokens` | `uint256`                     | The number of tokens to consume                                 |
| `tokenAddress`  | `address`                     | The token address (use address(0) for aggregate value capacity) |

### \_currentTokenBucketState

Retrieves the current state of a token bucket, including automatic refill calculations.

```solidity
function _currentTokenBucketState(TokenBucket memory bucket) internal view returns (TokenBucket memory);
```

> \*\*NOTE\*\*
>
>
>
> Updates the bucket state to reflect the current block timestamp:
>
> - Calculates token refill based on elapsed time
> - Updates the lastUpdated timestamp
> - Returns the current state without modifying storage

**Returns**

| Type                          | Description                           |
| ----------------------------- | ------------------------------------- |
| [`TokenBucket`](#tokenbucket) | The current state of the token bucket |

### \_setTokenBucketConfig

Updates the rate limiter configuration.

```solidity
function _setTokenBucketConfig(TokenBucket storage s_bucket, Config memory config) internal;
```

> \*\*NOTE\*\*
>
>
>
> Configuration update process:
>
> - Updates bucket state with current refill before applying changes
> - Adjusts token amount to respect new capacity
> - Updates bucket parameters (enabled state, capacity, rate)
> - Emits [`ConfigChanged`](#configchanged) event

**Parameters**

| Name       | Type                          | Description                    |
| ---------- | ----------------------------- | ------------------------------ |
| `s_bucket` | [`TokenBucket`](#tokenbucket) | The token bucket to configure  |
| `config`   | [`Config`](#config)           | The new configuration to apply |

### \_validateTokenBucketConfig

Validates rate limiter configuration parameters.

```solidity
function _validateTokenBucketConfig(Config memory config, bool mustBeDisabled) internal pure;
```

> \*\*NOTE\*\*
>
>
>
> Validation rules:
>
> - For enabled configurations:
>   - Rate must be non-zero and less than capacity
>   - Validates against mustBeDisabled requirement
> - For disabled configurations:
>   - Rate and capacity must be zero
> - May throw [`InvalidRateLimitRate`](#invalidratelimitrate), [`DisabledNonZeroRateLimit`](#disablednonzeroratelimit), or [`RateLimitMustBeDisabled`](#ratelimitmustbedisabled)

**Parameters**

| Name             | Type                | Description                                |
| ---------------- | ------------------- | ------------------------------------------ |
| `config`         | [`Config`](#config) | The configuration to validate              |
| `mustBeDisabled` | `bool`              | Whether the configuration must be disabled |

### \_calculateRefill

Calculates the number of tokens to add during a refill operation.

```solidity
function _calculateRefill(
  uint256 capacity,
  uint256 tokens,
  uint256 timeDiff,
  uint256 rate
) private pure returns (uint256);
```

> \*\*NOTE\*\*
>
>
>
> Refill calculation:
>
> - Computes tokens to add based on elapsed time and rate
> - Ensures result doesn't exceed bucket capacity
> - Returns the new token balance
> - Used internally by [`_currentTokenBucketState`](#_currenttokenbucketstate)

**Parameters**

| Name       | Type      | Description                                 |
| ---------- | --------- | ------------------------------------------- |
| `capacity` | `uint256` | Maximum token capacity                      |
| `tokens`   | `uint256` | Current token balance                       |
| `timeDiff` | `uint256` | Time elapsed since last refill (in seconds) |
| `rate`     | `uint256` | Tokens per second refill rate               |

**Returns**

| Type      | Description                        |
| --------- | ---------------------------------- |
| `uint256` | The new token balance after refill |

### \_min

Returns the smaller of two numbers.

```solidity
function _min(uint256 a, uint256 b) internal pure returns (uint256);
```

<Aside>Utility function for safe minimum value calculation.</Aside>

**Parameters**

| Name | Type      | Description   |
| ---- | --------- | ------------- |
| `a`  | `uint256` | First number  |
| `b`  | `uint256` | Second number |

**Returns**

| Type      | Description                    |
| --------- | ------------------------------ |
| `uint256` | The smaller of the two numbers |