RateLimiterLib
Title: RateLimiter Library
Authors: David Dada <daveproxy80@gmail.com> (https://github.com/dadadave80), Modified from Chainlink CCIP (https://github.com/smartcontractkit/ccip/blob/ccip-develop/contracts/src/v0.8/ccip/libraries/RateLimiter.sol)
Library implementing a token-bucket rate limiter for Diamond facets.
Each key has an independent bucket with a capacity (max tokens) and
refillRate (tokens per second). Tokens are lazily refilled on each
consume call based on elapsed time since the last interaction.
Functions
rateLimiterStorage
Returns the storage struct for RateLimiter at its ERC-7201 slot.
function rateLimiterStorage() internal pure returns (RateLimiterStorage storage $);Returns
| Name | Type | Description |
|---|---|---|
| $ | RateLimiterStorage |
registerInterface
Registers support for the IRateLimiter interface via ERC-165.
Writes true to the precomputed ERC-165 map slot.
function registerInterface() internal;__RateLimiter_init
Initializes the RateLimiter module.
Must be called inside an initializer-guarded function (see Initializable).
Registers the IRateLimiter interface ID for ERC-165 discovery.
function __RateLimiter_init() internal;configure
Configures or reconfigures a rate limit bucket.
Requires DEFAULT_ADMIN_ROLE. Sets tokens = capacity and lastRefill = now.
Reverts RateLimitInvalidConfig if capacity == 0 or refillRate == 0.
Emits RateLimitConfigured.
function configure(bytes32 key, uint256 capacity, uint256 refillRate) internal;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 based on elapsed time, then deducts amount.
Reverts RateLimitInvalidAmount if amount == 0.
Reverts RateLimitNotConfigured if the key has no configuration (capacity == 0).
Reverts RateLimitExceeded if fewer than amount tokens are available.
Emits RateLimitConsumed.
function consume(bytes32 key, uint256 amount) internal;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The rate limit key. |
| amount | uint256 | The number of tokens to consume (must be > 0). |
getAvailable
Returns the currently available tokens for key without modifying state.
Computes the refilled token count based on elapsed time but does not persist it. Returns 0 for unconfigured keys.
function getAvailable(bytes32 key) internal 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. |
getConfig
Returns the capacity and refill rate configured for key.
function getConfig(bytes32 key) internal 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. |
_configure
Internal — configures a bucket, resetting tokens and lastRefill.
function _configure(bytes32 key, uint256 capacity, uint256 refillRate) internal;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | |
| capacity | uint256 | |
| refillRate | uint256 |
_consume
Internal — refills and deducts tokens, reverts on insufficient balance.
function _consume(bytes32 key, uint256 amount) internal;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | |
| amount | uint256 |
_currentTokens
Internal — computes refilled token count (min of capacity and tokens + accrued).
Does NOT write to storage.
Saturates accrued at capacity before addition to prevent overflow when
elapsed * refillRate would exceed type(uint256).max.
function _currentTokens(RateLimiterBucket storage b) internal view returns (uint256);Parameters
| Name | Type | Description |
|---|---|---|
| b | RateLimiterBucket |
Returns
| Name | Type | Description |
|---|---|---|
| <none> | uint256 |
_refill
Internal — persists the refilled token amount and updates lastRefill timestamp.
function _refill(RateLimiterBucket storage b) internal returns (uint256 available);Parameters
| Name | Type | Description |
|---|---|---|
| b | RateLimiterBucket |
Returns
| Name | Type | Description |
|---|---|---|
| available | uint256 | The token count after refilling. |