IRateLimiter
Title: IRateLimiter
Author: Modified from Chainlink CCIP (https://github.com/smartcontractkit/ccip/blob/ccip-develop/contracts/src/v0.8/ccip/libraries/RateLimiter.sol)
Interface for the RateLimiter module — a token-bucket rate limiter keyed by bytes32.
Each key has a capacity (max bucket size) and refillRate (tokens per second).
Functions
getConfig
Returns the capacity and refill rate configured for key.
function getConfig(bytes32 key) external view returns (uint256 capacity, uint256 refillRate);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The rate limit key to query. |
Returns
| Name | Type | Description |
|---|---|---|
| capacity | uint256 | The maximum token capacity of the bucket. |
| refillRate | uint256 | The number of tokens refilled per second. |
getAvailable
Returns the currently available tokens for key (accounts for elapsed time).
This is a pure read — it does NOT update storage.
function getAvailable(bytes32 key) external view returns (uint256 available);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The rate limit key to query. |
Returns
| Name | Type | Description |
|---|---|---|
| available | uint256 | The number of tokens available right now. |
configure
Configures or reconfigures a rate limit bucket.
Requires DEFAULT_ADMIN_ROLE. Sets tokens = capacity and lastRefill = now.
Reverts with RateLimitInvalidConfig if capacity == 0 OR refillRate == 0.
Emits RateLimitConfigured.
function configure(bytes32 key, uint256 capacity, uint256 refillRate) external;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The rate limit key. |
| capacity | uint256 | The maximum token capacity (must be > 0). |
| refillRate | uint256 | The tokens-per-second refill rate (must be > 0). |
consume
Consumes amount tokens from the bucket for key.
Refills the bucket first based on elapsed time, then deducts amount.
Reverts with RateLimitInvalidAmount if amount == 0.
Reverts with RateLimitNotConfigured if the key has no configuration.
Reverts with RateLimitExceeded if fewer than amount tokens are available.
Emits RateLimitConsumed.
function consume(bytes32 key, uint256 amount) external;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The rate limit key. |
| amount | uint256 | The number of tokens to consume (must be > 0). |
Events
RateLimitConfigured
Emitted when a rate limit bucket is configured or updated.
event RateLimitConfigured(bytes32 indexed key, uint256 capacity, uint256 refillRate);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The rate limit key. |
| capacity | uint256 | The maximum number of tokens in the bucket. |
| refillRate | uint256 | The number of tokens added per second. |
RateLimitConsumed
Emitted when tokens are successfully consumed from a bucket.
event RateLimitConsumed(bytes32 indexed key, address indexed consumer, uint256 amount, uint256 remaining);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The rate limit key. |
| consumer | address | The address that consumed the tokens. |
| amount | uint256 | The number of tokens consumed. |
| remaining | uint256 | The number of tokens remaining in the bucket after consumption. |
Errors
RateLimitNotConfigured
Thrown when an operation is attempted on a key that has not been configured.
error RateLimitNotConfigured(bytes32 key);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The unconfigured rate limit key. |
RateLimitExceeded
Thrown when a consume request exceeds the currently available tokens.
error RateLimitExceeded(bytes32 key, uint256 requested, uint256 available);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The rate limit key. |
| requested | uint256 | The number of tokens requested. |
| available | uint256 | The number of tokens currently available. |
RateLimitInvalidConfig
Thrown when configure is called with a zero capacity or zero refill rate.
error RateLimitInvalidConfig();RateLimitInvalidAmount
Thrown when consume is called with amount == 0.
error RateLimitInvalidAmount();