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

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.

Classes

CCTPAttestation

Attestation data for a CCTP burn event.

HTTP_NOT_FOUND = 404

HTTP 404 status code indicating resource not found

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

• message (bytes) –

• attestation (bytes) –

• status (str) –

Return type

None

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

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.

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.

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