Documentation Home

CCIP v2.0.0 USDCTokenPoolProxy API Reference

Summary

USDCTokenPoolProxy is a forwarding pool that routes USDC lockOrBurn and releaseOrMint flows to specific child pool implementations.

It:

  • Implements [IPoolV1V2](/ccip/evm/api-reference/v2.0.0/i-pool-v1-v2)
  • Does not inherit [TokenPool](/ccip/evm/api-reference/v2.0.0/token-pool)
  • Forwards calls using call
  • Selects child pools based on:
    • LockOrBurnMechanism
    • Version tag prefix embedded in sourcePoolData

Supported routing targets:

  • CCTP v1 pool
  • CCTP v2 pool
  • CCTP v2 with CCV
  • Siloed lock-release pool

Contract

chains/evm/contracts/pools/usdc/USDCTokenPoolProxy.sol

Import

import {USDCTokenPoolProxy} from "chainlink-ccip/chains/evm/contracts/pools/usdc/USDCTokenPoolProxy.sol";

Target + upgrade model

This contract is not a storage proxy.

  • All calls are forwarded via call
  • No delegatecall is used
  • State is isolated from child pools
  • Owner can update child pool addresses

Inheritance

contract USDCTokenPoolProxy
  is IPoolV1V2,
     Ownable2StepMsgSender,
     ITypeAndVersion

typeAndVersion

string public constant override typeAndVersion =
  "USDCTokenPoolProxy 2.0.0";

State

Constants

uint16 internal constant WAIT_FOR_FINALITY = 0;

Immutables

IERC20 internal immutable i_token;
IRouter internal immutable i_router;
ICrossChainVerifierResolver internal immutable i_cctpVerifier;

Storage

mapping(uint64 => LockOrBurnMechanism)
  internal s_lockOrBurnMechanism;

address internal s_cctpV1Pool;
address internal s_cctpV2Pool;
address internal s_cctpV2PoolWithCCV;
address internal s_siloedLockReleasePool;

address internal s_feeAggregator;

Structs & Enums

LockOrBurnMechanism

enum LockOrBurnMechanism {
  NONE,
  CCTP_V1,
  CCTP_V2,
  CCTP_V2_CCV,
  LOCK_RELEASE
}

PoolAddresses

struct PoolAddresses {
  address cctpV1Pool;
  address cctpV2Pool;
  address cctpV2PoolWithCCV;
  address siloedLockReleasePool;
}

External API (forwarded surface)

lockOrBurn (V1)

function lockOrBurn(
  Pool.LockOrBurnInV1 calldata lockOrBurnIn
)
  public
  override
  returns (Pool.LockOrBurnOutV1 memory)
  • Requires caller equals i_router.getOnRamp(...)
  • Routes according to s_lockOrBurnMechanism
  • Reverts if no mechanism configured

lockOrBurn (V2)

function lockOrBurn(
  Pool.LockOrBurnInV1 calldata lockOrBurnIn,
  bytes4 requestedFinalityConfig,
  bytes memory tokenArgs
)
  public
  override
  returns (Pool.LockOrBurnOutV1 memory, uint256)
  • Supports CCV and LOCK_RELEASE mechanisms
  • Resolves outbound verifier via i_cctpVerifier

releaseOrMint (V1)

function releaseOrMint(
  Pool.ReleaseOrMintInV1 calldata releaseOrMintIn
)
  public
  override
  returns (Pool.ReleaseOrMintOutV1 memory)
  • Requires caller equals authorized OffRamp
  • Extracts version tag from sourcePoolData
  • Routes accordingly

releaseOrMint (V2)

function releaseOrMint(
  Pool.ReleaseOrMintInV1 calldata releaseOrMintIn,
  bytes4 requestedFinalityConfig
)
  public
  override
  returns (Pool.ReleaseOrMintOutV1 memory)
  • Supports CCV and LOCK_RELEASE
  • Routes based on version tag

getFee

Delegates to underlying pool supporting V2.

getStaticConfig

function getStaticConfig() external view returns (address token, address router, address cctpVerifier)

Returns the token, router, and CCTP verifier addresses the proxy was constructed with.

getPools

function getPools() public view returns (PoolAddresses memory)

Returns the current pool addresses the proxy routes to: cctpV1Pool, cctpV2Pool, cctpV2PoolWithCCV, and siloedLockReleasePool.

getLockOrBurnMechanism

function getLockOrBurnMechanism(
  uint64 remoteChainSelector
) public view returns (LockOrBurnMechanism)

Returns the lock or burn mechanism for a remote chain, including CCTP V1/V2 and Lock/Release.

isSupportedChain

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

Returns true if a lock or burn mechanism is set for the chain. A chain with no mechanism is not supported.

isSupportedToken

function isSupportedToken(address token) external view returns (bool)

Returns true if token is the token the proxy was constructed with.

getToken

function getToken() public view returns (IERC20 token)

Returns the token this pool can lock or burn.

getTokenTransferFeeConfig

function getTokenTransferFeeConfig(
  address localToken,
  uint64 destChainSelector,
  bytes4 requestedFinalityConfig,
  bytes calldata tokenArgs
) external view

Returns the token transfer fee config for a destination lane. Delegates to the underlying pool.

getRemoteToken

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

Returns the remote token address for a remote chain.

getRemotePools

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

Returns the pool addresses on the remote chain.

getRequiredCCVs

function getRequiredCCVs(
  address localToken,
  uint64 remoteChainSelector,
  uint256 amount,
  bytes4 requestedFinalityConfig,
  bytes calldata extraData,
  IPoolV2.MessageDirection direction
) external view returns (address[] memory)

Returns the CCVs required for a transfer. Delegates to the underlying pool for the mechanism.

getFeeAggregator

function getFeeAggregator() external view returns (address)

Returns the current fee aggregator address.

setFeeAggregator

function setFeeAggregator(address feeAggregator) external onlyOwner

Sets the fee aggregator that receives withdrawn fees.

supportsInterface

function supportsInterface(bytes4 interfaceId) external view returns (bool)

Returns true for the pool interfaces the proxy implements.

updatePoolAddresses

function updatePoolAddresses(
  PoolAddresses calldata pools
)
  external
  onlyOwner

updateLockOrBurnMechanisms

function updateLockOrBurnMechanisms(
  uint64[] calldata chainSelectors,
  LockOrBurnMechanism[] calldata mechanisms
)
  external
  onlyOwner

Reverts MismatchedArrayLengths() if the arrays differ in length, and MustSetPoolForMechanism(chainSelector, mechanism) if a mechanism is set whose pool address has not been set via updatePoolAddresses.

withdrawFeeTokens

function withdrawFeeTokens(
  address[] calldata feeTokens
) external

Permissionless. Forwards to FeeTokenHandler.

Events

event LockOrBurnMechanismUpdated(
  uint64 indexed remoteChainSelector,
  LockOrBurnMechanism mechanism
);

event PoolAddressesUpdated(PoolAddresses pools);

Errors

error AddressCannotBeZero();
error ChainNotSupportedByVerifier(uint64 remoteChainSelector);
error InvalidLockOrBurnMechanism(LockOrBurnMechanism mechanism);
error InvalidMessageVersion(bytes4 version);
error MismatchedArrayLengths();
error NoLockOrBurnMechanismSet(uint64 remoteChainSelector);
error CallerIsNotARampOnRouter(address caller);
error TokenPoolUnsupported(address pool);
error MustSetPoolForMechanism(
  uint64 remoteChainSelector,
  LockOrBurnMechanism mechanism
);

Security model

  • Owner controls routing configuration.
  • Router enforces ramp authorization.
  • No delegatecall: child pool storage remains isolated.
  • Version tag must match expected child pool semantics.
  • Misconfiguration can halt lane until corrected.

Related Interfaces & Contracts

Get the latest Chainlink content straight to your inbox.