Struct ReactiveRuntime 

pub struct ReactiveRuntime<N: Network = Ethereum> { /* private fields */ }

Reactive runtime.

Implementations

impl<N: Network> ReactiveRuntime<N>

pub fn new(config: ReactiveConfig) -> Self

Create an empty runtime.

pub fn track_account(&mut self, address: Address, policy: TrackingPolicy)

Track address under policy for the per-block root gate (Phase-8 step 4).

Tracking is strictly opt-in: a runtime with no tracked accounts runs the gate as a no-op. Registering an account clears any baseline it held (a policy change re-adopts on the next probe rather than diffing against a baseline captured under the old policy). Each RootGateCadence firing, the gate probes tracked WholeAccount and Scalars accounts’ roots/fields via the account-proof seam and, on a move no decoder covered, emits a ReactiveReport::CoverageGap and schedules a ResyncReason::RootMoved repair. Slots accounts are never root-gated (spec Decision 3).

pub fn untrack_account(&mut self, address: Address) -> bool

Stop tracking address, dropping its policy and any adopted baseline.

Returns true if the account was tracked.

pub fn set_root_gate_cadence(&mut self, cadence: RootGateCadence)

Set how often the root gate probes tracked accounts (default: RootGateCadence::default — every 16 canonical blocks; see the RootGateCadence docs for why skipping blocks loses no detection).

Reconfiguring resets the gate’s window bookkeeping (the touched-address accumulator and the last-fired block), so a stale window never leaks into the new cadence: the next canonical block fires the gate.

pub fn root_gate_cadence(&self) -> RootGateCadence

The configured RootGateCadence.

pub fn enable_freshness_stamping(&mut self)

Enable freshness stamping of canonical event-derived writes (opt-in).

Installs a FreshnessRegistry the runtime owns; while it is present, applying a canonical handler storage-slot effect for a block N stamps the touched (address, slot) as Validity::ValidThrough(N). The slot is therefore not volatile at N (event-maintained, no need to re-verify) but ages to volatile once the clock passes N.

Idempotent: if a registry is already installed it is left untouched, so an existing registry (and any stamps it holds) is never clobbered.

pub fn freshness(&self) -> Option<&FreshnessRegistry>

Borrow the runtime’s freshness registry, if stamping was enabled.

Returns None unless enable_freshness_stamping was called.

pub fn freshness_mut(&mut self) -> Option<&mut FreshnessRegistry>

Mutably borrow the runtime’s freshness registry, if stamping was enabled.

Returns None unless enable_freshness_stamping was called.

pub fn health(&self) -> CacheHealth

Return the current queryable CacheHealth of the runtime.

pub fn metrics(&self) -> CacheMetricsSnapshot

Return a point-in-time snapshot of the runtime’s observability counters.

pub fn reset_health(&mut self)

Complete the caller-driven self-heal by returning health to CacheHealth::Healthy.

A trust-loss event (a reorg deeper than the journal, or a detected missed block range) escalates health toward CacheHealth::Unhealthy as a “stop until rebuilt” signal that the caller must act on. Once the caller has resynced or rebuilt the affected state, it invokes this to clear the signal. It does not emit a ReactiveReport::Health report, since it is called outside an ingest cycle.

pub fn register_handler( &mut self, handler: Arc<dyn ReactiveHandler<N>>, ) -> Result<(), RegisterError>

Register a handler.

pub fn unregister_handler( &mut self, id: &HandlerId, ) -> Option<Arc<dyn ReactiveHandler<N>>>

Remove one handler from the runtime registry without resetting runtime state.

This delegates to ReactiveRegistry::unregister_handler only. It does not clear the reorg journal, health, metrics, hooks, pending resyncs, tracking policy, freshness registry, or root-gate baselines, and it does not purge EvmCache state. Callers that want cache eviction must issue explicit StateUpdate::purge updates or use cache purge APIs separately.

pub fn contains_handler(&self, id: &HandlerId) -> bool

Return true when the runtime has a registered handler with id.

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

Ids of all registered handlers, in registration (= routing) order.

pub fn handler_interests( &self, id: &HandlerId, ) -> Option<&[ReactiveInterest<N>]>

Borrow the interests owned by one registered handler.

pub fn last_canonical_block(&self) -> Option<BlockRef>

The most recently journaled canonical block, if any.

This is the runtime’s current chain position: the canonical block most recently recorded by ingestion. Reorged blocks are dropped from the journal during recovery, so a rolled-back head does not linger here. ReactiveEngine::register_handler uses it as the default backfill anchor for handlers registered mid-lifecycle. None until the first canonical input is journaled, and always None when ReactiveConfig::journal_depth is 0 (journaling disabled).

pub fn pending_resyncs(&self) -> &[ResyncRequest]

Queued resync requests: surfaced by handlers but not yet executed by an ingest_batch_with_resync pass.

Callers driving resync execution themselves (plain ingest_batch loops) can read the ledger here; reorg recovery cancels entries whose pinned blocks were dropped, and cancel_pending_resyncs drops entries for torn-down accounts.

pub fn cancel_pending_resyncs(&mut self, address: Address) -> Vec<ResyncRequest>

Cancel queued resync work that targets address, returning the cancelled portions.

Every pending ResyncRequest target referencing address is removed; a request reduced to zero targets is dropped entirely, while mixed-target requests keep their other accounts queued. Each returned request mirrors the original id/reason/block/priority and carries only the targets that were cancelled.

This is part of the adapter-teardown recipe (see ReactiveEngine::unregister_handler): it clears the pending ledger so a dropped pool’s queued repairs stop occupying memory and stop surfacing as cancellations in reorg reports. It cannot recall requests already returned to the caller in earlier batch reports.

pub fn register_hook( &mut self, hook: Arc<dyn ReactiveHook<N>>, ) -> Result<(), RegisterError>

Register a hook.

pub fn interests(&self) -> Vec<ReactiveInterest<N>>

Return all registered interests in handler registration order.

pub fn ingest_batch( &mut self, cache: &mut EvmCache, batch: ReactiveInputBatch<N>, ) -> Result<ReactiveBatchReport<N>, ReactiveError>

Ingest a batch, apply valid direct state effects, and dispatch reports.

pub fn ingest_batch_with_resync( &mut self, cache: &mut EvmCache, batch: ReactiveInputBatch<N>, ) -> Result<ReactiveBatchReport<N>, ReactiveError>

Ingest a batch, then execute surfaced storage resync requests.

This entrypoint preserves ingest_batch behavior for direct handler effects, then runs a synchronous resync phase over the collected ResyncRequests. Storage targets are fetched through EvmCache::storage_batch_fetcher grouped by ResyncBlock, successful values are applied as StateUpdate::slot updates through EvmCache::apply_updates, and unsupported or failed targets are reported in ResyncReport::failed. It does not start subscribers, background workers, or network transport.