diff --git a/docs/base-chain/network-information/base-solana-bridge.mdx b/docs/base-chain/network-information/base-solana-bridge.mdx index 92ae9dd3d..8125a0d90 100644 --- a/docs/base-chain/network-information/base-solana-bridge.mdx +++ b/docs/base-chain/network-information/base-solana-bridge.mdx @@ -16,6 +16,10 @@ Solana networks. This bridge allows you to: This guide covers the bridge architecture, the production addresses, and practical implementation patterns. + +If you are completing a CCTP-style delivery on Base and want a relayer to pay the destination gas, see [Auto-complete USDC delivery after a CCTP bridge](/base-chain/network-information/cctp-gasless-relay). + + ## How it works ### On Base diff --git a/docs/base-chain/network-information/bridging-and-withdrawals.mdx b/docs/base-chain/network-information/bridging-and-withdrawals.mdx index d7d9cedbf..caa398493 100644 --- a/docs/base-chain/network-information/bridging-and-withdrawals.mdx +++ b/docs/base-chain/network-information/bridging-and-withdrawals.mdx @@ -47,6 +47,8 @@ This can improve user experience, but it adds provider-specific assumptions and For available bridge providers and routes, see [Ecosystem Bridges](/base-chain/network-information/ecosystem-bridges). +If you are building a CCTP-style delivery flow where a relayer completes the destination-chain transaction on Base, see [Auto-complete USDC delivery after a CCTP bridge](/base-chain/network-information/cctp-gasless-relay). + ## Standard bridge contracts The standard bridges support cross-domain ETH and ERC-20 transfers. They are built on top of the cross-domain messenger contracts and provide a standard interface for deposits and withdrawals. diff --git a/docs/base-chain/network-information/cctp-gasless-relay.mdx b/docs/base-chain/network-information/cctp-gasless-relay.mdx new file mode 100644 index 000000000..3ea6d8b15 --- /dev/null +++ b/docs/base-chain/network-information/cctp-gasless-relay.mdx @@ -0,0 +1,79 @@ +--- +title: Auto-complete USDC delivery after a CCTP bridge +description: Learn how to relay Circle CCTP delivery on Base so recipients can receive USDC without holding ETH for gas. +--- + +import { GithubRepoCard } from "/snippets/GithubRepoCard.mdx" + +Base users who bridge USDC from Solana or another supported chain still need to call `receiveMessage` on Base after the attestation is ready. This guide shows how to remove that last gas payment by having a relayer submit the Base delivery transaction for the user. + + +This pattern is useful for Base Mainnet apps that want to complete CCTP delivery for users who do not yet hold ETH on Base. + + +## How the relay pattern works + + + +The source-chain transfer emits a CCTP message that Circle later attests. + + +Your backend checks Circle's attestation API until the message status becomes `complete`. + + +Once the attestation is ready, the relayer submits `receiveMessage` to Base's `MessageTransmitter` contract and pays the ETH gas cost. + + +The recipient receives USDC on Base without having to fund the destination wallet first. + + + +## What to validate before relaying + +Before you submit the relay transaction, validate the message instead of trusting client input: + +- Derive `destDomain` from the attested `messageBytes`. +- Confirm the destination chain is Base before submitting `receiveMessage`. +- Treat already-used nonces as idempotent success, not as a fatal error. +- Retry cleanly when the attestation is not ready yet. + + +If you let the client choose the destination domain or recipient unchecked, you can relay the wrong message or pay gas for an invalid request. + + +## Minimal relay flow + +The relayer needs three pieces of information: + +- the attested message payload +- the Base `MessageTransmitter` contract address +- ETH on Base to pay gas for the relay transaction + +```typescript cctp-relay.ts +const attestation = await getAttestation(messageHash); +if (attestation.status !== "complete") return; +await receiveMessageOnBase(messageBytes, attestation.attestation); +``` + +## Recommended integration points + +Use this pattern when your app already has a bridge completion flow and you want to remove destination-chain gas friction for new users. + + + +For adjacent bridge behavior, see [Bridging and Withdrawals](/base-chain/network-information/bridging-and-withdrawals) and [Base-Solana Bridge](/base-chain/network-information/base-solana-bridge). + +## Reference address + +Base `MessageTransmitter` contract: + +- `0x1682Ae6375C4E4A97e4B583BC394c861A46D8962` + +## Next step + +If you are building a production relay service, add: + +- per-message nonce tracking +- attestation polling backoff +- replay-safe handling for already-used messages +- chain-specific gas limits and error monitoring \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index cd74bfe65..583fa6bb6 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -149,6 +149,7 @@ "group": "Bridges", "pages": [ "base-chain/network-information/base-solana-bridge", + "base-chain/network-information/cctp-gasless-relay", "base-chain/network-information/ecosystem-bridges" ] },