erc8004 agent liveness

ERC-8004 Agent Liveness

Checks whether an agent registered in the real ERC-8004 "Trustless Agents" Identity Registry (Base Sepolia testnet) is actually alive right now -- not just that it was registered once. NEXUS candidate #10 -- manual build, not FORGE-generated, same manual-Cloud-Run-asset pattern as candidates #3/#4/#6/#8/#9/#13/#16.

• POST /verify-registered-agent {"agent_id": 3} -- $0.10/call.
• MCP tool verify_registered_agent at /mcp, same params -- currently free, see "Known limitations".
• GET /health, GET /.well-known/agent-card.json, GET /openapi.json (has x-payment-info), GET /.well-known/402index-verify.txt (402index claim verification file).

What this is (and why registration alone isn't enough)

ERC-8004 is a real, live Ethereum standard for on-chain agent identity: an agent mints an ERC-721 token in an IdentityRegistry, whose tokenURI points to an off-chain registration file (JSON: name, description, declared endpoints, active flag, supported trust methods). It went live on Ethereum mainnet 2026-01-29, with reference deployments on Base mainnet and Base/Ethereum/Linea Sepolia testnets. Registration is a one-time on-chain action -- a real registered agent can go completely dark (process killed, domain expired, endpoint changed) while its on-chain record persists unchanged forever. This asset closes that gap: it resolves the real on-chain registration AND performs a real MCP initialize handshake against whatever endpoint the registration declares, right now, at call time -- the same liveness-vs-registration distinction agent-verification-api (candidate #3) already draws for domain-claimed identities, applied here to on-chain-registered ones.

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

• Contract addresses, initially from a third-party summary, verified independently via eth_getCode against https://sepolia.base.org before being trusted: IdentityRegistry (0x8004A818BFB912233c491871b3d84c89A494BD9e) and ReputationRegistry (0x8004B663056A597Dffe9eCcC1965A193B7388713) both have real, non-empty deployed bytecode.
• ABI, pulled from the reference implementation (github.com/erc-8004/erc-8004-contracts/abis), tested live against 3 real registered agents (agentId 1-3) before being trusted for this asset:
  • Agent 1's tokenURI resolves to a data:application/json;base64,... URI.
  • Agent 2's resolves to ipfs://bafkreiff....
  • Agent 3's resolves to a real https://api.snack.money/agent/.../registration.json URL. All 3 of ERC-8004's real URI schemes confirmed working live, not just the one the spec's own examples show.
• getSummary requires a non-empty clientAddresses array -- confirmed live (reverts with "clientAddresses required" otherwise). This asset calls getClients(agentId) first and only calls getSummary if that returns at least one address; agents with zero feedback correctly report feedback_count: 0 without an RPC error.
• agentId=999999 (a real nonexistent token) correctly reverts with a custom error, confirmed live -- mapped to AGENT_NOT_FOUND, not a crash.

MCP handshake engine: reused, not reimplemented

Per the task brief's explicit instruction, _nexus_validate_public_url, _nexus_no_redirect_mcp_http_client, and _mcp_handshake_check are ported verbatim from manual_assets/agent-verification-api/main.py (candidate #3) -- same SSRF pre-check, same no-redirect posture (the exact fix applied there after the 2026-08-22 security review found a redirect-based SSRF bypass), same bounded timeout. Not modified beyond the asset-name constant. This asset's own contribution is upstream of that: resolving an ERC-8004 registration file (3 URI schemes) and picking a real endpoint out of its endpoints array to hand to that engine.

Chain scope, on purpose

Base Sepolia testnet only -- same network every other x402 payment in this codebase already uses. ERC-8004 is also live on Base mainnet and Ethereum mainnet (verified live this session), but this asset doesn't expose a caller-selectable chain: no evidence a buyer needs mainnet for a 7-day probation candidate (CLAUDE.md SS3).

Deploy target: Cloud Run

Same pipeline as candidates #4/#3/#6/#8/#9/#13/#16 -- see 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>

Known limitations (left unfixed on purpose -- CLAUDE.md SS3, no gate without evidence it's needed)

• MCP tool calls are not charged. Same in-process-call pattern as every other manual asset in this codebase.
• active: false short-circuits to REGISTERED_INACTIVE even if the endpoint is actually live. Trusts the registrant's own self-declaration over an independent liveness check in that one case -- an agent lying about being inactive (unusual incentive) would be misreported. Accepted: active is the registrant's own signal by spec design, overriding it would be second-guessing the standard's own field. REGISTERED_UNREACHABLE (the opposite failure mode -- declared active, not actually reachable) is this asset's actual value-add and is NOT similarly short-circuited.
  • Endpoint selection is a heuristic, not a spec requirement. ERC-8004's endpoints array is free-form (any name); this asset prefers mcp/x402/a2a/web (in that order) and falls back to the first entry. A registration using an unlisted name for its only real MCP-capable endpoint would still be picked (name matching isn't the only path -- unnamed-preference fallback covers it), but a registration with MULTIPLE endpoints where none of the preferred names points to the live one could report REGISTERED_UNREACHABLE based on the wrong endpoint.
• IPFS resolution uses a single public gateway (ipfs.io). No fallback gateway -- a registration whose CID isn't pinned/reachable via that specific gateway reports REGISTRATION_FETCH_FAILED even if the content exists on IPFS generally.
• No per-caller rate limiting. Fine for a 7-day disposable measurement window.
• reputation is a self-reported, ungated, un-staked signal. Any EVM address can call ReputationRegistry.giveFeedback for any agentId -- feedback_count/average_value are real on-chain numbers, but nothing stops an agent's own owner from Sybil-feeding themselves. Treat as an unverified signal, not a trust score (this caveat is also in the reputation field's own description in the API schema, not just here).

Quality gate (2026-08-23, from design not retroactive)

Same 2-agent process as candidates #3/#4/#6/#8/#9/#13/#16 (security lens; functional+quality+buyer-experience lens), run before the first deploy. Real findings, all fixed before going live:

• Security (0 exploitable findings): confirmed the 3 functions ported verbatim from agent-verification-api/main.py (_nexus_validate_public_url, _nexus_no_redirect_mcp_http_client, _mcp_handshake_check) carry the actual SSRF-redirect fix, byte-for-byte, and that the new https:///IPFS registration-fetch path applies the same defense one layer earlier, before any endpoint is extracted -- confirmed NOT to reintroduce that bug class. Two low/informational items, both addressed as defense-in-depth even though neither was a confirmed exploit: IPFS CID concatenation (confirmed live it couldn't escape the ipfs.io host, but now uses urllib.parse.quote to confine it to a single path segment anyway), and data: URI base64 decoding (confirmed linear/non-amplifying, no fix needed).
• Functional/buyer-experience (1 must-fix, 1 medium, applied): a registration file whose top-level JSON is a non-object (array/string/number -- registrant-controlled content) passed through as "ok": True with a non-dict registration, which every downstream consumer (_pick_liveness_endpoint, _classify_verdict, the response body) assumed was a dict -- an uncaught AttributeError became an unhandled 500 after x402 payment had already settled. Fixed: both JSON-parse sites in _resolve_registration_file now reject non-dict results as registration_not_an_object before returning "ok": True. Also added the reputation gameability caveat (see "Known limitations" above and the reputation field's own schema description). Two low/nice-to-have items (duplicate-name endpoint shadowing, unverified field casing on 2 optional registration keys) left as-is -- no evidence yet either matters for real registrations, consistent with CLAUDE.md SS3.
• Verified end-to-end against real production data before AND after fixes: 4 real ERC-8004 agent IDs on Base Sepolia (1, 2, 3, and a real nonexistent 999999) each produced the correct verdict -- REGISTERED_UNREACHABLE (real registration, endpoint doesn't answer MCP), REGISTRATION_FETCH_FAILED x2 (a real IPFS gateway timeout, and a real dead https:// registration URL -- both legitimate, not bugs), and AGENT_NOT_FOUND (real on-chain revert) -- plus real reputation data (74 feedback entries from 12 distinct clients on agent 1).

Measurement (candidate #10, 7-day window)

7-day window from 2026-08-23 (real deploy date) -> decision point 2026-08-30. Source of truth: traffic_events/revenue_events/mcp_call_events (asset_name = 'erc8004-agent-liveness'), not Cloud Run logs. Day 7: if zero real traffic (filtering crawlers), pause/delete the Cloud Run service (gcloud run services delete erc8004-agent-liveness --region us-central1 --project nexus-505016).