← Projects

BridgeTrace — Find Where a USDC Transfer Stopped

Active
React 19TypeScriptVinext (Vite)viemZodCloudflare Workers
Live ↗View Repository →
▶Product demo

Problem

A USDC transfer between chains can stop at three points: the source burn, Circle's attestation, or the destination receive transaction. Circle's 'complete' status only means the attestation is ready; it does not prove the destination receive happened. Users and support teams end up hopping between explorers and APIs, with no wallet-free way to see which step is missing.

Business Impact

'My USDC left the source chain — why hasn't it arrived?' is the question cross-chain support has to answer, and 'the attestation is complete' is not proof of delivery. BridgeTrace turns a transaction hash into one evidence report that names the missing step, so a user or support agent can answer with facts instead of assumptions — without connecting a wallet or jumping between explorers.

System Approach

  • Source check: reads the MessageSent log, validates the route and the canonical USDC contract, and matches Circle's decoded amount and recipient
  • Attestation check: reads the message status from Circle's attestation (Iris) API, including expired attestations
  • Destination check: reads usedNonces(bytes32) on the destination chain at an observed block; without RPC, a hinted destination transaction only counts after its MessageReceived event is verified
  • Six named outcomes: awaiting attestation, destination submission pending, expired attestation, confirmed receipt, reverted source, incomplete evidence
  • JSON report with provenance and evidence gaps, plus a copy-ready support summary
  • Server-side /api/trace endpoint built as a Cloudflare Worker — up to eight decoded messages per transaction, optional server-only RPC overrides

Key Decisions & Trade-offs

  • Read-only by design: no wallet connection, no transaction submission, no re-attestation requests
  • Attestation ready is never treated as delivered — only destination-chain evidence confirms receipt
  • Honest gaps: outages, rate limits, indexer lag or pruned history leave a stage marked incomplete instead of guessed
  • Three simulated samples are clearly labeled and make no blockchain requests, so demo data is never passed off as real
  • Tight v1 scope — CCTP V2 USDC between Ethereum and Base; other bridges, CCTP V1 and other chains are explicitly out of scope

Current Status

Public and open source (MIT) at github.com/rohitguta2432/bridgetrace, with a live public app. On October 6, 2026 a live lookup independently confirmed a completed 15-USDC Base Sepolia → Ethereum Sepolia transfer. Gated by 20 deterministic tests built on a captured public Circle response and mocked RPC receipts, covering delivery, expiry and missing-data cases.

Roadmap

  • More CCTP V2 chains beyond Ethereum and Base
  • Watch mode: re-check a pending transfer and flag when the destination receipt lands
  • Support for CCTP hooks and multiple identical burns in one transaction

What I'd Improve Next

  • Show the burn amount net of CCTP fees next to the gross amount
  • Fallback providers so one rate-limited RPC or explorer doesn't leave a stage incomplete

Explore More