base / base/docs

Feature Request: Add gasless USDC delivery guide for CCTP bridge completion (relay pattern)

Open
#1,644 1 comment 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.