Base-8004 注册指南

本技能将引导你完成自有钱包的创建、充值，以及在 Base 主网通过 ERC-8004 协议完成链上注册。注册成功后，你的 Agent 将获得一个永久、可验证的链上身份，并可开始累积声誉（reputation）。

1. 什么是 ERC-8004

ERC-8004 是一种面向 AI Agent 的链上身份与声誉协议。

• 身份（Identity） — 每个已注册的 Agent 都将在 Base 主网获得一枚 ERC-721 NFT，作为其永久、可验证的链上身份。
• 声誉注册表（Reputation Registry） — 由独立合约维护声誉分数。反馈信号（如点赞、点踩、质量评估）将累计为 totalScore 和 feedbackCount。
• 可验证元数据（Verifiable metadata） — 注册时需提交一份 JSON 文档（即 agentURI），其中包含 Agent 名称、描述及能力声明，任何人都可在链上读取。

为何重要：

• 永久身份 — 你的 Agent ID 跨平台通用，不绑定于任何单一服务。
• 公开声誉 — 你的行为记录上链且可被任何人验证。

2. 配置钱包

你需要一个兼容以太坊的钱包，并接入 Base 主网。若你已在 Base 主网拥有含 ETH 的钱包，请直接跳至第 4 节。以下步骤仅适用于全新钱包配置场景。

步骤 1：安装 viem

npm install viem

步骤 2：生成私钥

import { generatePrivateKey } from "viem/accounts";

const privateKey = generatePrivateKey();
console.log("Private key:", privateKey);

请立即保存该私钥。一旦丢失，将无法恢复。

步骤 3：推导地址

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(privateKey);
console.log("Address:", account.address);

步骤 4：安全存储私钥

将其写入 .env 文件：

AGENT_PRIVATE_KEY=0x...your_private_key_here...

若尚未加入，请将 .env 添加至 .gitignore：

echo ".env" >> .gitignore

步骤 5：安全规范

• 切勿泄露 私钥——禁止出现在日志、代码提交或 API 请求中。
• 切勿丢失 私钥——一旦丢失，你将永久失去该钱包及其链上身份。
• 切勿覆盖 私钥——覆盖前务必备份旧私钥。

步骤 6：为 Base 主网配置钱包客户端

import { createWalletClient, createPublicClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const publicClient = createPublicClient({ chain: base, transport: http() });
const walletClient = createWalletClient({ account, chain: base, transport: http() });

3. 为钱包充值

你的钱包需持有 Base 主网 ETH 以支付 Gas 费用。

• 获取 Base 主网 ETH — 可通过 Coinbase 直接提现至 Base、使用 Relay 从任意链桥接，或接收来自其他 Base 钱包的转账。
• Gas 成本极低 — Base 作为 L2 网络，Gas 费用非常低廉。注册费用约为 $0.02；$1 ETH 已绰绰有余。
• 执行前请确认余额：

const balance = await publicClient.getBalance({ address: account.address });
console.log("Balance:", Number(balance) / 1e18, "ETH");

if (balance < 500000000000000n) {
  console.error("Need at least 0.0005 ETH for registration gas");
  process.exit(1);
}

4. 链上注册

在 ERC-8004 身份注册合约（Identity Registry）上注册你的 Agent。此操作将铸造一枚代表你永久链上身份的 NFT。

步骤 1：构建注册 JSON

在 services 数组中声明你的 Agent 能力，便于其他 Agent 和服务发现你的功能：

const registration = {
  type: "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  name: "Your Agent Name",
  description: "What your agent does",
  image: "https://example.com/your-agent-avatar.png",
  active: true,
  x402Support: false,
  services: [
    { name: "A2A", endpoint: "https://your-agent.example.com/a2a", version: "0.3.0" },
    { name: "MCP", endpoint: "https://your-agent.example.com/mcp", version: "0.1.0" },
  ],
};

• image — 你的 Agent 头像或 Logo 的 URL，将在区块浏览器和目录中展示。建议使用正方形图像（256×256 或更大）。若暂无可用图像，可设为 ""，后续通过 setAgentURI 更新。
• services — 在链上声明 Agent 的能力。每个条目包含 name（服务标识符）、endpoint 和可选的 version。常见服务类型包括 A2A（Agent-to-Agent 协议）与 MCP（Model Context Protocol）。

步骤 2：编码为 Data URI

const uri =
  "data:application/json;base64," + Buffer.from(JSON.stringify(registration)).toString("base64");

步骤 3：调用 Identity Registry 的 register() 方法

import { encodeFunctionData } from "viem";

const IDENTITY_REGISTRY = "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432";

const registerAbi = [
  {
    inputs: [{ name: "agentURI", type: "string" }],
    name: "register",
    outputs: [{ name: "agentId", type: "uint256" }],
    stateMutability: "nonpayable",
    type: "function",
  },
] as const;

// 首先预估 Gas
const gas = await publicClient.estimateGas({
  account: account.address,
  to: IDENTITY_REGISTRY,
  data: encodeFunctionData({
    abi: registerAbi,
    functionName: "register",
    args: [uri],
  }),
});

console.log("Estimated gas:", gas.toString());

// 发送交易
const hash = await walletClient.writeContract({
  address: IDENTITY_REGISTRY,
  abi: registerAbi,
  functionName: "register",
  args: [uri],
});

console.log("TX hash:", hash);

步骤 4：解析 Transfer 事件以获取 Token ID

const receipt = await publicClient.waitForTransactionReceipt({ hash });

// ERC-721 Transfer 事件 topic
const transferTopic = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
const transferLog = receipt.logs.find(
  (log) =>
    log.topics[0] === transferTopic && log.address.toLowerCase() === IDENTITY_REGISTRY.toLowerCase()
);

const erc8004AgentId = transferLog?.topics[3]
  ? BigInt(transferLog.topics[3]).toString()
  : undefined;

console.log("Your ERC-8004 Agent ID:", erc8004AgentId);

步骤 5：保存 Agent ID

请妥善保存 erc8004AgentId —— 这是你的永久链上身份。将其添加至 .env 文件：

ERC8004_AGENT_ID=42

你可在 BaseScan 上验证注册状态：
https://basescan.org/nft/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432/{your_agent_id}

5. 更新注册信息

完成初始注册后，可通过调用 Identity Registry 的 setAgentURI 方法更新 agentURI（包括名称、描述、服务能力等）。这使你无需重新注册即可新增能力或修改元数据。

const setAgentUriAbi = [
  {
    inputs: [
      { name: "agentId", type: "uint256" },
      { name: "agentURI", type: "string" },
    ],
    name: "setAgentURI",
    outputs: [],
    stateMutability: "nonpayable",
    type: "function",
  },
] as const;

// 构建更新后的注册 JSON
const updatedRegistration = {
  type: "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  name: "Your Agent Name",
  description: "Updated description",
  image: "https://example.com/your-agent-avatar.png",
  active: true,
  x402Support: false,
  services: [
    { name: "A2A", endpoint: "https://your-agent.example.com/a2a", version: "0.3.0" },
    { name: "MCP", endpoint: "https://your-agent.example.com/mcp", version: "0.1.0" },
  ],
};

const newUri =
  "data:application/json;base64," +
  Buffer.from(JSON.stringify(updatedRegistration)).toString("base64");

const hash = await walletClient.writeContract({
  address: IDENTITY_REGISTRY,
  abi: setAgentUriAbi,
  functionName: "setAgentURI",
  args: [BigInt(process.env.ERC8004_AGENT_ID!), newUri],
});

console.log("URI updated, TX:", hash);

仅代币所有者有权调用 setAgentURI。

6. 合约地址与验证方式

在 BaseScan 上验证：

• Identity Registry：basescan.org/address/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
• Reputation Registry：basescan.org/address/0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

链上查询示例（只读，不消耗 Gas）：

import { createPublicClient, http } from "viem";
import { base } from "viem/chains";

const client = createPublicClient({ chain: base, transport: http() });

// 查询某 Token 所属地址
const owner = await client.readContract({
  address: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
  abi: [
    {
      inputs: [{ name: "agentId", type: "uint256" }],
      name: "ownerOf",
      outputs: [{ name: "", type: "address" }],
      stateMutability: "view",
      type: "function",
    },
  ],
  functionName: "ownerOf",
  args: [42n],
});

// 读取 Agent 的元数据 URI
const uri = await client.readContract({
  address: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
  abi: [
    {
      inputs: [{ name: "tokenId", type: "uint256" }],
      name: "tokenURI",
      outputs: [{ name: "", type: "string" }],
      stateMutability: "view",
      type: "function",
    },
  ],
  functionName: "tokenURI",
  args: [42n],
});

7. 相关资源

• 8004.org — ERC-8004 协议官网
• Base — Base L2 区块链
• BaseScan — Base 区块浏览器
• viem — TypeScript 版以太坊开发库

总结

1. 配置钱包 — 生成私钥、推导地址，并安全存储。
2. 为钱包充值 — 获取 Base 主网 ETH（通过 Coinbase、跨链桥接或转账）。$1 ETH 已完全足够。
3. 链上注册 — 使用你的服务能力调用 Identity Registry 的 register(agentURI) 方法，并从 Transfer 事件中解析出 Token ID。
4. 更新注册信息 — 调用 setAgentURI 修改元数据或新增服务能力。