cctp.testing

Documentation for eth_defi.cctp.testing Python module.

CCTP V2 test helpers for Anvil forked chains.

Utilities for testing CCTP receiveMessage() on Anvil forks where Circle’s Iris attestation service is unavailable.

The approach:

1. Replace the real CCTP attester with a test account we control

2. Craft a valid CCTP message (header + burn message body)

3. Sign it with the test attester to forge an attestation

4. Call receiveMessage() — the MessageTransmitter accepts our attestation and triggers the real mint flow

Example:

from eth_defi.cctp.testing import replace_attester_on_fork, craft_cctp_message, forge_attestation
from eth_defi.cctp.receive import prepare_receive_message

test_attester = replace_attester_on_fork(web3)
message = craft_cctp_message(
    source_domain=0,  # Ethereum
    destination_domain=6,  # Base
    nonce=1,
    mint_recipient=safe_address,
    amount=100 * 10**6,  # 100 USDC
    burn_token=USDC_ETHEREUM,
)
attestation = forge_attestation(message, test_attester)
receive_fn = prepare_receive_message(web3, message, attestation)
tx_hash = receive_fn.transact({"from": relayer})

See Circle’s CCTP specification for the message format.

Module Attributes

CCTP_MESSAGE_VERSION	CCTP message version for V2 protocol
BURN_MESSAGE_VERSION	Burn message body version

Functions

craft_cctp_message(source_domain, ...[, ...])	Craft a CCTP V2 message for testing receiveMessage() on forks.
forge_attestation(message, attester)	Sign a CCTP message with a test attester to create a valid attestation.
replace_attester_on_fork(web3)	Replace the CCTP attester with a test account on an Anvil fork.

CCTP_MESSAGE_VERSION = 1

CCTP message version for V2 protocol

BURN_MESSAGE_VERSION = 1

Burn message body version

replace_attester_on_fork(web3)

Replace the CCTP attester with a test account on an Anvil fork.

Impersonates the attesterManager on the forked MessageTransmitterV2 contract and adds a new test attester that we control. This allows forging attestations for receiveMessage() calls.

Parameters

web3 (web3.main.Web3) – Web3 connected to an Anvil fork

Returns

The test attester account (use with forge_attestation())

Return type

eth_account.signers.local.LocalAccount

craft_cctp_message(source_domain, destination_domain, nonce, mint_recipient, amount, burn_token, min_finality_threshold=2000)

Craft a CCTP V2 message for testing receiveMessage() on forks.

Builds a valid CCTP V2 message header + burn message body using abi.encodePacked format matching Circle’s on-chain encoding.

Message header (148 bytes):

• uint32 version (4 bytes)

• uint32 sourceDomain (4 bytes)

• uint32 destinationDomain (4 bytes)

• bytes32 nonce (32 bytes)

• bytes32 sender (32 bytes) — TokenMessenger on source

• bytes32 recipient (32 bytes) — TokenMessenger on dest

• bytes32 destinationCaller (32 bytes) — 0x00 for anyone

• uint32 minFinalityThreshold (4 bytes)

• uint32 finalityThresholdExecuted (4 bytes)

Burn message body (228 bytes):

• uint32 version (4 bytes)

• bytes32 burnToken (32 bytes)

• bytes32 mintRecipient (32 bytes)

• uint256 amount (32 bytes)

• bytes32 messageSender (32 bytes)

• bytes32 maxFee (32 bytes) — 0 for standard

• bytes32 feeExecuted (32 bytes) — 0 (set by attester)

• bytes32 expirationBlock (32 bytes) — 0 (set by attester)

Parameters

• source_domain (int) – CCTP domain of the source chain (e.g. 0 for Ethereum)

• destination_domain (int) – CCTP domain of the destination chain (e.g. 6 for Base)

• nonce (int) – Unique nonce (must not have been used before on this chain)

• mint_recipient (Union[eth_typing.evm.HexAddress, str]) – Address to receive minted USDC on the destination chain

• amount (int) – Amount of USDC in raw units (6 decimals)

• burn_token (Union[eth_typing.evm.HexAddress, str]) – USDC address on the source chain

• min_finality_threshold (int) – Finality threshold (2000 for standard, 1000 for fast)

Returns

Packed message bytes (376 bytes total)

Return type

bytes

forge_attestation(message, attester)

Sign a CCTP message with a test attester to create a valid attestation.

The attestation is an ECDSA signature over keccak256(message). For CCTP, the signature format is 65 bytes: r (32) + s (32) + v (1).

Parameters

• message (bytes) – The CCTP message bytes (from craft_cctp_message())

• attester (eth_account.signers.local.LocalAccount) – The test attester account (from replace_attester_on_fork())

Returns

65-byte attestation (ECDSA signature)

Return type

bytes