From 77761d0f13b0d8a1d616cf6a0700fba36bff69e6 Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Mon, 6 Jul 2026 23:57:32 +0100 Subject: [PATCH 1/2] Document attribution tags and Celo's x402 facilitator Adds a new Attribution Tags guide covering @celo/attribution-tags (ERC-8021), documents Celo's self-hosted x402 facilitator as an alternative to thirdweb's, and cross-links both from the places where they matter most (Proof of Ship, MiniPay, launch checklist, hackathon builders). Also notes attribution-for-x402-settlement as a proposed future integration, not a shipped feature. Co-Authored-By: Claude Sonnet 5 --- build-on-celo/attribution-tags.mdx | 136 ++++++++++++++++++ build-on-celo/build-on-minipay/quickstart.mdx | 4 + build-on-celo/build-with-ai/overview.mdx | 4 + build-on-celo/build-with-ai/x402.mdx | 71 +++++++++ build-on-celo/fund-your-project.mdx | 2 +- build-on-celo/launch-checklist.mdx | 1 + contribute-to-celo/builders.mdx | 2 +- docs.json | 1 + 8 files changed, 219 insertions(+), 2 deletions(-) create mode 100644 build-on-celo/attribution-tags.mdx diff --git a/build-on-celo/attribution-tags.mdx b/build-on-celo/attribution-tags.mdx new file mode 100644 index 000000000..da5ff965d --- /dev/null +++ b/build-on-celo/attribution-tags.mdx @@ -0,0 +1,136 @@ +--- +title: "Attribution Tags" +og:description: "Credit on-chain activity back to your app on Celo using ERC-8021 attribution tags." +--- + +Attribution tags let you mark transactions as coming from your app — so on-chain activity can be credited back to you for programs like [Proof of Ship](/build-on-celo/fund-your-project), MiniPay leaderboards, and hackathon tracking. This is Celo's implementation of [ERC-8021](https://oxlib.sh/ercs/erc8021/Attribution), the same standard behind [Base's Builder Codes](https://docs.base.org/apps/builder-codes/builder-codes). + +## How It Works + +ERC-8021 appends a small suffix to a transaction's calldata. The suffix is invisible to the contract being called — the EVM discards trailing bytes — so adding it never changes execution semantics. It just makes the transaction identifiable as having come through your app to anyone reading calldata off-chain. + + + Tagging a transaction is open to everyone. Whether a code gets *credited* on a leaderboard or rewards program is resolved at the registry/indexer layer, not at the tagging step. + + +## Install + +```bash +npm install @celo/attribution-tags viem +``` + +`viem` is an optional peer dependency — only required if you call `verifyTx` to decode a tag from a transaction hash. + +The SDK exports four functions: + +```ts +toDataSuffix(code | [codes]) // → encoded suffix (Hex) +codeFromHostname(hostname) // → "celo_" + 12 hex chars, derived from a hostname +fromDataSuffix(data) // → { codes, schemaId } | null +verifyTx({ client, hash }) // → { codes, schemaId } | null +``` + +## Quickstart: MiniPay Mini Apps + +If you're shipping a [MiniPay Mini App](/build-on-celo/build-on-minipay/overview), you don't need to register or be issued a code. The SDK derives a deterministic code from your app's hostname — same hostname, same code, every time: + +```ts +import { toDataSuffix, codeFromHostname } from "@celo/attribution-tags"; + +const tag = toDataSuffix(codeFromHostname(location.hostname)); + +await wallet.sendTransaction({ to, value, data: tag }); +``` + +That's the entire integration — no backend, no key, no registration form. + + + `codeFromHostname` reads `window.location`, so it's browser-only. In server-rendered frameworks (Next.js, Remix, SvelteKit), guard it with a `typeof window === "undefined"` check or call it from inside an event handler / effect — never at module top level in a `"use client"` file, since those still execute during SSR. + + +## Quickstart: Issued or Custom Codes + +If you've been issued a code (`celo_xxxxxxxx`) — for example through Proof of Ship onboarding or a hackathon registration — pass it directly: + +```ts +import { toDataSuffix } from "@celo/attribution-tags"; + +const tag = toDataSuffix("celo_b7k3p9da"); // issued code, or any custom string + +await wallet.sendTransaction({ to, value, data: tag }); +``` + +Any string matching `[a-z0-9_]` (1–32 characters) is a valid code. If a program assigned you a code, it must be present in the suffix — leaderboards and reward programs only credit the assigned code, not one you derive yourself with `codeFromHostname`. You can include both: + +```ts +const tag = toDataSuffix(["your_own_code", "celo_assigned1234"]); +``` + +## Tagging a Contract Call + +Concatenate your encoded calldata with the suffix: + +```ts +import { encodeFunctionData, concat } from "viem"; + +const callData = encodeFunctionData({ abi, functionName: "transfer", args }); +const taggedData = concat([callData, tag]); + +await wallet.sendTransaction({ to: tokenAddress, data: taggedData }); +``` + +With [wagmi](/tooling/dev-environments/thirdweb/overview), pass `dataSuffix` directly and wagmi handles the concatenation: + +```ts +const { writeContract } = useWriteContract(); + +writeContract({ + address, + abi, + functionName: "transfer", + args, + dataSuffix: tag, +}); +``` + +## The Layering Rule + +ERC-8021 suffixes can carry multiple codes, but **each code should only be added by the entity it represents**: + +- **Your app code** — added by your app, as shown above. +- **A platform code** like `minipay` — added by the platform itself (the wallet or cohort layer), never by your app. + +Adding a platform code from your own app would falsely claim every transaction ran inside that platform, polluting attribution data. + +## Verifying It Worked + +```ts +import { verifyTx } from "@celo/attribution-tags"; +import { createPublicClient, http } from "viem"; +import { celo } from "viem/chains"; + +const client = createPublicClient({ chain: celo, transport: http() }); + +const result = await verifyTx({ client, hash: "0x..." }); +console.log(result); // { codes: ["celo_b7k3p9da"], schemaId: 0 } +``` + +`verifyTx` returns `null` (never throws) if no tag is found. For offline decoding without an RPC call, use `fromDataSuffix(rawCalldata)` instead. + + + Some smart-account / bundler flows (ERC-4337 bundlers, meta-tx relayers) rewrite calldata and can strip trailing bytes. Verify on-chain with `verifyTx` before relying on tags in production. + + +## Resources + +| Resource | Link | +|----------|------| +| Source & full docs | [github.com/celo-org/attribution-tags](https://github.com/celo-org/attribution-tags) | +| npm package | [@celo/attribution-tags](https://www.npmjs.com/package/@celo/attribution-tags) | +| ERC-8021 standard | [oxlib.sh/ercs/erc8021](https://oxlib.sh/ercs/erc8021/Attribution) | + +## Related + +- [x402: Agent Payments](/build-on-celo/build-with-ai/x402) — attribution for x402 payments is a proposed next step, see that page for details +- [Fund your Project](/build-on-celo/fund-your-project) — Proof of Ship progress tracking uses attribution tags +- [Launch Checklist](/build-on-celo/launch-checklist) diff --git a/build-on-celo/build-on-minipay/quickstart.mdx b/build-on-celo/build-on-minipay/quickstart.mdx index 3e7857b4a..732502d7d 100644 --- a/build-on-celo/build-on-minipay/quickstart.mdx +++ b/build-on-celo/build-on-minipay/quickstart.mdx @@ -50,6 +50,10 @@ npx @celo/celo-composer@latest create -t minipay - Follow the [Helpful Tips Guide](#helpful-tips-to-make-your-mini-app-minipay-compatible) to ensure your app is MiniPay compatible. +#### Get credit for your app's activity: + +- Add an [attribution tag](/build-on-celo/attribution-tags) to your transactions. MiniPay apps need zero registration — `toDataSuffix(codeFromHostname(location.hostname))` derives a code from your app's hostname automatically. + ## 3. Get Testnet Tokens Request CELO testnet tokens from the Celo [faucet](https://faucet.celo.org/celo-sepolia/) to test your Mini App. After you got the CELO tokens, you can exchange them for stablecoins like USDm, USDT and USDC in the [mento app](https://app.mento.org/). diff --git a/build-on-celo/build-with-ai/overview.mdx b/build-on-celo/build-with-ai/overview.mdx index 5649aca77..2f5102e34 100644 --- a/build-on-celo/build-with-ai/overview.mdx +++ b/build-on-celo/build-with-ai/overview.mdx @@ -115,3 +115,7 @@ await sendUSDCWithFeeAbstraction("0xRecipient...", parseUnits("1", 6)); | USDC | Sepolia | [`0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B`](https://sepolia.celoscan.io/address/0x2f25deb3848c207fc8e0c34035b3ba7fc157602b) | [`0x4822e58de6f5e485eF90df51C41CE01721331dC0`](https://sepolia.celoscan.io/address/0x4822e58de6f5e485eF90df51C41CE01721331dC0) | For the full guide — including gas estimation, CIP-64 transaction types, and CLI usage — see [Fee Abstraction](/build-on-celo/fee-abstraction/using-fee-abstraction). + +## Crediting Agent Transactions to Your App + +Agents transacting on behalf of your app can also carry an [attribution tag](/build-on-celo/attribution-tags), so the on-chain activity they generate is credited back to you — useful for tracking usage across Proof of Ship, MiniPay, or your own analytics. diff --git a/build-on-celo/build-with-ai/x402.mdx b/build-on-celo/build-with-ai/x402.mdx index e6d684eb3..44ff07383 100644 --- a/build-on-celo/build-with-ai/x402.mdx +++ b/build-on-celo/build-with-ai/x402.mdx @@ -209,6 +209,75 @@ app.get("/api/premium", async (req, res) => { }); ``` +## Celo x402 Facilitator + +Celo runs its own self-hosted x402 facilitator at [x402.celo.org](https://x402.celo.org/), built on the open-source [`x402-rs`](https://github.com/x402-rs/x402-rs) implementation, as an alternative to thirdweb's facilitator. It accepts **USDC** and **USDT** on Celo via the gasless EIP-3009 `transferWithAuthorization` scheme — the buyer signs an authorization off-chain, and the facilitator submits it on-chain and pays the gas itself. The facilitator never custodies funds: `transferWithAuthorization` moves tokens directly payer → payee inside the token contract. + + + Source: `celo-org/x402-facilitator` (private repo). The endpoints below are live at [x402.celo.org](https://x402.celo.org/). + + +### Endpoints + +| Method | Path | Purpose | +|--------|--------------|--------------------------------------------------------------------| +| `POST` | `/verify` | Off-chain signature and simulation check of a payment payload. | +| `POST` | `/settle` | Submit the buyer's authorization on-chain (facilitator pays gas). | +| `GET` | `/supported` | List supported `(network, scheme)` pairs. | +| `GET` | `/health` | Liveness probe. | + + + cUSD / USDm are **not** supported by this facilitator — Mento's `StableTokenV2` implements only EIP-2612 `permit`, not EIP-3009. + + +### Pointing a Resource Server at It + +Any standard x402 middleware that accepts a custom facilitator URL can use the Celo facilitator. Example with `x402-express`: + +```ts +import express from "express"; +import { paymentMiddleware } from "x402-express"; + +const app = express(); + +app.use( + paymentMiddleware( + "0xYourSellerPayoutAddress", // where buyer funds land — not the facilitator's wallet + { + "GET /premium": { + price: { + amount: "10000", // smallest unit — USDC/USDT have 6 decimals, so 10000 = 0.01 + asset: { + address: "0xcEBA9300f2b948710d2653dD7B07f33A8B32118C", // Celo mainnet USDC + decimals: 6, + eip712: { name: "USDC", version: "2" }, // must match the token exactly + }, + }, + network: "eip155:42220", // Celo mainnet + }, + }, + { url: "https://x402.celo.org" }, // point at the Celo facilitator + ), +); + +app.get("/premium", (_req, res) => res.json({ data: "paid content" })); +app.listen(3000); +``` + + + USDT has no `version()` method on-chain — its EIP-712 domain resolves to `name: "Tether USD"`, `version: "1"`. Set those exactly in `asset.eip712` or signature verification fails. + + +### Attribution for x402 Payments (Proposed) + +There's no built-in way yet to credit an x402 payment on Celo back to the app that drove it — the equivalent of [Base's builder-code x402 extension](https://docs.cdp.coinbase.com/x402/builder-code.skill), which embeds a builder code into the facilitator's settlement transaction so payments are attributable on-chain. + +Celo's facilitator already submits the settlement transaction itself (the `transferWithAuthorization` call), so the same pattern could apply directly: the facilitator would accept an [attribution tag](/build-on-celo/attribution-tags) alongside the payment payload and append it as an ERC-8021 suffix — via `@celo/attribution-tags`'s `toDataSuffix` — to the settlement tx it submits. Client and resource server could then both verify the code post-settlement, the same way `verifyTx` works for ordinary transactions today. + + + This is a proposed integration, not a shipped feature — `celo-org/x402-facilitator`'s `/settle` endpoint has no attribution parameter today. + + ## x402 on Celo Celo is an ideal network for x402 due to: @@ -326,6 +395,7 @@ app.get("/articles/:id", async (req, res) => { | Resource | Link | |----------|------| | x402 Official Website | [x402.org](https://www.x402.org) | +| Celo x402 Facilitator | [x402.celo.org](https://x402.celo.org/) | | thirdweb x402 Docs | [portal.thirdweb.com/x402](https://portal.thirdweb.com/x402) | | thirdweb Playground | [playground.thirdweb.com/x402](https://playground.thirdweb.com/x402) | | GitHub | [github.com/coinbase/x402](https://github.com/coinbase/x402) | @@ -336,3 +406,4 @@ app.get("/articles/:id", async (req, res) => { - [ERC-8004](/build-on-celo/build-with-ai/8004) - Trust layer for AI agents - [Celopedia](/build-on-celo/build-with-ai/celopedia) - Celo ecosystem knowledge for coding assistants - [Fee Abstraction](/build-on-celo/fee-abstraction/overview) - Pay gas with stablecoins on Celo +- [Attribution Tags](/build-on-celo/attribution-tags) - Credit on-chain activity back to your app diff --git a/build-on-celo/fund-your-project.mdx b/build-on-celo/fund-your-project.mdx index 0a9170d3d..3fae887ca 100644 --- a/build-on-celo/fund-your-project.mdx +++ b/build-on-celo/fund-your-project.mdx @@ -19,7 +19,7 @@ Learn more about the programs below. Here’s how you can get started: -1. **Apply for monthly rewards with [Proof of Ship](https://celo-devs.beehiiv.com/subscribe)** Demonstrate consistent progress for automated retroactive rewards. +1. **Apply for monthly rewards with [Proof of Ship](https://celo-devs.beehiiv.com/subscribe)** Demonstrate consistent progress for automated retroactive rewards. Add [attribution tags](/build-on-celo/attribution-tags) to your transactions so your on-chain activity is credited to your project. ## Apply for Grant Opportunities diff --git a/build-on-celo/launch-checklist.mdx b/build-on-celo/launch-checklist.mdx index 23f733ac8..f518316e4 100644 --- a/build-on-celo/launch-checklist.mdx +++ b/build-on-celo/launch-checklist.mdx @@ -32,6 +32,7 @@ A comprehensive guide to assist you in launching dapps on Celo. ### Analytics & Monitoring +- [ ] **Attribution Tags**: Add [attribution tags](/build-on-celo/attribution-tags) to your transactions so on-chain activity is credited to your app (used by Proof of Ship and MiniPay tracking) - [ ] **Analytics Setup**: Configure analytics tracking (e.g., Google Analytics, Mixpanel) - [ ] **Monitoring Tools**: Set up monitoring and alerting (e.g., Sentry, DataDog) - [ ] **On-Chain Analytics**: Integrate on-chain analytics tools (e.g., Dune, The Graph) diff --git a/contribute-to-celo/builders.mdx b/contribute-to-celo/builders.mdx index 118e759f9..c007c097b 100644 --- a/contribute-to-celo/builders.mdx +++ b/contribute-to-celo/builders.mdx @@ -12,7 +12,7 @@ The Celo Builder Community is a global network of developers, entrepreneurs, and There are several ways to get started as a builder on Celo: -* [**Sign up to Proof of Ship**](https://celo-devs.beehiiv.com/subscribe): Prove their impact, showcase progress, and earn rewards. Your onchain reputation unlocks access to grants, retro funding, airdrops, and other funding opportunities. +* [**Sign up to Proof of Ship**](https://celo-devs.beehiiv.com/subscribe): Prove their impact, showcase progress, and earn rewards. Your onchain reputation unlocks access to grants, retro funding, airdrops, and other funding opportunities. Make sure your app includes an [attribution tag](/build-on-celo/attribution-tags) — self-derived or assigned at registration — so your transactions get credited. * **Join the Builder Community**: Connect with like-minded individuals on platforms like [Discord](https://discord.com/invite/celo) and the [Celo Forum](https://forum.celo.org/). You'll find channels dedicated to everything from smart contract development to mobile-first dApp creation. diff --git a/docs.json b/docs.json index 067c4528e..c103780ed 100644 --- a/docs.json +++ b/docs.json @@ -118,6 +118,7 @@ "build-on-celo/network-overview", "build-on-celo/cel2-architecture", "build-on-celo/launch-checklist", + "build-on-celo/attribution-tags", "build-on-celo/scaling-your-app", "build-on-celo/fund-your-project", "build-on-celo/nightfall" From 7c970c7a038e10922b2cb2e5c6c461b630662ddd Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Tue, 7 Jul 2026 00:05:43 +0100 Subject: [PATCH 2/2] Trim speculative and MiniPay-specific content from attribution docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removes the proposed (unshipped) x402 attribution integration section, drops the direct competitor comparison in the attribution tags intro, and removes the MiniPay-specific quickstart — that flow will get its own separate treatment later. Attribution Tags now has a single, general Quickstart section. Co-Authored-By: Claude Sonnet 5 --- build-on-celo/attribution-tags.mdx | 24 +++---------------- build-on-celo/build-on-minipay/quickstart.mdx | 4 ---- build-on-celo/build-with-ai/x402.mdx | 10 -------- 3 files changed, 3 insertions(+), 35 deletions(-) diff --git a/build-on-celo/attribution-tags.mdx b/build-on-celo/attribution-tags.mdx index da5ff965d..02864a7a8 100644 --- a/build-on-celo/attribution-tags.mdx +++ b/build-on-celo/attribution-tags.mdx @@ -3,7 +3,7 @@ title: "Attribution Tags" og:description: "Credit on-chain activity back to your app on Celo using ERC-8021 attribution tags." --- -Attribution tags let you mark transactions as coming from your app — so on-chain activity can be credited back to you for programs like [Proof of Ship](/build-on-celo/fund-your-project), MiniPay leaderboards, and hackathon tracking. This is Celo's implementation of [ERC-8021](https://oxlib.sh/ercs/erc8021/Attribution), the same standard behind [Base's Builder Codes](https://docs.base.org/apps/builder-codes/builder-codes). +Attribution tags let you mark transactions as coming from your app — so on-chain activity can be credited back to you for programs like [Proof of Ship](/build-on-celo/fund-your-project), MiniPay leaderboards, and hackathon tracking. Celo's implementation follows [ERC-8021](https://oxlib.sh/ercs/erc8021/Attribution). ## How It Works @@ -30,25 +30,7 @@ fromDataSuffix(data) // → { codes, schemaId } | null verifyTx({ client, hash }) // → { codes, schemaId } | null ``` -## Quickstart: MiniPay Mini Apps - -If you're shipping a [MiniPay Mini App](/build-on-celo/build-on-minipay/overview), you don't need to register or be issued a code. The SDK derives a deterministic code from your app's hostname — same hostname, same code, every time: - -```ts -import { toDataSuffix, codeFromHostname } from "@celo/attribution-tags"; - -const tag = toDataSuffix(codeFromHostname(location.hostname)); - -await wallet.sendTransaction({ to, value, data: tag }); -``` - -That's the entire integration — no backend, no key, no registration form. - - - `codeFromHostname` reads `window.location`, so it's browser-only. In server-rendered frameworks (Next.js, Remix, SvelteKit), guard it with a `typeof window === "undefined"` check or call it from inside an event handler / effect — never at module top level in a `"use client"` file, since those still execute during SSR. - - -## Quickstart: Issued or Custom Codes +## Quickstart If you've been issued a code (`celo_xxxxxxxx`) — for example through Proof of Ship onboarding or a hackathon registration — pass it directly: @@ -131,6 +113,6 @@ console.log(result); // { codes: ["celo_b7k3p9da"], schemaId: 0 } ## Related -- [x402: Agent Payments](/build-on-celo/build-with-ai/x402) — attribution for x402 payments is a proposed next step, see that page for details +- [x402: Agent Payments](/build-on-celo/build-with-ai/x402) - [Fund your Project](/build-on-celo/fund-your-project) — Proof of Ship progress tracking uses attribution tags - [Launch Checklist](/build-on-celo/launch-checklist) diff --git a/build-on-celo/build-on-minipay/quickstart.mdx b/build-on-celo/build-on-minipay/quickstart.mdx index 732502d7d..3e7857b4a 100644 --- a/build-on-celo/build-on-minipay/quickstart.mdx +++ b/build-on-celo/build-on-minipay/quickstart.mdx @@ -50,10 +50,6 @@ npx @celo/celo-composer@latest create -t minipay - Follow the [Helpful Tips Guide](#helpful-tips-to-make-your-mini-app-minipay-compatible) to ensure your app is MiniPay compatible. -#### Get credit for your app's activity: - -- Add an [attribution tag](/build-on-celo/attribution-tags) to your transactions. MiniPay apps need zero registration — `toDataSuffix(codeFromHostname(location.hostname))` derives a code from your app's hostname automatically. - ## 3. Get Testnet Tokens Request CELO testnet tokens from the Celo [faucet](https://faucet.celo.org/celo-sepolia/) to test your Mini App. After you got the CELO tokens, you can exchange them for stablecoins like USDm, USDT and USDC in the [mento app](https://app.mento.org/). diff --git a/build-on-celo/build-with-ai/x402.mdx b/build-on-celo/build-with-ai/x402.mdx index 44ff07383..41d870bec 100644 --- a/build-on-celo/build-with-ai/x402.mdx +++ b/build-on-celo/build-with-ai/x402.mdx @@ -268,16 +268,6 @@ app.listen(3000); USDT has no `version()` method on-chain — its EIP-712 domain resolves to `name: "Tether USD"`, `version: "1"`. Set those exactly in `asset.eip712` or signature verification fails. -### Attribution for x402 Payments (Proposed) - -There's no built-in way yet to credit an x402 payment on Celo back to the app that drove it — the equivalent of [Base's builder-code x402 extension](https://docs.cdp.coinbase.com/x402/builder-code.skill), which embeds a builder code into the facilitator's settlement transaction so payments are attributable on-chain. - -Celo's facilitator already submits the settlement transaction itself (the `transferWithAuthorization` call), so the same pattern could apply directly: the facilitator would accept an [attribution tag](/build-on-celo/attribution-tags) alongside the payment payload and append it as an ERC-8021 suffix — via `@celo/attribution-tags`'s `toDataSuffix` — to the settlement tx it submits. Client and resource server could then both verify the code post-settlement, the same way `verifyTx` works for ordinary transactions today. - - - This is a proposed integration, not a shipped feature — `celo-org/x402-facilitator`'s `/settle` endpoint has no attribution parameter today. - - ## x402 on Celo Celo is an ideal network for x402 due to: