Feedback Data Profile

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.

Version Info: This document describes the v2.0 specification (January 2026). For previous versions:
v1.x documentation
pre-v1 (legacy) documentation

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: value, valueDecimals, tag1, tag2, endpoint, feedbackURI, feedbackHash
The feedbackURI field is OPTIONAL

v2.0 Breaking Change: The score field (uint8, 0-100) has been replaced by value (int128) + valueDecimals (uint8, 0-18). See Key Changes in v2.0 for details.

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.

Key Changes in v2.0 (January 2026)

Field	v1.x	v2.0
Score/Value	`score` (uint8, 0-100)	`value` (int128) + `valueDecimals` (uint8, 0-18)
Negative Rating	Not supported	Supported (value can be negative)
Decimal Precision	Integer only	Up to 18 decimal places
Range	0-100	Unlimited (int128)

Why v2.0? The v1.x score field was limited to 0-100 integer values, which prevented many useful metric types. v2.0 introduces value (int128) + valueDecimals (uint8) which supports:
Arbitrary metrics: Response time (ms), uptime (%), revenues ($), block freshness, etc.
Decimal precision: 99.77% uptime → value=9977, valueDecimals=2
Large values: Response time 1100ms → value=1100, valueDecimals=0
Negative feedback: Disputes, fraud reports (e.g., -5 for bad service)
Flexible rating scales: 5-star, 10-point, percentage, or custom systems

Key Changes in v1.x (vs pre-v1)

Field	pre-v1 (legacy)	v1.x
Tag Types	`bytes32`	`string`
URI Naming	`feedbackUri`	`feedbackURI`
FeedbackAuth	Required	Removed
Endpoint	—	NEW
feedbackIndex	Calculated	From event

See migration guide for upgrading from pre-v1 (legacy).
See v1.x to v2.0 migration guide for upgrading from v1.x.

Terminology

This document follows conventions defined in Conventions. For attachment file patterns, see Attachment Pattern Standard.

Intended Audience

Service clients giving feedback
Registry implementers building indexers and explorers

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

Overview

Onchain vs Offchain Data

Onchain (Reputation Registry contract):

value (int128) - REQUIRED - Feedback value (can be negative)
valueDecimals (uint8, 0-18) - REQUIRED - Decimal precision for value
tag1, tag2 (string) - OPTIONAL (direct strings, no encoding)
endpoint (string) - OPTIONAL, specifies the service endpoint
feedbackURI (string) - OPTIONAL
feedbackHash (bytes32) - OPTIONAL
feedbackIndex (uint64) - From event emission (no longer calculated)

v2.0 Note: The actual rating is calculated as value / 10^valueDecimals. For example:
value=5, valueDecimals=0 → Rating: 5 (5-star rating)
value=450, valueDecimals=2 → Rating: 4.50 (4.5 out of 5)
value=-100, valueDecimals=0 → Rating: -100 (negative feedback)

Onchain Events (for indexers):

NewFeedback: agentId (indexed), clientAddress (indexed), feedbackIndex, value, valueDecimals, indexedTag1 (indexed), tag1, tag2, endpoint, 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.
Important (v1.1.1 update): tag1 is now emitted twice in NewFeedback:
indexedTag1 (indexed): Topic-hashed for efficient filtering
tag1 (non-indexed): Actual string value for direct access
This allows both efficient filtering AND direct value retrieval without decoding.

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

jsonc

{
  // ============ MUST FIELDS (per official spec) ============
  "agentRegistry": "eip155:84532:0x8004C269D0A5647E51E121FeB226200ECE932d55",
  "agentId": 22,
  "clientAddress": "eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "createdAt": "2026-01-20T12:00:00Z",

  // v2.0: value + valueDecimals (replaces score)
  "value": "5",              // BigDecimal as string (can be negative)
  "valueDecimals": 0,        // Decimal precision (0-18)

  // ============ ALL OPTIONAL FIELDS (per official spec) ============
  "tag1": "defi",
  "tag2": "analytics",
  "endpoint": "https://api.agent.example.com/v1",

  // A2A / OASF fields
  "skill": "analytical_skills/data_analysis",  // as-defined-by-A2A-or-OASF
  "domain": "technology/blockchain",            // as-defined-by-OASF (NEW in v1.1)
  "context": "Analyzed blockchain transaction data for portfolio optimization",
  "task": "Generate daily analytics report with recommendations",

  // MCP fields
  "capability": "tools",  // prompts, resources, tools, or completions
  "name": "blockchain_analyzer",

  // x402 payment proof
  "proofOfPayment": {
    "fromAddress": "0x742d35Cc...",
    "toAddress": "0x8004...",
    "chainId": "84532",
    "txHash": "0xabc123..."
  },

  // ============ BEST PRACTICES EXTENSIONS (this profile) ============
  "reasoning": "Excellent portfolio analysis service.",
  "attachments": [
    {
      "name": "Service Receipt",
      "uri": "ipfs://QmXxx...",
      "mimeType": "application/pdf",
      "size": 50000
    }
  ],

  // Other custom fields
  " ... ": { " ... " }
}

NOTE

This schema follows the official EIP-8004 spec structure. Fields marked "MUST" are required by the spec; fields marked "OPTIONAL" are defined by the spec but not required. "Best Practices Extensions" are additional recommendations from this profile.

v2.0 Changes:

The score field has been replaced by value + valueDecimals
value is a BigDecimal string that can be negative
The feedbackAuth field was removed in v1.x (feedback is permissionless)

Recommended Fields

Field	Type	Constraints	Description
`agentRegistry`	string	CAIP-10 format	Agent's identity registry address
`agentId`	number	uint128, ≥ 0	Agent token ID
`clientAddress`	string	CAIP-10 format	Client's wallet address
`createdAt`	string	ISO 8601 UTC	Feedback creation timestamp
`value`	string	BigDecimal (int128)	Feedback value (can be negative, must match onchain)
`valueDecimals`	number	0–18 inclusive (uint8)	Decimal precision for value

CAIP Format References:

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

Recommended Optional Fields

Field	Type	Description
`reasoning`	string	Human-readable explanation of the feedback score
`tag1`	string	Primary category tag (direct string, not encoded)
`tag2`	string	Secondary category tag (direct string)
`endpoint`	string	Service endpoint used for interaction (NEW in v1.1)

Note: In v1.1, tag1 and tag2 are direct strings on-chain. No encoding/decoding needed. The endpoint field is optional but recommended for tracking which specific service endpoint was used.

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 / OASF Protocol Fields

For feedback on Agent-to-Agent (A2A) interactions or OASF taxonomy:

Field	Type	Example	Description
`skill`	string	`"analytical_skills/data_analysis"`	A2A or OASF skill taxonomy
`domain`	string	`"technology/blockchain"`	OASF domain taxonomy (NEW)
`context`	string	`"Analyzed blockchain data"`	Task context (A2A)
`task`	string	`"Generate analytics report"`	Specific task (A2A)

NOTE

v1.1 Change: The skill field now accepts both A2A and OASF skill slugs. The domain field was added for OASF domain taxonomy.

Taxonomy References:

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

{
  "value": "95",
  "valueDecimals": 0,
  // ... 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

NOTE

v1.1 Change: The field name changed from proof_of_payment (snake_case) to proofOfPayment (camelCase) in January 2026 for JSON naming consistency.

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

typescript

// Official EIP-8004 spec fields
interface ProofOfPayment {
  fromAddress: string; // Payer address (0x...)
  toAddress: string; // Payee address (0x...)
  chainId: string; // Chain ID as string (e.g., "1", "84532")
  txHash: string; // Transaction hash (0x...)

  // Best practices extensions (this profile)
  amount?: string; // Payment amount (wei/smallest unit)
  currency?: string; // Currency symbol (e.g., "ETH", "USDC")
  protocol?: string; // Payment protocol (e.g., "x402")
  timestamp?: string; // Payment timestamp (ISO 8601)
}

Example: ETH Payment

json

{
  "proofOfPayment": {
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "toAddress": "0x8004C269D0A5647E51E121FeB226200ECE932d55",
    "chainId": "84532",
    "txHash": "0xabc123..."
  }
}

Example: ETH Payment with Extensions

json

{
  "proofOfPayment": {
    "fromAddress": "0x742d35Cc...",
    "toAddress": "0x8004...",
    "chainId": "84532",
    "txHash": "0xabc123...",
    "amount": "100000000000000000",
    "currency": "ETH",
    "protocol": "x402"
  }
}

Example: SOL Payment (Solana)

json

{
  "proofOfPayment": {
    "fromAddress": "D9bMDMbJungXQrE8n6ZsM3r6ZQLFTzygmsQL7yzGMDHw",
    "toAddress": "2KmHw8VbShuz9xfj3ecEjBM5nPKR5BcYHRDSFfK1286t",
    "chainId": "501",
    "txSignature": "5piJm888s7beTTrB9JuCR5WFvNxXHN78C9ifGEokTucoQy5mb6bKg3e6Fkiv8RznZG2NmzENBWUru5yUGbqMiTMp",
    "amount": "1000000000",
    "currency": "SOL",
    "decimals": 9
  }
}

Note: Solana uses txSignature (base58, 87-88 chars) instead of txHash. Amount is in lamports (1 SOL = 10^9 lamports). See Solana Chain Support Extension for details.

Authorization (Deprecated in v1.1)

⚠️ DEPRECATED: The feedbackAuth field and pre-authorization flow have been removed in v1.1.
In pre-v1 (legacy), feedback required cryptographic authorization from agents. In v1.1, anyone can submit feedback directly without pre-approval. Spam/Sybil protection now relies on off-chain filtering and reputation scoring.

See migration guide if you're upgrading from pre-v1 (legacy).

Examples

Example 1: Simple Feedback (5-star rating)

json

{
  "agentRegistry": "eip155:84532:0x8004C269D0A5647E51E121FeB226200ECE932d55",
  "agentId": 22,
  "clientAddress": "eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "createdAt": "2026-01-20T12:00:00Z",
  "value": "5",
  "valueDecimals": 0,

  "reasoning": "Great DeFi analytics agent. Quick response time and accurate insights.",
  "tag1": "defi",
  "tag2": "analytics",
  "endpoint": "https://api.example.com/analytics/v1"
}

Example 2: Detailed A2A Feedback with Payment Proof

json

{
  "agentRegistry": "eip155:84532:0x8004C269D0A5647E51E121FeB226200ECE932d55",
  "agentId": 45,
  "clientAddress": "eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "createdAt": "2026-01-20T14:30:00Z",
  "value": "4.8",
  "valueDecimals": 1,

  "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 Q1 2026",
  "task": "Generate comprehensive market analysis report with predictions",

  "proofOfPayment": {
    "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": "2026-01-20T14:00:00Z"
    },
    {
      "name": "Raw Data",
      "uri": "ipfs://QmYyy...",
      "mimeType": "text/csv",
      "size": 500000,
      "description": "Historical price data used for analysis",
      "uploadedAt": "2026-01-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": "2026-01-20T16:00:00Z",
  "value": "4",
  "valueDecimals": 0,

  "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
  }
}

Example 4: Negative Feedback (v2.0 feature)

json

{
  "agentRegistry": "eip155:84532:0x8004C269D0A5647E51E121FeB226200ECE932d55",
  "agentId": 99,
  "clientAddress": "eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "createdAt": "2026-01-20T18:00:00Z",
  "value": "-2",
  "valueDecimals": 0,

  "reasoning": "Service was unresponsive for 48 hours. No deliverables provided despite payment.",
  "tag1": "unresponsive",
  "tag2": "dispute",

  "attachments": [
    {
      "name": "Payment Receipt",
      "uri": "ipfs://QmZzz...",
      "mimeType": "application/pdf",
      "size": 25000,
      "description": "Proof of payment with no corresponding service"
    }
  ]
}

v2.0 Feature: Negative value allows explicit negative feedback. This is useful for dispute resolution and fraud reporting.

Best Practices

1. Always Provide Reasoning

❌ Bad:

json

{
  "value": "4",
  "valueDecimals": 0
}

✅ Good:

json

{
  "value": "4",
  "valueDecimals": 0,
  "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

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

3. Use Protocol-Specific Fields

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

A2A / OASF Example:

json

{
  "value": "4.5",
  "valueDecimals": 1,
  "tag1": "defi",
  "tag2": "analytics",
  "skill": "analytical_skills/data_analysis/blockchain_analysis",
  "domain": "technology/blockchain",
  "context": "Analyzed blockchain transaction patterns for portfolio optimization"
}

MCP Example:

json

{
  "value": "4",
  "valueDecimals": 0,
  "tag1": "mcp",
  "tag2": "tools",
  "capability": "tools",
  "name": "blockchain_analyzer",
  "context": "Used MCP tools capability for blockchain data analysis"
}

4. Include Payment Proof for x402

For agents supporting x402 payment protocol:

json

{
  "value": "5",
  "valueDecimals": 0,
  "proofOfPayment": {
    "txHash": "0x...",
    "amount": "100000000000000000",
    "currency": "ETH"
  }
}

5. Use CAIP Formats for Addresses

❌ Bad:

json

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

✅ Good:

json

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

6. Include Endpoint Information

Always include the endpoint field to track which service endpoint was used:

❌ Missing context:

json

{
  "value": "4.5",
  "valueDecimals": 1,
  "tag1": "defi"
}

✅ Good - with endpoint:

json

{
  "value": "4.5",
  "valueDecimals": 1,
  "tag1": "defi",
  "endpoint": "https://api.agent.example.com/v1",
  "reasoning": "Used the v1 API endpoint. Fast response and accurate results."
}

This helps distinguish feedback for different versions or deployments of the same agent.

7. Use String Tags Directly

Tags are direct strings (since v1.x), not encoded bytes32:

❌ Old pre-v1 format (deprecated):

json

{
  "tag1": "6465666900000000000000000000000000000000000000000000000000000000",
  "tag2": "616e616c7974696373000000000000000000000000000000000000000000000000"
}

✅ v1.x/v2.0 format:

json

{
  "tag1": "defi",
  "tag2": "analytics"
}

8. Timestamp Everything

json

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

9. Complete v2.0 Best Practice Example

Here's a comprehensive example following all v2.0 best practices:

json

{
  // Core required fields
  "agentRegistry": "eip155:84532:0x8004C269D0A5647E51E121FeB226200ECE932d55",
  "agentId": 22,
  "clientAddress": "eip155:84532:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "createdAt": "2026-01-20T12:00:00Z",

  // v2.0: value + valueDecimals (replaces score)
  "value": "4.75",
  "valueDecimals": 2,

  // Tags and endpoint
  "tag1": "defi",
  "tag2": "analytics",
  "endpoint": "https://api.agent.example.com/v2",

  // Human context
  "reasoning": "Excellent DeFi analytics service. Used the v2 API which provided faster response times. The portfolio optimization recommendations were accurate and well-explained.",

  // Protocol-specific fields (OASF)
  "skill": "analytical_skills/data_analysis/blockchain_analysis",
  "domain": "finance_and_business/finance",
  "context": "Portfolio optimization for DeFi positions across multiple chains",

  // Payment proof (x402)
  "proofOfPayment": {
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "toAddress": "0x8004C269D0A5647E51E121FeB226200ECE932d55",
    "chainId": "84532",
    "txHash": "0xabc123...",
    "amount": "100000000000000000",
    "currency": "ETH",
    "timestamp": "2026-01-20T11:45:00Z"
  },

  // Evidence attachments
  "attachments": [
    {
      "name": "Analysis Report",
      "uri": "ipfs://QmXxx...",
      "mimeType": "application/pdf",
      "size": 250000,
      "description": "Full 50-page portfolio analysis with recommendations",
      "uploadedAt": "2026-01-20T11:50:00Z"
    },
    {
      "name": "Service Receipt",
      "uri": "ipfs://QmYyy...",
      "mimeType": "application/pdf",
      "size": 50000,
      "description": "Invoice and proof of deliverables",
      "uploadedAt": "2026-01-20T11:55:00Z"
    }
  ]
}

Why this example follows best practices:

✅ Uses value + valueDecimals (v2.0 format)
✅ Uses CAIP-10 format for addresses
✅ Includes endpoint to track API version used
✅ Uses direct string tags (not hex-encoded)
✅ Provides detailed reasoning
✅ Includes protocol-specific fields (skill, domain)
✅ Has payment proof with full details
✅ Includes evidence attachments
✅ All timestamps in ISO 8601 UTC format

FAQ

Q: How do I handle feedback revocation or deletion?

A: Use the FeedbackRevoked event to mark feedback as deleted (immutability-safe approach).

Event structure:

FeedbackRevoked(agentId indexed, clientAddress indexed, feedbackIndex indexed)

Indexer handling:

Track FeedbackRevoked events
Mark feedback as deleted (don't remove it)
Exclude revoked feedback from reputation calculations
Show revocation status in UI ("This feedback was revoked")

Off-chain data: Archive revoked feedback but don't delete URIs (preserves immutability)

Q: How do I efficiently index and search large feedback volumes?

A: Leverage the indexed event parameters for optimized queries.

NewFeedback event indexed parameters (v2.0):

agentId (indexed) - Query by agent
clientAddress (indexed) - Query by reviewer
indexedTag1 (indexed) - Filter by tag efficiently (topic hash)

Non-indexed parameters:

feedbackIndex - Sequential ordering
value, valueDecimals - Feedback rating
tag1, tag2 - Actual tag values
endpoint, feedbackURI, feedbackHash

Optimization strategies:

Use indexed parameters for efficient filtering by agent, client, or tag
Aggregate in time windows: Cache averages per (agentId, tag) per time period
Use feedbackIndex for pagination: Sequential ordering allows efficient range queries
Separate hot/cold data: Recent feedback in fast index, historical in archive

Q: What's the relationship between value and valueDecimals?

A: The actual rating is calculated as value / 10^valueDecimals.

Examples:

value	valueDecimals	Actual Rating	Use Case
5	0	5	5-star rating
45	1	4.5	4.5 out of 5
475	2	4.75	High precision
-2	0	-2	Negative feedback
100	0	100	Percentage (100%)

Recommended scales:

5-star: valueDecimals=0, value in range [-5, 5]
10-point: valueDecimals=0, value in range [0, 10]
Percentage: valueDecimals=0, value in range [0, 100]
Decimal precision: valueDecimals=1-2 for 4.5, 4.75 style ratings

Q: What metric types can I use with tag1?

A: The tag1 field combined with value/valueDecimals supports various metric types beyond simple ratings:

tag1 (Metric)	Description	Example value	valueDecimals	Actual Value
`reachable`	Is endpoint reachable?	1	0	1 (binary: 0 or 1)
`ownerVerified`	Endpoint ownership proof	1	0	1 (binary: 0 or 1)
`starred`	Quality rating	85	0	85 (0-100 scale)
`uptime`	Endpoint uptime %	9977	2	99.77%
`responseTime`	Response time in ms	560	0	560 ms
`successRate`	Request success rate %	9950	2	99.50%
`blocktimeFreshness`	Block delay (# of blocks)	4	0	4 blocks
`correctness`	Response correctness	1	0	1 (binary: 0 or 1)
`revenues`	Cumulative revenues ($)	1100	0	$1100

Key insight: Since Solidity doesn't support floating-point numbers, valueDecimals lets you represent decimals as integers:

"30" → value=30, valueDecimals=0 → Actual: 30
"30.73" → value=3073, valueDecimals=2 → Actual: 30.73
"99.77%" → value=9977, valueDecimals=2 → Actual: 99.77

Feedback Data Profile

Description ​

Document Purpose ​

Relationship to EIP-8004 ​

Key Changes in v2.0 (January 2026) ​

Key Changes in v1.x (vs pre-v1) ​

Terminology ​

Intended Audience ​

Table of Contents ​

Overview ​

Onchain vs Offchain Data ​

Recommended Feedback Profile ​

Suggested Schema ​

Recommended Fields ​

Recommended Optional Fields ​

Attachment Pattern ​

Overview ​

Quick Reference ​

Common Use Cases ​

4. Screenshots/Evidence ​

Supported File Types ​

Protocol-Specific Fields ​

A2A / OASF Protocol Fields ​

MCP Protocol Fields ​

Custom Extensions ​

Payment Proof Integration ​

x402 Protocol Support ​

Example: ETH Payment ​

Example: ETH Payment with Extensions ​

Example: SOL Payment (Solana) ​

Authorization (Deprecated in v1.1) ​

Examples ​

Example 1: Simple Feedback (5-star rating) ​

Example 2: Detailed A2A Feedback with Payment Proof ​

Example 3: MCP Tool Feedback ​

Example 4: Negative Feedback (v2.0 feature) ​

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. Include Endpoint Information ​

7. Use String Tags Directly ​

8. Timestamp Everything ​

9. Complete v2.0 Best Practice Example ​

FAQ ​

Q: How do I handle feedback revocation or deletion? ​

Q: How do I efficiently index and search large feedback volumes? ​

Q: What's the relationship between value and valueDecimals? ​

Q: What metric types can I use with tag1? ​

See Also ​

Description

Document Purpose

Relationship to EIP-8004

Key Changes in v2.0 (January 2026)

Key Changes in v1.x (vs pre-v1)

Terminology

Intended Audience

Table of Contents

Overview

Onchain vs Offchain Data

Recommended Feedback Profile

Suggested Schema

Recommended Fields

Recommended Optional Fields

Attachment Pattern

Overview

Quick Reference

Common Use Cases

4. Screenshots/Evidence

Supported File Types

Protocol-Specific Fields

A2A / OASF Protocol Fields

MCP Protocol Fields

Custom Extensions

Payment Proof Integration

x402 Protocol Support

Example: ETH Payment

Example: ETH Payment with Extensions

Example: SOL Payment (Solana)

Authorization (Deprecated in v1.1)

Examples

Example 1: Simple Feedback (5-star rating)

Example 2: Detailed A2A Feedback with Payment Proof

Example 3: MCP Tool Feedback

Example 4: Negative Feedback (v2.0 feature)

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. Include Endpoint Information

7. Use String Tags Directly

8. Timestamp Everything

9. Complete v2.0 Best Practice Example

FAQ

Q: How do I handle feedback revocation or deletion?

Q: How do I efficiently index and search large feedback volumes?

Q: What's the relationship between value and valueDecimals?

Q: What metric types can I use with tag1?

See Also