Module reactive 

Protocol-neutral reactive runtime for cache state effects.

The reactive runtime generalizes the log-only events pipeline into a handler pipeline that can ingest logs, block notifications, and pending transaction signals. Handlers remain pure synchronous functions: they read through StateView, return structured ReactiveEffect values, and let the runtime validate and commit cache mutations through StateUpdate.

This module intentionally contains no protocol, AMM, strategy, signing, or transaction-submission concepts. Downstream crates can layer those domains on top by implementing ReactiveHandler and ReactiveHook.

Structs

AccountFieldMask

Account fields requested by a resync.

AlloySubscriber

Alloy-backed event subscriber.

AppliedReport

Applied state report.

BaseFlashblockBase

Stable index-zero header subset from Base’s Flashblocks wire format.

BaseFlashblockDiff

Stable commitment subset from Base’s Flashblocks wire format.

BaseFlashblockMetadata

Stable metadata subset used when index-greater-than-zero payloads omit the Base header object.

BaseFlashblockPayload

Indexed OP Stack newFlashblocks subscription payload.

BlockInterest

Interest in block inputs.

BlockRef

Minimal block identity carried through reports.

BlockReport

Block processing report.

CacheMetricsSnapshot

Point-in-time copy of the reactive runtime’s observability counters.

CanonicalSequenceState

Provider-neutral snapshot consumed by validate_canonical_sequence.

CanonicalSequenceValidation

Successful result of provider-neutral canonical envelope validation.

ChainControlReport

Report emitted after an ordered source control is accepted.

CoverageGapReport

Report that a tracked account’s storage root moved on a canonical block that no decoder covered — a coverage gap surfaced by the per-block root gate (Phase-8 step 4).

DecodedReport

Decoding report.

EndpointId

Stable, non-secret identity for one configured RPC provider endpoint.

EventDecoderHandler

Adapter that wraps a legacy EventDecoder as a log-only reactive handler.

FlashblockRef

Identity of one cumulative pre-confirmed Flashblock snapshot.

FlashblocksPreflight

Successful initial Flashblocks endpoint preflight.

FlashblocksRpcMetrics

Request/response traffic issued by one Flashblocks subscriber generation.

HandlerError

Error returned by a handler.

HandlerId

Identifier for a reactive handler.

HandlerIdError

An empty handler identity cannot be represented portably across subscriber protocols because the empty owner is reserved for canonical/global scope.

HandlerOutcome

Handler output for a single input.

HealthReport

Report of a CacheHealth transition, emitted into the ingest cycle that caused it and delivered to hooks through the normal dispatch path.

HookSignal

Domain-neutral hook signal emitted by a handler.

InputReport

Input acceptance report.

InvalidationRequest

Rich invalidation request lowered to StateUpdate::Purge.

LogInterest

Interest in logs.

LogRouteIndex

Non-empty exhaustive OR-set of exact log route keys.

MissedRangeReport

Report of a forward gap in the canonical block sequence: an arriving block whose number is more than one past the last-seen head, so the blocks in between were never observed (for example during a subscription disconnect).

PendingTxInterest

Interest in pending transaction inputs.

ProviderRef

Stable provider identity attached to provider-originated input.

ReactiveBatchReport

Batch report returned by ReactiveRuntime::ingest_batch and ReactiveRuntime::ingest_batch_with_resync.

ReactiveCanonicalBaseline

Exact chain/block identity of an RPC cache snapshot adopted as the starting point for reactive event continuity.

ReactiveConfig

Configuration for ReactiveRuntime.

ReactiveContext

Context supplied with each ReactiveInput.

ReactiveEngine

Binds a ReactiveRuntime to an EventSubscriber for the common subscribe-ingest lifecycle.

ReactiveErrorReport

Report of a non-fatal error surfaced during an ingest cycle, with the associated input (when known) and a human-readable message.

ReactiveInputBatch

Batch of reactive input records.

ReactiveInputBatchParts

Complete contents of a consumed ReactiveInputBatch.

ReactiveInputDelivery

One input together with its routing and canonical-processing provenance.

ReactiveInputIdentity

Validated, representation-aware identity for one reactive input.

ReactiveInputIdentityError

An explicit InputRef and ReactiveInputKind describe incompatible object/representation classes.

ReactiveInputRecord

One input and its execution context.

ReactiveLogRoute

Exact log route selected by ReactiveRegistry::route_log.

ReactiveRegistry

Registry and router for provider-neutral reactive handlers.

ReactiveRuntime

Reactive runtime.

ReorgReport

Report of a detected reorg and the recovery it performed: the dropped block(s) and inputs, the exact rollback updates applied for reversible dropped effects, the conservative purge updates for irreversible ones, the canceled hash-pinned resyncs, and why recovery ran.

ReportTag

Lightweight report label.

ResyncFailure

One resync target that could not be fetched or applied.

ResyncId

Resync id.

ResyncReport

Report of the storage resync requests executed during an ingest cycle: the requests considered, the authoritative updates built from successful fetches (and their applied diff), and any targets that could not be resynced.

ResyncRequest

Request for authoritative state repair.

SpeculativeId

Speculative request id.

SpeculativeRequest

Speculative signal emitted by handlers.

SubscriberBackfill

Historical log backfill requested when adding subscriber interests.

SubscriberCapabilities

Capability set advertised by an EventSubscriber.

SubscriberCheckpoint

Opaque source checkpoint associated with a delivered batch.

SubscriberConfig

Subscriber configuration.

SubscriberDeliveryToken

Opaque subscriber-owned token attached to a delivered input batch.

SubscriberInputBatch

Batch of subscriber inputs with enqueue-time owner provenance.

SubscriberInputRecord

Reactive input together with its canonical/owner-scoped delivery audience.

SubscriberOwnerEpoch

Opaque generation for one transaction-aware subscriber interest owner.

SubscriberOwnerProgress

Hash-certified catch-up position reached by one subscriber owner epoch.

SubscriberPayloadCommitment

Subscriber-supplied commitment to the exact canonical wire payload of one delivered batch.

SubscriberReconnectConfig

WebSocket/pubsub reconnect policy.

SubscriberResumePosition

Durable subscriber position restored together with cache/runtime state.

Enums

AddressMatcher

Address matching helper for pending transaction interests.

BlockInterestMode

Block subscription mode.

CacheHealth

Queryable coarse health of the reactive cache.

CanonicalRollbackKind

Stable category for a canonical transition that needs older retained history before it can be durably accepted.

CanonicalSequenceError

Structured failure returned by canonical-sequence diagnostic validation.

CanonicalSequenceMutation

Cache-free canonical transition proven by validate_canonical_sequence.

ChainControl

Ordered chain-lifecycle control delivered by an event subscriber.

ChainStatus

Lifecycle status for an input.

CheckpointedIngest

Result of one crash-safe subscriber ingest cycle.

DeliveryAudience

Runtime routing audience for one delivered subscriber batch.

DeliveryScope

How one delivered record participates in the runtime’s canonical state machine.

EffectTarget

Absolute write target used for conflict reports.

FlashblocksDelivery

Provider surface established for one Flashblocks generation.

HookBackpressure

Hook backpressure policy.

InputRef

Stable identity used for input deduplication and reports.

InputSource

Source of an input batch.

InvalidationReason

Invalidation reason.

LogRouteKey

Exact protocol-neutral key used to select candidate log handlers.

PreconfirmationMode

Whether the subscriber may use Flashblocks for speculative delivery.

ReactiveBaselineError

Error adopting an RPC snapshot as a runtime’s canonical continuity baseline.

ReactiveCheckpointRestoreError

Error restoring a durable checkpoint anchor into an active runtime.

ReactiveEffect

Effect emitted by a ReactiveHandler.

ReactiveEngineError

Error returned by ReactiveEngine helpers that combine subscriber polling and runtime ingestion.

ReactiveEngineRegisterError

Error returned when ReactiveEngine cannot register a handler on both the runtime and subscriber sides.

ReactiveError

Runtime error.

ReactiveInput

Input accepted by the reactive runtime.

ReactiveInputKind

Representation and lifecycle class retained alongside an InputRef.

ReactiveInterest

Reactive subscription interest.

ReactiveReport

Runtime report.

RegisterError

Handler registration error.

ReorgReason

Reason reorg recovery ran.

ResyncBlock

Block target for a resync.

ResyncFailureKind

Stable classification for a failed resync target.

ResyncPriority

Resync priority.

ResyncReason

Reason for a resync request.

ResyncTarget

State target for a resync.

RootGateCadence

How often the reactive root gate probes tracked accounts (TrackingPolicy::WholeAccount / TrackingPolicy::Scalars; the Scalars account-fields comparison rides the same firing).

RouteKey

Extracted route key.

RouteKeySpec

Route-key extraction strategy for logs.

SelectorMatcher

Calldata selector matching helper.

StateEffectQuality

Reliability of state effects emitted by a handler.

SubscriberCapability

One independently negotiable event-subscriber behavior.

SubscriberDriverPoll

Result of polling a scoped subscriber batch against one driver control future.

SubscriberError

Subscriber error.

SubscriberInputScope

Delivery audience retained with a subscriber input record.

SubscriberMode

Subscriber mode requested for the Alloy subscriber.

SubscriberOwnerError

Error staging a transaction-aware subscriber owner.

SubscriberOwnerStart

Catch-up policy applied when staging a transaction-aware interest owner.

SubscriberOwnerState

Transaction state of one epoch-scoped subscriber owner.

TrackingPolicy

How a tracked account is kept live by the per-block root gate (Phase-8 step 4).

Traits

EventSubscriber

Provider-agnostic subscriber interface.

InterestOwnerSubscriber

Extension trait for subscribers that can add and remove handler-owned interests incrementally.

LogMatcher

Local log predicate.

PendingTxMatcher

Local predicate over a full pending transaction.

ReactiveHandler

Pure synchronous handler for reactive inputs.

ReactiveHook

Hook invoked after reports are built and cache mutation phases have ended.

RouteKeyExtractor

Extracts custom route keys from logs.

Functions

normalize_and_validate_canonical_sequence

Validate a composite-source envelope and normalize harmless coverage overlap.

normalize_and_validate_canonical_sequence_diagnostic

Validate and normalize one composite-source envelope while retaining structured rollback diagnostics.

validate_canonical_sequence

Validate one provider-neutral delivery envelope without mutating runtime or cache state.

validate_canonical_sequence_diagnostic

Validate one provider-neutral delivery envelope and retain structured rollback diagnostics.

Type Aliases

SubscriberNextBatch

Boxed future returned by EventSubscriber::next_batch.

SubscriberNextScopedBatch

Boxed future returned by AlloySubscriber::next_scoped_batch.

SubscriberOperation

Boxed, sendable future returned by subscriber lifecycle operations.