cctp.attestation

Documentation for eth_defi.cctp.attestation Python module.

Circle CCTP V2 attestation service client.

Poll Circle’s Iris API for burn attestations needed to complete cross-chain USDC transfers.

After calling depositForBurn() on the source chain, you must wait for Circle’s attestation service to sign the burn event. This module provides utilities to poll for and retrieve the attestation.

Example:

from eth_defi.cctp.attestation import fetch_attestation
from eth_defi.cctp.constants import CCTP_DOMAIN_ETHEREUM

attestation = fetch_attestation(
    source_domain=CCTP_DOMAIN_ETHEREUM,
    transaction_hash="0x...",
    timeout=300.0,
)

# Use attestation.message and attestation.attestation
# with prepare_receive_message() on the destination chain

Functions

fetch_attestation(source_domain, ...[, ...])

Poll the Iris API until attestation is ready or timeout.

is_attestation_complete(source_domain, ...)

One-shot check if attestation is ready.

wait_for_cctp_attestation(source_chain_id, ...)

Wait for CCTP attestation and return message + attestation bytes.

Classes

CCTPAttestation

Attestation data for a CCTP burn event.
class CCTPAttestation

Bases: object

Attestation data for a CCTP burn event.

Contains the signed message and attestation needed to call receiveMessage() on the destination chain’s MessageTransmitterV2.

__init__(message, attestation, status)
Parameters
Return type

None

fetch_attestation(source_domain, transaction_hash, timeout=300.0, poll_interval=5.0, api_base_url='https://iris-api.circle.com', on_phase_change=None)

Poll the Iris API until attestation is ready or timeout.

Circle’s Iris service observes burn events on the source chain and produces a cryptographic attestation after block finality is reached. This function polls until the attestation is available.

The attestation goes through these Iris API statuses:

  • 404 — transaction not yet indexed by Circle

  • pending_confirmations — burn detected, waiting for block finality

  • complete — attestation signed and ready

Parameters

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

  • transaction_hash (str) – Transaction hash of the depositForBurn() call on the source chain.

  • timeout (float) – Maximum seconds to wait for attestation. Default 5 minutes.

  • poll_interval (float) – Seconds between polling attempts. Default 5 seconds.

  • api_base_url (str) – Iris API base URL. Defaults to mainnet.

  • on_phase_change (Optional[Callable[[str, int], None]]) – Optional callback invoked on every poll attempt. Receives (status, attempt) where status is one of "waiting_for_indexing", "pending_confirmations", or "complete" and attempt is the 1-based poll count. Used by bridge_usdc_cctp_parallel() for progress bar updates.

Returns

CCTPAttestation with message and attestation bytes.

Raises

  • TimeoutError – If attestation is not ready within the timeout period.

  • requests.HTTPError – If the Iris API returns a non-retryable error response.

Return type

eth_defi.cctp.attestation.CCTPAttestation

is_attestation_complete(source_domain, transaction_hash, api_base_url='https://iris-api.circle.com')

One-shot check if attestation is ready.

Parameters

  • source_domain (int) – CCTP domain ID of the source chain.

  • transaction_hash (str) – Transaction hash of the depositForBurn() call.

  • api_base_url (str) – Iris API base URL.

Returns

True if attestation is complete and available.

Return type

bool

wait_for_cctp_attestation(source_chain_id, dest_chain_id, burn_tx_hash, dest_safe_address, amount, simulate=False, test_attester=None, timeout=3600.0, nonce_base=999999000)

Wait for CCTP attestation and return message + attestation bytes.

Convenience wrapper that handles both simulation (forged attestation) and production (Iris API polling) modes.

In simulation mode, crafts a fake CCTP message and forges an attestation using the provided test attester key. In production mode, polls the Circle Iris API until the attestation is ready.

Parameters

  • source_chain_id (int) – Numeric chain ID of the source chain (where USDC was burned).

  • dest_chain_id (int) – Numeric chain ID of the destination chain (where USDC will be minted).

  • burn_tx_hash (str) – Transaction hash of the depositForBurn() call.

  • dest_safe_address (str) – Address that will receive the minted USDC on the destination chain.

  • amount (int) – Amount of USDC burned (in raw units, e.g. 1_000_000 for 1 USDC).

  • simulate (bool) – If True, forge attestation locally using test_attester.

  • test_attester (LocalAccount | None) – LocalAccount used to forge attestation in simulation mode. Required when simulate=True.

  • timeout (float) – Maximum seconds to wait for attestation (production mode only).

  • nonce_base (int) – Base nonce for forged messages in simulation mode.

Returns

Tuple of (message_bytes, attestation_bytes) ready for receive_usdc_cctp().

Return type

tuple[bytes, bytes]