TokenPool API Reference
TokenPool
The TokenPool contract is an abstract base class that defines common functionality for all token pools within the CCIP ecosystem. A token pool acts as an isolated location for holding tokens and executing token-specific logic, especially as tokens move across chains in a cross-chain interoperability setup. The contract implements validation mechanisms to ensure that tokens are securely transferred, burned, or locked when they are transferred between blockchains.
Errors
CallerIsNotARampOnRouter
error CallerIsNotARampOnRouter(address caller)
ZeroAddressNotAllowed
error ZeroAddressNotAllowed()
SenderNotAllowed
error SenderNotAllowed(address sender)
AllowListNotEnabled
error AllowListNotEnabled()
NonExistentChain
error NonExistentChain(uint64 remoteChainSelector)
ChainNotAllowed
error ChainNotAllowed(uint64 remoteChainSelector)
CursedByRMN
error CursedByRMN()
ChainAlreadyExists
error ChainAlreadyExists(uint64 chainSelector)
InvalidSourcePoolAddress
error InvalidSourcePoolAddress(bytes sourcePoolAddress)
InvalidToken
error InvalidToken(address token)
Unauthorized
error Unauthorized(address caller)
Events
Locked
event Locked(address sender, uint256 amount)
Burned
event Burned(address sender, uint256 amount)
Released
event Released(address sender, address recipient, uint256 amount)
Minted
event Minted(address sender, address recipient, uint256 amount)
ChainAdded
event ChainAdded(uint64 remoteChainSelector, bytes remoteToken, struct RateLimiter.Config outboundRateLimiterConfig, struct RateLimiter.Config inboundRateLimiterConfig)
ChainConfigured
event ChainConfigured(uint64 remoteChainSelector, struct RateLimiter.Config outboundRateLimiterConfig, struct RateLimiter.Config inboundRateLimiterConfig)
ChainRemoved
event ChainRemoved(uint64 remoteChainSelector)
RemotePoolSet
event RemotePoolSet(uint64 remoteChainSelector, bytes previousPoolAddress, bytes remotePoolAddress)
AllowListAdd
event AllowListAdd(address sender)
AllowListRemove
event AllowListRemove(address sender)
RouterUpdated
event RouterUpdated(address oldRouter, address newRouter)
Structs
ChainUpdate
struct ChainUpdate {
uint64 remoteChainSelector;
bool allowed;
bytes remotePoolAddress;
bytes remoteTokenAddress;
struct RateLimiter.Config outboundRateLimiterConfig;
struct RateLimiter.Config inboundRateLimiterConfig;
}
| Name | Type | Description |
|---|---|---|
| remoteChainSelector | uint64 | Remote chain selector. |
| allowed | bool | Whether the chain should be enabled. |
| remotePoolAddress | bytes | Address of the remote pool, ABI encoded in the case of a remote EVM chain. |
| remoteTokenAddress | bytes | Address of the remote token, ABI encoded in the case of a remote EVM chain. |
| outboundRateLimiterConfig | RateLimiter.Config | Outbound rate limited config, meaning the rate limits for all of the onRamps for the given chain. |
| inboundRateLimiterConfig | RateLimiter.Config | Inbound rate limited config, meaning the rate limits for all of the offRamps for the given chain. |
RemoteChainConfig
struct RemoteChainConfig {
struct RateLimiter.TokenBucket outboundRateLimiterConfig;
struct RateLimiter.TokenBucket inboundRateLimiterConfig;
bytes remotePoolAddress;
bytes remoteTokenAddress;
}
| Name | Type | Description |
|---|---|---|
| outboundRateLimiterConfig | RateLimiter.TokenBucket | Outbound rate limited config, meaning the rate limits for all of the onRamps for the given chain. |
| inboundRateLimiterConfig | RateLimiter.TokenBucket | Inbound rate limited config, meaning the rate limits for all of the offRamps for the given chain. |
| remotePoolAddress | bytes | Address of the remote pool, ABI encoded in the case of a remote EVM chain. |
| remoteTokenAddress | bytes | Address of the remote token, ABI encoded in the case of a remote EVM chain. |
Variables
i_token
IERC20 i_token
The bridgeable token that is managed by this pool.
i_rmnProxy
address i_rmnProxy
The address of the RMN proxy.
i_allowlistEnabled
bool i_allowlistEnabled
The immutable flag that indicates if the pool is access-controlled.
Mappings
s_allowList
struct EnumerableSet.AddressSet s_allowList
A set of addresses allowed to trigger lockOrBurn as original senders. Only takes effect if i_allowlistEnabled is true.
s_router
contract IRouter s_router
The address of the router.
s_remoteChainSelectors
struct EnumerableSet.UintSet s_remoteChainSelectors
A set of allowed chain selectors.
s_remoteChainConfigs
mapping(uint64 => struct TokenPool.RemoteChainConfig) s_remoteChainConfigs
s_rateLimitAdmin
address s_rateLimitAdmin
The address of the rate limiter admin. Can be address(0) if none is configured.
Functions
constructor
constructor(contract IERC20 token, address[] allowlist, address rmnProxy, address router) internal
getRmnProxy
function getRmnProxy() public view returns (address rmnProxy)
Gets the RMN proxy address.
Return Values
| Name | Type | Description |
|---|---|---|
| rmnProxy | address | Address of RMN proxy. |
isSupportedToken
function isSupportedToken(address token) public view virtual returns (bool)
Returns if the token pool supports the given token.
Parameters
| Name | Type | Description |
|---|---|---|
| token | address | The address of the token. |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | bool | true if the token is supported. |
getToken
function getToken() public view returns (contract IERC20 token)
Gets the IERC20 token that this pool can lock or burn.
Return Values
| Name | Type | Description |
|---|---|---|
| token | IERC20 | The IERC20 token. |
getRouter
function getRouter() public view returns (address router)
Gets the pool's Router.
Return Values
| Name | Type | Description |
|---|---|---|
| router | address | The pool's Router. |
setRouter
function setRouter(address newRouter) public
Sets the pool's Router.
Parameters
| Name | Type | Description |
|---|---|---|
| newRouter | address | The new Router address. |
supportsInterface
function supportsInterface(bytes4 interfaceId) public pure virtual returns (bool)
Signals which version of the pool interface is supported.
_validateLockOrBurn
function _validateLockOrBurn(struct Pool.LockOrBurnInV1 lockOrBurnIn) internal
Validates the lock or burn input for correctness.
Parameters
| Name | Type | Description |
|---|---|---|
| lockOrBurnIn | struct Pool.LockOrBurnInV1 | The input to validate. |
_validateReleaseOrMint
function _validateReleaseOrMint(struct Pool.ReleaseOrMintInV1 releaseOrMintIn) internal
Validates the release or mint input for correctness.
Parameters
| Name | Type | Description |
|---|---|---|
| releaseOrMintIn | struct Pool.ReleaseOrMintInV1 | The input to validate. |
getRemotePool
function getRemotePool(uint64 remoteChainSelector) public view returns (bytes)
Gets the pool address on the remote chain.
Parameters
| Name | Type | Description |
|---|---|---|
| remoteChainSelector | uint64 | Remote chain selector. |
getRemoteToken
function getRemoteToken(uint64 remoteChainSelector) public view returns (bytes)
Gets the token address on the remote chain.
Parameters
| Name | Type | Description |
|---|---|---|
| remoteChainSelector | uint64 | Remote chain selector. |
setRemotePool
function setRemotePool(uint64 remoteChainSelector, bytes remotePoolAddress) external
Sets the remote pool address for a given chain selector.
Parameters
| Name | Type | Description |
|---|---|---|
| remoteChainSelector | uint64 | The remote chain selector. |
| remotePoolAddress | bytes | The address of the remote pool. |
isSupportedChain
function isSupportedChain(uint64 remoteChainSelector) public view returns (bool)
Checks whether a remote chain is supported in the token pool.
Parameters
| Name | Type | Description |
|---|---|---|
| remoteChainSelector | uint64 | Remote chain selector. |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | bool | true if the chain is supported by the pool. |
getSupportedChains
function getSupportedChains() public view returns (uint64[] memory)
Gets the list of allowed chains.
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | uint64[] | List of allowed chains. |
applyChainUpdates
function applyChainUpdates(ChainUpdate[] calldata chains) external virtual onlyOwner
Sets the permissions for a list of chain selectors. The senders for these chains must be allowed on the Router to interact with this pool.
Parameters
| Name | Type | Description |
|---|---|---|
| chains | ChainUpdate[] calldata | A list of chains and their permission status & rate limits. |
setRateLimitAdmin
function setRateLimitAdmin(address rateLimitAdmin) external onlyOwner
Sets the rate limiter admin address.
Parameters
| Name | Type | Description |
|---|---|---|
| rateLimitAdmin | address | The new rate limiter admin address. |
getRateLimitAdmin
function getRateLimitAdmin() external view returns (address)
Gets the rate limiter admin address.
Return Values
| Name | Type | Description |
|---|---|---|
| rateLimitAdmin | address | The current rate limiter admin address. |
getCurrentOutboundRateLimiterState
function getCurrentOutboundRateLimiterState(uint64 remoteChainSelector) external view returns (RateLimiter.TokenBucket)
Gets the token bucket state for outbound rate limits.
Parameters
| Name | Type | Description |
|---|---|---|
| remoteChainSelector | uint64 | Remote chain selector. |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | RateLimiter.TokenBucket | The current state of the outbound rate limiter. |
getCurrentInboundRateLimiterState
function getCurrentInboundRateLimiterState(uint64 remoteChainSelector) external view returns (RateLimiter.TokenBucket)
Gets the token bucket state for inbound rate limits.
Parameters
| Name | Type | Description |
|---|---|---|
| remoteChainSelector | uint64 | Remote chain selector. |
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | RateLimiter.TokenBucket | The current state of the inbound rate limiter. |
setChainRateLimiterConfig
function setChainRateLimiterConfig(
uint64 remoteChainSelector,
RateLimiter.Config memory outboundConfig,
RateLimiter.Config memory inboundConfig
) external
Sets the chain rate limiter config.
Parameters
| Name | Type | Description |
|---|---|---|
| remoteChainSelector | uint64 | Remote chain selector. |
| outboundConfig | RateLimiter.Config | Outbound rate limiter configuration. |
| inboundConfig | RateLimiter.Config | Inbound rate limiter configuration. |
getAllowListEnabled
function getAllowListEnabled() external view returns (bool)
Gets whether the allowList functionality is enabled.
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | bool | true if the allowList is enabled. |
getAllowList
function getAllowList() external view returns (address[] memory)
Gets the list of allowed addresses in the allowlist.
Return Values
| Name | Type | Description |
|---|---|---|
| [0] | address[] | List of allowed addresses. |
applyAllowListUpdates
function applyAllowListUpdates(address[] calldata removes, address[] calldata adds) external onlyOwner
Applies updates to the allow list.
Parameters
| Name | Type | Description |
|---|---|---|
| removes | address[] | Addresses to remove from the allowlist. |
| adds | address[] | Addresses to add to the allowlist. |