Feedback Data Profile | ERC-8004 pre-v1 (Legacy)

Description

Recommended offchain data profile for ERC-8004 feedback records

This document provides implementation-agnostic guidance for structuring feedback data referenced by the feedbackUri field in ERC-8004 Reputation Registry contracts.

Document Purpose

This profile document offers practical, non-normative recommendations for feedback data formats used with ERC-8004 Reputation Registries, based on real-world usage patterns and community feedback.

Relationship to EIP-8004

Important: This is not part of the official EIP-8004 specification.

Official EIP-8004 defines:

Reputation Registry smart contract interface
Onchain fields: score, tag1, tag2, feedbackUri, feedbackHash
The feedbackUri field is OPTIONAL

This profile suggests:

Offchain JSON structure for feedback data
Protocol-specific field patterns (A2A, MCP)
Evidence attachment guidelines
Payment proof integration (x402)

The official EIP makes feedbackUri optional. When provided, this profile recommends patterns for its content.

Terminology

This document follows conventions defined in Conventions, including:

RFC 2119 keywords: MUST, SHOULD, MAY
Field types: string, number, boolean, object, array
CAIP formats: CAIP-2 for blockchain IDs, CAIP-10 for addresses
Timestamps: ISO 8601 format in UTC

For attachment file patterns, see Attachment Pattern Guidelines.

Intended Audience

Service Clients: Users giving feedback after agent interactions
Agent Developers: Implementing feedback authorization
Registry Implementers: Building Reputation Registry contracts and indexers
Explorer Developers: Parsing and displaying feedback data

Overview
Recommended Feedback Profile
Attachment Pattern
Protocol-Specific Fields
Payment Proof Integration
Feedback Authorization
Examples
Best Practices

Overview

Onchain vs Offchain Data

Onchain (Reputation Registry contract):

score (uint8, 0-100) - REQUIRED
tag1, tag2 (bytes32) - OPTIONAL
feedbackUri (string) - OPTIONAL
feedbackHash (bytes32) - OPTIONAL
feedbackIndex (uint64) - Auto-assigned, 1-indexed (starts from 1, not 0)

Onchain Events (for indexers):

NewFeedback: agentId (indexed), clientAddress (indexed), score, tag1 (indexed), tag2, feedbackUri, feedbackHash
FeedbackRevoked: agentId (indexed), clientAddress (indexed), feedbackIndex (indexed)
ResponseAppended: agentId (indexed), clientAddress (indexed), feedbackIndex, responder (indexed), responseUri, responseHash

Note for Indexers: The indexed parameters can be efficiently filtered in event queries. Non-indexed parameters require full log scanning.

Offchain (referenced by feedbackUri):

Detailed feedback context and reasoning
Proof of payment (x402 protocol)
Protocol-specific fields (A2A/MCP)
Evidence attachments
Custom extensions

Non-normative: The feedbackUri field is optional per EIP-8004. However, providing rich offchain data improves trust, transparency, and enables better discovery and dispute resolution.

Recommended Feedback Profile

Suggested Schema

json

{
  // ============ REQUIRED FIELDS ============
  "agentRegistry": "eip155:84532:0x8004C269D0A5647E51E121FeB226200ECE932d55",
  "agentId": 22,
  "clientAddress": "eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "createdAt": "2025-12-20T12:00:00Z",
  "feedbackAuth": "0x...",
  "score": 100,

  // ============ RECOMMENDED FIELDS ============
  "reasoning": "Excellent portfolio analysis service. Fast, accurate, and professional communication.",
  "tag1": "defi",
  "tag2": "analytics",

  // ============ PROTOCOL-SPECIFIC FIELDS (OPTIONAL) ============

  // A2A Protocol fields
  "skill": "analytical_skills/data_analysis",
  "context": "Analyzed blockchain transaction data for portfolio optimization",
  "task": "Generate daily analytics report with recommendations",

  // MCP Protocol fields
  "capability": "tools",
  "name": "blockchain_analyzer",

  // ============ PAYMENT PROOF (OPTIONAL) ============
  "proof_of_payment": {
    "fromAddress": "eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "toAddress": "eip155:84532:0x8004...",
    "chainId": 84532,
    "txHash": "0xabc123...",
    "amount": "100000000000000000",
    "currency": "ETH",
    "protocol": "x402"
  },

  // ============ ATTACHMENTS (OPTIONAL) ============
  "attachments": [
    {
      "name": "Service Receipt",
      "uri": "ipfs://QmXxx...",
      "mimeType": "application/pdf",
      "size": 50000,
      "description": "Detailed service receipt with deliverables",
      "uploadedAt": "2025-12-20T11:50:00Z"
    }
  ],

  // ============ CUSTOM EXTENSIONS (OPTIONAL) ============
  "rating_breakdown": {
    "speed": 95,
    "accuracy": 100,
    "communication": 90,
    "value": 100
  },
  "interaction_id": "550e8400-e29b-41d4-a716-446655440000"
}

Recommended Fields

Field	Type	Constraints	Description
`agentRegistry`	string	CAIP-10 format	Agent's identity registry address
`agentId`	number	uint256, ≥ 0	Agent token ID
`clientAddress`	string	CAIP-10 format	Client's wallet address
`createdAt`	string	ISO 8601 UTC	Feedback creation timestamp
`feedbackAuth`	string	hex (0x...)	Signature from agent authorizing feedback
`score`	number	0–100 inclusive (uint8 onchain)	Overall feedback score (must match onchain value)

CAIP Format References:

CAIP-10 (Contract Address): eip155:84532:0x8004C269... → Conventions
CAIP-10 (Account ID): eip155:84532:0x742d35Cc... → Conventions

Optional Fields

Field	Type	Description
`reasoning`	string	Human-readable explanation of the feedback score
`tag1`	string	Primary category tag (converted to bytes32 for onchain storage)
`tag2`	string	Secondary category tag (converted to bytes32 for onchain)

Note: The tag1 and tag2 fields are stored as bytes32 onchain in the ReputationRegistry contract. When providing these fields in the offchain JSON, use human-readable strings. The indexer/frontend is responsible for converting between string and bytes32 formats.

Attachment Pattern

Overview

The attachment pattern allows clients to provide evidence, receipts, or supporting documents with their feedback.

For complete attachment schema and guidelines, see Attachment Pattern Guidelines.

Quick Reference

Attachments use the following structure:

typescript

interface AttachmentFile {
  name: string; // Display name (required)
  uri: string; // File location (required)
  mimeType: string; // MIME type (required)
  size: number; // File size in bytes (required)
  description?: string; // Optional context
  uploadedAt?: string; // Optional timestamp (ISO 8601 UTC)
}

Example:

json

{
  "attachments": [
    {
      "name": "Service Receipt",
      "uri": "ipfs://QmXxx...",
      "mimeType": "application/pdf",
      "size": 50000,
      "description": "Invoice and deliverables",
      "uploadedAt": "2025-12-20T15:00:00Z"
    }
  ]
}

Common Use Cases

1. Service Receipts: Proof of service completion
2. Communication Logs: Chat transcripts showing responsiveness
3. Work Product: Deliverables and analysis reports
4. Screenshots: Visual evidence of results

Supported File Types: PDFs, images, videos, JSON, CSV, text files, and more.

See Attachment Pattern Guidelines for:

Detailed field specifications
Security considerations
Best practices
Implementation requirements

json

{
  "name": "Analysis Report",
  "uri": "ipfs://QmZzz...",
  "mimeType": "application/pdf",
  "description": "Final deliverable - 50-page portfolio analysis report"
}

4. Screenshots/Evidence

json

{
  "name": "Service Screenshot",
  "uri": "ipfs://QmAaa...",
  "mimeType": "image/png",
  "description": "Screenshot showing successful task completion at 10:45 UTC"
}

Supported File Types

✅ Documents: PDF, Word, Markdown, Text
✅ Images: PNG, JPEG, WebP, GIF
✅ Data: JSON, CSV, XML
✅ Archives: ZIP (for multiple files)
✅ Any other format (stored as-is)

Protocol-Specific Fields

A2A Protocol Fields

For feedback on Agent-to-Agent (A2A) interactions:

Field	Type	Example	Description
`skill`	string	`"analytical_skills/data_analysis"`	A2A skill taxonomy
`context`	string	`"Analyzed blockchain data"`	Task context
`task`	string	`"Generate analytics report"`	Specific task

A2A Skill Taxonomy: See OASF Taxonomy

MCP Protocol Fields

For feedback on Model Context Protocol (MCP) capabilities:

Field	Type	Values	Description
`capability`	string	`prompts`, `resources`, `tools`, `completions`	MCP capability type
`name`	string	`"blockchain_analyzer"`	Name of the tool/resource/prompt

Custom Extensions

The standard supports arbitrary custom fields:

json

{
  "score": 95,
  // ... standard fields ...

  // Custom breakdown
  "rating_breakdown": {
    "speed": 95,
    "accuracy": 100,
    "communication": 90
  },

  // Custom identifiers
  "interaction_id": "uuid-v4",
  "session_id": "session-123",

  // Custom metadata
  "service_duration_hours": 2.5,
  "revisions_requested": 1
}

Payment Proof Integration

x402 Protocol Support

The proof_of_payment field integrates with the x402 payment protocol for agents.

typescript

interface ProofOfPayment {
  // Required
  fromAddress: string; // Payer address (CAIP-10)
  toAddress: string; // Payee address (CAIP-10)
  chainId: number; // Chain ID (e.g., 84532 for Base Sepolia)
  txHash: string; // Transaction hash (0x...)

  // Recommended
  amount?: string; // Payment amount (wei/smallest unit)
  currency?: string; // Currency symbol (e.g., "ETH", "USDC")
  protocol?: string; // Payment protocol (e.g., "x402")

  // Optional
  timestamp?: string; // Payment timestamp (ISO 8601)
  invoiceId?: string; // Invoice identifier
}

Example: ETH Payment

json

{
  "proof_of_payment": {
    "fromAddress": "eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "toAddress": "eip155:84532:0x8004...",
    "chainId": 84532,
    "txHash": "0xabc123...",
    "amount": "100000000000000000",
    "currency": "ETH",
    "protocol": "x402",
    "timestamp": "2025-12-20T11:45:00Z"
  }
}

Example: USDC Payment

json

{
  "proof_of_payment": {
    "fromAddress": "eip155:84532:0x742d35Cc...",
    "toAddress": "eip155:84532:0x8004...",
    "chainId": 84532,
    "txHash": "0xdef456...",
    "amount": "100000000",
    "currency": "USDC",
    "tokenAddress": "eip155:84532:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "protocol": "x402"
  }
}

Feedback Authorization

feedbackAuth Field

The feedbackAuth field contains a cryptographic signature proving the agent authorized this feedback.

Purpose:

✅ Prevents spam feedback
✅ Proves client actually interacted with agent
✅ Enables dispute resolution

Authorization Structure

The signature is created by signing the following data:

solidity

struct FeedbackAuth {
  uint256 agentId;
  address clientAddress;
  uint64 indexLimit;       // Max feedback index allowed
  uint256 expiry;          // Timestamp when auth expires
  uint256 chainId;
  address identityRegistry;
  address signerAddress;   // Agent owner/operator
}

Signature Format

solidity

feedbackAuth = sign(keccak256(abi.encodePacked(
  agentId,
  clientAddress,
  indexLimit,
  expiry,
  chainId,
  identityRegistry,
  signerAddress
)))

Example:

json

{
  "feedbackAuth": "0x1234567890abcdef..."
}

Examples

Example 1: Simple Feedback

json

{
  "agentRegistry": "eip155:84532:0x8004C269D0A5647E51E121FeB226200ECE932d55",
  "agentId": 22,
  "clientAddress": "eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "createdAt": "2025-12-20T12:00:00Z",
  "feedbackAuth": "0xabc123...",
  "score": 95,

  "reasoning": "Great DeFi analytics agent. Quick response time and accurate insights.",
  "tag1": "defi",
  "tag2": "analytics"
}

Example 2: Detailed A2A Feedback with Payment Proof

json

{
  "agentRegistry": "eip155:84532:0x8004C269D0A5647E51E121FeB226200ECE932d55",
  "agentId": 45,
  "clientAddress": "eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "createdAt": "2025-12-20T14:30:00Z",
  "feedbackAuth": "0xdef456...",
  "score": 100,

  "reasoning": "Exceptional market analysis service. Provided comprehensive report with actionable insights.",
  "tag1": "trading",
  "tag2": "research",

  "skill": "analytical_skills/market_analysis",
  "context": "Analyzed crypto market trends for Q4 2025",
  "task": "Generate comprehensive market analysis report with predictions",

  "proof_of_payment": {
    "fromAddress": "eip155:84532:0x742d35Cc...",
    "toAddress": "eip155:84532:0x8004...",
    "chainId": 84532,
    "txHash": "0x789abc...",
    "amount": "500000000000000000",
    "currency": "ETH",
    "protocol": "x402"
  },

  "attachments": [
    {
      "name": "Market Analysis Report",
      "uri": "ipfs://QmXxx...",
      "mimeType": "application/pdf",
      "size": 2048000,
      "description": "75-page comprehensive market analysis with charts and predictions",
      "uploadedAt": "2025-12-20T14:00:00Z"
    },
    {
      "name": "Raw Data",
      "uri": "ipfs://QmYyy...",
      "mimeType": "text/csv",
      "size": 500000,
      "description": "Historical price data used for analysis",
      "uploadedAt": "2025-12-20T14:00:00Z"
    }
  ],

  "rating_breakdown": {
    "depth": 100,
    "accuracy": 100,
    "timeliness": 95,
    "presentation": 100
  },
  "interaction_id": "550e8400-e29b-41d4-a716-446655440000"
}

Example 3: MCP Tool Feedback

json

{
  "agentRegistry": "eip155:11155111:0x8004...",
  "agentId": 78,
  "clientAddress": "eip155:11155111:0x123...",
  "createdAt": "2025-12-20T16:00:00Z",
  "feedbackAuth": "0xghi789...",
  "score": 90,

  "reasoning": "Blockchain analyzer MCP tool worked well. Accurate transaction parsing.",
  "tag1": "mcp",
  "tag2": "tools",

  "capability": "tools",
  "name": "blockchain_transaction_parser",

  "rating_breakdown": {
    "accuracy": 95,
    "speed": 85,
    "reliability": 90
  }
}

Best Practices

1. Always Provide Reasoning

❌ Bad:

json

{
  "score": 80
}

✅ Good:

json

{
  "score": 80,
  "reasoning": "Good service overall. Response time was a bit slow (2 hours), but final deliverable quality was excellent."
}

2. Include Evidence for Disputes

For high-stakes or high-value interactions, include attachments:

json

{
  "score": 100,
  "reasoning": "...",
  "attachments": [
    {
      "name": "Service Receipt",
      "uri": "ipfs://...",
      "mimeType": "application/pdf",
      "description": "Official receipt showing completed deliverables"
    }
  ]
}

3. Use Protocol-Specific Fields

If using A2A or MCP, include relevant fields for better discoverability:

json

{
  "score": 95,
  "skill": "natural_language_processing/summarization",
  "capability": "completions"
}

4. Include Payment Proof for x402

For agents supporting x402 payment protocol:

json

{
  "score": 100,
  "proof_of_payment": {
    "txHash": "0x...",
    "amount": "100000000000000000",
    "currency": "ETH"
  }
}

5. Use CAIP Formats for Addresses

❌ Bad:

json

{
  "clientAddress": "0x742d35Cc..."
}

✅ Good:

json

{
  "clientAddress": "eip155:84532:0x742d35Cc..."
}

6. Timestamp Everything

json

{
  "createdAt": "2025-12-20T12:00:00Z",
  "proof_of_payment": {
    "timestamp": "2025-12-20T11:45:00Z"
  },
  "attachments": [
    {
      "uploadedAt": "2025-12-20T11:50:00Z"
    }
  ]
}

Description ​

Document Purpose ​

Relationship to EIP-8004 ​

Terminology ​

Intended Audience ​

Table of Contents ​

Overview ​

Onchain vs Offchain Data ​

Recommended Feedback Profile ​

Suggested Schema ​

Recommended Fields ​

Optional Fields ​

Attachment Pattern ​

Overview ​

Quick Reference ​

Common Use Cases ​

4. Screenshots/Evidence ​

Supported File Types ​

Protocol-Specific Fields ​

A2A Protocol Fields ​

MCP Protocol Fields ​

Custom Extensions ​

Payment Proof Integration ​

x402 Protocol Support ​

Example: ETH Payment ​

Example: USDC Payment ​

Feedback Authorization ​

feedbackAuth Field ​

Authorization Structure ​

Signature Format ​

Examples ​

Example 1: Simple Feedback ​

Example 2: Detailed A2A Feedback with Payment Proof ​

Example 3: MCP Tool Feedback ​

Best Practices ​

1. Always Provide Reasoning ​

2. Include Evidence for Disputes ​

3. Use Protocol-Specific Fields ​

4. Include Payment Proof for x402 ​

5. Use CAIP Formats for Addresses ​

6. Timestamp Everything ​

See Also ​

Description

Document Purpose

Relationship to EIP-8004

Terminology

Intended Audience

Table of Contents

Overview

Onchain vs Offchain Data

Recommended Feedback Profile

Suggested Schema

Recommended Fields

Optional Fields

Attachment Pattern

Overview

Quick Reference

Common Use Cases

4. Screenshots/Evidence

Supported File Types

Protocol-Specific Fields

A2A Protocol Fields

MCP Protocol Fields

Custom Extensions

Payment Proof Integration

x402 Protocol Support

Example: ETH Payment

Example: USDC Payment

Feedback Authorization

feedbackAuth Field

Authorization Structure

Signature Format

Examples

Example 1: Simple Feedback

Example 2: Detailed A2A Feedback with Payment Proof

Example 3: MCP Tool Feedback

Best Practices

1. Always Provide Reasoning

2. Include Evidence for Disputes

3. Use Protocol-Specific Fields

4. Include Payment Proof for x402

5. Use CAIP Formats for Addresses

6. Timestamp Everything

See Also