Struct OracleRuntime 

pub struct OracleRuntime<P> { /* private fields */ }

High-level facade for registration, typed events, reads, and reconciliation.

Implementations

impl<P> OracleRuntime<P>

pub fn mock_price<F, M>( &self, overlay: &mut EvmOverlay, state: &dyn StateView, feed_id: F, mock: M, ) -> Result<OracleMockReport, OracleMockError>

where F: AsRef<str>, M: Into<OraclePriceMock>,

Mock one registered oracle price in an EvmOverlay.

The cache/runtime are not mutated. For Chainlink OCR1/OCR2 feeds with a detected layout and warmed hot slot, this writes the same storage slots a live oracle event would update. If the feed cannot be direct-written, the report returns applied = false.

impl<P> OracleRuntime<P>

pub fn builder(provider: P) -> OracleRuntimeBuilder<P>

Start building a runtime around a provider.

pub fn provider(&self) -> &P

Borrow the provider used for authoritative proxy reads and reconciliation.

pub fn tracker(&self) -> &OracleTracker

Borrow the typed state store for snapshot, price, and registration reads.

pub fn tracker_mut(&mut self) -> &mut OracleTracker

Mutably borrow the tracker.

Warning: mutating the tracker directly (registering or removing feeds through OracleTracker methods) desynchronizes this runtime’s adapter bookkeeping: adapter_states still references removed feeds (or misses added ones), so Self::reactive_handlers and the refresh_handlers* methods rebuild handler routing from a stale feed set. Use Self::register_seeded_feed, Self::register_adapter, Self::unregister_feed_by_id, or Self::unregister_feed_by_proxy instead — they keep typed state and handler routing in sync. Reserve this accessor for operations that do not change the registration set (for example OracleTracker::reconcile or OracleTracker::apply_batch_report).

pub fn feed_readiness(&self) -> Vec<OracleFeedReadinessReport>

Return feed/runtime readiness for all registered feeds.

pub fn with_storage_sync(self, storage_sync: OracleStorageSync) -> Self

Replace the direct-storage registry used by subsequently constructed reactive handlers and storage warmup calls.

This is primarily useful after cache-native discovery returns an OracleTracker that needs a deployment-specific storage adapter: construct the facade with OracleRuntime::from_tracker, then retain the custom registry here before calling Self::reactive_runtime, Self::reactive_handler, or Self::prewarm_storage.

If this runtime’s handlers are already installed in a live reactive engine, replace the registry only as part of a handler refresh so the installed handlers cannot retain the old storage policy.

pub fn reactive_handler(&self) -> OracleReactiveHandler

Build a fresh built-in Chainlink-compatible reactive handler from current registrations.

Adapter plugin handlers are not included. Use Self::reactive_handlers, Self::reactive_runtime, or Self::register_subscriber when the runtime was built with installed adapter plugins.

pub fn reactive_handlers(&self) -> Vec<Arc<dyn ReactiveHandler<Ethereum>>>

Build fresh reactive handlers for every source installed in this runtime.

The first handler is the built-in Chainlink-compatible handler. Any adapter plugin handlers discovered during cache-native startup follow it.

Handler ids must be unique across installed adapter plugins: when two adapters return handlers with the same HandlerId, only the first handler is kept and the second adapter’s event routing is silently dropped (a tracing warning is emitted). An adapter handler that reuses the built-in Chainlink handler id is fine — the built-in handler is rebuilt from all current registrations, so it already routes that adapter’s feeds.

pub fn reactive_handler_ids(&self) -> Vec<HandlerId>

Return current reactive handler ids for this runtime.

pub fn reactive_runtime(&self) -> Result<ReactiveRuntime<Ethereum>, OracleError>

Build a reactive runtime with this oracle runtime’s handlers already installed.

pub fn install_handlers<S>( &self, engine: &mut ReactiveEngine<S, Ethereum>, ) -> Result<OracleReactiveInstallReport, OracleError>

where S: InterestOwnerSubscriber<Ethereum>,

Register this runtime’s handlers with an engine, using continuity-safe backfill.

Errors

Returns OracleError::Reactive when the engine rejects a handler registration (for example a handler id that is already installed).

pub fn refresh_handlers<S>( &self, engine: &mut ReactiveEngine<S, Ethereum>, installed: &mut OracleReactiveInstallReport, ) -> Result<OracleReactiveRefreshReport, OracleError>

where S: InterestOwnerSubscriber<Ethereum>,

Refresh an existing engine install after registering or unregistering feeds.

installed must be the report returned by a previous install/refresh. The old handler ids in that report are removed first, then the runtime’s current handlers are installed with continuity-safe backfill.

pub fn refresh_handlers_with_backfill<S>( &self, engine: &mut ReactiveEngine<S, Ethereum>, installed: &mut OracleReactiveInstallReport, backfill: SubscriberBackfill, ) -> Result<OracleReactiveRefreshReport, OracleError>

where S: InterestOwnerSubscriber<Ethereum>,

Refresh an existing engine install after mutation using explicit backfill.

pub fn refresh_handlers_live_only<S>( &self, engine: &mut ReactiveEngine<S, Ethereum>, installed: &mut OracleReactiveInstallReport, ) -> Result<OracleReactiveRefreshReport, OracleError>

where S: InterestOwnerSubscriber<Ethereum>,

Refresh an existing engine install after mutation without backfill.

pub fn uninstall_installed_handlers<S>( &self, engine: &mut ReactiveEngine<S, Ethereum>, installed: &mut OracleReactiveInstallReport, ) -> OracleReactiveUninstallReport

where S: InterestOwnerSubscriber<Ethereum>,

Unregister exactly the handlers recorded by a previous install/refresh report.

pub fn install_handlers_with_backfill<S>( &self, engine: &mut ReactiveEngine<S, Ethereum>, backfill: SubscriberBackfill, ) -> Result<OracleReactiveInstallReport, OracleError>

where S: InterestOwnerSubscriber<Ethereum>,

Register this runtime’s handlers with explicit owner-scoped backfill.

Errors

Returns OracleError::Reactive when the engine rejects a handler registration (for example a handler id that is already installed).

pub fn install_handlers_live_only<S>( &self, engine: &mut ReactiveEngine<S, Ethereum>, ) -> Result<OracleReactiveInstallReport, OracleError>

where S: InterestOwnerSubscriber<Ethereum>,

Register this runtime’s handlers without any backfill.

Errors

Returns OracleError::Reactive when the engine rejects a handler registration (for example a handler id that is already installed).

pub fn uninstall_handlers<S>( &self, engine: &mut ReactiveEngine<S, Ethereum>, ) -> OracleReactiveUninstallReport

where S: InterestOwnerSubscriber<Ethereum>,

Unregister this runtime’s handlers from an engine.

Warning: this recomputes handler ids from the current registration set. If the runtime’s registrations changed since the handlers were installed (feeds registered or unregistered, adapters added), the recomputed set can miss handlers that are still installed in the engine, leaving them registered. Prefer Self::uninstall_installed_handlers with the report returned by the original install/refresh call — it removes exactly the handler ids that were installed.

pub fn register_subscriber<S>( &self, subscriber: &mut S, ) -> Result<(), OracleError>

where S: EventSubscriber<Ethereum>,

Register this runtime’s oracle interests with an event subscriber.

pub async fn next_subscriber_events<S>( &mut self, cache: &mut EvmCache, runtime: &mut ReactiveRuntime<Ethereum>, subscriber: &mut S, ) -> Result<Option<OracleBatchReport>, OracleError>

where S: EventSubscriber<Ethereum>,

Read one subscriber batch, apply it to the cache, and return the typed batch digest, or None when the subscriber has no batch ready.

pub fn read_overlay(&self) -> OracleReadOverlay<'_>

Build a read overlay over the current tracker state.

pub fn register_seeded_feed( &mut self, registration: FeedRegistration, round: RoundData, ) -> Result<OracleRuntimeMutationReport, OracleError>

Register an already-discovered feed and seed its latest round.

This updates typed state immediately. If a reactive engine has already installed this runtime’s handlers, call one of the refresh_handlers* methods with the previous install report so the subscriber receives the new event interests.

Errors

Returns OracleError::DuplicateFeedId or OracleError::DuplicateProxy when the registration collides with an existing feed; typed state is unchanged in that case.

pub fn register_adapter_seeded_feed( &mut self, adapter_id: impl AsRef<str>, registration: FeedRegistration, round: RoundData, ) -> Result<OracleRuntimeMutationReport, OracleError>

Register an already-discovered adapter-owned feed and seed its latest round.

The adapter must already be installed in this runtime. This is the low-level path for adapter code that discovers one additional feed and wants that feed included in the adapter handler rebuilt on refresh.

Errors

Returns OracleError::Config when adapter_id is not installed in this runtime, and OracleError::DuplicateFeedId/ OracleError::DuplicateProxy when the registration collides with an existing feed.

pub fn unregister_feed_by_id( &mut self, id: FeedId, ) -> Result<OracleRuntimeMutationReport, OracleError>

Unregister a feed by id.

This removes typed state, pending reconciliation, and any adapter routing references for the feed. Refresh installed handlers afterward to apply the routing change to a live engine.

Errors

Returns OracleError::FeedNotFound when no feed is registered under id.

pub fn unregister_feed_by_proxy( &mut self, proxy: Address, ) -> Result<OracleRuntimeMutationReport, OracleError>

Unregister a feed by proxy.

Errors

Returns OracleError::FeedNotFound when no feed is registered under proxy.

pub fn price(&self, id: impl AsRef<str>) -> Result<OraclePrice, OracleError>

Return the latest typed price by feed id string.

Errors

Returns OracleError::FeedNotFound when no feed is registered under id or the feed has no current snapshot.

pub fn price_by_proxy(&self, proxy: Address) -> Result<OraclePrice, OracleError>

Return the latest typed price by proxy address.

Errors

Returns OracleError::FeedNotFound when no feed is registered under proxy or the feed has no current snapshot.

pub fn latest_round( &self, id: impl AsRef<str>, ) -> Result<RoundData, OracleError>

Return the latest round by feed id string.

Errors

Returns OracleError::FeedNotFound when no feed is registered under id or the feed has no current snapshot.

pub fn apply_batch_report<N: Network>( &mut self, report: &ReactiveBatchReport<N>, ) -> Result<OracleBatchReport, OracleError>

Apply a committed reactive batch and return the typed batch digest.

The returned crate::OracleBatchReport carries the raw per-event hooks (events, in emission order) plus the digested per-feed changes, continuity incidents, and the requires_full_refresh routing flag — the same consumer shape as evm-amm-state’s AmmSyncBatchReport. Registered callbacks fire for every event before this returns.

Legacy oracle.answer_updated signals (emitted by custom handlers that predate the rich OraclePriceUpdate payload) update typed tracker state but are not decoded into OracleHookEvents, so on_event/ on_price_update callbacks do not fire for them. Emit the rich oracle.price_update signal from custom handlers to get typed callbacks.

pub async fn reconcile_pending( &mut self, ) -> Result<Vec<OracleHookEvent>, OracleError>

where P: ChainlinkFeedProvider,

Reconcile all currently pending proxy-kind event updates.

Derived-source requests (crate::OracleReconciliationKind::DerivedProtocolRead) are left queued; satisfy those with OracleRuntime::reconcile_derived.

pub fn reconcile_derived( &mut self, cache: &mut EvmCache, ) -> DerivedReconcileReport

Reconcile all currently pending derived-source updates through their protocols’ own view calls (Morpho price(), Euler getQuote), read through cache.

Successful reads promote EventPending snapshots to Confirmed or Corrected and fire the registered hook callbacks; failed reads leave their requests queued and are surfaced in crate::DerivedReconcileReport::failed.

pub fn reactive_interests(&self) -> Vec<ReactiveInterest<Ethereum>>

Return the complete log/event interest set for built-in and adapter handlers.

pub fn storage_warmup_slots(&self) -> Vec<(Address, U256)>

Return the oracle storage slots this runtime can prewarm for direct event writes.

pub fn prewarm_storage(&self, cache: &mut EvmCache) -> OracleStorageWarmupReport

Bulk-load direct-write oracle storage slots into the supplied cache.

pub fn cold_start_storage( &self, cache: &mut EvmCache, ) -> OracleStorageWarmupReport

Verify direct-write oracle storage slots through EvmCache::run_cold_start.

impl OracleRuntime<()>

pub fn cache_builder() -> OracleCacheRuntimeBuilder

Start building a cache-native runtime from oracle adapter plugins.

pub fn from_tracker(tracker: OracleTracker) -> Self

Build a runtime facade from a cache-native tracker.

The returned runtime starts with Chainlink-default storage sync and no adapter-plugin routing, regardless of how the tracker’s feeds were discovered: any custom OracleStorageSync configuration is reset to OracleStorageSync::chainlink_defaults unless replaced with OracleRuntime::with_storage_sync, and non-Chainlink feeds already in the tracker (Pyth, RedStone, custom adapter families) remain visible in typed state but receive no reactive events — their adapter handlers are gone until the adapters are re-installed via Self::register_adapter. Prefer keeping the runtime returned by OracleCacheRuntimeBuilder::build when adapter plugins are in play.

pub async fn register_adapter<A>( &mut self, adapter: A, cache: &mut EvmCache, ) -> Result<OracleRuntimeMutationReport, OracleError>

where A: OracleAdapterPlugin + 'static,

Discover and register feeds from an adapter on an existing cache-native runtime.

This mutates typed state and retains the adapter for future handler rebuilds. If handlers are already installed in an engine, call one of the refresh_handlers* methods with the previous install report afterward.

Errors

Returns OracleError::Provider when adapter discovery reads fail, and OracleError::DuplicateFeedId/OracleError::DuplicateProxy when a discovered feed collides with an existing registration. On error the runtime is unchanged: feeds inserted earlier in the same call are rolled back and the adapter is not retained.

Trait Implementations

impl<P: Debug> Debug for OracleRuntime<P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.