CCIP v2.0.0 RateLimiter API Reference

RateLimiter implements token bucket rate limiting for CCIP contracts.

It enforces throughput limits by:

This ensures that cross-chain operations such as token transfers and message execution do not exceed configured limits.

This library provides reusable helper functions and is not deployed as a standalone application-facing contract.

Usage Boundary

You do not call this library directly.

Contracts use this library to enforce rate limits on token transfers or message execution.
Rate limiting is applied per token or per resource bucket.
You are responsible for configuring appropriate capacity and refill rates.

libraries/RateLimiter.sol

import {RateLimiter} from "chainlink-ccip/libraries/RateLimiter.sol";

If you have not installed the package:

npm install @chainlink/contracts-ccip@2.0.0

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

Consumes tokens from the bucket to satisfy a request.

function _currentTokenBucketState(
  TokenBucket memory bucket
) internal view returns (TokenBucket memory)

Returns the current token bucket state after applying time-based refill.

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

Updates the token bucket configuration.

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

Computes the number of tokens to refill based on elapsed time and rate.

function _min(uint256 a, uint256 b) internal pure returns (uint256)

Returns the minimum of two values.

error BucketOverfilled()
error TokenMaxCapacityExceeded(uint256 capacity, uint256 requested, address tokenAddress)
error TokenRateLimitReached(uint256 minWaitInSeconds, uint256 available, address tokenAddress)
error InvalidRateLimitRate(Config rateLimiterConfig)
error DisabledNonZeroRateLimit(Config config)

For a cross-contract error index, see Errors.

Token buckets refill linearly over time based on the configured rate.
The number of tokens never exceeds the configured capacity.
Each request consumes tokens proportional to the requested amount.
Requests exceeding available tokens will revert with rate limit errors.
Invalid configurations (e.g. zero rate with enabled bucket) will revert.
Rate limiting is typically applied per token or per lane to control cross-chain throughput.

Used by:

Rate limiting is applied to control transfer throughput and prevent excessive usage.