diff --git a/build-on-celo/build-with-ai/8004.mdx b/build-on-celo/build-with-ai/8004.mdx index 6ebd11c93..f2be4caba 100644 --- a/build-on-celo/build-with-ai/8004.mdx +++ b/build-on-celo/build-with-ai/8004.mdx @@ -259,6 +259,7 @@ ERC-8004 works seamlessly with Celo's ecosystem: - **Fee abstraction**: Register agents and give feedback paying gas in stablecoins - **x402 payments**: Combine trust verification with instant payments - **MCP servers**: Agents can expose capabilities via Celo MCP Server +- **Self Agent ID**: A deployment of all three ERC-8004 registries on Celo that adds a zero-knowledge proof-of-human to each agent identity — see [Self Agent ID](/build-on-celo/build-with-ai/self-agent-id) ## Resources @@ -273,6 +274,7 @@ ERC-8004 works seamlessly with Celo's ecosystem: ## Related Protocols +- [Self Agent ID](/build-on-celo/build-with-ai/self-agent-id) - ERC-8004 registries with proof-of-human, live on Celo - [x402](/build-on-celo/build-with-ai/x402) - Payment layer for AI agents - [MPP](/build-on-celo/build-with-ai/mpp) - Machine Payments Protocol: charge USDC per request over HTTP - [Celopedia](/build-on-celo/build-with-ai/celopedia) - Celo ecosystem knowledge for coding assistants diff --git a/build-on-celo/build-with-ai/self-agent-id.mdx b/build-on-celo/build-with-ai/self-agent-id.mdx new file mode 100644 index 000000000..57df70d6d --- /dev/null +++ b/build-on-celo/build-with-ai/self-agent-id.mdx @@ -0,0 +1,173 @@ +--- +title: "Self Agent ID: Proof-of-Human Identity for Agents" +sidebarTitle: "Self: Agent Identity" +description: Give an AI agent a soulbound on-chain identity on Celo, backed by a zero-knowledge passport proof, and verify agent requests in your service with Self Agent ID +--- + +This page is for developers who build AI agents and for services that want to accept requests from agents without accepting bots. Self Agent ID is an on-chain registry on Celo that binds an agent's signing key to a zero-knowledge proof that one real, unique human stands behind it. The agent receives a soulbound ERC-721 NFT; services check it with one middleware call. It implements the [ERC-8004](/build-on-celo/build-with-ai/8004) registries and adds a proof-of-human extension. + +For verifying *humans* in your app (passport, EU ID, Aadhaar), see [Build with Self](/build-on-celo/build-with-self). + +## How it works + +1. A human scans their passport or ID in the Self app. The zero-knowledge proof is generated on the phone; no personal data leaves the device. +2. The Self Hub verifies the proof on Celo and calls the registry. +3. The registry mints a soulbound NFT that links the agent's key to the human's unique nullifier. One human can back a bounded number of agents — the default sybil limit is one. +4. The agent signs every outbound request with its key. The service verifies the signature against the registry and reads the human-proof flags (age, OFAC, freshness) it needs. + +## Contracts + +All addresses below were checked with `eth_getCode` on 2026-08-21; the identity registry reports `name() = "Self Agent ID"`, `symbol() = "SAID"`. + +| Contract | Celo mainnet (42220) | Celo Sepolia (11142220) | +|---|---|---| +| SelfAgentRegistry (identity, proof-of-human) | [`0xaC3DF9ABf80d0F5c020C06B04Cced27763355944`](https://celoscan.io/address/0xaC3DF9ABf80d0F5c020C06B04Cced27763355944) | [`0x043DaCac8b0771DD5b444bCC88f2f8BBDBEdd379`](https://celo-sepolia.blockscout.com/address/0x043DaCac8b0771DD5b444bCC88f2f8BBDBEdd379) | +| SelfReputationRegistry | [`0x69Da18CF4Ac27121FD99cEB06e38c3DC78F363f4`](https://celoscan.io/address/0x69Da18CF4Ac27121FD99cEB06e38c3DC78F363f4) | see [Self smart contracts](https://docs.self.xyz/docs/agent-id/smart-contracts/) | +| SelfValidationRegistry | [`0x71a025e0e338EAbcB45154F8b8CA50b41e7A0577`](https://celoscan.io/address/0x71a025e0e338EAbcB45154F8b8CA50b41e7A0577) | see [Self smart contracts](https://docs.self.xyz/docs/agent-id/smart-contracts/) | +| Celo Agent Visa | [`0xCa97f7586CF9De62B8ca516d7Ee25f6AEae5e109`](https://celoscan.io/address/0xCa97f7586CF9De62B8ca516d7Ee25f6AEae5e109) | [`0xf049FD6260Fce964B82728A86CF1BbEB8AB3E875`](https://celo-sepolia.blockscout.com/address/0xf049FD6260Fce964B82728A86CF1BbEB8AB3E875) | + + +Self Agent ID is deployed on **Celo Sepolia (chain ID 11142220)**, not on the retired Alfajores testnet (44787). On mainnet the Self app requires a real passport or ID document; on Celo Sepolia it accepts mock documents, so you can test the whole flow without one. + + +## Prerequisites + +- Node.js 18+ (TypeScript SDK) — Python (`pip install selfxyz-agent-sdk`) and Rust (`cargo add self-agent-sdk`) SDKs exist too +- The [Self app](https://self.xyz/) on a phone, to scan the registration QR code +- A Celo RPC endpoint: `https://forno.celo.org` (mainnet) or `https://forno.celo-sepolia.celo-testnet.org` (Celo Sepolia) + +## Register an agent + +The CLI ships with the SDK. Registration is a browser handoff: the terminal creates a session, you scan a QR code with the Self app, the proof is verified on-chain, and the agent NFT is minted. + +```bash +npm install -g @selfxyz/agent-sdk + +# 1. Create a session on Celo Sepolia. --mode linked keeps the NFT in the human's wallet. +# For an agent that owns its own NFT use --mode wallet-free and drop --human-address. +self-agent register init \ + --mode linked \ + --human-address 0xYourWalletAddress \ + --network testnet \ + --minimum-age 18 \ + --ofac \ + --out .self/session.json + +# 2. Open the QR code in your browser and scan it with the Self app +self-agent register open --session .self/session.json + +# 3. Wait for the on-chain verification to complete +self-agent register wait --session .self/session.json + +# 4. Export the agent address, agent ID and key. The private key is only printed with --unsafe. +self-agent register export --session .self/session.json --unsafe --print-private-key +``` + +Store the exported private key in a secrets manager or an environment variable (`AGENT_PRIVATE_KEY` below). Never commit it. Use `--network mainnet` for a production agent. + +### Registration modes + +| Mode | Wallet needed | Who owns the NFT | +|---|---|---| +| `linked` | Yes, at registration only | The human's wallet | +| `wallet-free` | No | The agent's own key | +| `ed25519` | No | Address derived from an Ed25519 key | +| `ed25519-linked` | Yes, at registration only | The human's wallet | +| `privy` | No (social login) | An embedded wallet created for the human | +| `smartwallet` | No (passkey) | A passkey smart wallet; gasless on mainnet | + +All modes work on both networks and produce the same soulbound NFT. Details: [Registration modes](https://docs.self.xyz/docs/agent-id/registration-modes/). + +## Call a service as an agent + +`agent.fetch()` is `fetch()` with three signed headers added to every request: `x-self-agent-address`, `x-self-agent-signature`, and `x-self-agent-timestamp`. + +```ts +import { SelfAgent } from "@selfxyz/agent-sdk"; + +// Celo Sepolia (11142220). For mainnet pass registryAddress and rpcUrl instead of network: +// { privateKey, registryAddress: "0xaC3DF9ABf80d0F5c020C06B04Cced27763355944", rpcUrl: "https://forno.celo.org" } +const agent = new SelfAgent({ + privateKey: process.env.AGENT_PRIVATE_KEY!, + network: "testnet", +}); + +const res = await agent.fetch("https://api.example.com/protected", { + method: "POST", + body: JSON.stringify({ action: "hello" }), +}); + +// Check the agent's own registration state +const registered = await agent.isRegistered(); +const creds = await agent.getCredentials(); +``` + +## Verify agents in your service + +The verifier checks the signature, looks the address up in the registry, and enforces the human-proof rules you configure. The Express middleware rejects anything that fails before your handler runs. + +```ts +import express from "express"; +import { SelfAgentVerifier } from "@selfxyz/agent-sdk"; + +const app = express(); + +const verifier = SelfAgentVerifier.create() + .requireAge(18) // proof says the human is 18 or older + .requireOFAC() // proof passed the OFAC check + .sybilLimit(1) // at most one agent per human may call this service + .build(); + +app.use("/api", verifier.auth()); +``` + +Without Express, call `verifier.verify({ signature, timestamp, method, url, body })` with the values from the three headers and the request. + +Defaults: sybil limit 1, replay protection on, and requests older than 300 seconds are rejected. + +## Troubleshooting + +- **The Self app refuses the document on mainnet.** Mainnet accepts real passports and IDs only. Develop against `--network testnet` (Celo Sepolia), where mock documents are accepted. +- **Registration never completes.** Check the session state with `self-agent register status --session .self/session.json`; states run `initialized → handoff_opened → callback_received → onchain_verified`. If it stalls at `handoff_opened`, the QR code was not scanned or the app is on the other network. +- **`register export` prints no private key.** Add `--unsafe --print-private-key`; the key is withheld by default. +- **Requests are rejected by the verifier although the agent is registered.** The timestamp window is 300 seconds — keep the agent host's clock in sync. Also confirm both sides use the same network; a Celo Sepolia agent is unknown to a mainnet registry. +- **`userDefinedData` is garbled on-chain.** The SDK passes it as a UTF-8 string; use ASCII characters, not raw bytes. + +## Celo Agent Visa + +Celo Agent Visa is a tiered soulbound NFT that records an agent's on-chain activity on Celo. Claims are gasless — the Self relayer pays. Tracked metrics are transaction count and stablecoin volume in USDT, USDC and USDm. + +| Tier | Requirement | +|---|---| +| 1 — Tourist Visa | Registered in the Self Agent Registry + 1 transaction | +| 2 — Work Visa | Human proof + 1,000 transactions or $5,000 stablecoin volume | +| 3 — Citizenship | Human proof + 10,000 transactions or $15,000 stablecoin volume; manual review | + +Flow: register → transact on Celo → check eligibility → claim (tiers 1–2 directly, tier 3 after approval). Contract addresses are in the table above; the claim API is `https://agent-api.self.xyz`. Details: [Celo Agent Visa](https://docs.self.xyz/docs/agent-id/celo-agent-visa/). + +## How this relates to ERC-8004 + +Self Agent ID implements all three ERC-8004 registry roles — identity (`SelfAgentRegistry`), reputation (`SelfReputationRegistry`) and validation (`SelfValidationRegistry`) — and extends the identity registry with `registerWithHumanProof()`, `revokeHumanProof()`, proof-validity queries, and nullifier-based sybil detection. The extension is provider-agnostic through an `IHumanProofProvider` interface, so any zero-knowledge identity system can plug in. + +These are Self's own deployments. The reference ERC-8004 registries on Celo (`0x8004A169…` mainnet) listed on the [ERC-8004 page](/build-on-celo/build-with-ai/8004#contract-deployments) are separate contracts; an agent can be registered in both. + +## Resources + +| Resource | Link | +|---|---| +| Overview | [docs.self.xyz/docs/agent-id/overview](https://docs.self.xyz/docs/agent-id/overview/) | +| Register an agent | [docs.self.xyz/docs/agent-id/register-an-agent](https://docs.self.xyz/docs/agent-id/register-an-agent/) | +| SDK integration | [docs.self.xyz/docs/agent-id/sdk-integration](https://docs.self.xyz/docs/agent-id/sdk-integration/) | +| CLI reference | [docs.self.xyz/docs/agent-id/cli](https://docs.self.xyz/docs/agent-id/cli/) | +| REST / A2A API | `https://agent-api.self.xyz` — [reference](https://docs.self.xyz/docs/agent-id/rest-api/) | +| Service operator guide | [docs.self.xyz/docs/agent-id/guides/service-operator](https://docs.self.xyz/docs/agent-id/guides/service-operator/) | +| Troubleshooting | [docs.self.xyz/docs/agent-id/troubleshooting](https://docs.self.xyz/docs/agent-id/troubleshooting/) | +| Source | [github.com/selfxyz/self-agent-id](https://github.com/selfxyz/self-agent-id) | + +## Related + +- [ERC-8004](/build-on-celo/build-with-ai/8004) - The trust standard Self Agent ID implements +- [Build with Self](/build-on-celo/build-with-self) - Verify humans, not agents, with the same proofs +- [x402](/build-on-celo/build-with-ai/x402) - Let a verified agent pay per request +- [MPP](/build-on-celo/build-with-ai/mpp) - Charge agents per API call in USDC +- [Fee abstraction](/build-on-celo/fee-abstraction/overview) - Pay gas in stablecoins from the agent wallet diff --git a/build-on-celo/build-with-self.mdx b/build-on-celo/build-with-self.mdx index 4d5c2b273..8376a9415 100644 --- a/build-on-celo/build-with-self.mdx +++ b/build-on-celo/build-with-self.mdx @@ -1,97 +1,51 @@ --- title: Build with Self -description: A comprehensive guide to understanding and using Self identity protocol on Celo +description: Verify that your users are real, unique humans — and prove age or nationality — with zero-knowledge proofs from passports, EU ID cards and Aadhaar, using Self on Celo --- -Self is a leading digital identity infrastructure for Web2 and Web3. Self leverages zero-knowledge cryptography to disclose verifiable credentials without revealing any sensitive information. No third parties. No data leaks. +This page is for app developers who need to know that a user is a real, unique human, or that they meet an age or nationality rule, without collecting their documents. [Self](https://self.xyz/) is an open-source identity protocol: the user scans a passport, EU ID card or Indian Aadhaar with their phone, a zero-knowledge proof is generated on the device, and your app receives only the facts the user chose to disclose. Attestations are recorded on Celo. - -Self is the only leader in the space that is production-ready, live across iOS and Google Play Store, and fully audited by third-party zkSecurity that doesn’t rely on additional dependencies such as biometric hardware. - +If you are giving an **AI agent** an identity rather than verifying a person, go to [Self Agent ID](/build-on-celo/build-with-ai/self-agent-id). -By the conclusion of this guide, you will have a comprehensive understanding of Self and how to integrate it into your Celo applications. +## How it works -This document will cover: +1. **Scan.** The user scans the NFC chip of their passport, EU ID card or Aadhaar with the Self app. +2. **Prove.** The app generates a zero-knowledge proof over the document, disclosing only the attributes your app asked for — for example "over 18" or "not on a sanctions list", never the passport number. +3. **Share.** The user scans your app's QR code (or taps a deeplink) and the proof is delivered to your backend or smart contract, where it is verified against Self's hub contract on Celo. -- What is Self? -- Getting Started -- New Features (2025) -- Technical Resources -- Use Cases +No personal data leaves the device. The same proof also yields a nullifier, so you can tell one human from another without knowing who they are. -## What is Self? +## What you can check -[Self](https://self.xyz/) is a privacy-first, open-source identity protocol that uses zero-knowledge proofs for secure identity verification. +| Check | Typical use | +|---|---| +| Proof of humanity and uniqueness | Sybil-resistant airdrops, quadratic funding, polls, one-account-per-person marketplaces | +| Age | Age-gated products and content | +| Nationality and sanctions status | Geo-restricted or compliance-gated services | +| Wallet recovery | Re-link a wallet to a verified person | -It enables Sybil resistance and selective disclosure using real-world attestations like passports, EU ID cards, and Indian Aadhaar. With a few lines of code, developers can easily check if their users are humans, while preserving their privacy. +## Get started -### How It Works +1. Try the [playground](https://playground.self.xyz/) to see which attributes a proof can disclose. +2. Follow the [Self quickstart](https://docs.self.xyz/docs/self-pass/quickstart) to add the QR-code flow to your frontend with the [QRCode SDK](https://docs.self.xyz/docs/self-pass/frontend/qrcode-sdk). +3. Verify proofs either on-chain with the [contract integration guide](https://docs.self.xyz/docs/self-pass/contracts/basic-integration) — deployed hub addresses are in [Deployed contracts](https://docs.self.xyz/docs/self-pass/contracts/deployed-contracts) — or in your backend with the [backend integration guide](https://docs.self.xyz/docs/self-pass/backend/basic-integration). -Self Protocol simplifies digital identity verification with zero-knowledge proofs in three steps: +Self's contracts on Celo follow the same fee rules as any other contract: your users can pay gas in USDm, USDC or USDT through [fee abstraction](/build-on-celo/fee-abstraction/overview), so a verification flow never requires them to hold CELO. -1. **Scan Your Identity Document**: Users scan their passport, EU ID card, or Aadhaar using the NFC reader of their phone. -2. **Generate a Proof**: Generate a zk proof over the identity document, selecting only what you want to disclose. -3. **Share Your Proof**: Share the zk proof with the selected application. +## Resources -## Use cases +| Resource | Link | +|---|---| +| Self documentation | [docs.self.xyz](https://docs.self.xyz/) | +| Playground | [playground.self.xyz](https://playground.self.xyz/) | +| Staging playground | [playground.staging.self.xyz](https://playground.staging.self.xyz/) | +| Deployed contracts | [docs.self.xyz/docs/self-pass/contracts/deployed-contracts](https://docs.self.xyz/docs/self-pass/contracts/deployed-contracts) | +| Builder group (Telegram) | [t.me/selfprotocolbuilder](https://t.me/selfprotocolbuilder) | +| Celo Discord, `#build-with-celo` | [discord.com/invite/celo](https://discord.com/invite/celo) | -Seamlessly and securely verify your digital identity with Self. It allows you to: +## Related -- **Prove Your Humanity:** Confirm you are human without revealing personal information. - - Airdrop Protection - - Social Media & Marketplaces (add trust to user profiles) - - Quadratic Funding - - Sybil-Resistant Polling -- **Prove Identity, Age, Nationality:** Demonstrate where you're from while maintaining privacy. Securely capture the first page data and RFID from your passport to verify your identity. - - Sanction List Checking - - Age Verification - - Wallet Recovery -- **Privacy-preserving Technology:** Protect your users' private information. They will only disclose credentials and information that they allow. -- **Streamline Verification:** Enjoy a smooth and efficient identity verification process. -- **Optimized for Web3 and Universal Apps:** Harness zero-knowledge proofs and one-tap verifications in Web3 apps. - -## New Features (2025) - -### Expanded Identity Document Support - -Self now supports: - -- **EU Biometric ID Cards**: Scan NFC-enabled EU IDs covering 27 countries -- **Indian Aadhaar**: Support for Aadhaar verification -- **Passports**: Continued support for passport verification - -All verification leverages zero-knowledge proofs (ZKPs) and no data leaves the user's device. - -### Points/Rewards System - -Self has introduced a points program that incentivizes consistent, secure use: - -- Users earn points for setting up Self Pass -- Points earned for continued use across partner platforms -- Points can be redeemed for rewards -- Designed to drive engagement and validate active, verified users - -### Major Integrations - -- **Google Cloud**: Integrated Self's SDK and ZKP-based proof-of-humanity in its Web3 Portal -- **Aave**: DeFi protocol integration enabling compliance checks, sybil-resistant airdrops, and age/country-gated services -- **Celo Blockchain**: On-chain attestations leverage the Celo blockchain for transparency and auditability - - -## Technical Resources - -- [Self Website](https://self.xyz/) -- [Self Documentation](https://docs.self.xyz/) -- [Self Playground](https://playground.self.xyz/) -- [Self Staging Playground](https://playground.staging.self.xyz/) -- [Self Quickstart Guide](https://docs.self.xyz/docs/self-pass/quickstart) -- [Contract Integration Guide](https://docs.self.xyz/docs/self-pass/contracts/basic-integration) -- [Backend Integration Guide](https://docs.self.xyz/docs/self-pass/backend/basic-integration) -- [QRCode SDK Documentation](https://docs.self.xyz/docs/self-pass/frontend/qrcode-sdk) -- [Deployed Contracts](https://docs.self.xyz/docs/self-pass/contracts/deployed-contracts) - -## Support - -Join the [Self Builder Group](https://t.me/selfprotocolbuilder) on Telegram for community support and updates. - -For Celo-specific integrations, visit the [Celo Discord](https://discord.com/invite/celo) and ask in the #build-with-celo channel. +- [Self Agent ID](/build-on-celo/build-with-ai/self-agent-id) - Proof-of-human identity for AI agents +- [ERC-8004](/build-on-celo/build-with-ai/8004) - Agent identity, reputation and validation registries +- [SocialConnect](/build-on-celo/build-on-socialconnect) - Map phone numbers to addresses +- [Fee abstraction](/build-on-celo/fee-abstraction/overview) - Let users pay gas in stablecoins diff --git a/docs.json b/docs.json index 9cccf828f..189eb6cb1 100644 --- a/docs.json +++ b/docs.json @@ -130,9 +130,15 @@ "build-on-celo/build-with-ai/overview", "build-on-celo/build-with-ai/use-docs-with-ai", { - "group": "Agent Infrastructure", + "group": "Agent Identity", "pages": [ "build-on-celo/build-with-ai/8004", + "build-on-celo/build-with-ai/self-agent-id" + ] + }, + { + "group": "Agent Infrastructure", + "pages": [ "build-on-celo/build-with-ai/x402", "build-on-celo/build-with-ai/mpp", "build-on-celo/build-with-ai/celopedia",