erc8004-agent-liveness

ERC-8004 Agent 存活状态

检查在真实 ERC-8004「Trustless Agents」身份注册表（Base 主网——付款和注册表读取均在该网络上，详见下文「链范围」）中注册的 Agent 当前是否确实在线，而不只是曾经注册过。NEXUS 候选项 #10——手动构建，非 FORGE 生成，采用与候选项 #3/#4/#6/#8/#9/#13/#16 相同的手动 Cloud Run 资产模式。

• POST /verify-registered-agent {"agent_id": 3} —— 每次调用 $0.10。
• /mcp 上的 MCP 工具 verify_registered_agent，参数相同——目前免费，详见「已知限制」。
• GET /health、GET /.well-known/agent-card.json、GET /openapi.json（包含 x-payment-info）、 GET /.well-known/402index-verify.txt（402index 声明验证文件）。

这是什么（以及为什么仅注册还不够）

ERC-8004 是一项真实运行中的以太坊链上 Agent 身份标准：Agent 在 IdentityRegistry 中铸造 ERC-721 代币，其 tokenURI 指向链下注册文件（JSON：名称、描述、声明的端点、active 标志、支持的信任方法）。该标准于 2026-01-29 在以太坊主网上线，并在 Base 主网以及 Base/以太坊/Linea Sepolia 测试网上部署了参考实现。注册是一次性的链上操作——真实注册的 Agent 可能完全离线（进程被终止、域名过期、端点变更），而其链上记录却永远保持不变。此资产弥补了这一缺口：它会解析真实的链上注册信息，并在调用时立即对注册信息中声明的端点执行真实的 MCP initialize 握手——这与 agent-verification-api（候选项 #3）对域名声明身份区分存活状态与注册状态的做法相同，只是应用于链上注册的 Agent。

依据（本次会话中已实时验证，并非仅凭单一来源假设）

• 合约地址最初来自第三方摘要，随后通过 https://sepolia.base.org 上的 eth_getCode 独立验证后才予以采信：IdentityRegistry （0x8004A818BFB912233c491871b3d84c89A494BD9e）和 ReputationRegistry （0x8004B663056A597Dffe9eCcC1965A193B7388713）均有真实且非空的已部署字节码。
• ABI取自参考实现（github.com/erc-8004/erc-8004-contracts/abis），在采信并用于此资产前，已针对 3 个真实注册的 Agent（agentId 1-3）进行实时测试：
  • Agent 1 的 tokenURI 解析为 data:application/json;base64,... URI。
  • Agent 2 的 tokenURI 解析为 ipfs://bafkreiff...。
  • Agent 3 的 tokenURI 解析为真实的 https://api.snack.money/agent/.../registration.json URL。 已实时确认 ERC-8004 的 3 种真实 URI 方案均可正常工作，而不只是标准自身示例中展示的那一种。
• getSummary 要求 clientAddresses 数组非空——已实时确认（否则会以 "clientAddresses required" 回退）。此资产会先调用 getClients(agentId)，仅当结果至少包含一个地址时才调用 getSummary；对于没有反馈的 Agent，会正确报告 feedback_count: 0，不会产生 RPC 错误。
• **agentId=999999（真实不存在的代币）**会按预期以自定义错误回退，已实时确认——该错误会映射为 AGENT_NOT_FOUND，不会导致崩溃。

MCP 握手引擎：复用，而非重新实现

按照任务说明中的明确要求，_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 数组中选取真实端点，交由该引擎处理。

链范围

截至 2026-09-04，已统一。 x402 付款以真实 USDC 在 Base 主网结算。链上 IdentityRegistry 读取（即实际的身份／活跃状态检查）现在也在 Base 主网进行，使用经验证的 IdentityRegistryUpgradeable 部署（0x8004A169FB4a3325136EB29fA0ceB6D2e539a432）——详见下文“主网注册表已更正”。 ReputationRegistry 读取仍使用原地址（已在 Sepolia 验证）——本次会话未验证其对应的主网地址，详见“待处理”。 此资产仍未提供由调用方选择链的功能——没有证据表明买家在使用任一支付通道时需要此功能。

主网注册表已更正（2026-09-04）

下文 2026-09-03 的部分回滚是在调查错误的合约。0x8004A818BFB912233c491871b3d84c89A494BD9e 本身是 erc-8004/erc-8004-contracts 的 vanity 地址部署模式所生成的 Base SEPOLIA IdentityRegistry 确定性地址——它从来都不是 Base 主网的真实部署地址；每个网络的真实地址都不同。 Base 主网的真实 IdentityRegistry 地址是 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432：其实现合约 0x7274e874ca62410a93bd8bf61c69d8045e399c02 已在 Etherscan 上验证为 IdentityRegistryUpgradeable（名称与参考仓库完全一致，编译器为 v0.8.24+commit.e11b9ed9），ownerOf 读取成功；Basescan 导出记录显示，该合约上有 25 笔真实的 Base 主网 交易（2026-09-04 09:02-10:06 UTC，25 笔全部成功：5 次 register、20 次 setMetadata）——相比之下，旧地址上有 19 笔历史交易（2026-01-31 至 2026-04-20），其中 17 笔回滚。完整验证记录：scripts/verify_mainnet_registry_candidate.py，分支 claude/erc8004-registry-address-verify-u2db8u。本次会话未验证 ReputationRegistry 的真实主网地址——保持原样，详见“待处理”。

主网切换（2026-09-03）及当天的部分回退

最初在 Base Sepolia 测试网上构建并测量（x402 支付和注册表读取均在该网络上）。同一时段切换到 Base 主网：x402 结算改为使用 CDP facilitator（create_facilitator_config()，已对 ws/live-entity-verification 应用相同更改），收款钱包改为使用 NEXUS_X402_PAYTO_ADDRESS （必需的环境变量，缺失时快速失败，不设占位符默认值），注册表 RPC 也切换到了 Base 主网，合约地址仍是原来的两个地址——操作员在切换前直接通过 Basescan 确认了这些地址在不同链上复用，并非在进行代码更改的会话中独立重新验证（该环境无法向 mainnet.base.org 发起出站网络请求）。

几小时后，仅回退了注册表读取部分。 两个独立来源（实时 eth_call 和 Basescan 自带的 “Read as Proxy” 选项卡）确认，在 Base 主网上针对 IdentityRegistry 代理合约（0x8004A818BFB912233c491871b3d84c89A494BD9e）调用 ownerOf/balanceOf 均会以 “execution reverted, no data” 回退；但针对同一代理合约调用 register() 确实有效（已有 19 笔真实且已确认的铸造交易）。主网上代理背后的实现合约（0xd53dE688e0b0ad436FBdbDa00036832FF6499234，通过 Basescan 的代理实现槽确认）在 Etherscan/Basescan 上都没有已验证的源代码或 ABI——因此无法确认已部署的主网字节码是否仍与 github.com/erc-8004/erc-8004-contracts（提交 b9e466c）一致，而 Sepolia 部署的字节码最初曾得到确认（见上文“依据”）。继续按名称调用 ownerOf/tokenURI/getClients/getSummary，并针对未验证的主网字节码操作，可能会触发本工具要捕获的恰恰那种故障，只不过受影响的是它自己的买家：对真实 Agent 返回看似合理的错误答案（AGENT_NOT_FOUND），却仍按正确答案收费。

BASE_RPC_URL（默认值 https://mainnet.base.org）和 _IDENTITY_REGISTRY_ADDRESS （0x8004A169FB4a3325136EB29fA0ceB6D2e539a432）现在都指向真实且已验证的 Base 主网 IdentityRegistry——参见上文“主网注册表已修正”。此代码库其他地方没有可复用的 CDP RPC 节点模式（已检查 onchain-activity-index、x402-receipt-verifier、new-x402-listings-feed——它们都不通过 RPC 读取链上数据，只有 x402 支付使用了 CDP），因此这里复用了首次尝试于 2026-09-03 切换时使用的同一公共端点和环境变量名称。所有面向买家的内容（agent-card、OpenAPI 描述、本 README）均已更新，明确说明支付和注册表读取都在 Base 主网上进行。

待处理

已于 2026-09-04 解决：本节此前称主网切换受阻于反编译 0xd53dE688e0b0ad436FBdbDa00036832FF6499234——事实证明并不需要这样做。该地址从来都不是真正的主网 IdentityRegistry 实现；真正的实现 （0x7274e874ca62410a93bd8bf61c69d8045e399c02）已在 Etherscan 上独立验证为 IdentityRegistryUpgradeable，且切换已完成（参见上文“主网注册表已更正”）。

仍未解决的问题，特此明确说明，而非凭猜测处理：

• 本次未验证 ReputationRegistry 在 Base 主网上的真实地址——声誉读取仍通过现在的主网 RPC 使用 Sepolia 确定性地址，这可能是错误的。在信任该地址之前，需要像刚刚处理 IdentityRegistry 一样验证字节码和实现。
• _BASE_RPC 使用免费的公共端点 https://mainnet.base.org——没有 SLA。CDP 自带的 SDK（已是此处的依赖项）提供一个“Base Node” RPC 端点，可复用已为 x402 协调器配置的相同 CDP 凭据（cdp.base_node_rpc_url.get_base_node_rpc_url，已通过阅读实际的 cdp-sdk 源代码验证），但切换到该端点需要重构异步启动流程（目前的 RPC 客户端是在模块导入时同步构建的），且尚未确认其套餐级别是否提供该端点。暂不处理，除非有明确的可靠性或成本理由需要这么做——参见 main.py 中 _BASE_RPC 上方的注释。

部署目标：Cloud Run

与候选项 #4/#3/#6/#8/#9/#13/#16 使用相同的流程——参见 skills/infra-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>

已知限制（有意未修复——CLAUDE.md SS3；没有证据表明确有需要时，不设置门槛）

• MCP 工具调用不收费。 与此代码库中的其他手动资产一样，采用进程内调用模式。
• active: false 会直接返回 REGISTERED_INACTIVE，即使端点实际在线也是如此。 在这一情形下，信任注册者自己的声明，而不做独立的在线状态检查——如果某个 Agent 谎称自己处于非活动状态（动机不常见），报告结果就会有误。已接受此行为：按照规范设计，active 是注册者自己的信号；覆盖它就等于质疑标准自身的字段。 REGISTERED_UNREACHABLE（相反的故障模式——声明为活动状态，但实际上无法访问）是此资产的实际增值所在，因此不会以类似方式直接返回。
  • 端点选择是一种启发式方法，并非规范要求。 ERC-8004 的 endpoints 数组格式自由（name 可以是任意值）；此资产优先选择 mcp/x402/a2a/web（按此顺序），找不到时则回退到第一项。若注册项仅有一个实际支持 MCP 的端点，且其 name 未列出，该端点仍会被选中（匹配名称并非唯一途径——回退逻辑会处理未命中首选名称的情况）；但如果注册项包含多个端点，且首选名称都未指向在线端点，则可能会根据错误的端点报告 REGISTERED_UNREACHABLE。
• IPFS 解析仅使用一个公共网关（ipfs.io）。 没有备用网关——如果某个注册项的 CID 无法通过该网关固定或访问，即使其内容通常在 IPFS 上存在，也会报告 REGISTRATION_FETCH_FAILED。
• 没有针对每个调用方的速率限制。 对于为期 7 天的一次性测量窗口来说足够。
• reputation 是自我报告、无门槛、无质押的信号。 任何 EVM 地址都可以对任意 agentId 调用 ReputationRegistry.giveFeedback——feedback_count/average_value 是真实的链上数字，但没有任何机制阻止 Agent 自己的所有者通过女巫攻击给自己刷数据。应将其视为未经验证的信号，而非信任评分（此注意事项也写在 API 架构中 reputation 字段自身的描述里，不仅限于此处）。

质量关卡（2026-08-23，基于设计而非事后补做）

与候选项目 #3/#4/#6/#8/#9/#13/#16 相同的双 Agent 流程（安全视角；功能、质量和买家体验视角），在首次部署前运行。发现的问题均属实，并在上线前全部修复：

• 安全（0 个可利用的问题）： 确认从 agent-verification-api/main.py 原样移植的 3 个函数（_nexus_validate_public_url、_nexus_no_redirect_mcp_http_client、_mcp_handshake_check）确实包含了实际的 SSRF 重定向修复，逐字节一致；同时确认新的 https:///IPFS 注册信息获取路径在提取任何端点之前，就在更早的一层应用了同样的防护，确认没有重新引入这类漏洞。两个低风险/提示性问题均已作为纵深防御措施处理，尽管二者都不是已确认可利用的问题：IPFS CID 拼接（确认实际运行中无法逃出 ipfs.io 主机，但现在仍使用 urllib.parse.quote 将其限制在单一路径段内），以及 data: URI 的 base64 解码（确认是线性且不会放大，无需修复）。
• 功能/买家体验（1 个必须修复、1 个中等问题，均已处理）： 顶层 JSON 不是对象的注册文件（数组/字符串/数字，内容由注册者控制）会以 "ok": True 和非字典类型的 registration 继续传递，而所有下游使用方（_pick_liveness_endpoint、_classify_verdict、响应正文）都假设它是字典——未捕获的 AttributeError 会导致未处理的 500 错误，而此时 x402 付款已完成结算。修复方式：_resolve_registration_file 中的两个 JSON 解析位置现在都会拒绝非字典结果，并在返回 "ok": True 之前将其标记为 registration_not_an_object。另外还补充了声誉可操纵性的注意事项（见上文“已知限制”和 reputation 字段自身的架构描述）。另外两个低优先级/可选改进项（重复 name 的端点遮蔽，以及 2 个可选注册键未经验证的字段大小写）保持原样——目前没有证据表明它们会影响真实注册信息，这与 CLAUDE.md SS3 一致。
• 修复前后均通过真实生产数据进行了端到端验证：Base Sepolia 上 4 个真实 ERC-8004 Agent ID（1、2、3，以及实际不存在的 999999）均产生了正确判定结果——REGISTERED_UNREACHABLE（注册真实存在，但端点不响应 MCP）、REGISTRATION_FETCH_FAILED x2（一次真实的 IPFS 网关超时，以及一个真实失效的 https:// 注册 URL；两者均属正常情况，并非缺陷），以及 AGENT_NOT_FOUND（真实的链上回滚）；此外还获取了真实声誉数据（Agent 1 有 12 个不同客户端留下的 74 条反馈）。

测量（候选项目 #10，7 天观察期）

从 2026-08-23（实际部署日期）起观察 7 天，决策日期为 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）。