feat(bridge): ERC-8004 Day 2 — registry_reader.py + web3.py mainnet wiring

[kenneives]

Summary

Day 2 of the 3-day ERC-8004 bridge MVP. Wires web3.py against Ethereum mainnet so AgentGraph can read entries from the three EIP-8004 registries (Identity / Reputation / Validation) and surface them as ERC8004Entry Pydantic models for downstream normalization (Day 3).

Closes #86. Day 3 (#87) lands attestation_normalizer.py + score_ingest.py + src/trust/score.py integration next.

Architecture decisions

• Web3 injected, not hidden — ERC8004RegistryReader(web3, config) accepts a Web3 instance as a constructor argument. Tests pass MagicMock. Production passes Web3(HTTPProvider(alchemy_url)). No monkeypatching, no globals.
• Async-ready, sync-default — Day 2 ships a synchronous reader because the trust score recompute job (which will consume this in Day 3) is already sync. An AsyncHTTPProvider-backed variant is trivial to add later without changing the reader's public API.
• ABI as overridable artifact — abi/erc8004_registry.json is the minimal canonical ABI inferred from EIP-8004 semantics (getEntry, entryCount, EntrySubmitted). Override via ERC8004_ABI_PATH env var when the finalised EIP-8004 ABI lands. No hardcoded ABI tuples scattered through the code.
• Optional dependency — web3 + eth-account land in [project.optional-dependencies].erc8004 rather than as hard deps. The main backend stays lean; ERC-8004 is opt-in via env config + pip install agentgraph[erc8004].

Test plan

• Unit tests with mocked Web3: 13/13 PASS, 1 live skipped
  • URN parsing across all 3 registries
  • Negative entry_id rejection
  • Empty subjectDid → None
  • exists=false → RegistryReadError
  • RPC connection exception wrapped to RegistryReadError
  • entry_count() success + failure paths
  • is_reachable() for mainnet / chain-id mismatch / RPC down
• Live mainnet smoke against Alchemy free tier: 1/1 PASS
  • Confirms RPC responds, chain_id=1, block height > 25M
  • Skipped by default; runs when ETH_RPC_URL is set (which it is in both dev + prod)

$ cd /tmp/agbridge-test && python3 -m pytest agentgraph_bridge_erc8004/tests/test_registry_reader.py -v
================== 13 passed, 1 skipped, 2 warnings in 0.46s ===================

$ ETH_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/<KEY> python3 -m pytest -k TestLiveMainnetSmoke
======================== 1 passed, 2 warnings in 0.67s =========================

What's NOT in this PR (Day 3 scope)

• Actual EIP-8004 mainnet contract addresses (ERC8004_*_ADDRESS env vars still point at placeholder zeros in config.py). Day 3 fixtures (#88) land these once the canonical EIP-8004 deployment is verified.
• CTEF envelope parsing of the data field bytes (Day 3 attestation_normalizer.py)
• Ed25519 signature verification on embedded CTEF attestation (Day 3)
• Integration with src/trust/score.py composite score (EXTERNAL: 0.35 slot, Day 3)
• 3 mainnet snapshot fixtures for offline reproduction (Day 3 #88)

Files changed

• src/agentgraph_bridge_erc8004/registry_reader.py (new, 174 LoC)
• src/agentgraph_bridge_erc8004/abi/__init__.py (new, 24 LoC)
• src/agentgraph_bridge_erc8004/abi/erc8004_registry.json (new, 28 LoC)
• src/agentgraph_bridge_erc8004/tests/test_registry_reader.py (new, 196 LoC, 13 tests + 1 live smoke)
• src/agentgraph_bridge_erc8004/__init__.py (+exports, version 0.0.1 → 0.1.0)
• pyproject.toml (+[erc8004] optional deps)

🤖 Generated with Claude Code

[github-actions]

AgentGraph Trust Scan

Security Scan Grade: ? (0/100) — No summary available

Category	Score

Findings: 0 critical, 0 high, 61 medium, 0 low

View full report | Add badge to README

This is a code security scan score. Full composite trust score (including identity verification and external signals) is available on AgentGraph.