Documenting the oracle architecture
Five details an oracle review has to record — and the one that decides when it matters.
This lesson has had no expert review. It was written for this platform and against the evidence it cites; nobody has gone through it independently.
Learning objectives
- You can distinguish heartbeat updates from deviation updates.
- You can check who may trigger a fallback mechanism.
Check your prior knowledge
Answer these for yourself before reading on. Wherever you hesitate is where this lesson pays off.
- How often must a price update to stay usable?
- What happens if the source fails?
- Who decides to switch to a replacement source?
Core concept
Two triggers for an update
A price is written either after a period elapses or when it deviates from the last value by more than a set percentage — usually both at once, with different values. The period sets how old a price can be in a calm market; the deviation threshold sets how finely a move is passed through. Both numbers need to be documented, not merely the oracle's existence.
A fallback is also a right to intervene
When a source fails, at best a second mechanism takes over. Whoever may trigger it is thereby entitled to change a live market's price source. A fallback a single address can activate is therefore also a governance risk — and belongs in both sections of the analysis, not only the one about oracles.
Several sources are not automatically more robust
A network of several reporters protects against one of them failing. It does not protect when all reporters take their prices from the same venues — they then share a common cause, and the redundancy exists only in delivery. The relevant question is therefore not “how many reporters” but “how many independent price sources behind them”.
Definitions
- Heartbeat
- The maximum time after which a price is rewritten regardless of movement.
- Deviation threshold
- The price change from which a price is rewritten early.
- Fallback mechanism
- A replacement procedure taking over when the primary source fails.
Model
Heartbeat
Deviation threshold
Number of reporters
Number of independent price sources behind them
Fallback: which one, triggered by whom, with what delay
Formulas
Maximum price age in a calm market
Age ≤ heartbeat, unless the deviation threshold triggers first- heartbeat
- time until a forced rewrite
- deviation threshold
- price change that writes early
Limit: Describes normal operation. On a congested network the write itself can be delayed — the actual age is then higher than the documented period.
Worked example
Two oracles, the same description
- Description
- “decentralized oracle network with fallback”
- Oracle X
- heartbeat 1 h, deviation 0.5 %, 21 reporters, 7 independent sources
- Oracle Y
- heartbeat 24 h, deviation 2 %, 9 reporters, 2 independent sources
- Fallback triggerable by
- X: governance with timelock; Y: one address, immediately
With Y a price can be up to 24 hours old in a calm market, a move below 2 % is not passed through at all, and a single address can switch the source.
The same description, four markedly different numbers — and a right to intervene in Y that X does not have.
Reading: An analysis noting “decentralized oracle with fallback” has treated both cases alike. The five details separate them in minutes.
Retrieval
Exercise on real data
Record that a shared oracle provider appears at this level — and that the five details above determine how strongly that shared dependency acts.
Dimension 10: dependencies →Application
You are documenting a lending market's oracle architecture. Which line do you write when the fallback authority cannot be established?
Related case studies
Institutional reading
- Bank
- Is the maximum price age compatible with the institution's own valuation frequency?
- Insurance
- Would a source switch via fallback be an insured event, or an exclusion?
Metrics in this lesson
Key takeaways
- Heartbeat and deviation threshold are two numbers, not one property.
- Reporter count protects against delivery failures, not against a common source.
- Whoever may trigger the fallback holds a right to intervene in live positions.
Evidence
- EVD-2026-0004
Annual Review of Financial Economics — Smart Contracts and Decentralized Finance