سجلات القرارات · ADR-015
ADR-015: Oracle rounds keyed by round number, not wall clock
Commodity prices are agreed in numbered rounds per commodity, finalized at quorum with the median, so results do not depend on when submissions fall relative to a time bucket.
- معرّف المستند
- ADR-015
- التاريخ
- 2026-09-21
- المصدر
- docs/adr/ADR-015.md
| Field | Value |
|---|---|
| ID | ADR-015 |
| Subject area | Data integration |
| Status | Accepted |
| Date | 2026-09-21 |
| Owners | A-REX Contributors |
| Related requirements | FR-13, NFR-05 (SDD §3) |
| Supersedes / superseded by | — |
Context
The earlier oracle module grouped submissions by block.timestamp / 300. The same set of submissions produced different rounds depending on when they landed relative to the five-minute edges, and its tests failed intermittently for that reason.
Issue
How should a small set of reporters agree on a commodity price deterministically?
Assumptions
- Reporters are a small, known set.
- Consumers decide how old a price may be.
Constraints
- Deterministic, testable behaviour (NFR-05).
Alternatives considered
| Alternative | For | Against | Outcome |
|---|---|---|---|
| Time buckets | Implicit rounds | Non-deterministic results and tests | Rejected |
| Monotonic round ids per commodity; finalize at quorum; manual finalize at a minimum; median | Deterministic; manipulation needs a majority | Staleness is checked by the caller | Accepted |
Decision
CommodityPriceOracle numbers rounds per commodity, finalizes automatically when quorum reporters have submitted and manually once minSubmissions is reached, and publishes the median. Weather, quality and IoT data are attestations or metadata, not oracle rounds.
Argument
Numbering rounds removes time from the consensus rule; the median tolerates a minority of bad reports.
Consequences
Positive
- Deterministic results and tests.
- Clear separation between prices and evidence.
Negative
- Callers must check staleness with
isStale(commodity, maxAge).
Obligations it creates
- Consumers set a maximum age appropriate to their use.
Implementation and evidence
| What | Where |
|---|---|
| Contract | contracts/reference/extensions/CommodityPriceOracle.sol |
| Test | test/standard/Extensions.test.js: finalizes rounds by quorum with the median, independent of wall-clock buckets |