@a3stack/identity 0.1.0

package/bin/agent-id.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * agent-id CLI — verify and inspect ERC-8004 agent identities
+ * 
+ * Usage:
+ *   npx @a3stack/identity verify <globalId>
+ *   npx @a3stack/identity lookup <walletAddress>
+ *   npx @a3stack/identity chains
+ */
+
+import { verifyAgent, getMcpEndpoint, getAgentCount, parseAgentId, SUPPORTED_CHAINS } from "../src/index.js";
+import { findAllRegistrations } from "../src/multichain.js";
+
+const [cmd, ...args] = process.argv.slice(2);
+
+const HELP = `
+🆔 agent-id — ERC-8004 Agent Identity CLI
+
+Commands:
+  verify <globalId>       Verify an agent's on-chain identity
+  lookup <wallet>         Find all registrations for a wallet address
+  chains                  List supported chains
+
+Examples:
+  npx @a3stack/identity verify "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432#2376"
+  npx @a3stack/identity lookup 0xYOUR_WALLET_ADDRESS
+  npx @a3stack/identity chains
+`;
+
+async function main() {
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    console.log(HELP);
+    return;
+  }
+
+  if (cmd === "verify") {
+    const globalId = args[0];
+    if (!globalId) {
+      console.error("Usage: agent-id verify <globalId>");
+      process.exit(1);
+    }
+
+    console.log(`\n🔍 Verifying: ${globalId}\n`);
+
+    const ref = parseAgentId(globalId);
+    console.log(`   Chain:    ${ref.chainId}`);
+    console.log(`   Registry: ${ref.registry}`);
+    console.log(`   Agent ID: ${ref.agentId}`);
+
+    const result = await verifyAgent(globalId);
+
+    if (!result.valid) {
+      console.log(`\n   ❌ FAILED: ${result.error}\n`);
+      process.exit(1);
+    }
+
+    console.log(`\n   ✅ Verified!`);
+    console.log(`   Owner:          ${result.owner}`);
+    console.log(`   Payment wallet: ${result.paymentWallet ?? "(defaults to owner)"}`);
+
+    if (result.registration) {
+      console.log(`   Name:           ${result.registration.name}`);
+      console.log(`   Active:         ${result.registration.active}`);
+      console.log(`   x402 Payments:  ${result.registration.x402Support}`);
+
+      if (result.registration.services?.length) {
+        console.log(`\n   Services:`);
+        for (const s of result.registration.services) {
+          console.log(`   - ${s.name}: ${s.endpoint}`);
+        }
+      }
+    }
+    console.log();
+
+  } else if (cmd === "lookup") {
+    const wallet = args[0] as `0x${string}`;
+    if (!wallet?.startsWith("0x")) {
+      console.error("Usage: agent-id lookup <0xWalletAddress>");
+      process.exit(1);
+    }
+
+    console.log(`\n🌐 Scanning all chains for ${wallet}...\n`);
+    const regs = await findAllRegistrations(wallet, { timeoutMs: 15000 });
+
+    if (regs.length === 0) {
+      console.log("   No registrations found.\n");
+      return;
+    }
+
+    console.log(`   Found ${regs.length} registration(s):\n`);
+    for (const r of regs) {
+      console.log(`   ✅ ${r.chainName.padEnd(12)} #${String(r.agentId).padEnd(6)}  ${r.globalId}`);
+    }
+    console.log();
+
+  } else if (cmd === "chains") {
+    console.log("\n🌐 Supported ERC-8004 chains:\n");
+    for (const [id, chain] of Object.entries(SUPPORTED_CHAINS)) {
+      console.log(`   ${chain.name.padEnd(15)} chain ${id}`);
+    }
+    console.log(`\n   Total: ${Object.keys(SUPPORTED_CHAINS).length} chains\n`);
+
+  } else {
+    console.error(`Unknown command: ${cmd}`);
+    console.log(HELP);
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@a3stack/identity",
+  "version": "0.1.0",
+  "description": "ERC-8004 agent identity registration, verification, and discovery",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "bin": {
+    "agent-id": "./bin/agent-id.ts"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --outDir dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "viem": "^2.39.3",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,159 @@
+/**
+ * ERC-8004 contract addresses and ABIs
+ */
+
+/**
+ * ERC-8004 Identity Registry — deployed at same address on all supported chains
+ * The address 0x8004... is a vanity address (mirrors the EIP number)
+ * Verified on-chain: has bytecode on Base (8453) and Ethereum (1)
+ */
+export const IDENTITY_REGISTRY_ADDRESS =
+  "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" as const;
+
+/**
+ * Chains where ERC-8004 is confirmed deployed (as of Feb 2026)
+ */
+export const SUPPORTED_CHAINS: Record<
+  number,
+  { name: string; rpc: string; chainId: number }
+> = {
+  1: { name: "Ethereum", rpc: "https://eth.llamarpc.com", chainId: 1 },
+  8453: { name: "Base", rpc: "https://mainnet.base.org", chainId: 8453 },
+  10: { name: "Optimism", rpc: "https://mainnet.optimism.io", chainId: 10 },
+  42161: { name: "Arbitrum", rpc: "https://arb1.arbitrum.io/rpc", chainId: 42161 },
+  137: { name: "Polygon", rpc: "https://polygon-rpc.com", chainId: 137 },
+  56: { name: "BNB Chain", rpc: "https://bsc-dataseed.binance.org", chainId: 56 },
+  100: { name: "Gnosis", rpc: "https://rpc.gnosischain.com", chainId: 100 },
+  42220: { name: "Celo", rpc: "https://forno.celo.org", chainId: 42220 },
+  59144: { name: "Linea", rpc: "https://rpc.linea.build", chainId: 59144 },
+  534352: { name: "Scroll", rpc: "https://rpc.scroll.io", chainId: 534352 },
+  167000: { name: "Taiko", rpc: "https://rpc.mainnet.taiko.xyz", chainId: 167000 },
+  43114: { name: "Avalanche", rpc: "https://api.avax.network/ext/bc/C/rpc", chainId: 43114 },
+  5000: { name: "Mantle", rpc: "https://rpc.mantle.xyz", chainId: 5000 },
+  1088: { name: "Metis", rpc: "https://andromeda.metis.io/?owner=1088", chainId: 1088 },
+  2741: { name: "Abstract", rpc: "https://api.mainnet.abs.xyz", chainId: 2741 },
+  143: { name: "Monad", rpc: "https://rpc.monad.xyz", chainId: 143 },
+};
+
+/**
+ * ERC-8004 Identity Registry ABI
+ */
+export const IDENTITY_REGISTRY_ABI = [
+  // Core registration
+  {
+    name: "register",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "agentURI", type: "string" }],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+  {
+    name: "register",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "agentURI", type: "string" },
+      { name: "metadataKeys", type: "string[]" },
+      { name: "metadataValues", type: "bytes[]" },
+    ],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+  {
+    name: "setAgentURI",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "agentId", type: "uint256" },
+      { name: "newURI", type: "string" },
+    ],
+    outputs: [],
+  },
+  // ERC-721 standard
+  {
+    name: "balanceOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "owner", type: "address" }],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+  {
+    name: "ownerOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "address" }],
+  },
+  {
+    name: "tokenURI",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "string" }],
+  },
+  // Transfer event (for extracting agentId from receipt)
+  {
+    name: "Transfer",
+    type: "event",
+    inputs: [
+      { name: "from", type: "address", indexed: true },
+      { name: "to", type: "address", indexed: true },
+      { name: "tokenId", type: "uint256", indexed: true },
+    ],
+  },
+  // Payment wallet
+  {
+    name: "setAgentWallet",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "agentId", type: "uint256" },
+      { name: "newWallet", type: "address" },
+      { name: "deadline", type: "uint256" },
+      { name: "signature", type: "bytes" },
+    ],
+    outputs: [],
+  },
+  {
+    name: "getAgentWallet",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "agentId", type: "uint256" }],
+    outputs: [{ name: "", type: "address" }],
+  },
+  {
+    name: "unsetAgentWallet",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "agentId", type: "uint256" }],
+    outputs: [],
+  },
+  // On-chain metadata
+  {
+    name: "getMetadata",
+    type: "function",
+    stateMutability: "view",
+    inputs: [
+      { name: "agentId", type: "uint256" },
+      { name: "metadataKey", type: "string" },
+    ],
+    outputs: [{ name: "", type: "bytes" }],
+  },
+  {
+    name: "setMetadata",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "agentId", type: "uint256" },
+      { name: "metadataKey", type: "string" },
+      { name: "metadataValue", type: "bytes" },
+    ],
+    outputs: [],
+  },
+] as const;
+
+export const REGISTRATION_TYPE =
+  "https://eips.ethereum.org/EIPS/eip-8004#registration-v1";
+
+/** Zero address — returned when no payment wallet is set */
+export const ZERO_ADDRESS =
+  "0x0000000000000000000000000000000000000000" as const;

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @a3stack/identity
+ * ERC-8004 agent identity: registration, verification, and discovery
+ */
+
+export { AgentIdentity } from "./registry.js";
+export {
+  parseAgentId,
+  formatAgentId,
+  fetchRegistrationFile,
+  verifyAgent,
+  getMcpEndpoint,
+  getA2aEndpoint,
+  getAgentCount,
+} from "./verify.js";
+export {
+  IDENTITY_REGISTRY_ADDRESS,
+  IDENTITY_REGISTRY_ABI,
+  SUPPORTED_CHAINS,
+  REGISTRATION_TYPE,
+} from "./constants.js";
+export { findAllRegistrations } from "./multichain.js";
+export type { ChainRegistration } from "./multichain.js";
+export type {
+  AgentService,
+  AgentRegistrationFile,
+  AgentRegistrationRef,
+  AgentRef,
+  VerificationResult,
+  RegisterOptions,
+  RegisterResult,
+  IdentityConfig,
+  DiscoverOptions,
+} from "./types.js";

package/src/multichain.ts

@@ -0,0 +1,146 @@
+/**
+ * Multi-chain agent discovery — find all registrations across supported chains
+ */
+
+import { createPublicClient, http } from "viem";
+import {
+  IDENTITY_REGISTRY_ADDRESS,
+  IDENTITY_REGISTRY_ABI,
+  SUPPORTED_CHAINS,
+} from "./constants.js";
+import { fetchRegistrationFile } from "./verify.js";
+import type { AgentRegistrationFile } from "./types.js";
+
+export interface ChainRegistration {
+  chainId: number;
+  chainName: string;
+  agentId: number;
+  owner: `0x${string}`;
+  agentUri: string;
+  registration: AgentRegistrationFile | null;
+  globalId: string;
+}
+
+/**
+ * Find all ERC-8004 registrations for a wallet address across all supported chains.
+ * Scans Transfer events (mint from 0x0) on each chain in parallel.
+ * 
+ * @example
+ * ```ts
+ * const regs = await findAllRegistrations("0x1be93C...");
+ * console.log(`Found ${regs.length} registrations across ${regs.map(r => r.chainName).join(", ")}`);
+ * ```
+ */
+export async function findAllRegistrations(
+  walletAddress: `0x${string}`,
+  options?: {
+    /** Only scan these chain IDs (default: all supported) */
+    chainIds?: number[];
+    /** Fetch and parse registration files (slower, default: false) */
+    fetchRegistration?: boolean;
+    /** Registry address override */
+    registry?: `0x${string}`;
+    /** Timeout per chain in ms (default: 10000) */
+    timeoutMs?: number;
+  }
+): Promise<ChainRegistration[]> {
+  const registry = options?.registry ?? IDENTITY_REGISTRY_ADDRESS;
+  const chainIds = options?.chainIds ?? Object.keys(SUPPORTED_CHAINS).map(Number);
+  const fetchReg = options?.fetchRegistration ?? false;
+  const timeout = options?.timeoutMs ?? 10000;
+
+  const results: ChainRegistration[] = [];
+
+  // Scan all chains in parallel
+  const promises = chainIds.map(async (chainId) => {
+    const chain = SUPPORTED_CHAINS[chainId];
+    if (!chain) return;
+
+    try {
+      const client = createPublicClient({ transport: http(chain.rpc) });
+
+      // Check balance first (fast)
+      const balance = (await Promise.race([
+        client.readContract({
+          address: registry,
+          abi: IDENTITY_REGISTRY_ABI,
+          functionName: "balanceOf",
+          args: [walletAddress],
+        }),
+        new Promise<bigint>((_, reject) =>
+          setTimeout(() => reject(new Error("timeout")), timeout)
+        ),
+      ])) as bigint;
+
+      if (balance === 0n) return;
+
+      // Find the agent IDs via Transfer events (mint from 0x0)
+      const paddedAddress = walletAddress.toLowerCase().replace("0x", "0x000000000000000000000000");
+      const logs = await client.getLogs({
+        address: registry,
+        event: {
+          type: "event",
+          name: "Transfer",
+          inputs: [
+            { type: "address", indexed: true, name: "from" },
+            { type: "address", indexed: true, name: "to" },
+            { type: "uint256", indexed: true, name: "tokenId" },
+          ],
+        },
+        args: {
+          from: "0x0000000000000000000000000000000000000000" as `0x${string}`,
+          to: walletAddress,
+        },
+        fromBlock: 0n,
+        toBlock: "latest",
+      });
+
+      for (const log of logs) {
+        const agentId = Number(log.args.tokenId);
+
+        // Get the current owner (could have been transferred)
+        const currentOwner = (await client.readContract({
+          address: registry,
+          abi: IDENTITY_REGISTRY_ABI,
+          functionName: "ownerOf",
+          args: [BigInt(agentId)],
+        })) as `0x${string}`;
+
+        // Only include if still owned by the queried wallet
+        if (currentOwner.toLowerCase() !== walletAddress.toLowerCase()) continue;
+
+        // Get agent URI
+        const agentUri = (await client.readContract({
+          address: registry,
+          abi: IDENTITY_REGISTRY_ABI,
+          functionName: "tokenURI",
+          args: [BigInt(agentId)],
+        })) as string;
+
+        let registration: AgentRegistrationFile | null = null;
+        if (fetchReg) {
+          try {
+            registration = await fetchRegistrationFile(agentUri);
+          } catch { /* ignore fetch errors */ }
+        }
+
+        results.push({
+          chainId,
+          chainName: chain.name,
+          agentId,
+          owner: currentOwner,
+          agentUri,
+          registration,
+          globalId: `eip155:${chainId}:${registry}#${agentId}`,
+        });
+      }
+    } catch {
+      // Chain unreachable or other error — skip silently
+    }
+  });
+
+  await Promise.allSettled(promises);
+
+  // Sort by chainId for consistent ordering
+  return results.sort((a, b) => a.chainId - b.chainId);
+}

package/src/registry.ts

@@ -0,0 +1,273 @@
+/**
+ * AgentIdentity — register and manage ERC-8004 agent identity
+ */
+
+import { createPublicClient, createWalletClient, http, parseEventLogs } from "viem";
+import type { Account, Chain, WalletClient } from "viem";
+import {
+  IDENTITY_REGISTRY_ADDRESS,
+  IDENTITY_REGISTRY_ABI,
+  REGISTRATION_TYPE,
+  ZERO_ADDRESS,
+  SUPPORTED_CHAINS,
+} from "./constants.js";
+import type {
+  IdentityConfig,
+  RegisterOptions,
+  RegisterResult,
+  AgentRegistrationFile,
+} from "./types.js";
+
+export class AgentIdentity {
+  private config: IdentityConfig;
+  private registry: `0x${string}`;
+  private rpcUrl: string;
+
+  constructor(config: IdentityConfig) {
+    this.config = config;
+    this.registry = config.registry ?? IDENTITY_REGISTRY_ADDRESS;
+
+    // Resolve RPC URL
+    const chainDefaults = SUPPORTED_CHAINS[config.chain.id];
+    this.rpcUrl =
+      config.rpc ??
+      config.chain.rpcUrls?.default?.http?.[0] ??
+      chainDefaults?.rpc ??
+      "";
+
+    if (!this.rpcUrl) {
+      throw new Error(
+        `No RPC URL provided for chain ${config.chain.id}. Pass rpc option or use a supported chain.`
+      );
+    }
+  }
+
+  private getPublicClient() {
+    return createPublicClient({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      chain: this.config.chain as any,
+      transport: http(this.rpcUrl),
+    });
+  }
+
+  private getWalletClient() {
+    // The account must be a full viem Account for write operations
+    if (!this.config.account?.signTransaction && !this.config.account?.sign) {
+      throw new Error(
+        "Write operations require a full viem Account with signing capability. " +
+          "Use privateKeyToAccount() from viem/accounts."
+      );
+    }
+    return createWalletClient({
+      account: this.config.account as Account,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      chain: this.config.chain as any,
+      transport: http(this.rpcUrl),
+    });
+  }
+
+  /**
+   * Build the registration JSON and encode as data URI
+   */
+  buildRegistrationUri(options: RegisterOptions, agentId?: number): string {
+    const chainId = this.config.chain.id;
+    const registrations = options.existingRegistrations
+      ? [...options.existingRegistrations]
+      : [];
+
+    // Add current chain registration if we have an agentId
+    if (agentId !== undefined) {
+      registrations.unshift({
+        agentId,
+        agentRegistry: `eip155:${chainId}:${this.registry}`,
+      });
+    }
+
+    const file: AgentRegistrationFile = {
+      type: REGISTRATION_TYPE,
+      name: options.name,
+      description: options.description,
+      ...(options.image ? { image: options.image } : {}),
+      services: options.services ?? [],
+      x402Support: options.x402Support ?? false,
+      active: options.active ?? true,
+      registrations,
+      ...(options.supportedTrust ? { supportedTrust: options.supportedTrust } : {}),
+    };
+
+    const json = JSON.stringify(file);
+    return "data:application/json;base64," + Buffer.from(json).toString("base64");
+  }
+
+  /**
+   * Check if this wallet is already registered on the current chain
+   */
+  async isRegistered(): Promise<{ registered: boolean; agentId?: number }> {
+    const client = this.getPublicClient();
+    const balance = await client.readContract({
+      address: this.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "balanceOf",
+      args: [this.config.account.address],
+    });
+
+    if (balance === 0n) {
+      return { registered: false };
+    }
+
+    // We'd need to scan Transfer events to find the agentId — return basic result
+    return { registered: true };
+  }
+
+  /**
+   * Register this agent on the current chain
+   */
+  async register(options: RegisterOptions): Promise<RegisterResult> {
+    const walletClient = this.getWalletClient();
+
+    // Build a temporary URI without agentId first (we don't know it yet)
+    // We'll build it with a placeholder, then update after we have the ID
+    const placeholderUri = this.buildRegistrationUri(options);
+
+    // Estimate gas if not provided
+    const publicClient = this.getPublicClient();
+
+    const { request } = await publicClient.simulateContract({
+      account: this.config.account as Account,
+      address: this.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "register",
+      args: [placeholderUri],
+    });
+
+    const txHash = await walletClient.writeContract({
+      ...request,
+      ...(options.gasLimit ? { gas: options.gasLimit } : {}),
+    });
+
+    // Wait for receipt
+    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
+
+    // Extract agentId from Transfer event (ERC-721 mint: from=0x0)
+    const logs = parseEventLogs({
+      abi: IDENTITY_REGISTRY_ABI,
+      eventName: "Transfer",
+      logs: receipt.logs,
+    });
+
+    const mintLog = logs.find(
+      (log) =>
+        "args" in log &&
+        log.args.from === ZERO_ADDRESS
+    );
+
+    if (!mintLog || !("args" in mintLog)) {
+      throw new Error("Could not find Transfer event in registration receipt");
+    }
+
+    const agentId = Number(mintLog.args.tokenId);
+    const chainId = this.config.chain.id;
+
+    // Now update the URI with the actual agentId
+    const finalUri = this.buildRegistrationUri(options, agentId);
+    await this.setAgentURI(agentId, finalUri);
+
+    const globalId = `eip155:${chainId}:${this.registry}#${agentId}`;
+
+    return { agentId, txHash, globalId, agentUri: finalUri };
+  }
+
+  /**
+   * Update the agent's URI (registration file location)
+   */
+  async setAgentURI(agentId: number, newUri: string): Promise<`0x${string}`> {
+    const walletClient = this.getWalletClient();
+    const publicClient = this.getPublicClient();
+
+    const { request } = await publicClient.simulateContract({
+      account: this.config.account as Account,
+      address: this.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "setAgentURI",
+      args: [BigInt(agentId), newUri],
+    });
+
+    return walletClient.writeContract(request);
+  }
+
+  /**
+   * Get the agentURI for a given agentId
+   */
+  async getAgentURI(agentId: number): Promise<string> {
+    const client = this.getPublicClient();
+    return client.readContract({
+      address: this.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "tokenURI",
+      args: [BigInt(agentId)],
+    }) as Promise<string>;
+  }
+
+  /**
+   * Get the payment wallet for a given agentId
+   */
+  async getPaymentWallet(agentId: number): Promise<`0x${string}` | null> {
+    const client = this.getPublicClient();
+    const wallet = (await client.readContract({
+      address: this.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "getAgentWallet",
+      args: [BigInt(agentId)],
+    })) as `0x${string}`;
+
+    return wallet === ZERO_ADDRESS ? null : wallet;
+  }
+
+  /**
+   * Get on-chain metadata for an agent
+   */
+  async getMetadata(agentId: number, key: string): Promise<string | null> {
+    const client = this.getPublicClient();
+    const raw = (await client.readContract({
+      address: this.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "getMetadata",
+      args: [BigInt(agentId), key],
+    })) as `0x${string}`;
+
+    if (!raw || raw === "0x") return null;
+    return Buffer.from(raw.slice(2), "hex").toString("utf8");
+  }
+
+  /**
+   * Set on-chain metadata for an agent (requires ownership)
+   */
+  async setMetadata(agentId: number, key: string, value: string): Promise<`0x${string}`> {
+    const walletClient = this.getWalletClient();
+    const publicClient = this.getPublicClient();
+
+    const valueBytes = `0x${Buffer.from(value, "utf8").toString("hex")}` as `0x${string}`;
+    const { request } = await publicClient.simulateContract({
+      account: this.config.account as Account,
+      address: this.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "setMetadata",
+      args: [BigInt(agentId), key, valueBytes],
+    });
+
+    return walletClient.writeContract(request);
+  }
+
+  /**
+   * Get the owner of an agent
+   */
+  async getOwner(agentId: number): Promise<`0x${string}`> {
+    const client = this.getPublicClient();
+    return client.readContract({
+      address: this.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "ownerOf",
+      args: [BigInt(agentId)],
+    }) as Promise<`0x${string}`>;
+  }
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+/**
+ * ERC-8004 Agent Identity Types
+ */
+
+export interface AgentService {
+  name: string;
+  endpoint: string;
+  version?: string;
+  skills?: string[];
+  domains?: string[];
+}
+
+export interface AgentRegistrationFile {
+  type: string;
+  name: string;
+  description: string;
+  image?: string;
+  services: AgentService[];
+  x402Support: boolean;
+  active: boolean;
+  registrations: AgentRegistrationRef[];
+  supportedTrust?: string[];
+}
+
+export interface AgentRegistrationRef {
+  agentId: number;
+  agentRegistry: string; // "eip155:{chainId}:{registryAddress}"
+}
+
+export interface AgentRef {
+  namespace: string;        // "eip155"
+  chainId: number;          // 8453
+  registry: `0x${string}`; // "0x8004..."
+  agentId: number;          // 2376
+}
+
+export interface VerificationResult {
+  valid: boolean;
+  agentId: number;
+  owner: `0x${string}` | null;
+  paymentWallet: `0x${string}` | null;
+  registration: AgentRegistrationFile | null;
+  globalId: string;
+  error?: string;
+}
+
+export interface RegisterOptions {
+  name: string;
+  description: string;
+  image?: string;
+  services?: AgentService[];
+  x402Support?: boolean;
+  active?: boolean;
+  supportedTrust?: string[];
+  /** Extra cross-chain registrations to include in the file */
+  existingRegistrations?: AgentRegistrationRef[];
+  /** Store as data URI (on-chain) vs IPFS URL. Default: data URI */
+  storage?: "data-uri" | "ipfs";
+  /** Optional gas limit override */
+  gasLimit?: bigint;
+}
+
+export interface RegisterResult {
+  agentId: number;
+  txHash: `0x${string}`;
+  globalId: string;
+  agentUri: string;
+}
+
+export interface IdentityConfig {
+  /**
+   * viem Account (e.g. from privateKeyToAccount())
+   * For read-only operations, a partial account with just address works.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  account: any;
+  /**
+   * viem Chain object (e.g. import { base } from "viem/chains")
+   * Any object with at least { id, name } works.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  chain: any;
+  /** RPC URL override */
+  rpc?: string;
+  /** Registry contract address override */
+  registry?: `0x${string}`;
+}
+
+export interface DiscoverOptions {
+  chain?: {
+    id: number;
+    rpcUrls?: { default?: { http?: string[] } };
+  };
+  /** Filter agents that have this service type (e.g. "MCP") */
+  hasService?: string;
+  /** Filter by x402Support flag */
+  x402Support?: boolean;
+  /** Filter by active flag */
+  active?: boolean;
+  /** Max number of results */
+  limit?: number;
+}

package/src/verify.ts

@@ -0,0 +1,268 @@
+/**
+ * Agent identity verification and resolution
+ */
+
+import { createPublicClient, http } from "viem";
+import {
+  IDENTITY_REGISTRY_ADDRESS,
+  IDENTITY_REGISTRY_ABI,
+  ZERO_ADDRESS,
+  SUPPORTED_CHAINS,
+} from "./constants.js";
+import type { AgentRef, VerificationResult, AgentRegistrationFile } from "./types.js";
+
+/**
+ * Parse an ERC-8004 global agent ID string
+ * Format: "eip155:{chainId}:{registry}#{agentId}"
+ * Example: "eip155:8453:0x8004...#2376"
+ */
+export function parseAgentId(globalId: string): AgentRef {
+  // Support both "eip155:8453:0x8004...#2376" and "eip155:8453:0x8004.../2376"
+  const normalized = globalId.replace("/", "#");
+  const match = normalized.match(/^(eip155):(\d+):(0x[0-9a-fA-F]+)#(\d+)$/);
+  if (!match) {
+    throw new Error(
+      `Invalid agent global ID format: "${globalId}"\n` +
+        `Expected: "eip155:{chainId}:{registry}#{agentId}" (e.g. "eip155:8453:0x8004...#2376")`
+    );
+  }
+  return {
+    namespace: match[1],
+    chainId: Number(match[2]),
+    registry: match[3] as `0x${string}`,
+    agentId: Number(match[4]),
+  };
+}
+
+/**
+ * Format a parsed AgentRef back to a global ID string
+ */
+export function formatAgentId(ref: AgentRef): string {
+  return `${ref.namespace}:${ref.chainId}:${ref.registry}#${ref.agentId}`;
+}
+
+/**
+ * Fetch and parse an agent's registration file from its URI
+ * Handles: data: URIs, https:// URLs, ipfs:// CIDs (via gateway)
+ */
+export async function fetchRegistrationFile(
+  agentUri: string,
+  ipfsGateway = "https://ipfs.io/ipfs/"
+): Promise<AgentRegistrationFile> {
+  let json: string;
+
+  if (agentUri.startsWith("data:application/json;base64,")) {
+    const b64 = agentUri.slice("data:application/json;base64,".length);
+    json = Buffer.from(b64, "base64").toString("utf8");
+  } else if (agentUri.startsWith("data:application/json,")) {
+    json = decodeURIComponent(agentUri.slice("data:application/json,".length));
+  } else if (agentUri.startsWith("ipfs://")) {
+    const cid = agentUri.slice("ipfs://".length);
+    const response = await fetch(`${ipfsGateway}${cid}`);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch IPFS URI: ${agentUri} (${response.status})`);
+    }
+    json = await response.text();
+  } else if (agentUri.startsWith("https://") || agentUri.startsWith("http://")) {
+    const response = await fetch(agentUri, {
+      headers: { Accept: "application/json" },
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to fetch agent URI: ${agentUri} (${response.status})`);
+    }
+    json = await response.text();
+  } else {
+    throw new Error(
+      `Unsupported URI scheme: "${agentUri}". ` +
+        `Supported: data:, ipfs://, https://, http://`
+    );
+  }
+
+  const parsed = JSON.parse(json) as AgentRegistrationFile;
+  return parsed;
+}
+
+/**
+ * Verify an agent's identity from its global ID
+ * Performs full on-chain + off-chain verification
+ */
+export async function verifyAgent(
+  globalIdOrRef:
+    | string
+    | { chainId: number; agentId: number; registry?: `0x${string}`; rpc?: string }
+): Promise<VerificationResult> {
+  let ref: AgentRef;
+
+  if (typeof globalIdOrRef === "string") {
+    ref = parseAgentId(globalIdOrRef);
+  } else {
+    ref = {
+      namespace: "eip155",
+      chainId: globalIdOrRef.chainId,
+      registry: globalIdOrRef.registry ?? IDENTITY_REGISTRY_ADDRESS,
+      agentId: globalIdOrRef.agentId,
+    };
+  }
+
+  const globalId = formatAgentId(ref);
+  const chainDefaults = SUPPORTED_CHAINS[ref.chainId];
+  const rpcUrl =
+    (typeof globalIdOrRef === "object" && "rpc" in globalIdOrRef
+      ? globalIdOrRef.rpc
+      : undefined) ??
+    chainDefaults?.rpc;
+
+  if (!rpcUrl) {
+    return {
+      valid: false,
+      agentId: ref.agentId,
+      owner: null,
+      paymentWallet: null,
+      registration: null,
+      globalId,
+      error: `No RPC URL available for chain ${ref.chainId}. Add to SUPPORTED_CHAINS or pass rpc option.`,
+    };
+  }
+
+  const client = createPublicClient({
+    transport: http(rpcUrl),
+  });
+
+  try {
+    // Step 1: Get owner
+    const owner = (await client.readContract({
+      address: ref.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "ownerOf",
+      args: [BigInt(ref.agentId)],
+    })) as `0x${string}`;
+
+    // Step 2: Get payment wallet
+    const paymentWalletRaw = (await client.readContract({
+      address: ref.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "getAgentWallet",
+      args: [BigInt(ref.agentId)],
+    })) as `0x${string}`;
+
+    const paymentWallet =
+      paymentWalletRaw === ZERO_ADDRESS ? null : paymentWalletRaw;
+
+    // Step 3: Get agent URI and fetch registration file
+    const agentUri = (await client.readContract({
+      address: ref.registry,
+      abi: IDENTITY_REGISTRY_ABI,
+      functionName: "tokenURI",
+      args: [BigInt(ref.agentId)],
+    })) as string;
+
+    let registration: AgentRegistrationFile | null = null;
+    try {
+      registration = await fetchRegistrationFile(agentUri);
+    } catch (e) {
+      return {
+        valid: false,
+        agentId: ref.agentId,
+        owner,
+        paymentWallet,
+        registration: null,
+        globalId,
+        error: `Failed to fetch registration file: ${(e as Error).message}`,
+      };
+    }
+
+    // Step 4: Verify back-reference (registration file should list this chain's registration)
+    const registryPrefix = `eip155:${ref.chainId}:${ref.registry.toLowerCase()}`;
+    const hasBackref = registration.registrations?.some(
+      (r) =>
+        r.agentId === ref.agentId &&
+        r.agentRegistry.toLowerCase() === registryPrefix
+    );
+
+    if (!hasBackref) {
+      return {
+        valid: false,
+        agentId: ref.agentId,
+        owner,
+        paymentWallet,
+        registration,
+        globalId,
+        error:
+          `Registration file does not contain a back-reference to this chain's registry. ` +
+          `Expected registrations entry: { agentId: ${ref.agentId}, agentRegistry: "${registryPrefix}" }`,
+      };
+    }
+
+    return {
+      valid: true,
+      agentId: ref.agentId,
+      owner,
+      paymentWallet,
+      registration,
+      globalId,
+    };
+  } catch (e) {
+    // ownerOf throws if token doesn't exist
+    const message = (e as Error).message;
+    return {
+      valid: false,
+      agentId: ref.agentId,
+      owner: null,
+      paymentWallet: null,
+      registration: null,
+      globalId,
+      error: message.includes("revert") || message.includes("ERC721")
+        ? `Agent #${ref.agentId} does not exist on chain ${ref.chainId}`
+        : message,
+    };
+  }
+}
+
+/**
+ * Get the MCP endpoint for an agent by resolving their registration
+ */
+export async function getMcpEndpoint(globalId: string): Promise<string | null> {
+  const result = await verifyAgent(globalId);
+  if (!result.valid || !result.registration) return null;
+
+  const mcpService = result.registration.services.find(
+    (s) => s.name.toUpperCase() === "MCP"
+  );
+  return mcpService?.endpoint ?? null;
+}
+
+/**
+ * Get the A2A endpoint for an agent
+ */
+export async function getA2aEndpoint(globalId: string): Promise<string | null> {
+  const result = await verifyAgent(globalId);
+  if (!result.valid || !result.registration) return null;
+
+  const a2aService = result.registration.services.find(
+    (s) => s.name.toUpperCase() === "A2A"
+  );
+  return a2aService?.endpoint ?? null;
+}
+
+/**
+ * Lightweight check: does this address own any agents on a given chain?
+ */
+export async function getAgentCount(
+  address: `0x${string}`,
+  chainId: number,
+  rpc?: string
+): Promise<number> {
+  const chainDefaults = SUPPORTED_CHAINS[chainId];
+  const rpcUrl = rpc ?? chainDefaults?.rpc;
+  if (!rpcUrl) throw new Error(`No RPC for chain ${chainId}`);
+
+  const client = createPublicClient({ transport: http(rpcUrl) });
+  const balance = (await client.readContract({
+    address: IDENTITY_REGISTRY_ADDRESS,
+    abi: IDENTITY_REGISTRY_ABI,
+    functionName: "balanceOf",
+    args: [address],
+  })) as bigint;
+
+  return Number(balance);
+}