cctp.transfer

Documentation for eth_defi.cctp.transfer Python module.

Circle CCTP V2 cross-chain USDC transfers.

Initiate cross-chain USDC transfers using Circle’s CCTP V2 protocol.

Example of preparing a cross-chain transfer from Ethereum to Arbitrum:

from web3 import Web3
from eth_defi.cctp.transfer import prepare_deposit_for_burn, prepare_approve_for_burn

web3 = Web3(Web3.HTTPProvider("https://..."))

# First approve USDC spending
approve_fn = prepare_approve_for_burn(web3, amount=1_000_000)  # 1 USDC
approve_fn.transact({"from": sender})

# Then initiate the cross-chain transfer
burn_fn = prepare_deposit_for_burn(
    web3,
    amount=1_000_000,
    destination_chain_id=42161,  # Arbitrum
    mint_recipient="0x...",  # Recipient on Arbitrum
)
tx_hash = burn_fn.transact({"from": sender})

The burnToken is always the native USDC on the source chain. The destination chain’s TokenMinterV2 automatically resolves the local USDC address via its remoteTokensToLocalTokens mapping.

Functions

`encode_mint_recipient`(address)	Convert an Ethereum address to bytes32 format for the `mintRecipient` parameter.
`get_message_transmitter_v2`(web3)	Load the MessageTransmitterV2 contract at its known address.
`get_token_messenger_v2`(web3)	Load the TokenMessengerV2 contract at its known address.
`prepare_approve_for_burn`(web3, amount[, ...])	Build a USDC `approve()` call to TokenMessengerV2.
`prepare_deposit_for_burn`(web3, amount, ...)	Build a bound `depositForBurn()` call on TokenMessengerV2.
`resolve_token_messenger_address`(chain_id)	Pick mainnet or testnet TokenMessengerV2 address based on chain ID.

resolve_token_messenger_address(chain_id)

Pick mainnet or testnet TokenMessengerV2 address based on chain ID.

Parameters: chain_id (int) – EVM chain ID. Testnet chain IDs return the testnet address.
Returns: Checksummed TokenMessengerV2 contract address.
Return type: eth_typing.evm.HexAddress

get_token_messenger_v2(web3)

Load the TokenMessengerV2 contract at its known address.

Automatically selects mainnet or testnet address based on the connected chain.

Parameters: web3 (web3.main.Web3) – Web3 connection
Returns: Contract proxy for TokenMessengerV2
Return type: web3.contract.contract.Contract

get_message_transmitter_v2(web3)

Load the MessageTransmitterV2 contract at its known address.

Automatically selects mainnet or testnet address based on the connected chain.

Parameters: web3 (web3.main.Web3) – Web3 connection
Returns: Contract proxy for MessageTransmitterV2
Return type: web3.contract.contract.Contract

encode_mint_recipient(address)

Convert an Ethereum address to bytes32 format for the mintRecipient parameter.

CCTP uses bytes32 for recipient addresses to support non-EVM chains. For EVM chains, the address is left-padded with zeros to 32 bytes.

Parameters: address (Union[eth_typing.evm.HexAddress, str]) – Ethereum address (0x-prefixed hex string)
Returns: 32-byte representation of the address
Return type: bytes

prepare_deposit_for_burn(web3, amount, destination_chain_id, mint_recipient, burn_token=None, destination_caller=None, max_fee=0, min_finality_threshold=2000)

Build a bound depositForBurn() call on TokenMessengerV2.

This burns USDC on the source chain to be minted on the destination chain. USDC must be approved to TokenMessengerV2 before calling this.

Parameters

web3 (web3.main.Web3) – Web3 connection to the source chain
amount (int) – Amount of USDC to transfer in raw token units (6 decimals). E.g. 1_000_000 for 1 USDC.
destination_chain_id (int) – EVM chain ID of the destination (e.g. 42161 for Arbitrum). Automatically converted to CCTP domain ID.
mint_recipient (Union[eth_typing.evm.HexAddress, str]) – Address to receive USDC on the destination chain.
burn_token (Optional[Union[eth_typing.evm.HexAddress, str]]) – USDC address on the source chain. If None, auto-detected from the source chain ID.
destination_caller (bytes | None) – If set, restricts who can call receiveMessage() on the destination chain. None means anyone can relay (bytes32 zero).
max_fee (int) – Maximum fee for fast finality transfers. 0 for standard transfers.
min_finality_threshold (int) – Finality level: 2000 for standard (finalized), 1000 for fast (confirmed).

Returns

Bound contract function ready to be transacted or encoded.

Raises

ValueError – If the destination chain or source chain is not supported by CCTP.

Return type

web3.contract.contract.ContractFunction

prepare_approve_for_burn(web3, amount, burn_token=None)

Build a USDC approve() call to TokenMessengerV2.

Must be called before prepare_deposit_for_burn().

Parameters

web3 (web3.main.Web3) – Web3 connection to the source chain
amount (int) – Amount of USDC to approve in raw token units (6 decimals)
burn_token (Optional[Union[eth_typing.evm.HexAddress, str]]) – USDC address on the source chain. If None, auto-detected.

Returns

Bound contract function for USDC.approve(TokenMessengerV2, amount)

Return type

web3.contract.contract.ContractFunction