self-agent-id-overview

name: self-agent-id-overview description: > Conceptual overview of the Self Agent ID system — on-chain identity registry, ERC-8004 standard, ZK proof-of-human, provider system, trust model, and soulbound NFTs on Celo. Use when the user asks "what is self agent id", "explain self agent id", "how does agent identity work", "self protocol agents", "ERC-8004", or "proof of human for agents". Do NOT use for specific workflows like registration, signing, verification, or integration — use the dedicated skills for those. license: MIT metadata: author: Self Protocol version: 1.0.0 mcp-server: self-agent-id

Self Agent ID — Overview

What Self Agent ID Is

Self Agent ID is an on-chain identity registry deployed on the Celo blockchain that binds AI agent identities to Self Protocol human proofs. Each registered agent receives a soulbound ERC-721 NFT backed by a zero-knowledge passport verification performed through the Self mobile app.

The core purpose: enable trustless, on-chain proof-of-human for autonomous AI agents. Any service, smart contract, or protocol can query the registry to verify that an agent is backed by a real, unique human — without revealing any personal information. This solves the fundamental trust problem in agentic AI: how does a service know it is interacting with a legitimate agent operated by a real person, not a bot farm or impersonator?

The registration flow works as follows: a human scans their passport with the Self mobile app, which reads the NFC chip and generates a zero-knowledge proof locally on the device. This proof is submitted to Self Protocol's Hub V2 contract on-chain, which verifies the proof and calls back into the SelfAgentRegistry. The registry then mints a soulbound ERC-721 NFT to represent the verified agent identity. Once registered, the agent can sign HTTP requests with ECDSA, and any receiving service can verify both the signature and the on-chain proof status in a single step.

The system consists of:

• Smart contracts — An ERC-721 registry with soulbound NFTs, proof providers, reputation scoring, and freshness validation. Deployed on Celo Mainnet and Celo Sepolia testnet.
• SDKs — Client libraries in TypeScript, Python, and Rust for agent registration, HTTP request signing, and server-side verification.
• MCP Server — A Model Context Protocol server (@selfxyz/mcp-server) exposing 10 tools for AI coding assistants like Claude Code and Cursor.
• REST API — Hosted endpoints at agent-api.self.xyz for registration flows, agent discovery, verification, and agent cards.

ERC-8004 Standard

ERC-8004 is a proposed standard for on-chain AI agent registries. Self Agent ID implements three ERC-8004 registry types:

Identity Registry (Core)

The SelfAgentRegistry contract is the primary ERC-721 identity registry. It issues soulbound (non-transferable) NFTs to registered agents. Each NFT represents a verified agent identity with an associated human proof, proof provider, nullifier (for sybil resistance), and optionally ZK-attested credentials (nationality, age, OFAC status).

Reputation Registry

The SelfReputationProvider contract implements the ERC-8004 reputation registry pattern. It provides a getReputationScore(agentId) function returning a score from 0 to 100, derived from the verification strength of the proof provider that verified the agent. Self Protocol scores 100 (passport NFC + biometric). A hypothetical video-liveness provider might score 40.

Validation Registry

The SelfValidationProvider contract implements the ERC-8004 validation registry pattern. It performs freshness checks — determining whether an agent's proof is still considered "fresh" based on how many blocks have elapsed since registration. The default threshold is approximately 1 year on Celo (~6,307,200 blocks at 5 seconds per block).

Provider System

The registry uses a pluggable IHumanProofProvider interface, allowing any identity verification system to serve as a proof-of-human provider. Each provider reports:

• providerName() — A human-readable identifier (e.g., "self")
• verificationStrength() — A score from 0 to 100 reflecting the rigor of verification
• verifyHumanProof() — The verification entry point (synchronous or async depending on provider)

Self Protocol Provider

Self Protocol's implementation (SelfHumanProofProvider) has these characteristics:

The async pattern works as follows: the dApp calls verifySelfProof() on the registry, Hub V2 verifies the ZK proof, then Hub V2 calls back into the registry's customVerificationHook() which mints the NFT.

Other Potential Providers

The provider system is designed to be extensible. Other identity protocols could implement IHumanProofProvider with different verification strengths:

Trust Model

Zero-Knowledge Proofs

Passport data never leaves the user's phone. The Self mobile app reads the passport NFC chip locally and generates a ZK proof. Only the proof (not the underlying data) is submitted on-chain. The registry stores only the nullifier and optionally disclosed credential claims (nationality, age threshold, OFAC status) — never raw passport data.

Nullifier-Based Sybil Resistance

Each human produces a deterministic nullifier scoped to the registry. The same human scanning the same passport against the same registry scope always produces the same nullifier. This enables sybil detection: the registry can enforce a maximum number of agents per human (default: 1) and expose sameHuman(agentIdA, agentIdB) for cross-agent checks.

Zero PII On-Chain

No personally identifiable information is stored on-chain. The only stored values are:

• The nullifier (a cryptographic hash, not reversible to identity)
• Disclosed credential claims (optional, chosen by the user at registration time)
• The proof provider address
• The registration block number (for freshness checks)

The user controls exactly which credential claims to disclose during registration by selecting a verification config. Config 0 discloses basic data only; configs 1-2 add age thresholds (18+/21+); configs 3-5 add OFAC screening. Even with full disclosure, only the verified claims are stored — never the raw passport data or biometric information.

Soulbound NFTs

Agent identity NFTs are non-transferable. The ERC-721 _update function reverts on any transfer attempt (from != 0 AND to != 0). Only minting (from = 0) and burning (to = 0) are permitted. This ensures agent identities cannot be sold, traded, or transferred to another party. The identity is permanently bound to the human who created it, and can only be destroyed through deregistration or guardian revocation.

Guardian System

For wallet-free and smart-wallet registration modes, agents can have a designated guardian address. The guardian serves as a safety mechanism — if an agent's private key is compromised, the guardian can force-revoke the agent's identity by calling guardianRevoke(). This is particularly important for autonomous agents that may operate unsupervised for extended periods.

Proof Expiry

Human proofs have a limited validity period. Each registration sets proofExpiresAt = min(passport_document_expiry, block.timestamp + maxProofAge), where maxProofAge defaults to 365 days.

Key functions:

• isProofFresh(agentId) — returns true only while block.timestamp < proofExpiresAt. Use this for time-sensitive access control.
• hasHumanProof(agentId) — returns true as long as a proof was ever submitted. Does NOT check expiry.
• proofExpiresAt(agentId) — raw expiry timestamp (unix seconds).

To refresh an expiring or expired proof, use requestProofRefresh() — the human scans their passport again and proofExpiresAt is updated in-place without changing the agentId. The contract emits HumanProofRefreshed. Alternatively, deregister (burn NFT) and re-register (new agentId with fresh expiry) if changing verification config. SDKs include a 30-day warning threshold for proactive monitoring.

Quick Reference

Registration Modes

Verification Configs

6 configs registered with Hub V2 at deployment (age threshold x OFAC screening):

Registration Modes (Ed25519)

In addition to the 4 ECDSA modes above, 2 Ed25519 modes are available:

Ed25519 agents produce identical HTTP auth headers and are verified transparently by SelfAgentVerifier.

Authentication Headers

Services verify agent HTTP requests using three headers:

SDKs

All SDKs expose identical APIs for registration, signing, verification, credentials, and agent cards. Two agent classes are available:

• SelfAgent — ECDSA (secp256k1) signing. Uses Ethereum keypairs. Lower on-chain gas (~3K). Best for EVM-native projects.
• Ed25519Agent — Ed25519 signing. Uses 32-byte random keys. Best for Python, Rust, Solana, and non-EVM ecosystems. Produces identical HTTP auth headers — SelfAgentVerifier handles both transparently.

The SelfAgentVerifier class is used by the receiving service to verify incoming requests against on-chain state. It accepts both ECDSA and Ed25519 signatures automatically.

MCP Server

Package: @selfxyz/mcp-server — 10 tools across 4 categories:

• Identity (4): register agent, check status, get info, deregister
• Auth (2): sign request, create auth headers
• Discovery (2): list agents for address, search verified agents
• Verification (2): verify agent on-chain, validate freshness

Plus 2 resources (self://networks, self://identity) and 1 prompt (self_integrate_verification).

Networks

Key Concepts

Agent Key

Every agent identity is keyed by a bytes32 value derived from an Ethereum address: bytes32(uint256(uint160(agentAddress))). In simple mode, the agent address is the human's wallet. In advanced, wallet-free, and smart-wallet modes, the agent has its own keypair. The agent key serves as the primary lookup key in all registry mappings.

Verification Config Selection

At registration time, the user (or SDK) selects one of 6 verification configs by placing a digit ('0' through '5') at position [1] in the userDefinedData field. This digit is sent as a UTF-8 character (the Self SDK encodes all user data as UTF-8 strings, not raw bytes). The config determines which credential checks are performed during the ZK verification.

Credential Storage

ZK-attested credentials are stored on-chain at registration time. These include: nationality (ISO 3166-1 alpha-3), age threshold verified (0/18/21), OFAC screening results (3 booleans for SDN/nonSDN/consolidated lists), issuing state, and optionally name, ID number, date of birth, gender, and expiry date. All credential fields are populated from the ZK proof disclosure output — they are cryptographically verified, not self-reported.

Skill Routing

To perform specific workflows, use the appropriate skill:

Reference Documentation

For detailed technical documentation, see:

• System architecture, data flows, SDK internals, API endpoints — references/architecture.md
• Contract addresses, function signatures, interfaces, Solidity integration patterns — references/contracts.md