Crate evm_oracle_state

Expand description

A real-time oracle state engine built on a forked-EVM state cache (evm_fork_cache).

evm-oracle-state is the oracle domain crate layered over evm_fork_cache: the companion crate owns generic cache invalidation, reactive batching, and reorg reporting, while this crate owns oracle-specific metadata, event decoding, typed snapshots, staleness policy, reconciliation, and feed lookup. Chainlink-compatible feeds are registered through their proxy addresses; adapter-owned oracle families (Aave, Morpho, Euler, Pyth, RedStone) plug into the same typed state, hook, and overlay surfaces behind feature flags.

The central contract:

Events are fast-path hints; proxy reads are authoritative.

Oracle log events update typed state immediately, so simulations can observe a new answer with no RPC on the hot path; authoritative proxy reads confirm, correct, or repair that state afterwards:

oracle log event (AnswerUpdated / OCR1+OCR2 NewTransmission / adapter event)
  -> reactive handler decodes it; an OraclePriceUpdate hook fires immediately
  -> OracleTracker stores an EventPending typed snapshot
  -> OracleReadOverlay serves registered oracle view calls from typed state
  -> OracleReconciler reads the proxy latestRoundData()
  -> the snapshot becomes Confirmed or Corrected (or Stale / RequiresRepair)

§Main types

The internal modules are private; everything below is re-exported at the crate root:

OracleRuntime — the high-level runtime, built from a provider (OracleRuntime::builder) or an existing cache (OracleRuntime::cache_builder): ChainlinkFeed registrations, typed event callbacks, storage/code warmup, and the reactive install / refresh / uninstall lifecycle.
OracleAdapter — the cache-native registration path over an evm_fork_cache::cache::EvmCache: Feed builders, Multicall3-batched discovery reads, and skip-aware build reports.
OracleTracker — the typed state store: OracleSnapshot lookup with freshness classification, OraclePriceUpdate hook payloads, and reconciliation through OracleReconciler.
OracleRegistry — feed registrations (FeedRegistration, FeedId), aggregator and dependency bookkeeping, and feed-readiness reporting.
OracleReactiveHandler — dependency-aware log routing bridged into the evm_fork_cache reactive runtime; detected OCR1/OCR2 layouts get exact direct storage writes, everything else takes the conservative purge/refetch fallback.
OracleReadOverlay — serves registered oracle view calls (latestRoundData(), adapter reads such as Morpho price(), Euler getQuote(...), Pyth getPriceUnsafe(...)) from typed state, so simulations see event prices before a follow-up RPC read completes.
PricePolicy / CheckedPrice — the typed price vocabulary (AssetId, Denomination, TokenAmount): promote raw oracle answers into policy-vetted values before liquidation or valuation decisions.
OracleAdapterPlugin — the extension seam for oracle families that are not plain Chainlink proxies: adapter-owned discovery plus an adapter-owned reactive handler over the same runtime.
Feature-gated adapters — AaveV3OracleAdapter (aave), MorphoBlueOracleAdapter (morpho), EulerOracleAdapter (euler), PythOracleAdapter (pyth), and RedstoneOracleAdapter (redstone).

See the crate’s examples/local_oracle_lifecycle.rs for the compile-checked quickstart: a deterministic, RPC-free walk through register → synthetic event → hook → overlay read → reconciliation.

Re-exports§

pub use alloy_primitives;
pub use evm_fork_cache;

Structs§

AaveAssetaave: Declarative Aave V3 asset source registration.
AaveV3OracleAdapteraave: Cache-backed Aave V3 oracle source discovery adapter.
AggregatorChange: Aggregator routing change found during reconciliation.
AggregatorLayoutEvidence: Evidence collected while identifying an aggregator implementation.
AnswerUpdated: Decoded Chainlink AnswerUpdated event.
AssetId: Stable typed asset identifier used for oracle bases and token amounts.
ChainlinkFeed: Builder-friendly Chainlink feed registration.
ChainlinkOcr1StorageAdapter: Verified direct-storage adapter for Chainlink OCR1 aggregators.
ChainlinkOcr2StorageAdapter: Verified direct-storage adapter for Chainlink OCR2 aggregators.
CheckedPrice: Oracle price that has satisfied a caller-selected policy.
DerivedReconcileFailure: One derived-source protocol read that failed during a OracleTracker::reconcile_derived_pending_with pass.
DerivedReconcileReport: Summary of one OracleTracker::reconcile_derived_pending_with pass.
EulerOracleAdaptereuler: Cache-backed Euler price oracle discovery adapter.
EulerQuotePaireuler: Declarative Euler quote-pair registration.
EvmCacheChainlinkReader: Chainlink view reader backed by an evm-fork-cache fork cache.
Feed: Typed feed registration primitive.
FeedAccess: Read-only accessors for finalized typed feed registrations.
FeedBuilderState: Marker for builder-stage typed feed registrations.
FeedConfig: Feed registration configuration.
FeedId: Stable id for a registered feed.
FeedMetadata: Static metadata read from a Chainlink-compatible proxy.
FeedReady: Marker for finalized typed feed registrations.
FeedRegistration: Registered Chainlink-compatible proxy feed.
MorphoBlueMarketmorpho: Declarative Morpho Blue market oracle registration.
MorphoBlueOracleAdaptermorpho: Cache-backed Morpho Blue oracle discovery adapter.
MorphoChainlinkFeed: One optional Chainlink feed used by MorphoChainlinkOracleV2.
MorphoMarketParamsmorpho: Morpho Blue market parameters.
NewRound: Decoded Chainlink NewRound event.
Ocr1NewTransmission: Decoded Chainlink OCR1 NewTransmission event.
Ocr1TransmissionStorageUpdate: OCR1 transmission data that can be translated into exact aggregator storage writes.
Ocr2NewTransmission: Decoded Chainlink OCR2 NewTransmission event.
Ocr2TransmissionStorageUpdate: OCR2 transmission data that can be translated into exact aggregator storage writes.
OracleAdapter: Cache-native oracle adapter entry point.
OracleAdapterBuildReport: Best-effort cache-native oracle registration report.
OracleAdapterBuilder: Builder for cache-backed oracle tracker registration.
OracleAdapterFeedSkip: Feed skipped during best-effort cache-native registration.
OracleAdapterId: Stable identifier for an oracle adapter family.
OracleBatchReport: Typed digest of one committed reactive batch.
OracleBlockRef: Block identity for hash-pinned oracle reconciliation reads.
OracleCacheRuntimeBuildReport: Best-effort cache-native oracle runtime build report.
OracleCacheRuntimeBuilder: Cache-native runtime builder with first-class oracle adapter plugins.
OracleChangeImpact: Downstream consequences of a feed change, mirroring evm-amm-state’s AmmChangeImpact { state, quoteability, topology }.
OracleCodeInstall: One successfully installed bytecode entry.
OracleCodeInstallError: Code install failure for one entry.
OracleCodeMismatch: Code-hash mismatch for a canonical seed.
OracleCodePolicyViolation: Summary of the code warmup report entries that violated an enforced OracleCodeWarmupPolicy, carried by OracleError::CodePolicy.
OracleCodeRegistry: Registry of oracle bytecode claims to install before discovery or simulation.
OracleCodeSeed: One bytecode install request for an oracle-related contract.
OracleCodeUnverifiable: Canonical code claim that could not be verified due to transport or provider limitations.
OracleCodeWarmupPolicy: Failure policy for oracle bytecode warmup.
OracleCodeWarmupReport: Report for code seeding, verification, and explicit etching.
OracleColdStartWarmupReport: Summary of an oracle cold-start storage warmup run.
OracleDependency: One Chainlink-compatible dependency used by a derived oracle source.
OracleDiscoveredFeed: One feed discovered and seeded by an oracle adapter plugin.
OracleDiscoveryContext: Cache-native discovery context passed to oracle adapter plugins.
OracleDiscoveryReport: Result of adapter discovery.
OracleFeedChange: One digested per-feed change inside an OracleBatchReport.
OracleFeedReadinessReport: Feed/runtime readiness surfaced by registry, warmup, build, repair, and health reports.
OracleFeedSkip: Complete description of one adapter feed skip, carried by OracleError::FeedSkipped when a fail-fast build surfaces a skip as an error. Use the build_report methods to receive skips as data instead.
OracleMockReport: Result of applying an overlay-scoped oracle mock.
OraclePrice: Consumer-facing typed oracle price.
OraclePriceConfirmed: Hook emitted when an event price is confirmed by the proxy.
OraclePriceCorrected: Hook emitted when a proxy read corrects an event price.
OraclePriceMock: A requested oracle price mock.
OraclePriceStale: Hook emitted when the proxy read is stale under policy.
OraclePriceUpdate: Rich event-derived oracle price update emitted by the reactive handler.
OracleReactiveHandler: Reactive-runtime bridge for Chainlink-compatible oracle feeds.
OracleReactiveInstallReport: Result of registering oracle handlers with a reactive engine.
OracleReactiveRefreshReport: Result of refreshing oracle handlers after runtime mutation.
OracleReactiveUninstallReport: Result of unregistering oracle handlers from a reactive engine.
OracleReadOverlay: Simulation-facing ABI call overlay backed by typed oracle state.
OracleReconciler: Reconciles event-derived oracle state against authoritative proxy reads.
OracleReconciliationRequest: Event-specific reconciliation request queued after an event update.
OracleReconciliationResult: One completed event reconciliation.
OracleRegistry: Registry plus latest proxy-read snapshots.
OracleRuntime: High-level facade for registration, typed events, reads, and reconciliation.
OracleRuntimeBuilder: Builder for a high-level oracle runtime facade.
OracleRuntimeMutationReport: Result of mutating a runtime’s oracle registration set.
OracleSnapshot: Typed current oracle state for one registered proxy feed.
OracleSourceDescriptor: Open descriptor for an adapter-owned oracle source.
OracleStorageSync: Ordered collection of oracle storage adapters.
OracleStorageWarmupFailure: One failed oracle storage warmup slot.
OracleStorageWarmupReport: Result of prewarming oracle storage slots through evm-fork-cache.
OracleTracker: Mutable typed oracle state.
OracleUpdate: Event-derived oracle update carried in reactive hook payloads.
PricePolicy: Policy for promoting raw oracle prices into checked prices.
PythFeedpyth: Builder-style Pyth EVM feed registration config.
PythOracleAdapterpyth: Pyth EVM oracle adapter plugin.
PythPriceFeedUpdatepyth: Decoded Pyth PriceFeedUpdate event.
PythReactiveHandlerpyth: Reactive handler for Pyth EVM PriceFeedUpdate logs.
ReconcileReport: Reconciliation summary.
RedstoneFeedredstone: Declarative RedStone push-feed registration.
RedstoneMultiFeedStorageAdapterredstone: Storage helpers for RedStone MultiFeedAdapterWithoutRounds push feeds.
RedstoneOracleAdapterredstone: Cache-backed RedStone push oracle discovery adapter.
RedstonePriceFeedsStorageAdapterredstone: Storage helpers for RedStone PriceFeedsAdapter* push-feed layouts.
RedstoneReactiveHandlerredstone: Reactive-runtime bridge for RedStone push oracle feeds.
RedstoneValueUpdateredstone: Decoded RedStone ValueUpdate event.
RoundData: Round tuple returned by latestRoundData().
StalenessPolicy: Policy used to classify round freshness and answer validity.
TokenAmount: Raw token amount in the base asset’s smallest units.
ValuedAmount: Checked quote-denominated value produced from a typed oracle price.

Enums§

AggregatorLayout: Known aggregator storage layouts.
AggregatorLayoutConfidence: How an aggregator layout was detected.
ChainlinkEventDecodeError: Errors returned by Chainlink event decoding.
Denomination: Typed quote denomination for oracle prices and valued amounts.
EulerQuoteLeg: One dependency leg inside an Euler quote adapter.
FeedSource: Network source and transform for a registered feed.
MorphoChainlinkFeedRole: Role of a Chainlink dependency inside MorphoChainlinkOracleV2.
OracleAdapterSkipReason: Classified reason for skipping a feed in best-effort registration.
OracleCodeInstallMode: How an oracle bytecode entry should be installed into the fork cache.
OracleConfigError: Caller or programming errors carried by OracleError::Config.
OracleError: Errors returned by registry, reconciliation, and report application.
OracleFeedChangeKind: Classified per-feed change kind.
OracleFeedStatus: Lifecycle readiness of a registered oracle feed.
OracleHookEvent: Rich oracle hook events emitted by reconciliation.
OracleIncident: Continuity incident observed while applying a batch.
OracleMockError: Errors returned by oracle mocking helpers.
OracleReconciliationKind: How a queued OracleReconciliationRequest is satisfied.
OracleRoundStatus: Classified usability of an oracle round under the feed policy.
OracleSignal: Borrowed typed view over an oracle hook signal payload.
OracleSignalDecodeError: Errors returned when decoding oracle hook signals.
OracleSignalKind: Strongly typed oracle hook signal kind.
OracleStorageEffect: Result of attempting event-derived oracle storage sync.
OracleStorageError: Errors returned by oracle storage adapters.
OracleStorageWarmupMode: Storage warmup implementation to use for oracle direct-write slots.
OracleTransformDescriptor: Open transform descriptor for non-Chainlink-native source adapters.
OracleValueSource: Source that produced an oracle value.
OracleValueStatus: Reconciliation lifecycle for an oracle value.
PricePolicyViolation: Structured reason a PricePolicy check or valuation was rejected.

Constants§

ANSWER_UPDATED_TOPIC: AnswerUpdated(int256,uint256,uint256) topic0.
NEW_ROUND_TOPIC: NewRound(uint256,address,uint256) topic0.
OCR1_NEW_TRANSMISSION_TOPIC: OCR1 NewTransmission(uint32,int192,address,int192[],bytes,bytes32) topic0.
OCR2_NEW_TRANSMISSION_TOPIC: OCR2 NewTransmission(uint32,int192,address,uint32,int192[],bytes,int192,bytes32,uint40) topic0.
ORACLE_LEGACY_ANSWER_UPDATED_KIND: Legacy event-update hook kind retained for compatibility.
ORACLE_SIGNAL_NAMESPACE: Namespace used by every oracle hook signal.
PYTH_PRICE_FEED_UPDATE_TOPICpyth: Pyth PriceFeedUpdate(bytes32,uint64,int64,uint64) topic0.
REDSTONE_VALUE_UPDATE_TOPICredstone: RedStone ValueUpdate(uint256,bytes32,uint256) topic0.

Traits§

ChainlinkFeedProvider: Minimal read seam for Chainlink-compatible proxy feeds.
OracleAdapterPlugin: Public plugin interface for oracle families layered over evm-fork-cache.
OracleDerivedReader: Reads the authoritative protocol value for a derived oracle source.
OracleOverlayMockExt: Extension trait for overlay-scoped oracle price mocks.
OracleStorageAdapter: Adapter that can translate oracle events into direct EVM cache state updates.

Functions§

classify_type_and_version: Classify a Chainlink-style typeAndVersion() string.
decode_answer_updated: Decode a Chainlink AnswerUpdated log.
decode_new_round: Decode a Chainlink NewRound log.
decode_ocr1_new_transmission: Decode a Chainlink OCR1 NewTransmission log.
decode_ocr2_new_transmission: Decode a Chainlink OCR2 NewTransmission log.
decode_pyth_price_feed_updatepyth: Decode a Pyth PriceFeedUpdate log.
decode_redstone_value_updateredstone: Decode a RedStone ValueUpdate log.

Type Aliases§

AdapterFuture: Boxed async result returned by oracle adapter extension points.
FeedBuilder: Builder-stage typed feed registration.
OracleAggregatorChanged: Hook emitted when proxy reconciliation detects an aggregator change.
ProviderFuture: Boxed future used by the provider seam.