cctp.whitelist

Documentation for eth_defi.cctp.whitelist Python module.

CCTP whitelisting for Lagoon vaults.

Utilities for whitelisting CCTP contracts in Guard contracts for cross-chain USDC transfers through managed vaults.

When a Lagoon vault needs to perform cross-chain USDC transfers, the guard contract must whitelist:

The TokenMessengerV2 contract (for depositForBurn() calls)
Each allowed destination domain (CCTP domain IDs)
USDC as an allowed asset (via whitelistToken())
The vault/Safe address as an allowed receiver

Example:

from eth_defi.cctp.whitelist import CCTPDeployment

cctp = CCTPDeployment.create_for_chain(
    chain_id=1,  # Ethereum
    allowed_destinations=[42161, 8453],  # Arbitrum, Base
)

# Pass to Lagoon vault deployment
deploy_automated_lagoon_vault(
    ...
    cctp_deployment=cctp,
)

Functions

setup_cctp_whitelisting(web3, guard, ...)

Whitelist CCTP contracts in a guard for cross-chain transfers.

Classes

CCTPDeployment

CCTP V2 deployment configuration for guard whitelisting.

class CCTPDeployment

Bases: object

CCTP V2 deployment configuration for guard whitelisting.

All CCTP V2 contracts share the same address across EVM chains (CREATE2), so this mainly configures which destination domains are allowed.

__init__(token_messenger=<factory>, message_transmitter=<factory>, token_minter=<factory>, allowed_destination_domains=<factory>)

Parameters

token_messenger (eth_typing.evm.HexAddress) –
message_transmitter (eth_typing.evm.HexAddress) –
token_minter (eth_typing.evm.HexAddress) –
allowed_destination_domains (list[int]) –

Return type

None

classmethod create_for_chain(chain_id, allowed_destinations=None)

Create a CCTP deployment configuration for a given chain.

Supports both mainnet and testnet (Sepolia) chain IDs. Testnet chains automatically use testnet contract addresses.

Parameters

chain_id (int) – EVM chain ID of the source chain (e.g. 1 for Ethereum, 421614 for Arbitrum Sepolia).
allowed_destinations (Optional[list[int]]) – List of EVM chain IDs for allowed destination chains. Automatically converted to CCTP domain IDs. If None, no destinations are allowed (add them separately).

Returns

Configured CCTPDeployment instance.

Raises

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

Return type

eth_defi.cctp.whitelist.CCTPDeployment

setup_cctp_whitelisting(web3, guard, cctp_deployment, owner)

Whitelist CCTP contracts in a guard for cross-chain transfers.

Calls the guard’s whitelistCCTP() and whitelistCCTPDestination() functions to enable cross-chain USDC transfers.

Parameters

web3 (web3.main.Web3) – Web3 connection
guard (web3.contract.contract.Contract) – Guard contract (TradingStrategyModuleV0 or similar)
cctp_deployment (eth_defi.cctp.whitelist.CCTPDeployment) – CCTP deployment configuration
owner (Union[eth_typing.evm.HexAddress, str]) – Address of the guard owner (typically the Safe)

Returns

List of transaction hashes

Return type

list[hexbytes.main.HexBytes]