Migration Guide: v1.x → v2.0

This guide helps implementers upgrade from ERC-8004 v1.x to v2.0 feedback specification.

Overview of Changes

Breaking Change: score → value + valueDecimals

The primary change in v2.0 is replacing the fixed score field with flexible value + valueDecimals fields.

Aspect	v1.x	v2.0
Field name	score	value + valueDecimals
Type	uint8 (0-100)	int128 + uint8 (0-18)
Range	0-100 only	Unlimited (int128)
Negative values	Not supported	Supported
Decimal precision	Integer only	Up to 18 decimals

Why This Change?

The v1.x score field was limited:

• Fixed 0-100 range made many metric types impossible (uptime %, response time, revenues)
• No support for negative feedback (disputes, fraud reports)
• No decimal precision for granular ratings (99.77% uptime)

v2.0 value + valueDecimals provides:

• Arbitrary metrics: uptime (%), response time (ms), revenues ($), block freshness, etc.
• Decimal precision: 99.77% → value=9977, valueDecimals=2
• Large values: 1100ms response time → value=1100, valueDecimals=0
• Negative feedback: Disputes, fraud reports
• Flexible rating scales: 5-star, 10-point, percentage, custom

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

• "30" → value=30, valueDecimals=0
• "30.73" → value=3073, valueDecimals=2

Schema Changes

v1.x Schema (Before)

{
  "agentRegistry": "eip155:84532:0x8004...",
  "agentId": 22,
  "clientAddress": "eip155:84532:0x742d...",
  "createdAt": "2026-01-01T12:00:00Z",
  "score": 95,
  "tag1": "defi",
  "tag2": "analytics",
  "endpoint": "https://api.example.com/v1"
}

v2.0 Schema (After)

{
  "agentRegistry": "eip155:84532:0x8004...",
  "agentId": 22,
  "clientAddress": "eip155:84532:0x742d...",
  "createdAt": "2026-01-01T12:00:00Z",
  "value": "4.75",
  "valueDecimals": 2,
  "tag1": "defi",
  "tag2": "analytics",
  "endpoint": "https://api.example.com/v1"
}

Migration Steps

Step 1: Update Contract Calls

v1.x contract call:

submitFeedback(agentId, score, tag1, tag2, endpoint, feedbackURI, feedbackHash)

v2.0 contract call:

submitFeedback(agentId, value, valueDecimals, tag1, tag2, endpoint, feedbackURI, feedbackHash)

Step 2: Convert Score to Value

When migrating existing v1.x feedback data:

v1.x score	v2.0 value	v2.0 valueDecimals	Rating
100	5	0	5 stars
80	4	0	4 stars
60	3	0	3 stars
40	2	0	2 stars
20	1	0	1 star
0	0	0	0 stars

Conversion formula (0-100 to 5-star):

value = score / 20;
valueDecimals = 0;

Or keep percentage scale:

value = score;
valueDecimals = 0;

Step 3: Update Event Listeners

v1.x event:

NewFeedback(agentId, clientAddress, feedbackIndex, score, indexedTag1, tag1, tag2, endpoint, feedbackURI, feedbackHash)

v2.0 event:

NewFeedback(agentId, clientAddress, feedbackIndex, value, valueDecimals, indexedTag1, tag1, tag2, endpoint, feedbackURI, feedbackHash)

Step 4: Update Off-chain Data

Update your JSON schema to use value and valueDecimals instead of score:

{
  "value": "4.5",
  "valueDecimals": 1
  // ... other fields unchanged
}

Backward Compatibility

Reading Historical Data

Indexers should support both formats during transition:

1. Check if value field exists → Use v2.0 format
2. Check if score field exists → Use v1.x format (legacy)
3. Convert v1.x data to v2.0 representation for unified API

Recommended Normalization

For displaying v1.x data in v2.0 format:

v1.x score	Normalized value	valueDecimals
0-100	score	0

For displaying v2.0 data as percentage (for legacy UIs):

v2.0 value	valueDecimals	Normalized percentage
5	0	100% (5-star)
4	0	80% (4-star)
4.5	1	90% (4.5-star)
-2	0	0% (negative)

Common Rating Scales

5-Star Rating

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

Possible values: -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5

10-Point Rating

{
  "value": "8.5",
  "valueDecimals": 1
}

Possible values: 0.0 to 10.0 (or negative for disputes)

Percentage Rating

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

Possible values: 0 to 100 (like v1.x, but can now be negative)

Binary Thumbs Up/Down

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

Possible values: -1 (thumbs down), 0 (neutral), 1 (thumbs up)

Common Metric Types (tag1)

v2.0 enables many metric types that were impossible with v1.x's 0-100 score:

tag1 (Metric)	Description	Example value	valueDecimals	Actual Value
reachable	Is endpoint reachable?	1	0	1 (binary)
ownerVerified	Endpoint ownership proof	1	0	1 (binary)
starred	Quality rating	85	0	85 (0-100)
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)
revenues	Cumulative revenues ($)	1100	0	$1100

Checklist

• [ ] Update contract ABI for v2.0 submitFeedback function
• [ ] Update event listeners for v2.0 NewFeedback event
• [ ] Update off-chain JSON schema to use value + valueDecimals
• [ ] Add backward compatibility for reading v1.x data
• [ ] Update UI to handle flexible rating scales
• [ ] Consider supporting negative feedback in UI
• [ ] Update documentation and API references

See Also

• Feedback Data Profile v2.0 - Complete v2.0 specification
• v1.x Feedback Standard - Previous version reference
• Migration Guide (pre-v1 → v1.x) - Earlier migration guide