diff --git a/build-on-celo/attribution-tags.mdx b/build-on-celo/attribution-tags.mdx new file mode 100644 index 000000000..02864a7a8 --- /dev/null +++ b/build-on-celo/attribution-tags.mdx @@ -0,0 +1,118 @@ +--- +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. Celo's implementation follows [ERC-8021](https://oxlib.sh/ercs/erc8021/Attribution). + +## 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 + +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) +- [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-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..41d870bec 100644 --- a/build-on-celo/build-with-ai/x402.mdx +++ b/build-on-celo/build-with-ai/x402.mdx @@ -209,6 +209,65 @@ 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. + + ## x402 on Celo Celo is an ideal network for x402 due to: @@ -326,6 +385,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 +396,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"