Value Decimals Patterns (ERC-8004 Extension)

Status: Draft
Created: 2026-01-30

Introduction

The transition from a fixed 0-100 score to a flexible value (int128) and valueDecimals (uint8) system in ERC-8004 v2.0 opens up a wide range of use cases for agent feedback. This document outlines standard patterns and best practices for utilizing this system effectively to capture diverse metrics like uptime, financial yield, latency, and binary verifications.

Core Concept

The feedback system uses a fixed-point arithmetic model similar to ERC-20 tokens:

• value (int128): The raw integer value stored on-chain.
• valueDecimals (uint8): The number of decimal places to interpret the value.
• tag1 (string): The identifier that defines what is being measured.

To get the "real world" number:
$$ \text{Real Value} = \frac{\text{value}}{10^{\text{valueDecimals}}} $$

Standard Patterns

To ensure composability across the ecosystem, agents and clients SHOULD adhere to these standard patterns for common metrics.

1. Percentages and Probability

For metrics representing a fraction of 100 or a probability.

• Recommended tag1: uptime, successRate, confidence
• Recommended valueDecimals: 2 (allows for 99.99%) or 4 (allows for 99.9999%)
• Example: 99.77% Uptime
  • value: 9977
  • valueDecimals: 2
  • Calculation: $9977 / 10^2 = 99.77$

2. Binary Status / Flags

For boolean states (True/False).

• Recommended tag1: reachable, ownerVerified, kycCleared
• Recommended valueDecimals: 0
• Values: 1 for True, 0 for False.
• Example: Endpoint is reachable
  • value: 1
  • valueDecimals: 0

3. Financial Metrics

For revenues, costs, or yields.

• Recommended tag1: revenues, dailyCost, tradingYield
• Recommended valueDecimals:
  • 0 or 2 for fiat-pegged values (e.g., USD cents).
  • 6 or 18 for crypto-native values (USDC, ETH).
• Example: $560.00 Revenue
  • value: 560
  • valueDecimals: 0 (if representing whole dollars) or 56000 / 2 (cents)
• Example: -3.2% Yield
  • value: -32
  • valueDecimals: 1

4. Time and Latency

For duration measurements.

• Recommended tag1: responseTime, processingTime, blockDelay
• Recommended valueDecimals: 0
• Unit Convention:
  • Milliseconds (ms) for responseTime
  • Seconds (s) for processingTime
  • Blocks for blockDelay
• Example: 560ms Response Time
  • value: 560
  • valueDecimals: 0

5. Ratings and Scores

For subjective or objective ratings on a specific scale.

• Recommended tag1: quality, accuracy, starred
• Recommended valueDecimals: 1 (allows for 4.5 stars)
• Example: 4.5/5 Stars
  • value: 45
  • valueDecimals: 1

Domain-Specific Patterns

Beyond general metrics, specific industries can standardize on the following patterns to ensure interoperability among specialized agents.

6. AI & LLM Agents

Metrics specific to Large Language Model performance and costs.

• Throughput (Tokens per Second)
  • tag1: tps
  • valueDecimals: 1
  • Example: 45.5 tok/s → value: 455, decimals: 1
• Cost Efficiency (e.g., Cost per 1M tokens)
  • tag1: costPer1M
  • valueDecimals: 6 (Micro-USD or Gwei)
  • Example: $0.50 → value: 500000, decimals: 6

7. DeFi & Trading Agents

Risk and return metrics for autonomous financial agents.

• Sharpe Ratio (Risk-adjusted return)
  • tag1: sharpeRatio
  • valueDecimals: 2
  • Example: Ratio of 2.55 → value: 255, decimals: 2
• Max Drawdown (Risk metric)
  • tag1: maxDrawdown
  • valueDecimals: 2
  • Example: -15.40% → value: -1540, decimals: 2 (Note the negative sign)

8. DePIN & Physical Infrastructure

For agents managing hardware, sensors, or location-based services.

• Geospatial Coordinates (GPS)
  • tag1: latitude / longitude
  • valueDecimals: 6 (Standard GPS precision)
  • Example: NYC Lat 40.712800 → value: 40712800, decimals: 6
• Signal Strength (RSSI/dBm)
  • tag1: signalStrength
  • valueDecimals: 0
  • Example: -75 dBm → value: -75, decimals: 0
• Network Bandwidth
  • tag1: uploadSpeed / downloadSpeed
  • valueDecimals: 1 (Mbps)
  • Example: 100.5 Mbps → value: 1005, decimals: 1

Comprehensive Reference Table

Metric Category	tag1 (Convention)	value Example	valueDecimals	Human Readable	Notes
Boolean	reachable	1	0	True	1=True, 0=False
	ownerVerified	1	0	True
Quality	starred	87	0	87/100	Classic 0-100 score
	f1Score	945	3	0.945
Performance	uptime	9999	2	99.99%
	successRate	985	1	98.5%
Latency	responseTime	250	0	250ms	Default unit: ms
	blocktimeFreshness	2	0	2 blocks	Default unit: blocks
Financial	revenues	150050	2	1500.50	Currency usually implied by context or tag2
	tradingYield	-155	2	-1.55%	Negative values supported
AI / LLM	tps	505	1	50.5 tok/s
DeFi Risk	sharpeRatio	210	2	2.10
	maxDrawdown	-1250	2	-12.50%
DePIN/Geo	latitude	40712800	6	40.712800	Standard GPS precision
	signalStrength	-75	0	-75 dBm
Hardware	gpuMemory	24	0	24 GB	Context needed

Best Practices

1. Tag Consistency: Always use camelCase for tag1.
2. Explicit Units: If the unit isn't obvious (like revenues), consider using tag2 to specify it (e.g., tag1="revenues", tag2="USD").
3. Negative Values: Utilize the signed nature of int128 for metrics like loss, drift, or deviations.
4. Handling Overflow: int128 is large ($10^{38}$), but extremely high precision decimals (e.g., 18) combined with large values can still overflow in off-chain calculations if not handled with BigInt libraries.
5. Aggregation: When aggregating metrics (e.g., calculating average response time), ensure you only aggregate feedback with the exact same tag1 AND valueDecimals to avoid magnitude errors. If decimals differ, normalize them first.

Migration from Score (v1.x)

If your system relies on the legacy score (0-100):

• Treat score as tag1="quality" (or empty tag), value=score, valueDecimals=0.
• 100 becomes value=100, valueDecimals=0.