ERC-8004

Appearance

Sources & References

ReferenceVersion0.1UpdatedDec 20, 2025Reference

Description ​

Source tracking for ERC-8004 standards documentation

Document Structure ​

This directory contains three comprehensive standards documents based on the official EIP-8004 specification and real-world production data:

  1. Agent Metadata Standard - AgentURI offchain data format
  2. Feedback Standard - Reputation Registry offchain data format
  3. Validation Standard - Validation Registry offchain data format

All documents positioned as "8004scan's official supplementary recommended standards for ERC-8004".

Primary Sources ​

1. Official ERC-8004 Specification ​

Organization: Ethereum Foundation
Document: EIP-8004: Trustless Agents
URL: https://eips.ethereum.org/EIPS/eip-8004
Status: Peer Review (as of 2025-12-20)

Reference Repository:

What We Used:

  • AgentURI metadata schema (required/recommended/optional fields)
  • Reputation Registry feedback structure
  • Validation Registry request/response structure
  • Onchain metadata key-value specification
  • Trust model definitions (reputation, crypto-economic, tee-attestation)
  • Contract interface specifications

2. Agent0 SDK Documentation ​

Organization: Agent0 Project (ERC-8004 reference implementation)
Repository: https://github.com/agent0/agent0 (assumed - verify actual URL)
Documentation Site: https://docs.agent0.xyz/ (assumed - verify actual URL)

Key Documents:

  • 1-welcome-1-4-erc-8004.md - ERC-8004 overview and integration
  • 2-usage-2-2-configure-agents.md - Agent configuration guide
  • 2-usage-2-3-registration-ipfs.md - IPFS registration workflow
  • 5-reference-5-2-agent.md - Agent API reference

What We Used:

  • Standard agent metadata format (type, endpoints, registrations)
  • MCP and A2A endpoint specifications
  • IPFS storage patterns
  • Timestamp field usage (createdAt, updatedAt)
  • Feedback submission patterns
  • Validation request/response patterns

3. ERC-8004 Best Practices Guide ​

Organization: ERC-8004 Community
Repository: https://github.com/erc-8004/best-practices (assumed - verify)
Document: README.md - "4 Golden Rules for Agent Registration"

What We Used:

  • Rule 1: Name, Image, Description importance
  • Rule 2: Endpoint types and formats (MCP, A2A, OASF, ENS, DID, agentWallet)
  • Rule 3: OASF skills and domains taxonomy usage
  • Rule 4: Registrations array bidirectional verification
  • x402 support flag
  • Active status flag

4. OASF (Open Agentic Schema Framework) ​

Organization: agntcy (now Linux Foundation)
Repository: https://github.com/agntcy/oasf
Version: v0.8.0
Schema Browser: https://schema.oasf.outshift.com/0.8.0

What We Used:

  • Skills taxonomy structure (categories/subcategories)
  • Domains taxonomy structure
  • OASF endpoint format and version specification
  • Recommended skills for blockchain agents
  • Recommended domains for financial/technical agents

Resources:

5. CAIP Standards ​

Organization: Chain Agnostic Improvement Proposals (ChainAgnostic)
Repository: https://github.com/ChainAgnostic/CAIPs

CAIP-2: Blockchain ID Specification:

CAIP-10: Account ID Specification:

6. Protocol Documentation ​

MCP (Model Context Protocol):

A2A (Agent-to-Agent Protocol):

  • URL: https://a2a.to/
  • Standard Version: v0.3.0
  • What We Used: A2A endpoint structure, agent card format, skills taxonomy

7. Community Resources ​

Awesome ERC-8004:

Trustless Agents Reference Implementation:

Real-World Data Sources ​

8. Production Agent Metadata ​

Organization: 8004scan Project
Data Collection Date: 2025-12-19
Sample Size: 400 agents (8.5% of 4,725 total with metadata)

Collection Method:

sql
SELECT
    chain_id,
    agent_id,
    metadata_uri,
    metadata_json,
    metadata_parse_status,
    metadata_parse_warnings
FROM agents
WHERE metadata_json IS NOT NULL
ORDER BY created_at DESC
LIMIT 400;

Key Statistics:

  • URI types: IPFS 51%, HTTP 22%, Data URI 18%
  • Endpoint adoption: A2A 85%, MCP 75%, OASF 60%
  • Parse success: 69.9% (including warnings), 58.1% perfect
  • Common issues: ~15% empty endpoints, ~30% null agentId

Documented Patterns:

  1. Agent0 SDK Standard Format
  2. Alias AI Star Card Format
  3. ChaosChain Studio Format
  4. Minimal/Test Agents

9. Production Validation Data ​

Organization: 8004scan Project
Data Collection Date: 2025-12-20
Sample Size: 8,219 validation records (Base Sepolia)

Key Findings:

  • 100% Groth16 zkSNARK proofs (8,219 records)
  • No ERC-8004 standard format validations (yet)
  • Circuit: zyfi-rebalancing-validation (ZyFi protocol)
  • All contain: proof.pi_a/pi_b/pi_c, publicSignals, verifierAddress

Implications:

  • Led to design of three-level format compatibility system
  • Groth16 recognized as Level 2 (Known Custom Format)
  • Migration guides created for Groth16 → ERC-8004 standard

10. v1 Frontend Implementation ​

Organization: 8004scan v1 Project
Data: v1 frontend code and patterns

Key Discoveries:

  • Attachment Pattern: Flexible evidence system supporting any file type
  • Upload methods: File upload, JSON paste, manual URI
  • Metadata structure: name, uri, mimeType, size, description, uploadedAt
  • Use cases: Security audits (PDF), test results (JSON/CSV), screenshots, videos

Impact:

  • Integrated attachment pattern into Feedback and Validation standards
  • Documented best practices for evidence collection
  • Created migration examples

Synthesis Methodology ​

Step 1: Official Spec Analysis ​

  1. Read EIP-8004 specification in full
  2. Extract schema definitions (required/recommended/optional)
  3. Document contract interfaces
  4. Note trust model specifications

Step 2: Reference Implementation Review ​

  1. Study Agent0 SDK documentation
  2. Identify standard patterns and conventions
  3. Extract endpoint format specifications
  4. Document IPFS storage patterns

Step 3: Community Best Practices Integration ​

  1. Review "4 Golden Rules" from best practices guide
  2. Integrate OASF taxonomy usage
  3. Document x402 and active flags
  4. Cross-reference with CAIP standards

Step 4: Real-World Data Analysis ​

Agent Metadata (4,725 agents):

  1. Collect 400 production samples
  2. Categorize by pattern (4 major patterns)
  3. Calculate adoption statistics
  4. Identify common issues and edge cases
  5. Document non-standard but common fields

Validation Data (8,219 validations):

  1. Analyze all validation records on Base Sepolia
  2. Identify dominant format (100% Groth16)
  3. Document custom proof structures
  4. Design three-level compatibility system
  5. Create migration guides

v1 Frontend Analysis:

  1. Review v1 attachment implementation
  2. Extract reusable patterns
  3. Document best practices
  4. Integrate into new standards

Step 5: Validation Rule Derivation ​

Agent Metadata:

  • Level 1 (Required): From EIP-8004 spec + ERC-721 compatibility
  • Level 2 (Endpoints): From best practices + real-world usage
  • Level 3 (Registrations): From EIP-8004 + CAIP standards
  • Level 4 (Trust Models): From EIP-8004 + community extensions
  • Level 5 (Status Fields): From best practices + real-world usage

Validation Format:

  • Level 1 (ERC-8004 Standard): From official spec + suggested improvements
  • Level 2 (Known Custom): From production data analysis (Groth16)
  • Level 3 (Unknown): Fallback for unrecognized formats

Step 6: Documentation Structure Design ​

  1. Separate feedback and validation standards
  2. Create professional developer-facing documents
  3. Position as "supplementary recommended standards"
  4. Add implementation guides and references
  5. Include migration guides for existing formats

Update Process ​

When updating these documents in the future:

1. Check Official Sources ​

  • [ ] Review EIP-8004 specification for changes
  • [ ] Check agent0 SDK documentation updates
  • [ ] Verify OASF taxonomy version (currently v0.8.0)
  • [ ] Review CAIP standards for updates
  • [ ] Check MCP/A2A protocol versions

2. Collect Fresh Data ​

  • [ ] Export latest agent samples from database
  • [ ] Export latest validation samples
  • [ ] Export latest feedback samples (when available)
  • [ ] Run statistical analysis on full datasets
  • [ ] Identify new patterns or changes in adoption

3. Identify Changes ​

  • [ ] Compare new data with previous baseline
  • [ ] Document any schema drift
  • [ ] Note new common fields or patterns
  • [ ] Identify deprecated patterns
  • [ ] Check for new trust models or endpoint types

4. Update Documentation ​

  • [ ] Revise standard documents for spec changes
  • [ ] Update statistics and examples
  • [ ] Add new patterns to implementation guides
  • [ ] Update parser validation rules if needed
  • [ ] Revise migration guides

5. Version Control ​

  • [ ] Update "Last Updated" date in all documents
  • [ ] Note version changes in this sources.md
  • [ ] Git commit with clear message describing changes
  • [ ] Tag release if major update (e.g., v3.0)

Documentation Coverage ​

StandardStatusData SourcesReal-World Samples
Agent Metadata✅ CompleteEIP-8004 + Agent0 + OASF + CAIP400 agents
Feedback✅ CompleteEIP-8004 + v1 frontendv1 patterns
Validation✅ CompleteEIP-8004 + production data8,219 validations

Implementation Guides:

  • ✅ Agent Metadata Parsing
  • ✅ Feedback Best Practices
  • ✅ Validation Best Practices

Reference Materials:

  • ✅ Sources & References (this document)

Known Format Variants ​

Agent Metadata ​

  • Standard: Agent0 SDK format (most common)
  • Custom: Alias AI Star Card, ChaosChain Studio
  • Edge Cases: Empty endpoints, null agentId, version typos

Validation ​

  • Standard: ERC-8004 format (0% adoption currently)
  • Custom Level 2: Groth16 zkSNARK (100% of production data)
  • Future: PLONK, STARK (designed but not yet seen)

Feedback ​

  • Standard: ERC-8004 format
  • Extension: v1 attachment pattern
  • Protocol Fields: A2A, MCP, x402 specific fields

Contact and Maintenance ​

Primary Maintainer: 8004scan Development Team
Documentation Owner: Backend Team
Review Frequency: Monthly
Next Scheduled Review: 2026-01-20

For Updates:

  1. Check official sources listed above
  2. Collect fresh production data
  3. Follow update process in this document
  4. Update version and date in all documents

For Questions:

  • Specification interpretation → Refer to EIP-8004 official spec
  • Implementation patterns → Refer to Agent0 SDK docs
  • Real-world usage → Refer to production data analysis
  • CAIP formats → Refer to ChainAgnostic CAIPs repo
  • OASF taxonomy → Refer to OASF v0.8.0 schema browser

References Summary ​

SourceOrganizationTypeURL
EIP-8004Ethereum FoundationOfficial Spechttps://eips.ethereum.org/EIPS/eip-8004
erc-8004-contractsERC-8004 ProjectReference Implhttps://github.com/erc-8004/erc-8004-contracts
agent0 docsAgent0 ProjectSDK Docshttps://docs.agent0.xyz/
best-practicesERC-8004 CommunityGuidehttps://github.com/erc-8004/best-practices
OASF v0.8.0agntcy/Linux FoundationTaxonomyhttps://github.com/agntcy/oasf
CAIP-2ChainAgnosticStandardhttps://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md
CAIP-10ChainAgnosticStandardhttps://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md
MCP ProtocolModel Context ProtocolProtocol Docshttps://modelcontextprotocol.io/
A2A ProtocolAgent-to-AgentProtocol Docshttps://a2a.to/
awesome-erc8004CommunityResource Listhttps://github.com/sudeepb02/awesome-erc8004
trustless-agents-erc-riChaosChainReference Implhttps://github.com/ChaosChain/trustless-agents-erc-ri
8004scan Production DBThis ProjectReal-world Data4,725 agents, 8,219 validations
8004scan v1 FrontendThis ProjectImplementationAttachment pattern