Oracles, Automation and Randomness
Introduction
Protocols often need facts or actions that deterministic execution cannot originate alone. This branch makes the data publisher, aggregation, freshness, normalization, liveness, callback, and randomness assumptions explicit.
Why It Matters
A correct price read can still be stale, on the wrong decimal scale, unavailable during sequencer downtime, manipulable within its window, or correlated with a supposedly independent fallback. Automation and randomness add their own liveness and callback failures.
Mental Model
An adapter converts an external assertion into a narrowly validated protocol input. It should authenticate source/context, normalize once, check time and bounds, handle domain availability, and fail according to a documented safety/liveness policy.
Questions This Branch Answers
- When should bad or missing data pause, degrade, or use a fallback?
- What manipulation cost does a price window actually create?
- How do keeper and randomness callbacks fail without corrupting state?
Scope
Push/pull feeds, aggregation, heartbeat/staleness/decimals, deviation/circuit breakers, TWAPs, L2 sequencer feeds, automation, failure injection, VRF-style flows, and commit-reveal.
Out of Scope
Price predictions, guaranteed liveness, hidden randomness, production keeper fleets, and treating a reputable provider as a complete protocol threat model.
Dependencies
time/finality, market manipulation, and callback-safe state machines.
Candidate Note Roadmap
oracle-problem-and-trust-models— Classify data origin, reporters, aggregation, update, and consumer trust.push-pull-feeds-and-medianization— Compare update paths and bounded reporter aggregation.heartbeats-staleness-and-normalization— Enforce freshness and decimal/unit contracts.deviation-bounds-and-circuit-breakers— Define fail-closed, pause, fallback, and recovery policies.twap-and-manipulation-cost— Measure windowed prices and adversarial capital/time assumptions.sequencer-uptime-and-l2-oracles— Gate L2 consumption around sequencer outage and grace periods.keepers-automation-and-failure-injection— Build idempotent jobs and exercise missed/duplicate callbacks.verifiable-randomness-and-commit-reveal— Prevent outcome selection after commitments are known.
Future Project
An Oracle Adapter and fallback router, local automation service, and Verifiable Random Raffle with injected stale feeds, sequencer downtime, missed jobs, duplicate callbacks, and unavailable randomness.
Initial Invariants
Invalid/stale prices never reach protected transitions; units normalize exactly once; fallback rules cannot silently widen acceptable error; jobs and callbacks are idempotent; outcomes cannot be chosen after participant commitments.
Initial Threat Model
Reporter/provider compromise, staleness, decimals/sign errors, correlated fallbacks, flash/TWAP manipulation, sequencer downtime, keeper censorship, duplicate or failed callbacks, block-variable bias, and subscription exhaustion.
Primary Sources
Chainlink and protocol documentation, Uniswap oracle specifications, randomness designs, and maintained references in SOURCES.md.
Connects to: lending, AMMs, and monitoring.