Feature Request: Add gasless USDC delivery guide for CCTP bridge completion (relay pattern)
- Dominant language
- JavaScript
- Stars
- 337
- Forks
- 792
- Avg merge
- 17h 23m
- Merged PRs (30d)
- 49
Description
## Feature Request: Gasless USDC delivery guide for CCTP + Base Mainnet
**Docs section:** Payments → CCTP / Cross-Chain
---
### What's missing
Base's four product pillars include **Payments** and the **Solana Bridge** (CCTP-based). The current docs explain how to *initiate* a CCTP burn on the source chain, but there's no guide covering the **last mile**: automatically completing delivery on Base after the attestation is ready.
Today, users who bridge USDC to Base must:
1. Wait for Circle's attestation API to return `complete`
2. Manually (or programmatically) call `receiveMessage` on the Base `MessageTransmitter` contract
3. **Pay ETH gas** to do so — a significant UX barrier for users who don't yet hold ETH on Base
This gap is especially relevant for the Base Solana Bridge, where recipients are often new-to-Base users with zero ETH.
---
### Proposed docs page
**Title:** "Auto-complete USDC delivery after a CCTP bridge (gasless relay)"
**Covers:**
- How CCTP v1 works end-to-end (burn → attest → receive)
- Polling Circle's attestation API (`https://iris-api.circle.com/attestations/{messageHash}`)
- Calling `receiveMessage` on Base's `MessageTransmitter` (`0x1682Ae6375C4E4A97e4B583BC394c861A46D8962`)
- A relay pattern where the **relayer pays ETH gas** so the recipient gets USDC with zero friction
- Error handling: nonce-already-used detection (idempotent re-submission), attestation-not-ready polling
- Security: why you should derive `destDomain` from `messageBytes` rather than trusting the client
---
### Reference implementation
We built this in **BasePay** (open source, Base Mainnet):
- Full CCTP relay route: https://github.com/osr21/basepay/blob/main/artifacts/api-server/src/routes/cctp.ts
- Handles attestation polling, `receiveMessage` submission, nonce-already-used idempotency
- Per-chain nonce serialization to prevent gas waste from concurrent relay submissions
Happy to contribute a draft PR to the docs repo if this is something the team would accept. Just wanted to flag the gap first.
---
### Why this matters for Base adoption
The **Base Solana Bridge** launch is a flagship feature. Frictionless USDC arrival — zero ETH required — is the difference between a good bridge UX and a great one. A relay guide here directly supports Base's "bringing the world onchain" mission.
Thanks!
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by locating the existing Payments → CCTP / Cross-Chain documentation on initiating a burn, then read the referenced BasePay relay route in artifacts/api-server/src/routes/cctp.ts. The guide is done when it covers burn, attestation polling, receiveMessage, relay gas payment, idempotent nonce handling, polling errors, and deriving destDomain from messageBytes.
Written by the indexing model from the issue text.
Assessment
- Domain
- blockchain, documentation, payments
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100