ERC-8004 Agent Liveness

检查在真实 ERC-8004 "Trustless Agents" 身份注册表（Base Sepolia 测试网）中注册的代理现在是否真的活着——而不只是曾经注册过。NEXUS 候选 #10——手动构建，非 FORGE 生成，与候选 #3/#4/#6/#8/#9/#13/#16 采用相同的手动 Cloud Run 资产模式。

• POST /verify-registered-agent {"agent_id": 3} -- 每次调用需 $0.10。

• MCP 工具 verify_registered_agent 位于 /mcp 路径，参数相同 -- 目前免费，见"Known limitations"。

• GET /health、GET /.well-known/agent-card.json、GET /openapi.json（包含 x-payment-info）、GET /.well-known/402index-verify.txt（402index 声明验证文件）。

What this is

ERC-8004 是一个真实、可用的以太坊链上代理身份标准：代理在 IdentityRegistry 中铸造 ERC-721 token，其 tokenURI 指向链下注册文件（JSON：name、description、声明的 endpoints、active 标志、受支持的信任方法）。它于 2026-01-29 在以太坊主网上线，并在 Base 主网以及 Base/Ethereum/Linea Sepolia 测试网有参考部署。注册是一次性链上操作——一个真正注册过的代理完全可以彻底下线（进程终止、域名过期、端点变更），而其链上记录却永久保留不变。这个资产弥合了这个缺口：它在调用时立即解析真实链上注册，并针对注册声明（whatever the convention requires）的当前端点执行真实的 MCP initialize 握手——也就是候选 #3 的 agent-verification-api 已经对"声称拥有域名"身份作出的"存活 vs 注册"区分，只不过这里是应用于链上注册身份。

Grounding (verified live this session, not assumed from any single source)

• Contract addresses 初始来自第三方汇总，但在经 https://sepolia.base.org 用 eth_getCode 独立验证之前没有信任：IdentityRegistry（0x8004A818BFB912233c491871b3d84c89A494BD9e) 和 ReputationRegistry（0x8004B663056A597Dffe9eCcC1965A193B7388713）均有真实且非空的已部署字节码。

• ABI 取自参考实现（github.com/erc-8004/erc-8004-contracts/abis），在为本资产所信任前，已针对 4 个真实注册代理（agentId 1-3）真实测试：

  • 代理 1 的 tokenURI 解析为 data:application/json;base64,... URI。

  • 代理 2 的解析为 ipfs://bafkrei... URI。

  • 代理 3 的解析为真实 https://api.snack.money/agent/.../registration.json URL。

    ERC-8004 的 3 种真实 URI 方案都已实际验证可工作，并不仅限规范中的示例。

• getSummary 要求非空的 clientAddresses 数组 -- 已实时确认（没有则返回 "clientAddresses required" 而 revert）。该资产先调用 getClients(agentId)，只在其返回至少一个地址时才调用 getSummary；零反馈的代理能正确返回 feedback_count: 0，而无 RPC 错误。

• agentId=999999（确证的 token 不存在） 实时确认会以自定义错误 revert -- 映射为 AGENT_NOT_FOUND，而不是崩溃。

MCP handshake engine: 复用而非重复实现

按照任务说明的明确指示，_nexus_validate_public_url、_nexus_no_redirect_mcp_http_client 和 _mcp_handshake_check 均从 manual_assets/agent-verification-api/main.py（候选 #3）按原样移植——相同的 SSRF 预检、相同的"不重定向"姿势（即 2026-08-22 安全评审发现重定向 SSRF 绕过问题后在此处应用的确切修复）、相同的有界超时。未对该资产名常量之外做任何改动。此资产自身贡献在其上游端：它解析 ERC-8004 注册文件（3 种 URI 方案），并从其 endpoints 数组中挑出一个真实端点交给该引擎。

Chain scope: 刻意限定

仅 Base Sepolia 测试网——与目前代码库中一切 x402 支付都使用的网络相同。ERC-8004 在 base 主网和以太坊主网上也活着，但此资产不提供调用方可选链：没有证据说明 7 天试用候选者需要主网（CEAUDE.md SS3）。

Deploy target: Cloud Run

与候选 #4/#3/#6/#8/#9/#13/#16 相同的流水线 -- 见 skills/deploy-ops。

# 1. First deploy -- PUBLIC_DOMAIN not known yet, every real request 421s until step 2.
./scripts/deploy_cloud_run.sh erc8004-agent-liveness manual_assets/erc8004-agent-liveness

# 2. Grab the printed *.run.app URL, then (only if it differs from env-vars.deploy.yaml's guess):
gcloud run services update erc8004-agent-liveness --region us-central1 --project nexus-505016 \
    --update-env-vars PUBLIC_DOMAIN=<the-real-domain>

Known limitations（刻意不修复 -- CLAUDE.md SS3, 无证据时不加关卡）

• MCP 工具调用不收费。 与库中其他所有手动手动资产一样，采用进程内调用模式。

• active: false 直接短路为 REGISTERED_INACTIVE，即使端点实际在运行。 它等待于一种注册者的自行声明，而非独立活性检查——一个虚假假称自己非活跃的代理（这种激励不常见）会被误报。关于该字段自身设计上属于注册者自己的信号，若在此去覆盖，等于对标准的字段又一次"猜测"；而 REGISTERED_UNREACHABLE（相反的失败模式——声明 active 但实际不可达）才是本资产的真正价值所在，不会被短路。

  • Endpoint 选择是启发式，并不是规范要求。 ERC-8004 的 endpoints 数组是自由格式（任意 name）；本资产按 mcp/x402/a2a/web 顺序优先，并回退到第一条。一个注册仅有的真实 MCP 能力端点若名为非进位 name，也仍会被选中（名称匹配不是唯一途径——未命名偏好回退已包括这种情况）可。但是如果一个注册有多个 endpoints，其中没有任何一个 preferred name 指向实际 active 的 endpoint，可能错误地依据极端端点报 REGISTERED_UNREACHABLE。

• IPFS 解析使用单一公共入口（ipfs.io）。 无回退 gateway——如果一个 CID 没有经由该特定 gateway 固定/不可达，即使内容在 IPFS 上客观存在，也会报 REGISTRATION_FETCH_FAILED。

• 没有按调用方限制速率。 这对 7 天的认知测量窗口是合适的。

• reputation 是自报的、无须 gate、无质押的信号。 任何 EVM 地址都可以对任意 agentId 调用 ReputationRegistry.giveFeedback —— feedback_count/average_value 是真实链上数字，但并未阻止 agent 自身的所有者不自已通过 Sybil 喂养自己。应视为未验证的信号，不应视为信任评分（这一点文案在 API schema 的 reputation 字段描述中也写了，不只是此处）。

Quality gate（2026-08-23, 设计源头，非事后）

与候选 #3/#4/#6/#8/#9/#13/#16 相同的双代理过程（安全工作站 + 功能/质量/买家体验工作站），运行在首次部署之前。真实发现的问题，全都在上线前修复：

• 安全（0 个可利用问题）：确认从 agent-verification-api/main.py 原封不动移植的 3 个函数（_nexus_validate_public_url、_nexus_no_redirect_mcp_http_client、_mcp_handshake_check）逐字节携带了 SSRF 重定向修复，而且新的 https:///IPFS 注册读路径在解析端点之前更早一层就应用相同防御——确认没有重新引入该 bug 类别。两项低/信息级别问题均以“纵深防护”方式处理，即便没有一个是明确的漏洞利用：IPFS CID 拼接（但是确实已经实况确认不能跳出 ipfs.io 主机，且仍用 urllib.parse.quote 将其限制在单个路径段中）与 data: URI base64 解码（确认线性/不可放大，不需要修复）。

• 功能 / 买家体验（1 个必须修复、1 个中，已应用）：当注册文件的顶层 JSON 是非对象（数组/字符串/数字——registrant 可控内容）时，会被当作 "ok": True 且 non-dict 的 registration 传给下游；而所有下游消费者（_pick_liveness_endpoint、_classify_verdict、response body）都认为这是 dict —— 未经处理的 AttributeError 变成了 x402 支付已经钱之后 的 500。修复：_resolve_registration_file 中的两处 JSON 解析位置现在会将非 dict 结果视为 registration_not_an_object 并将 "ok": True 返回前驳回；同时把 reputation 的可玩法性（低值攻击）警示加入（见上方"已知限制"以及 /openapi.json reputation 字段的说明）。两项低/可有可无项（复制的 name 端点重叠、2 个可选注册键未校验大小写）按原样保留——尚无证据表明语义影响真实，符合文档 CLAUDE.md §7。

• 修复前后均用真实生产数据端到端验证；Base Sepolia 上 4 个真实的 ERC-8004 代理 ID（1、2、3 和确为不存在的 999999）各自给出了正确判断——REGISTERED_UNREACHABLE（真实注册，端点不响应 MCP）、REGISTRATION_FETCH_FAILED x2（真实 IPFS 网关超时，以及真实失效 https:// 注册 URL——两者都是正常现象，不是 bug）、以及 AGENT_NOT_FOUND（真实链上 revert）——也获得了真实 reputation 数据（agent 1 上的 74 条反馈来自 12 个独立 client。

Measurement（候选 #10，7 天窗口）

7 天窗口自 2026-08-23（真实部署日期）起，决策点 2026-08-30。数据源以 traffic_events/revenue_events/mcp_call_events（asset_name = 'erc8004-agent-liveness'）为准，而非 Cloud Run 日志。第 7 天如无真实流量（已排除爬虫），则暂停/删除 Cloud Run 服务（gcloud run services delete erc8004-agent-liveness --region us-central1 --project nexus-505016）。