CCIP v1.5.1 TokenPool Contract API Reference

The TokenPool abstract contract provides base functionality for token pools in CCIP, handling cross-chain token transfers with decimal adjustments and rate limiting.

Errors

CallerIsNotARampOnRouter

error CallerIsNotARampOnRouter(address caller)

Thrown when caller is not a valid ramp on router.

ZeroAddressNotAllowed

error ZeroAddressNotAllowed()

Thrown when a zero address is provided.

SenderNotAllowed

error SenderNotAllowed(address sender)

Thrown when sender is not on allowlist.

AllowListNotEnabled

error AllowListNotEnabled()

Thrown when trying to use allowlist features while disabled.

NonExistentChain

error NonExistentChain(uint64 remoteChainSelector)

Thrown when chain selector doesn't exist.

ChainNotAllowed

error ChainNotAllowed(uint64 remoteChainSelector)

Thrown when chain is not configured.

CursedByRMN

error CursedByRMN()

Thrown when RMN has cursed the operation.

ChainAlreadyExists

error ChainAlreadyExists(uint64 chainSelector)

Thrown when adding an existing chain.

InvalidSourcePoolAddress

error InvalidSourcePoolAddress(bytes sourcePoolAddress)

Thrown when source pool address is invalid.

InvalidToken

error InvalidToken(address token)

Thrown when token is not supported.

Unauthorized

error Unauthorized(address caller)

Thrown when caller lacks required permissions.

PoolAlreadyAdded

error PoolAlreadyAdded(uint64 remoteChainSelector, bytes remotePoolAddress)

Thrown when attempting to add an already existing pool.

InvalidRemotePoolForChain

error InvalidRemotePoolForChain(uint64 remoteChainSelector, bytes remotePoolAddress)

Thrown when remote pool configuration is invalid for the specified chain.

InvalidRemoteChainDecimals

error InvalidRemoteChainDecimals(bytes sourcePoolData)

Thrown when remote chain decimals data is invalid.

OverflowDetected

error OverflowDetected(uint8 remoteDecimals, uint8 localDecimals, uint256 remoteAmount)

Thrown when decimal conversion would result in overflow.

InvalidDecimalArgs

error InvalidDecimalArgs(uint8 expected, uint8 actual)

Thrown when provided decimal arguments don't match expected values.

Events

Locked

event Locked(address indexed sender, uint256 amount)

Emitted when tokens are locked in the pool.

Burned

event Burned(address indexed sender, uint256 amount)

Emitted when tokens are burned.

Released

event Released(address indexed sender, address indexed recipient, uint256 amount)

Emitted when tokens are released from the pool.

Minted

event Minted(address indexed sender, address indexed recipient, uint256 amount)

Emitted when tokens are minted.

ChainAdded

event ChainAdded(
    uint64 remoteChainSelector,
    bytes remoteToken,
    RateLimiter.Config outboundRateLimiterConfig,
    RateLimiter.Config inboundRateLimiterConfig
)

Emitted when a new chain is added to the pool.

ChainConfigured

event ChainConfigured(
    uint64 remoteChainSelector,
    RateLimiter.Config outboundRateLimiterConfig,
    RateLimiter.Config inboundRateLimiterConfig
)

Emitted when a chain's configuration is updated.

ChainRemoved

event ChainRemoved(uint64 remoteChainSelector)

Emitted when a chain is removed from the pool.

RemotePoolAdded

event RemotePoolAdded(uint64 indexed remoteChainSelector, bytes remotePoolAddress)

Emitted when a remote pool is added.

RemotePoolRemoved

event RemotePoolRemoved(uint64 indexed remoteChainSelector, bytes remotePoolAddress)

Emitted when a remote pool is removed.

AllowListAdd

event AllowListAdd(address sender)

Emitted when an address is added to the allowlist.

AllowListRemove

event AllowListRemove(address sender)

Emitted when an address is removed from the allowlist.

RouterUpdated

event RouterUpdated(address oldRouter, address newRouter)

Emitted when the router address is updated.

RateLimitAdminSet

event RateLimitAdminSet(address rateLimitAdmin)

Emitted when the rate limit admin is set.

Structs

ChainUpdate

struct ChainUpdate {
  uint64 remoteChainSelector;
  bytes[] remotePoolAddresses;
  bytes remoteTokenAddress;
  RateLimiter.Config outboundRateLimiterConfig;
  RateLimiter.Config inboundRateLimiterConfig;
}

Functions

constructor

constructor(
    IERC20 token,
    uint8 localTokenDecimals,
    address[] memory allowlist,
    address rmnProxy,
    address router
)

Initializes the token pool with the specified parameters.

Parameters

Chain Management

function applyChainUpdates(
    uint64[] calldata remoteChainSelectorsToRemove,
    ChainUpdate[] calldata chainsToAdd
) external onlyOwner

Updates supported chains and their configurations.

Rate Limiting

function setChainRateLimiterConfig(
    uint64 remoteChainSelector,
    RateLimiter.Config memory outboundConfig,
    RateLimiter.Config memory inboundConfig
) external

Sets rate limiting configuration for a chain.

Validation

function _validateLockOrBurn(
    Pool.LockOrBurnInV1 calldata lockOrBurnIn
) internal

Validates lock/burn operations for:

• Token validity
• RMN curse status
• Allowlist status
• OnRamp validity
• Rate limits

Decimal Handling

function _calculateLocalAmount(
    uint256 remoteAmount,
    uint8 remoteDecimals
) internal view returns (uint256)

Calculates local token amounts based on remote amounts and decimals, with overflow protection.

Token Management

isSupportedToken

function isSupportedToken(
    address token
) public view virtual returns (bool)

Checks if the given token is supported by this pool.

Parameters

Return Value

getToken

function getToken() public view returns (IERC20 token)

Gets the IERC20 token that this pool can lock or burn.

Return Value

Router Management

getRmnProxy

function getRmnProxy() public view returns (address rmnProxy)

Gets the RMN proxy address.

Return Value

getRouter

function getRouter() public view returns (address router)

Gets the pool's Router address.

Return Value

setRouter

function setRouter(
    address newRouter
) public onlyOwner

Sets the pool's Router address.

Parameters

Interface Support

supportsInterface

function supportsInterface(
    bytes4 interfaceId
) public pure virtual override returns (bool)

Signals which version of the pool interface is supported.

Parameters

Return Value

Validation Functions

_validateLockOrBurn

function _validateLockOrBurn(
    Pool.LockOrBurnInV1 calldata lockOrBurnIn
) internal

Validates lock or burn operations for security and configuration requirements.

Parameters

_validateReleaseOrMint

function _validateReleaseOrMint(
    Pool.ReleaseOrMintInV1 calldata releaseOrMintIn
) internal

Validates release or mint operations for security and configuration requirements.

Parameters

Token Decimals Functions

getTokenDecimals

function getTokenDecimals() public view virtual returns (uint8 decimals)

Gets the IERC20 token decimals on the local chain.

Return Value

_encodeLocalDecimals

function _encodeLocalDecimals() internal view virtual returns (bytes memory)

Encodes the local token decimals for cross-chain communication.

Return Value

_parseRemoteDecimals

function _parseRemoteDecimals(
    bytes memory sourcePoolData
) internal view virtual returns (uint8)

Parses the remote chain's token decimals from the source pool data.

Parameters

Return Value

_calculateLocalAmount

function _calculateLocalAmount(
    uint256 remoteAmount,
    uint8 remoteDecimals
) internal view virtual returns (uint256)

Calculates the local amount based on remote amount and decimals.

Parameters

Return Value

Chain Permissions Functions

getRemotePools

function getRemotePools(
    uint64 remoteChainSelector
) public view returns (bytes[] memory)

Gets the pool addresses on the remote chain.

Parameters

Return Value

isRemotePool

function isRemotePool(
    uint64 remoteChainSelector,
    bytes calldata remotePoolAddress
) public view returns (bool)

Checks if a pool address is configured on the remote chain.

Parameters

Return Value

getRemoteToken

function getRemoteToken(
    uint64 remoteChainSelector
) public view returns (bytes memory)

Gets the token address on the remote chain.

Parameters

Return Value

addRemotePool

function addRemotePool(
    uint64 remoteChainSelector,
    bytes calldata remotePoolAddress
) external onlyOwner

Adds a remote pool for a given chain selector. Useful when a pool is upgraded on the remote chain.

Parameters

removeRemotePool

function removeRemotePool(
    uint64 remoteChainSelector,
    bytes calldata remotePoolAddress
) external onlyOwner

Removes a remote pool address for a given chain selector.

Parameters

Chain Support Functions

isSupportedChain

function isSupportedChain(
    uint64 remoteChainSelector
) public view returns (bool)

Checks if a chain is supported.

Parameters

Return Value

getSupportedChains

function getSupportedChains() public view returns (uint64[] memory)

Gets list of all supported chains.

Return Value

applyChainUpdates

function applyChainUpdates(
    uint64[] calldata remoteChainSelectorsToRemove,
    ChainUpdate[] calldata chainsToAdd
) external virtual onlyOwner

Updates chain permissions and configurations.

Parameters

Rate Limiting Functions

setRateLimitAdmin

function setRateLimitAdmin(
    address rateLimitAdmin
) external onlyOwner

Sets the rate limiter admin address.

Parameters

getRateLimitAdmin

function getRateLimitAdmin() external view returns (address)

Gets the rate limiter admin address.

Return Value

getCurrentOutboundRateLimiterState

function getCurrentOutboundRateLimiterState(
    uint64 remoteChainSelector
) external view returns (RateLimiter.TokenBucket memory)

Gets the current outbound token bucket state.

Parameters

Return Value

getCurrentInboundRateLimiterState

function getCurrentInboundRateLimiterState(
    uint64 remoteChainSelector
) external view returns (RateLimiter.TokenBucket memory)

Gets the current inbound token bucket state.

Parameters

Return Value

setChainRateLimiterConfig

function setChainRateLimiterConfig(
    uint64 remoteChainSelector,
    RateLimiter.Config memory outboundConfig,
    RateLimiter.Config memory inboundConfig
) external

Sets the chain rate limiter configuration.

Parameters

Access Control Functions

_onlyOnRamp

function _onlyOnRamp(
    uint64 remoteChainSelector
) internal view

Validates that msg.sender is a permissioned onRamp for the given chain.

Parameters

_onlyOffRamp

function _onlyOffRamp(
    uint64 remoteChainSelector
) internal view

Validates that msg.sender is a permissioned offRamp for the given chain.

Parameters

Allowlist Functions

getAllowListEnabled

function getAllowListEnabled() external view returns (bool)

Checks if allowlist functionality is enabled.

Return Value

getAllowList

function getAllowList() external view returns (address[] memory)

Gets all allowed addresses.

Return Value

applyAllowListUpdates

function applyAllowListUpdates(
    address[] calldata removes,
    address[] calldata adds
) external onlyOwner

Updates the allowlist by adding and removing addresses.

Parameters