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:

  1. The TokenMessengerV2 contract (for depositForBurn() calls)

  2. Each allowed destination domain (CCTP domain IDs)

  3. USDC as an allowed asset (via whitelistToken())

  4. 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.

token_messenger: eth_typing.evm.HexAddress

TokenMessengerV2 contract address

message_transmitter: eth_typing.evm.HexAddress

MessageTransmitterV2 contract address

token_minter: eth_typing.evm.HexAddress

TokenMinterV2 contract address

allowed_destination_domains: list[int]

CCTP domain IDs of allowed destination chains. Use eth_defi.cctp.constants.CHAIN_ID_TO_CCTP_DOMAIN to convert chain IDs to domain IDs.

classmethod create_for_chain(chain_id, allowed_destinations=None)

Create a CCTP deployment configuration for a given chain.

Parameters

  • chain_id (int) – EVM chain ID of the source chain (e.g. 1 for Ethereum).

  • allowed_destinations (list[int] | None) – 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

__init__(token_messenger=<factory>, message_transmitter=<factory>, token_minter=<factory>, allowed_destination_domains=<factory>)
Parameters
Return type

None

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
Returns

List of transaction hashes

Return type

list[hexbytes.main.HexBytes]