fetch_attestation

Documentation for eth_defi.cctp.attestation.fetch_attestation function.

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