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

Module Attributes

HTTP_NOT_FOUND

HTTP 404 status code indicating resource not found

CCTP_EXPLORER_BASE_URL

Range CCTP explorer base URL for transaction status lookup

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.
HTTP_NOT_FOUND = 404

HTTP 404 status code indicating resource not found

CCTP_EXPLORER_BASE_URL = 'https://usdc.range.org/status'

Range CCTP explorer base URL for transaction status lookup

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.

message: bytes

The CCTP message bytes to relay to the destination chain

attestation: bytes

The signed attestation bytes from Circle’s Iris service

status: str

Status from Iris API (e.g. “complete”)

__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

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]

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