TokenController

Manages token pair mappings and burn limits for cross-chain transfers

The TokenController contract provides token configuration management for CCTP, including mapping local tokens to remote tokens across domains and setting per-message burn limits.

Contract: src/roles/TokenController.sol

Key Concepts

• Token Pairs: Links between local tokens and their corresponding remote domain tokens
• Burn Limits: Maximum amount of each token that can be burned per message
• Token Controller Role: Authorized address that manages token configuration

State Variables

burnLimitsPerMessage

mapping(address => uint256) public burnLimitsPerMessage

Maps local token addresses to their maximum burn amount per message.

Key: Local token address
Value: Maximum burn amount per message (in token’s smallest unit)

Usage: A burn limit of 0 means the token is not supported for burning.

remoteTokensToLocalTokens

mapping(bytes32 => address) public remoteTokensToLocalTokens

Maps remote domain and token pairs to local token addresses.

Key: keccak256(abi.encodePacked(remoteDomain, remoteToken))
Value: Local token address

Usage: Enables validation and minting when receiving messages from remote domains.

_tokenController

address private _tokenController

Private state variable storing the address of the token controller.

Functions

linkTokenPair

function linkTokenPair(
    address localToken,
    uint32 remoteDomain,
    bytes32 remoteToken
) external onlyTokenController

Links a pair of local and remote tokens to be supported by the TokenMinter.

Parameters:

• localToken: Address of the local token
• remoteDomain: Domain ID of the remote chain
• remoteToken: Address of the token on the remote domain (as bytes32)

Requirements:

• Caller must be the token controller
• Remote token must not already be linked to a local token

Emits: TokenPairLinked(address localToken, uint32 remoteDomain, bytes32 remoteToken)

Source: TokenController.sol:126

Note:

• A remote token can only map to one local token
• Multiple remote tokens can map to the same local token
• Linking does not enable deposits (must also call setMaxBurnAmountPerMessage)

unlinkTokenPair

function unlinkTokenPair(
    address localToken,
    uint32 remoteDomain,
    bytes32 remoteToken
) external onlyTokenController

Removes the link between a local token and a remote token.

Parameters:

• localToken: Address of the local token
• remoteDomain: Domain ID of the remote chain
• remoteToken: Address of the token on the remote domain (as bytes32)

Requirements:

• Caller must be the token controller
• Token pair must currently be linked

Emits: TokenPairUnlinked(address localToken, uint32 remoteDomain, bytes32 remoteToken)

Source: TokenController.sol:157

Note: Unlinking does not disable burning the local token (must separately call setMaxBurnAmountPerMessage with 0)

setMaxBurnAmountPerMessage

function setMaxBurnAmountPerMessage(
    address localToken,
    uint256 burnLimitPerMessage
) external onlyTokenController

Sets the maximum burn amount per message for a given local token.

Parameters:

• localToken: Address of the local token
• burnLimitPerMessage: Maximum burn amount per message (0 to disable burning)

Requirements:

• Caller must be the token controller

Emits: SetBurnLimitPerMessage(address indexed token, uint256 burnLimitPerMessage)

Source: TokenController.sol:186

Important:

• Burns exceeding this limit will revert
• Mints do not respect this limit
• Reducing the limit does not affect previously burned tokens (they can still be minted)
• Setting to 0 disables burning for that token

tokenController

function tokenController() external view returns (address)

Returns the address of the token controller.

Returns: Address of the current token controller

Source: TokenController.sol:113

Internal Functions

_setTokenController

function _setTokenController(address newTokenController) internal

Internal function to set the token controller address.

Parameters:

• newTokenController: Address of the new token controller

Requirements:

• New token controller must be non-zero address

Emits: SetTokenController(address tokenController)

Source: TokenController.sol:202

_getLocalToken

function _getLocalToken(
    uint32 remoteDomain,
    bytes32 remoteToken
) internal view returns (address)

Gets the local token associated with a remote domain and token.

Parameters:

• remoteDomain: Domain ID of the remote chain
• remoteToken: Address of the token on the remote domain (as bytes32)

Returns: Local token address, or zero address if not linked

Source: TokenController.sol:217

_hashRemoteDomainAndToken

function _hashRemoteDomainAndToken(
    uint32 remoteDomain,
    bytes32 remoteToken
) internal pure returns (bytes32)

Hashes a remote domain and token address together.

Parameters:

• remoteDomain: Domain ID of the remote chain
• remoteToken: Address of the token on the remote domain (as bytes32)

Returns: Keccak256 hash of packed remote domain and token

Source: TokenController.sol:235

Modifiers

onlyTokenController

modifier onlyTokenController()

Restricts function access to the token controller only.

Reverts: “Caller is not tokenController” if caller is not the token controller

Source: TokenController.sol:82

onlyWithinBurnLimit

modifier onlyWithinBurnLimit(address token, uint256 amount)

Ensures that a burn operation does not exceed the per-message burn limit.

Parameters:

• token: Address of the token to burn
• amount: Amount to burn

Reverts:

• “Burn token not supported” if burn limit is 0
• “Burn amount exceeds per tx limit” if amount exceeds limit

Source: TokenController.sol:98

Events

TokenPairLinked

event TokenPairLinked(
    address localToken,
    uint32 remoteDomain,
    bytes32 remoteToken
)

Emitted when a token pair is linked.

Parameters:

• localToken: Local token address
• remoteDomain: Remote domain ID
• remoteToken: Remote token address as bytes32

TokenPairUnlinked

event TokenPairUnlinked(
    address localToken,
    uint32 remoteDomain,
    bytes32 remoteToken
)

Emitted when a token pair is unlinked.

SetBurnLimitPerMessage

event SetBurnLimitPerMessage(
    address indexed token,
    uint256 burnLimitPerMessage
)

Emitted when a burn limit is set for a token.

Parameters:

• token: Local token address
• burnLimitPerMessage: New burn limit per message

SetTokenController

event SetTokenController(address tokenController)

Emitted when the token controller address is set.

Parameters:

• tokenController: New token controller address

Usage Examples

Setting Up a New Token

// Step 1: Link token pair (as token controller)
// Link local USDC to Ethereum USDC
tokenController.linkTokenPair(
    0xLOCAL_USDC_ADDRESS,
    0, // Ethereum domain ID
    0x000000000000000000000000ETHEREUM_USDC_ADDRESS
);

// Step 2: Set burn limit to enable deposits
// Allow burning up to 1 million USDC per message
tokenController.setMaxBurnAmountPerMessage(
    0xLOCAL_USDC_ADDRESS,
    1_000_000 * 10**6 // 1M USDC (6 decimals)
);

Updating Configuration

// Reduce burn limit
tokenController.setMaxBurnAmountPerMessage(
    0xLOCAL_USDC_ADDRESS,
    100_000 * 10**6 // 100K USDC
);

// Temporarily disable burning (set to 0)
tokenController.setMaxBurnAmountPerMessage(
    0xLOCAL_USDC_ADDRESS,
    0
);

// Unlink token pair
tokenController.unlinkTokenPair(
    0xLOCAL_USDC_ADDRESS,
    0, // Ethereum domain ID
    0x000000000000000000000000ETHEREUM_USDC_ADDRESS
);

Checking Configuration

// Check burn limit
uint256 limit = tokenMinter.burnLimitsPerMessage(0xLOCAL_USDC_ADDRESS);

// Check if remote token is linked
bytes32 key = keccak256(abi.encodePacked(
    uint32(0), // Ethereum domain
    bytes32(uint256(uint160(0xETHEREUM_USDC_ADDRESS)))
));
address localToken = tokenMinter.remoteTokensToLocalTokens(key);

Security Considerations

• Token controller should be a trusted address (e.g., multisig or DAO)
• Burn limits should be set based on liquidity and risk assessment
• A token pair can only be linked once (prevents conflicting mappings)
• Minting is not limited by burn limits (asymmetric by design)
• Setting burn limit to 0 effectively disables deposits for that token
• Unlinking a token pair does not automatically disable burning
• Remote tokens are stored as bytes32 to support non-EVM chains
• Multiple remote tokens can map to the same local token (useful for wrapped tokens)

Integration with TokenMinter

The TokenMinter contract inherits from TokenController and uses these functions in:

• depositForBurn(): Checks burn limit via onlyWithinBurnLimit modifier
• handleReceiveMessage(): Uses _getLocalToken() to determine which token to mint
• Administrative setup: Owner uses inherited functions to configure supported tokens

Remote Token Address Format

Remote tokens are represented as bytes32 to support both EVM and non-EVM chains:

// Convert EVM address to bytes32
bytes32 remoteToken = bytes32(uint256(uint160(evmAddress)));

// Extract EVM address from bytes32
address evmAddress = address(uint160(uint256(remoteToken)));

For non-EVM chains, the bytes32 format is used directly without conversion.