CCIP v1.5.1 TokenPool Contract API Reference
TokenPool
An abstract contract that provides base functionality for managing cross-chain token operations in CCIP. It handles token decimals across different chains, rate limiting, and access control.
Inherits:
Events
AllowListAdd
Emitted when an address is added to the allowlist via applyAllowListUpdates.
event AllowListAdd(address sender);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
sender | address | No | The address that was added to the allowlist |
AllowListRemove
Emitted when an address is removed from the allowlist via applyAllowListUpdates.
event AllowListRemove(address sender);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
sender | address | No | The address that was removed from the allowlist |
Burned
Emitted when tokens are burned by the pool.
event Burned(address indexed sender, uint256 amount);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
sender | address | Yes | The address initiating the burn operation |
amount | uint256 | No | The amount of tokens burned |
ChainAdded
Emitted when a new chain is configured in the pool via applyChainUpdates.
event ChainAdded(
uint64 remoteChainSelector,
bytes remoteToken,
RateLimiter.Config outboundRateLimiterConfig,
RateLimiter.Config inboundRateLimiterConfig
);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
remoteChainSelector | uint64 | No | The identifier of the newly added chain |
remoteToken | bytes | No | The token address on the remote chain |
outboundRateLimiterConfig | RateLimiter.Config | No | Rate limit configuration for outbound transfers |
inboundRateLimiterConfig | RateLimiter.Config | No | Rate limit configuration for inbound transfers |
ChainConfigured
Emitted when a chain's configuration is updated via setChainRateLimiterConfig or setChainRateLimiterConfigs.
event ChainConfigured(
uint64 remoteChainSelector,
RateLimiter.Config outboundRateLimiterConfig,
RateLimiter.Config inboundRateLimiterConfig
);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
remoteChainSelector | uint64 | No | The identifier of the chain being configured |
outboundRateLimiterConfig | RateLimiter.Config | No | Updated rate limit configuration for outbound transfers |
inboundRateLimiterConfig | RateLimiter.Config | No | Updated rate limit configuration for inbound transfers |
ChainRemoved
Emitted when a chain is removed from the pool's configuration via applyChainUpdates.
event ChainRemoved(uint64 remoteChainSelector);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
remoteChainSelector | uint64 | No | The identifier of the chain being removed |
Locked
Emitted when tokens are locked by the pool.
event Locked(address indexed sender, uint256 amount);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
sender | address | Yes | The address initiating the lock operation |
amount | uint256 | No | The amount of tokens locked |
Minted
Emitted when tokens are minted by the pool.
event Minted(address indexed sender, address indexed recipient, uint256 amount);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
sender | address | Yes | The address initiating the mint operation |
recipient | address | Yes | The address receiving the minted tokens |
amount | uint256 | No | The amount of tokens minted |
RemotePoolAdded
Emitted when a new remote pool is added via addRemotePool or applyChainUpdates.
event RemotePoolAdded(uint64 indexed remoteChainSelector, bytes remotePoolAddress);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
remoteChainSelector | uint64 | Yes | The identifier of the chain for the new pool |
remotePoolAddress | bytes | No | The address of the newly added pool |
Released
Emitted when tokens are released by the pool.
event Released(address indexed sender, address indexed recipient, uint256 amount);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
sender | address | Yes | The address initiating the release operation |
recipient | address | Yes | The address receiving the released tokens |
amount | uint256 | No | The amount of tokens released |
RemotePoolRemoved
Emitted when a remote pool is removed via removeRemotePool.
event RemotePoolRemoved(uint64 indexed remoteChainSelector, bytes remotePoolAddress);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
remoteChainSelector | uint64 | Yes | The identifier of the chain for the pool |
remotePoolAddress | bytes | No | The address of the removed pool |
RouterUpdated
Emitted when the router address is updated via setRouter.
event RouterUpdated(address oldRouter, address newRouter);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
oldRouter | address | No | The previous router contract address |
newRouter | address | No | The new router contract address |
RateLimitAdminSet
Emitted when the rate limit administrator is changed via setRateLimitAdmin.
event RateLimitAdminSet(address rateLimitAdmin);
Parameters
| Name | Type | Indexed | Description |
|---|---|---|---|
rateLimitAdmin | address | No | The new rate limit administrator address |
Errors
AllowListNotEnabled
error AllowListNotEnabled();
CallerIsNotARampOnRouter
error CallerIsNotARampOnRouter(address caller);
ChainAlreadyExists
error ChainAlreadyExists(uint64 chainSelector);
Parameters
| Name | Type | Description |
|---|---|---|
chainSelector | uint64 | The selector of the chain that already exists |
ChainNotAllowed
error ChainNotAllowed(uint64 remoteChainSelector);
CursedByRMN
error CursedByRMN();
InvalidDecimalArgs
error InvalidDecimalArgs(uint8 expected, uint8 actual);
Parameters
| Name | Type | Description |
|---|---|---|
expected | uint8 | The expected number of decimals |
actual | uint8 | The actual number of decimals provided |
InvalidRemoteChainDecimals
error InvalidRemoteChainDecimals(bytes sourcePoolData);
Parameters
| Name | Type | Description |
|---|---|---|
sourcePoolData | bytes | The invalid decimal configuration data |
InvalidRemotePoolForChain
error InvalidRemotePoolForChain(uint64 remoteChainSelector, bytes remotePoolAddress);
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector being queried |
remotePoolAddress | bytes | The invalid pool address |
InvalidSourcePoolAddress
error InvalidSourcePoolAddress(bytes sourcePoolAddress);
InvalidToken
error InvalidToken(address token);
Parameters
| Name | Type | Description |
|---|---|---|
token | address | The address of the invalid token |
MismatchedArrayLengths
error MismatchedArrayLengths();
NonExistentChain
error NonExistentChain(uint64 remoteChainSelector);
OverflowDetected
error OverflowDetected(uint8 remoteDecimals, uint8 localDecimals, uint256 remoteAmount);
Parameters
| Name | Type | Description |
|---|---|---|
remoteDecimals | uint8 | The decimals on the remote chain |
localDecimals | uint8 | The decimals on the local chain |
remoteAmount | uint256 | The amount that caused the overflow |
PoolAlreadyAdded
error PoolAlreadyAdded(uint64 remoteChainSelector, bytes remotePoolAddress);
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector where the pool exists |
remotePoolAddress | bytes | The address of the already existing pool |
SenderNotAllowed
error SenderNotAllowed(address sender);
Unauthorized
error Unauthorized(address caller);
Parameters
| Name | Type | Description |
|---|---|---|
caller | address | The address that attempted the action |
ZeroAddressNotAllowed
error ZeroAddressNotAllowed();
Structs
ChainUpdate
Configuration data for adding or updating a chain.
struct ChainUpdate {
uint64 remoteChainSelector;
bytes[] remotePoolAddresses;
bytes remoteTokenAddress;
RateLimiter.Config outboundRateLimiterConfig;
RateLimiter.Config inboundRateLimiterConfig;
}
RemoteChainConfig
Internal configuration for a remote chain.
struct RemoteChainConfig {
RateLimiter.TokenBucket outboundRateLimiterConfig;
RateLimiter.TokenBucket inboundRateLimiterConfig;
bytes remoteTokenAddress;
EnumerableSet.Bytes32Set remotePools;
}
State Variables
i_token
The token managed by this pool. Currently supports one token per pool.
IERC20 internal immutable i_token;
i_tokenDecimals
The number of decimals for the managed token.
uint8 internal immutable i_tokenDecimals;
i_rmnProxy
The Risk Management Network (RMN) proxy address.
address internal immutable i_rmnProxy;
i_allowlistEnabled
Flag indicating if the pool uses access control.
bool internal immutable i_allowlistEnabled;
s_allowlist
Set of addresses authorized to initiate cross-chain operations.
EnumerableSet.AddressSet internal s_allowlist;
s_router
The CCIP Router contract address.
IRouter internal s_router;
s_remoteChainSelectors
Set of authorized chain selectors for cross-chain operations.
EnumerableSet.UintSet internal s_remoteChainSelectors;
s_remoteChainConfigs
Configuration for each remote chain, including rate limits and token details.
mapping(uint64 remoteChainSelector => RemoteChainConfig) internal s_remoteChainConfigs;
s_remotePoolAddresses
Maps hashed pool addresses to their original form for verification.
mapping(bytes32 poolAddressHash => bytes poolAddress) internal s_remotePoolAddresses;
s_rateLimitAdmin
The address authorized to manage rate limits.
address internal s_rateLimitAdmin;
Functions
_applyAllowListUpdates
Internal version of applyAllowListUpdates to allow for reuse in the constructor.
function _applyAllowListUpdates(address[] memory removes, address[] memory adds) internal;
Parameters
| Name | Type | Description |
|---|---|---|
removes | address[] | Array of addresses to remove from the allowlist |
adds | address[] | Array of addresses to add to the allowlist |
_calculateLocalAmount
Calculates the local amount based on the remote amount and decimals.
This function protects against overflows. If there is a transaction that hits the overflow check, it is probably incorrect as that means the amount cannot be represented on this chain. If the local decimals have been wrongly configured, the token issuer could redeploy the pool with the correct decimals and manually re-execute the CCIP tx to fix the issue.
function _calculateLocalAmount(uint256 remoteAmount, uint8 remoteDecimals) internal view virtual returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
remoteAmount | uint256 | The amount on the remote chain. |
remoteDecimals | uint8 | The decimals of the token on the remote chain. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The local amount. |
_checkAllowList
Internal function to verify if a sender is authorized when allowlist is enabled.
function _checkAllowList(address sender) internal view;
Parameters
| Name | Type | Description |
|---|---|---|
sender | address | The address to check for permission |
_consumeInboundRateLimit
Internal function to consume rate limiting capacity for incoming transfers.
function _consumeInboundRateLimit(uint64 remoteChainSelector, uint256 amount) internal;
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector for the source chain |
amount | uint256 | The amount of tokens being transferred |
_consumeOutboundRateLimit
Internal function to consume rate limiting capacity for outgoing transfers.
function _consumeOutboundRateLimit(uint64 remoteChainSelector, uint256 amount) internal;
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector for the destination chain |
amount | uint256 | The amount of tokens being transferred |
_encodeLocalDecimals
Internal function to encode the local token's decimals for cross-chain communication.
function _encodeLocalDecimals() internal view virtual returns (bytes memory);
Returns
| Type | Description |
|---|---|
bytes | ABI-encoded decimal places of the local token |
_onlyOffRamp
Checks whether remote chain selector is configured on this contract, and if the msg.sender is a permissioned offRamp for the given chain on the Router.
function _onlyOffRamp(uint64 remoteChainSelector) internal view;
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector to validate authorization for |
_onlyOnRamp
Checks whether remote chain selector is configured on this contract, and if the msg.sender is a permissioned onRamp for the given chain on the Router.
function _onlyOnRamp(uint64 remoteChainSelector) internal view;
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector to validate authorization for |
_parseRemoteDecimals
Internal function to decode the decimal configuration received from a remote chain.
function _parseRemoteDecimals(bytes memory sourcePoolData) internal view virtual returns (uint8);
Parameters
| Name | Type | Description |
|---|---|---|
sourcePoolData | bytes | The encoded decimal configuration data |
Returns
| Type | Description |
|---|---|
uint8 | The number of decimals used on the remote chain |
_setRateLimitConfig
Internal function to update rate limit configuration for a chain.
function _setRateLimitConfig(
uint64 remoteChainSelector,
RateLimiter.Config memory outboundConfig,
RateLimiter.Config memory inboundConfig
) internal;
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector to configure |
outboundConfig | RateLimiter.Config | Rate limit configuration for outgoing transfers |
inboundConfig | RateLimiter.Config | Rate limit configuration for incoming transfers |
_setRemotePool
Internal function to add a pool address to the allowed remote token pools for a chain. Called during chain configuration and when adding individual remote pools.
function _setRemotePool(uint64 remoteChainSelector, bytes memory remotePoolAddress) internal;
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector to add the pool for |
remotePoolAddress | bytes | The address of the remote pool (encoded to support non-EVM chains) |
_validateLockOrBurn
Internal function to validate lock or burn operations.
function _validateLockOrBurn(Pool.LockOrBurnInV1 calldata lockOrBurnIn) internal;
_validateReleaseOrMint
Internal function to validate release or mint operations.
function _validateReleaseOrMint(Pool.ReleaseOrMintInV1 calldata releaseOrMintIn) internal;
addRemotePool
Adds a new pool address for a remote chain.
function addRemotePool(uint64 remoteChainSelector, bytes calldata remotePoolAddress) external onlyOwner;
applyAllowListUpdates
Apply updates to the allow list.
function applyAllowListUpdates(address[] calldata removes, address[] calldata adds) external onlyOwner;
Parameters
| Name | Type | Description |
|---|---|---|
removes | address[] | The addresses to be removed. |
adds | address[] | The addresses to be added. |
applyChainUpdates
Updates chain configurations in bulk.
function applyChainUpdates(
uint64[] calldata remoteChainSelectorsToRemove,
ChainUpdate[] calldata chainsToAdd
) external virtual onlyOwner;
constructor
constructor(IERC20 token, uint8 localTokenDecimals, address[] memory allowlist, address rmnProxy, address router);
Parameters
| Name | Type | Description |
|---|---|---|
token | IERC20 | The token to be managed by this pool |
localTokenDecimals | uint8 | The token's decimal places on this chain |
allowlist | address[] | Initial set of authorized addresses (if any) |
rmnProxy | address | The Risk Management Network proxy address |
router | address | The CCIP Router contract address |
getAllowList
Gets the allowed addresses.
function getAllowList() external view returns (address[] memory);
Returns
| Name | Type | Description |
|---|---|---|
<none> | address[] | The allowed addresses. |
getAllowListEnabled
Returns whether allowlist functionality is active.
function getAllowListEnabled() external view returns (bool);
Returns
| Name | Type | Description |
|---|---|---|
<none> | bool | true is enabled, false if not. |
getCurrentInboundRateLimiterState
Returns the current state of inbound rate limiting for a chain.
function getCurrentInboundRateLimiterState(
uint64 remoteChainSelector
) external view returns (RateLimiter.TokenBucket memory);
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector to get rate limiter state for |
Returns
| Type | Description |
|---|---|
RateLimiter.TokenBucket | Current state of the inbound rate limiter |
getCurrentOutboundRateLimiterState
Returns the current state of outbound rate limiting for a chain.
function getCurrentOutboundRateLimiterState(
uint64 remoteChainSelector
) external view returns (RateLimiter.TokenBucket memory);
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector to get rate limiter state for |
Returns
| Type | Description |
|---|---|
RateLimiter.TokenBucket | Current state of the outbound rate limiter |
getRateLimitAdmin
Returns the current rate limit administrator address.
function getRateLimitAdmin() external view returns (address);
getRemotePools
Returns the configured pool addresses for a remote chain.
function getRemotePools(uint64 remoteChainSelector) public view returns (bytes[] memory);
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The remote chain identifier |
Returns
| Type | Description |
|---|---|
bytes[] | Array of encoded pool addresses on remote chain |
getRemoteToken
Returns the token address on a remote chain.
function getRemoteToken(uint64 remoteChainSelector) public view returns (bytes memory);
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The remote chain identifier |
Returns
| Type | Description |
|---|---|
bytes | The encoded token address on the remote chain |
getRmnProxy
Returns the Risk Management Network proxy address.
function getRmnProxy() public view returns (address rmnProxy);
Returns
| Type | Description |
|---|---|
address | The RMN proxy contract address |
getRouter
Returns the current router address.
function getRouter() public view returns (address router);
Returns
| Type | Description |
|---|---|
address | The CCIP router contract address |
getSupportedChains
Returns all configured chain selectors.
function getSupportedChains() public view returns (uint64[] memory);
Returns
| Type | Description |
|---|---|
uint64[] | Array of configured chain selectors |
getToken
Returns the token managed by this pool.
function getToken() public view returns (IERC20 token);
Returns
| Type | Description |
|---|---|
IERC20 | The token contract address |
getTokenDecimals
Returns the number of decimals for the managed token.
function getTokenDecimals() public view virtual returns (uint8 decimals);
Returns
| Type | Description |
|---|---|
uint8 | The number of decimal places for the token |
isRemotePool
Verifies if a pool address is configured for a remote chain.
function isRemotePool(uint64 remoteChainSelector, bytes calldata remotePoolAddress) public view returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The remote chain identifier |
remotePoolAddress | bytes | The pool address to verify |
Returns
| Type | Description |
|---|---|
bool | True if the pool is configured for the chain |
isSupportedChain
Checks if a chain is configured in the pool.
function isSupportedChain(uint64 remoteChainSelector) public view returns (bool);
Returns
| Type | Description |
|---|---|
bool | True if the chain is configured in the pool |
isSupportedToken
Checks if a given token is supported by this pool.
function isSupportedToken(address token) public view virtual returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
token | address | The token address to check |
Returns
| Type | Description |
|---|---|
bool | True if the token is supported by this pool |
removeRemotePool
Removes a pool address from a remote chain's configuration.
function removeRemotePool(uint64 remoteChainSelector, bytes calldata remotePoolAddress) external onlyOwner;
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The chain selector to remove the pool from |
remotePoolAddress | bytes | The address of the pool to remove |
setChainRateLimiterConfig
Sets the chain rate limiter config.
function setChainRateLimiterConfig(
uint64 remoteChainSelector,
RateLimiter.Config memory outboundConfig,
RateLimiter.Config memory inboundConfig
) external;
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelector | uint64 | The remote chain selector for which the rate limits apply. |
outboundConfig | RateLimiter.Config | The new outbound rate limiter config, meaning the onRamp rate limits for the given chain. |
inboundConfig | RateLimiter.Config | The new inbound rate limiter config, meaning the offRamp rate limits for the given chain. |
setChainRateLimiterConfigs
Updates rate limit configurations for multiple chains.
function setChainRateLimiterConfigs(
uint64[] calldata remoteChainSelectors,
RateLimiter.Config[] calldata outboundConfigs,
RateLimiter.Config[] calldata inboundConfigs
) external;
Parameters
| Name | Type | Description |
|---|---|---|
remoteChainSelectors | uint64[] | The chain selectors to configure |
outboundConfigs | RateLimiter.Config[] | The new outbound rate limiter configs, meaning the onRamp rate limits for the given chains |
inboundConfigs | RateLimiter.Config[] | The new inbound rate limiter configs, meaning the offRamp rate limits for the given chains |
setRateLimitAdmin
Sets the address authorized to manage rate limits.
function setRateLimitAdmin(address rateLimitAdmin) external onlyOwner;
setRouter
Updates the router contract address.
function setRouter(address newRouter) public onlyOwner;
Parameters
| Name | Type | Description |
|---|---|---|
newRouter | address | The new router contract address |
supportsInterface
Implements ERC165 interface detection.
function supportsInterface(bytes4 interfaceId) public pure virtual override returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
interfaceId | bytes4 | The interface identifier to check |
Returns
| Type | Description |
|---|---|
bool | True if the contract implements the interface |