TokenMessengerV2

​

Overview

​

Key Features

​

New Features vs V1

1. Fee Mechanism: Support for destination domain fees with maxFee parameter
2. Minimum Fee Control: Configurable minimum fee requirements in basis points
3. Finality Thresholds: Messages can specify minimum finality requirements
4. Hook Execution: Optional hookData for custom logic on destination domain
5. Destination Caller: Specify authorized caller on destination domain
6. Denylist Support: Ability to denylist addresses from using the protocol

​

Constructor

constructor(
    address _messageTransmitter,
    uint32 _messageBodyVersion
)

​

Parameters

• _messageTransmitter (address): Message transmitter address
• _messageBodyVersion (uint32): Message body version

​

Initialization

struct TokenMessengerV2Roles {
    address owner;
    address rescuer;
    address feeRecipient;
    address denylister;
    address tokenMinter;
    address minFeeController;
}

function initialize(
    TokenMessengerV2Roles calldata roles,
    uint256 minFee_,
    uint32[] calldata remoteDomains_,
    bytes32[] calldata remoteTokenMessengers_
) external

​

Parameters

• roles (TokenMessengerV2Roles): Struct containing all role addresses
  • owner: Owner address (cannot be zero)
  • rescuer: Rescuer address
  • feeRecipient: Address to receive collected fees
  • denylister: Address with permission to manage denylist
  • tokenMinter: Local token minter address
  • minFeeController: Address with permission to set minimum fee
• minFee_ (uint256): Initial minimum fee (in 1/1000 basis points)
• remoteDomains_ (uint32[]): Array of remote domain IDs
• remoteTokenMessengers_ (bytes32[]): Array of remote TokenMessenger addresses (must match remoteDomains_ length)

​

Requirements

• Owner must be non-zero address
• Remote domains and remote token messengers arrays must have equal length
• All remote token messenger addresses must be non-zero

​

Core Functions

​

depositForBurn

function depositForBurn(
    uint256 amount,
    uint32 destinationDomain,
    bytes32 mintRecipient,
    address burnToken,
    bytes32 destinationCaller,
    uint256 maxFee,
    uint32 minFinalityThreshold
) external

​

Parameters

• amount (uint256): Amount of tokens to burn (must be nonzero)
• destinationDomain (uint32): Destination domain to receive message on
• mintRecipient (bytes32): Address of mint recipient on destination domain
• burnToken (address): Token to burn amount of, on local domain
• destinationCaller (bytes32): Authorized caller on the destination domain as bytes32. If equal to bytes32(0), any address can broadcast the message
• maxFee (uint256): Maximum fee to pay on the destination domain, specified in units of burnToken
• minFinalityThreshold (uint32): The minimum finality at which the burn message will be attested to

​

Requirements

• Caller must not be denylisted
• Amount must be nonzero
• Mint recipient must be nonzero
• Burn token must be supported
• Destination domain must have a TokenMessenger registered
• maxFee must be less than amount
• maxFee must be >= amount * minFee / MIN_FEE_MULTIPLIER (if minFee > 0)
• Sender must have sufficient balance and approval

​

Events

event DepositForBurn(
    address indexed burnToken,
    uint256 amount,
    address indexed depositor,
    bytes32 mintRecipient,
    uint32 destinationDomain,
    bytes32 destinationTokenMessenger,
    bytes32 destinationCaller,
    uint256 maxFee,
    uint32 indexed minFinalityThreshold,
    bytes hookData
);

​

depositForBurnWithHook

function depositForBurnWithHook(
    uint256 amount,
    uint32 destinationDomain,
    bytes32 mintRecipient,
    address burnToken,
    bytes32 destinationCaller,
    uint256 maxFee,
    uint32 minFinalityThreshold,
    bytes calldata hookData
) external

​

Parameters

• hookData (bytes): Hook data to append to burn message for interpretation on destination domain (must be non-empty)

​

Requirements

• hookData must have length > 0

​

handleReceiveFinalizedMessage

function handleReceiveFinalizedMessage(
    uint32 remoteDomain,
    bytes32 sender,
    uint32 finalityThresholdExecuted,
    bytes calldata messageBody
) external returns (bool)

​

Parameters

• remoteDomain (uint32): The domain where the message originated from
• sender (bytes32): The sender of the message (remote TokenMessenger)
• finalityThresholdExecuted (uint32): The level of finality at which the message was attested (unused in finalized handler)
• messageBody (bytes): The message body bytes

​

Returns

• success (bool): True if successful

​

Requirements

• Caller must be the local MessageTransmitter
• Sender must be a registered remote TokenMessenger for the given domain

​

handleReceiveUnfinalizedMessage

function handleReceiveUnfinalizedMessage(
    uint32 remoteDomain,
    bytes32 sender,
    uint32 finalityThresholdExecuted,
    bytes calldata messageBody
) external returns (bool)

​

Parameters

• remoteDomain (uint32): The domain where the message originated from
• sender (bytes32): The sender of the message (remote TokenMessenger)
• finalityThresholdExecuted (uint32): The level of finality at which the message was attested to
• messageBody (bytes): The message body bytes

​

Returns

• success (bool): True if successful

​

Requirements

• Caller must be the local MessageTransmitter
• Sender must be a registered remote TokenMessenger for the given domain
• finalityThresholdExecuted must be >= TOKEN_MESSENGER_MIN_FINALITY_THRESHOLD (500)

​

Fee Management Functions

​

getMinFeeAmount

function getMinFeeAmount(uint256 amount) external view returns (uint256)

​

Parameters

• amount (uint256): The amount for which to calculate the minimum fee (must be > 1)

​

Returns

• Minimum fee for the given amount

​

Formula

minFeeAmount = (amount * minFee) / MIN_FEE_MULTIPLIER

​

setFeeRecipient

function setFeeRecipient(address _feeRecipient) external

​

Parameters

• _feeRecipient (address): Address of fee recipient (cannot be zero address)

​

Events

event FeeRecipientSet(address feeRecipient);

​

setMinFeeController

function setMinFeeController(address _minFeeController) external

​

Parameters

• _minFeeController (address): Address of minimum fee controller (cannot be zero address)

​

Events

event MinFeeControllerSet(address minFeeController);

​

setMinFee

function setMinFee(uint256 _minFee) external

​

Parameters

• _minFee (uint256): Minimum fee (must be < MIN_FEE_MULTIPLIER)

​

Events

event MinFeeSet(uint256 minFee);

​

Denylist Functions

​

addToDenylist

function addToDenylist(address account) external

​

removeFromDenylist

function removeFromDenylist(address account) external

​

Remote TokenMessenger Management

​

addRemoteTokenMessenger

function addRemoteTokenMessenger(
    uint32 domain,
    bytes32 tokenMessenger
) external

​

removeRemoteTokenMessenger

function removeRemoteTokenMessenger(uint32 domain) external

​

Local Minter Management

​

addLocalMinter

function addLocalMinter(address newLocalMinter) external

​

removeLocalMinter

function removeLocalMinter() external

​

State Variables

​

Immutable

• localMessageTransmitter (address): Local Message Transmitter address
• messageBodyVersion (uint32): Version of message body format

​

Storage

• localMinter (ITokenMinterV2): Local token minter contract
• remoteTokenMessengers (mapping(uint32 => bytes32)): Valid TokenMessengers on remote domains
• feeRecipient (address): Address to receive collected fees
• minFeeController (address): Minimum fee controller address
• minFee (uint256): Minimum fee for all transfers in 1/1000 basis points
• MIN_FEE_MULTIPLIER (uint256): Constant value of 10,000,000 (1/1000 basis point precision)

​

Integration Example

// Approve tokens first
usdc.approve(address(tokenMessenger), amount);

// Deposit for burn with fee and finality
tokenMessenger.depositForBurn(
    1000000, // 1 USDC (6 decimals)
    destinationDomain,
    recipientAddress,
    address(usdc),
    bytes32(0), // Any caller
    5000, // Max fee: 0.005 USDC
    1000 // Confirmed finality
);

// With hook data for custom logic
tokenMessenger.depositForBurnWithHook(
    1000000,
    destinationDomain,
    recipientAddress,
    address(usdc),
    bytes32(0),
    5000,
    1000,
    customHookData // Interpreted on destination
);

​

Fee Calculation Example

Amount: 1,000,000 (1 USDC)
minFeeAmount = (1,000,000 * 5000) / 10,000,000 = 500 (0.0005 USDC)

​

Event Signature Changes

• destinationCaller (bytes32): Authorized caller specification
• maxFee (uint256): Maximum fee willing to pay
• minFinalityThreshold (uint32): Minimum finality requirement (indexed)
• hookData (bytes): Optional hook data

​

Security Considerations

1. Fee Validation: Max fee is validated to be less than amount and meet minimum fee requirements
2. Denylist Protection: Denylisted addresses cannot initiate burns
3. Caller Authorization: Optional destination caller restriction
4. Finality Thresholds: Minimum finality of 500 required for unfinalized messages
5. Message Expiration: Burn messages can include expiration blocks