Add more practical examples and real-world use cases

[NdruMan]

Some sections lack concrete examples, making it harder to understand how to apply the concepts in practice.

Suggested improvements:

• Add code snippets or workflows
• Include real-world scenarios
• Provide end-to-end examples where possible

This would improve developer experience significantly

I’d be happy to contribute a PR for this

[ensdomain]

Code snippets will be a great add to make it more easy to work with it

[osr21]

Here's a real-world end-to-end example that might be useful for this section: a CCTP V2 cross-chain USDC bridge that runs on Base Sepolia today.

Project: Arc Relay Bridge — burn USDC on one chain, attest via Circle Iris, mint natively on the destination. No wrapped tokens, no liquidity pools. Base Sepolia is one of four supported chains (CCTP domain 6).

---

Why Base Sepolia is a strong choice for cross-chain USDC apps

Base Sepolia ships with full CCTP V2 support out of the box. Developers get:

• Native USDC bridging to/from Ethereum Sepolia, Avalanche Fuji, and others
• Fast "safe" finality (~1–2 min attestation with minFinalityThreshold=1000)
• ERC-4337 Account Abstraction support — users can pay gas in USDC via a Paymaster, so they never need ETH to bridge

---

Minimal end-to-end example (Base Sepolia → Ethereum Sepolia)

Step 1 — Approve + Burn on Base Sepolia

const CCTP_V2_ABI = [
  "function depositForBurn(uint256 amount, uint32 destinationDomain, bytes32 mintRecipient, address burnToken, bytes32 destinationCaller, uint256 maxFee, uint32 minFinalityThreshold) returns (uint64)"
];
const TOKEN_MESSENGER = "0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA";
const BASE_SEPOLIA_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";

// Approve
const usdc = new ethers.Contract(BASE_SEPOLIA_USDC, ["function approve(address,uint256) returns (bool)"], signer);
await usdc.approve(TOKEN_MESSENGER, amountInUnits);

// Burn — destinationDomain 0 = Ethereum Sepolia
const messenger = new ethers.Contract(TOKEN_MESSENGER, CCTP_V2_ABI, signer);
const mintRecipient = ethers.zeroPadValue(recipientAddress, 32); // right-aligned bytes32
const tx = await messenger.depositForBurn(
  amountInUnits,
  0,                         // Ethereum Sepolia CCTP domain
  mintRecipient,
  BASE_SEPOLIA_USDC,
  ethers.ZeroHash,           // destinationCaller = anyone may relay
  0n,                        // maxFee
  1000                       // minFinalityThreshold: "safe" (~1-2 min)
);
const receipt = await tx.wait();

Step 2 — Parse the MessageSent event

const iface = new ethers.Interface(["event MessageSent(bytes message)"]);
const topic = iface.getEvent("MessageSent")!.topicHash;
const log = receipt.logs.find(l => l.topics[0] === topic);
const messageBytes = iface.parseLog(log)!.args[0];
const messageHash = ethers.keccak256(messageBytes);

Step 3 — Poll Circle Iris for the attestation

// Poll /v1/attestations/{messageHash} every 2s — 404 means still pending (not an error)
const IRIS = "https://iris-api-sandbox.circle.com";
let attestation: string | null = null;
while (!attestation) {
  await new Promise(r => setTimeout(r, 2000));
  const res = await fetch(`${IRIS}/v1/attestations/${messageHash}`);
  if (res.ok) {
    const data = await res.json();
    if (data.attestation && data.attestation !== "PENDING") {
      attestation = data.attestation;
    }
  }
}

Step 4 — Mint on Ethereum Sepolia

// Switch MetaMask to Ethereum Sepolia, then:
const MT_ABI = ["function receiveMessage(bytes message, bytes attestation) returns (bool)"];
const MESSAGE_TRANSMITTER = "0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275";
const transmitter = new ethers.Contract(MESSAGE_TRANSMITTER, MT_ABI, destinationSigner);
await transmitter.receiveMessage(messageBytes, attestation);

---

Contract addresses are identical across all supported testnets (Base Sepolia, Ethereum Sepolia, Avalanche Fuji), which makes multi-chain support straightforward.

Hope this is useful as a practical example for the docs.

[osr21]

Hey — building BasePay (a production USDC payments dApp on Base Mainnet) surfaced a few patterns that would make great practical examples here.

1. ERC-20 allowance gate before any contract call

This trips up almost every developer new to Base. The USDC contract on Base uses 6 decimals (not 18), and you must check allowance before calling a router or paymaster — not just balance.

import { useReadContract, useWriteContract } from "wagmi";

const USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const USDC_DECIMALS = 6;

function parseUSDC(amount: string): bigint {
  const [whole = "0", frac = ""] = amount.split(".");
  return BigInt(whole) * 10n ** 6n + BigInt(frac.padEnd(6, "0").slice(0, 6));
}

// 1. Read current allowance
const { data: allowance } = useReadContract({
  address: USDC, abi: ERC20_ABI, functionName: "allowance",
  args: [userAddress, ROUTER_ADDRESS],
});

// 2. Approve only the exact gross amount — not type(uint256).max
// Unlimited approvals are flagged by Blockaid and other wallet security scanners
const { writeContract: approve } = useWriteContract();
if ((allowance ?? 0n) < grossAmount) {
  approve({ address: USDC, abi: ERC20_ABI, functionName: "approve",
    args: [ROUTER_ADDRESS, grossAmount] });
}

2. Fee-inclusive routing — atomic split in the contract

Instead of calculating fee splits in the UI (fragile), the router contract handles it atomically:

// In the router: one transferFrom covers both fee + net
uint256 fee = (amount * feeBps) / 10_000;
IERC20(token).transferFrom(msg.sender, feeCollector, fee);
IERC20(token).transferFrom(msg.sender, recipient, amount - fee);

UI approval is for the gross amount only; the contract splits it.

3. Watching tx confirmation with wagmi v2

const { writeContract, data: hash } = useWriteContract();
const { isSuccess, isLoading } = useWaitForTransactionReceipt({ hash });
// show pending state while isLoading, success toast when isSuccess

Happy to contribute a PR that expands on any of these patterns. Live reference: base-pay.replit.app

[osr21]

One more practical pattern from building BasePay on Base Mainnet that fits this section — EIP-3009 gasless USDC transfers. Different from the ERC-4337 + paymaster approach and from the allowance pattern above. It's native to Base because Circle's USDC there implements EIP-3009 out of the box.

---

EIP-3009: zero-gas USDC transfers using transferWithAuthorization

The user signs a single off-chain typed message. A server-side relayer submits the transaction and pays gas. No ETH required in the user's wallet, no smart account, no paymaster allowlist — works with any standard EOA (MetaMask, Coinbase Wallet, etc.).

USDC on Base Mainnet (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) natively implements EIP-3009 as part of Circle's FiatToken standard.

Step 1 — User signs off-chain (wagmi + viem, zero gas)

import { useSignTypedData } from 'wagmi';
import { parseSignature } from 'viem';

const USDC_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';

const USDC_DOMAIN = {
  name: 'USD Coin',
  version: '2',
  chainId: 8453,          // Base Mainnet
  verifyingContract: USDC_ADDRESS,
} as const;

const TRANSFER_TYPES = {
  TransferWithAuthorization: [
    { name: 'from',        type: 'address' },
    { name: 'to',          type: 'address' },
    { name: 'value',       type: 'uint256' },
    { name: 'validAfter',  type: 'uint256' },
    { name: 'validBefore', type: 'uint256' },
    { name: 'nonce',       type: 'bytes32' },
  ],
} as const;

function randomBytes32() {
  const arr = new Uint8Array(32);
  crypto.getRandomValues(arr);
  return '0x' + Array.from(arr, b => b.toString(16).padStart(2, '0')).join('');
}

// In your component:
const { signTypedDataAsync } = useSignTypedData();

async function signGaslessTransfer(from, to, amount) {
  const nonce       = randomBytes32();
  const now         = BigInt(Math.floor(Date.now() / 1000));
  const validBefore = now + 1800n; // 30 min window

  const sig = await signTypedDataAsync({
    domain:      USDC_DOMAIN,
    types:       TRANSFER_TYPES,
    primaryType: 'TransferWithAuthorization',
    message:     { from, to, value: amount, validAfter: 0n, validBefore, nonce },
  });

  const { v, r, s } = parseSignature(sig);
  return { v: Number(v), r, s, nonce, validBefore };
}

Step 2 — Server relays on-chain (Express + viem, relayer pays gas)

import { createWalletClient, createPublicClient, http, parseAbi } from 'viem';
import { base } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const USDC_ABI = parseAbi([
  'function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, uint8 v, bytes32 r, bytes32 s) external',
  'function authorizationState(address, bytes32) external view returns (bool)',
  'function balanceOf(address) external view returns (uint256)',
]);

// Singleton — parse key once at startup, not per request
const account      = privateKeyToAccount(process.env.RELAYER_KEY);
const walletClient = createWalletClient({ account, chain: base, transport: http() });
const publicClient = createPublicClient({ chain: base, transport: http() });

app.post('/api/gasless/transfer', async (req, res) => {
  const { from, to, value, validAfter, validBefore, nonce, v, r, s } = req.body;

  // 1. Replay guard — on-chain state is authoritative
  const used = await publicClient.readContract({
    address: USDC_ADDRESS, abi: USDC_ABI,
    functionName: 'authorizationState', args: [from, nonce],
  });
  if (used) return res.status(400).json({ error: 'Nonce already used' });

  // 2. Balance check
  const bal = await publicClient.readContract({
    address: USDC_ADDRESS, abi: USDC_ABI,
    functionName: 'balanceOf', args: [from],
  });
  if (bal < BigInt(value)) return res.status(400).json({ error: 'Insufficient USDC' });

  // 3. Submit — USDC moves directly from -> to; relayer only pays ETH for gas
  const txHash = await walletClient.writeContract({
    address: USDC_ADDRESS, abi: USDC_ABI,
    functionName: 'transferWithAuthorization',
    args: [from, to, BigInt(value), BigInt(validAfter), BigInt(validBefore), nonce, v, r, s],
  });

  res.json({ txHash });
});

Step 3 — Frontend: full 3-step send flow

const [step, setStep] = useState('idle'); // idle | signing | relaying | done

async function handleSend() {
  setStep('signing');
  const sig = await signGaslessTransfer(address, recipient, parseUSDC(amount));

  setStep('relaying');
  const { txHash } = await fetch('/api/gasless/transfer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ from: address, to: recipient,
      value: parseUSDC(amount).toString(),
      validAfter: '0', validBefore: sig.validBefore.toString(),
      nonce: sig.nonce, v: sig.v, r: sig.r, s: sig.s }),
  }).then(r => r.json());

  setStep('done');
}

---

Why this matters for Base developers

	ERC-4337 + Paymaster	EIP-3009 Relay
Smart account required	Yes	No — standard EOA
Paymaster allowlist	Yes	Not needed
Wallet support	ERC-4337 compatible only	MetaMask, Coinbase Wallet, any EOA
Token scope	Any token + call	USDC only (on Base Mainnet)
Relayer cost per transfer	~$0.001–0.003 (Base gas)	~$0.001–0.003 (Base gas)
Setup complexity	High	Low (one hook + one API route)

On Base specifically, gas is cheap enough (~$0.001–$0.003/transfer) that a relayer wallet with $5 of ETH subsidises thousands of transfers. New users who hold USDC but no ETH can transact immediately — which directly addresses one of the biggest onboarding friction points for new Base users.

Key security rules for the relay server:

• Validate: value > 0, value ≤ max, from !== to, neither address is zero, timing window valid
• Use an in-memory Set<string> of pending nonces to block concurrent duplicate requests before they hit the chain
• Record spent nonces in a DB table as a fast-path cache; authorizationState on-chain is the authoritative guard
• Parse the relayer private key once at module load — not per request

Full implementation: BasePay gasless docs — live on Base Mainnet at base-pay.replit.app/gasless.

[osr21]

We built BasePay as a production reference implementation for USDC payments on Base Mainnet and have two open PRs for the docs (#1578, #1579) that might address this request.

The repo covers end-to-end examples for patterns that don't have good reference code in the current docs:

Pattern	What it demonstrates
EIP-3009 gasless relay	Server-side relayer pays gas; user signs off-chain only. Shows replay protection (nonce DB + on-chain authorizationState)
EIP-2612 permit flow	One-tx send with signTypedData + permitWithAuthorization — no separate approve tx
Gasless USDC↔EURC swap	Two-step relay through Aerodrome Router — full flow from quote to on-chain confirmation
Batch payments	multicall-style batching up to 200 recipients in one tx
x402 payment-gated API	Express middleware pattern for micro-payment–gated endpoints
EAS attestation badge	On-chain Coinbase verified account detection
Basenames resolution	.base.eth forward resolution with wagmi

Complete with integration examples in viem v2, ethers.js v6, and wagmi v3 hooks: contracts/integration/

Happy to break out any of these into standalone code snippets or guides if the format would fit the docs better.

[osr21]

previous malfunctionsa fixed but some updates have been made

[osr21]

Adding BasePay as a candidate reference for practical, real-world examples.

It's a full-stack USDC payments dApp on Base Mainnet covering five payment patterns that developers frequently ask about:

Pattern	What it demonstrates
EIP-2612 permit send	One-signature USDC transfer — no separate approve tx
EIP-3009 gasless relay	User signs, relayer pays ETH gas; includes EOA vs smart wallet detection
Batch payments	Up to 200 recipients in one tx via BatchPayV2 contract
Escrow	Time-locked USDC with release/refund, on-chain state machine
Subscriptions	Recurring on-chain charges, permissionless trigger

Also covers: OnchainKit wallet connection, Coinbase onramp (FundButton), EAS attestation badges, Coinbase Smart Wallet (ERC-4337), x402 API payment gating with CDP mainnet facilitator, wagmi v3 + viem v2 patterns throughout.

All four contracts are verified on Base Mainnet. MIT licensed.

Live app: https://base-pay.replit.app
Source: https://github.com/osr21/basepay-dapp

[osr21]

One more pattern worth adding to a practical examples page — hit this during production load testing of the BasePay relay:

---

Authenticated vs. public Base RPC in server-side relay flows

When building a gasless relay (EIP-3009 + transferWithAuthorization), the relay handler makes many RPC calls per swap: ETH balance check, token balance check, live quote, TX1 submit, TX1 receipt poll, allowance check, TX2 submit, TX2 receipt poll. On the free public mainnet.base.org endpoint this triggers rate-limiting under modest production traffic, causing intermittent 503s that look like smart contract errors but are actually just RPC throttling.

The fix is a one-line change to use the authenticated Coinbase node:

// server/lib/rpc.ts
import { createPublicClient, createWalletClient, http } from "viem";
import { base } from "viem/chains";

const rpcUrl = process.env.VITE_ONCHAINKIT_API_KEY
  ? `https://api.developer.coinbase.com/rpc/v1/base/${process.env.VITE_ONCHAINKIT_API_KEY}`
  : "https://mainnet.base.org"; // fallback for local dev without a key

export const baseTransport    = http(rpcUrl);
export const basePublicClient = createPublicClient({ chain: base, transport: baseTransport });

Centralising this into a single rpc.ts module (rather than duplicating the URL across route files) also means changing the provider later is a one-line change. The full implementation is in BasePay — artifacts/api-server/src/lib/rpc.ts.

[osr21]

Practical pattern: server-side gasless CCTP relay

One more concrete end-to-end example from BasePay — the gasless CCTP receive relay. This lets users bridge USDC cross-chain without holding ETH on the destination chain. It's a useful complement to the burn flow (which requires ETH on the source chain).

The problem it solves: CCTP's receiveMessage call must be submitted on the destination chain, but users who just received USDC from another chain often have zero ETH there. A paymaster-free alternative is a relay server that calls receiveMessage on their behalf.

Pattern (Express/Node):

// POST /api/cctp/relay-receive
// Body: { messageBytes: "0x..." }  — client sends ONLY the raw message bytes
router.post("/cctp/relay-receive", async (req, res) => {
  const { messageBytes } = req.body;

  // 1. Derive destination from the message — never trust the client
  //    CCTP v1 header: bytes 8-11 = destinationDomain (big-endian uint32)
  const destDomain = parseInt(messageBytes.slice(2 + 16, 2 + 24), 16);
  const chainId    = DOMAIN_TO_CHAIN_ID[destDomain];

  // 2. Dedup — one message can only be relayed once (contract enforces this too)
  const relayKey = keccak256(messageBytes);
  if (pendingRelays.has(relayKey)) return res.status(409).json({ error: "Already relaying" });
  pendingRelays.add(relayKey);

  try {
    // 3. Fetch attestation from Circle directly — never use a client-provided value
    const attestation = await fetchFromCircle(keccak256(messageBytes));

    // 4. Submit receiveMessage on behalf of the user
    const txHash = await walletClient.writeContract({
      address: CHAIN_CONFIGS[chainId].messageTransmitter,
      abi: MESSAGE_TRANSMITTER_ABI,
      functionName: "receiveMessage",
      args: [messageBytes, attestation],
      gas: 400_000n,  // eth_estimateGas false-reverts for CCTP — use explicit ceiling
    });

    res.json({ txHash });
  } finally {
    pendingRelays.delete(relayKey);
  }
});

Key decisions:

• Client sends messageBytes only — the relay derives destDomain and fetches attestation itself. A crafted attestation or wrong domain from the client would waste relayer gas on a revert.
• gas: 400_000n explicit ceiling — eth_estimateGas returns false reverts for CCTP v1 calls on Base Mainnet (simulation can't see the Circle attestation). Hard cap avoids estimation entirely; unused gas is refunded.
• In-flight dedup (pendingRelays Set) — prevents double-submission race if the user clicks twice.
• mintRecipient is contract-enforced — no redirect risk. The relay can only submit to the address already encoded in the message.

Full implementation + completed relay map + balance check + 409 "already received" handling: artifacts/api-server/src/routes/cctp.ts

Reference documentation: docs/GASLESS_CCTP.md