Struct AlloySubscriber 

pub struct AlloySubscriber<P, N: Network = Ethereum> { /* private fields */ }

Alloy-backed event subscriber.

The default transport slice drives Alloy pubsub subscriptions for logs, block headers, and pending transaction hashes. The HTTP polling watch_* transport remains available behind the opt-in reactive-polling feature. Pubsub streams reconnect automatically after termination, and log subscriptions are backfilled from the last seen block. Owner-scoped log additions can request backfill from an explicit block anchor. Full pending transaction hydration and full block bodies remain explicit follow-up work.

Historical log fetching is deliberately a bounded live-subscriber aid, not a high-volume indexer: each filter/window is issued as one complete-range eth_getLogs request. SubscriberConfig::max_backfill_log_bytes rejects an oversized decoded response, but the subscriber does not adaptively split block ranges and cannot bypass an RPC provider’s result cap. Keep owner registration and reconnect windows modest; use an indexing source such as HyperSync behind EventSubscriber for deep or high-density catch-up.

With no registered interests, EventSubscriber::next_batch returns Ok(None).

Implementations

impl<P, N: Network> AlloySubscriber<P, N>

pub fn new(provider: P, mode: SubscriberMode, config: SubscriberConfig) -> Self

Create a new Alloy subscriber.

pub fn provider(&self) -> &P

Borrow the provider.

pub fn with_provider_ref(self, provider: ProviderRef) -> Self

Bind this subscriber to the concrete provider lease that supplies Flashblocks. Callers obtain the lease from a transport endpoint marked with the single flashblocks = true flag.

pub fn with_flashblocks_state_provider(self, provider: P) -> Self

Pair the subscriber’s event transport with the request/response transport for the same configured provider ID and generation.

Optimism pending block/log sampling uses this provider. Preflight reads its chain ID and rejects a mismatch before pending data can be emitted. Use type-erased Alloy providers when the WebSocket and HTTP transports have different concrete Rust types.

pub fn with_log_verification_provider(self, provider: P) -> Self

Use a separate provider for canonical log-context verification.

This is recommended with SubscriberConfig::verify_log_block_context in high-volume pubsub deployments. The provider must target the same chain; every fetched block is still checked against the log’s number, hash, and timestamp.

pub fn mode(&self) -> SubscriberMode

Subscriber mode.

pub fn config(&self) -> &SubscriberConfig

Subscriber config.

pub const fn flashblocks_rpc_metrics(&self) -> FlashblocksRpcMetrics

Request/response traffic issued for Flashblocks qualification and pending-state sampling since the last full interest reset.

pub fn registered_interests(&self) -> &[ReactiveInterest<N>]

Registered interests across base and owner-scoped registrations.

pub fn stage_interest_owner( &mut self, owner: HandlerId, interests: &[ReactiveInterest<N>], start: SubscriberOwnerStart, ) -> Result<SubscriberOwnerEpoch, SubscriberOwnerError>

Stage a fresh, epoch-scoped interest owner without making its inputs canonically routable yet.

The returned token is required by every later lifecycle operation. A staged owner participates in provider subscription planning immediately, while its matching input remains owner-scoped until activate_interest_owner succeeds. Post-block owners require hash-certified reconcile_interest_owner progress on the current clean stream revision before activation.

Errors

Returns SubscriberOwnerError for invalid subscriber configuration, duplicate owners, unsupported post-block interests, unsupported transport interests, block-number overflow, or epoch exhaustion.

pub fn stage_interest_owner_replacement( &mut self, owner: HandlerId, interests: &[ReactiveInterest<N>], start: SubscriberOwnerStart, ) -> Result<SubscriberOwnerEpoch, SubscriberOwnerError>

Stage replacement interests for one currently active logical owner.

The active epoch remains canonical while the replacement reconciles. Commit both epochs atomically with commit_interest_owner_replacement, or abort the staged epoch with abort_interest_owner.

Errors

Returns SubscriberOwnerError for invalid subscriber configuration, missing/non-unique active owner state, unsupported post-block interests, unsupported transport interests, block-number overflow, or epoch exhaustion.

pub fn interest_owner_state( &self, epoch: &SubscriberOwnerEpoch, ) -> Option<SubscriberOwnerState>

Current transaction state for an exact owner epoch.

pub fn interest_owner_progress( &self, epoch: &SubscriberOwnerEpoch, ) -> Option<&SubscriberOwnerProgress>

Latest hash-certified reconcile progress for an exact owner epoch.

pub fn activate_interest_owner(&mut self, epoch: &SubscriberOwnerEpoch) -> bool

Make a staged owner canonical after its actor-side installation commits.

Returns false for stale tokens and owners not currently staged.

pub fn commit_interest_owner_replacement( &mut self, active: &SubscriberOwnerEpoch, replacement: &SubscriberOwnerEpoch, ) -> bool

Atomically replace one active owner epoch with one reconciled staged epoch.

pub fn prepare_interest_owner_removal( &mut self, epoch: &SubscriberOwnerEpoch, ) -> bool

Prepare an exact active owner for removal without changing desired interests, streams, anchors, or queued canonical input.

The caller establishes its delivery fence after this transition. Use abort_interest_owner to restore the owner on actor-side failure, or finalize_interest_owner_removal once canonical routing has been removed.

pub fn finalize_interest_owner_removal( &mut self, epoch: &SubscriberOwnerEpoch, ) -> Option<Vec<ReactiveInterest<N>>>

Finalize a previously prepared exact owner removal.

Returns the removed interests, or None for stale tokens and owners not currently in SubscriberOwnerState::Removing. Repeating finalization is therefore idempotent.

pub fn abort_interest_owner(&mut self, epoch: &SubscriberOwnerEpoch) -> bool

Abort an epoch-scoped owner lifecycle operation.

A staged owner is removed completely. A prepared removal is restored to active. Active and unknown epochs are unchanged. Repeating the same abort is therefore safe and returns false after the first effect.

pub fn upsert_interest_owners( &mut self, owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>, ) -> Result<(), SubscriberError>

Atomically add or replace several owners while preserving unrelated ones.

Errors

Returns SubscriberError for invalid configuration, duplicate owners, mixed lifecycle APIs, unsupported interests, or backfill-capacity exhaustion. No owner state changes on error.

pub fn upsert_interest_owners_with_backfill( &mut self, owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>, backfill: SubscriberBackfill, ) -> Result<(), SubscriberError>

Atomically add or replace several owners and queue one common backfill policy for every log interest while preserving unrelated owners.

Errors

Returns SubscriberError for invalid configuration, duplicate owners, mixed lifecycle APIs, unsupported interests, or backfill-capacity exhaustion. No owner or backfill state changes on error.

pub fn replace_interest_owners( &mut self, owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>, ) -> Result<(), SubscriberError>

Atomically replace every compatibility owner without requesting historical delivery.

Errors

Returns SubscriberError for invalid configuration, duplicate owners, mixed lifecycle APIs, unsupported interests, or resource exhaustion. The previous topology remains authoritative on error.

pub fn replace_interest_owners_with_global_backfill( &mut self, owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>, backfill: SubscriberBackfill, ) -> Result<(), SubscriberError>

Atomically replace every compatibility owner and queue one global post-baseline backfill for the resulting union of log interests.

Base interests are replaced. Epoch-scoped lifecycle operations cannot be mixed with this compatibility replacement because silently deleting an in-flight epoch would violate its activation transaction.

Errors

Returns SubscriberError for invalid configuration, duplicate owners, mixed lifecycle APIs, unsupported interests, or backfill-capacity exhaustion. The previous topology remains authoritative on error.

pub fn add_interest_owner( &mut self, owner: HandlerId, interests: &[ReactiveInterest<N>], ) -> Result<(), SubscriberError>

Add or replace the interests owned by owner.

This preserves unrelated owners, queued/pending records, recent dedupe state, and last-seen log anchors. The live transport is reconciled on the next EventSubscriber::next_batch call so newly added log filters can be subscribed without rebuilding the whole subscriber object.

Replacing an existing owner is continuity-safe: filters the owner already had keep their delivery anchors, and any changed or new filter shape is automatically backfilled from the owner’s oldest prior anchor — growing a pool set on an established owner does not open a delivery gap for what the old subscription had already covered. A brand-new owner has no anchor to inherit; pass an explicit add_interest_owner_with_backfill anchor (or register through ReactiveEngine::register_handler, which anchors to the runtime’s last canonical block).

Errors

Returns SubscriberError for invalid configuration, incompatible lifecycle state, unsupported interests, or continuity-backfill capacity exhaustion. The prior owner state remains authoritative on error.

pub fn add_interest_owner_with_backfill( &mut self, owner: HandlerId, interests: &[ReactiveInterest<N>], backfill: SubscriberBackfill, ) -> Result<(), SubscriberError>

Add or replace owner interests and schedule log backfill for that owner.

Backfill is queued only for log interests; block and pending transaction interests are live-only. Queued records can be delivered immediately; the subsequent provider stream is then caught up from the seeded delivery anchor, and overlap is deduplicated — so the discovery boundary is closed end to end as long as backfill starts at (or before) the block the interest was discovered in. Continuity backfill for a replaced owner (see add_interest_owner) is queued in addition, unless this explicit backfill is open-ended and already starts at or below the owner’s prior anchor.

Errors

Returns SubscriberError for invalid configuration, incompatible lifecycle state, unsupported interests, or backfill-capacity exhaustion. The prior owner state remains authoritative on error.

pub fn add_interest_owner_with_canonical_catchup( &mut self, owner: HandlerId, interests: &[ReactiveInterest<N>], retained: BlockRef, ) -> Result<(), SubscriberError>

Add or replace one owner at retained canonical block C, then queue the coordinated cutover required by ReactiveEngine::register_handler.

The new owner alone receives matching records from C so its effects attach to the runtime’s existing journal entry. Every matching log from C + 1 through the activation head is then delivered canonically over the complete interest union. Self::next_scoped_batch installs the desired live streams before draining either window, closing the subscribe/backfill gap. Alloy cannot reconstruct historical block or pending-transaction deliveries through this log backfill path, so a mixed interest topology is rejected rather than silently underfilled.

Errors

Returns SubscriberError for invalid configuration, incompatible lifecycle state, unsupported non-log catch-up, block-number overflow, or resource exhaustion. The prior owner state remains authoritative on error.

pub fn remove_interest_owner( &mut self, owner: &HandlerId, ) -> Option<Vec<ReactiveInterest<N>>>

Remove one owner’s interests, preserving unrelated owner/base interests.

The owner’s queued backfills are dropped, and source-id/anchor bookkeeping for filters no other owner references is retired. Live streams for retired filters are torn down on the next EventSubscriber::next_batch call (dropping an Alloy subscription unsubscribes provider-side); events already in flight from them stop matching the merged interest set and are discarded.

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

Borrow the interests currently owned by owner.

impl<P, N> AlloySubscriber<P, N>

where P: Provider<N> + Send + Sync, N: Network + 'static, N::HeaderResponse: Send + 'static,

pub async fn establish_flashblocks_preflight( &mut self, expected_chain_id: u64, ) -> Result<FlashblocksPreflight, SubscriberError>

Validate one pinned OP Stack provider generation and establish its chain-specific Flashblocks surface.

The caller must register at least one active log interest first. The method requires a matching chain id and stable ProviderRef. Base additionally requires pubsub, newFlashblocks, and one pendingLogs acknowledgement per planned provider filter. Optimism probes the bounded pending block/log/receipt surface. op_supportedCapabilities is queried opportunistically and retained as opaque evidence because provider implementations do not expose a uniform capability vocabulary.

A successful return is deliberately not a liveness qualification. The acceptance window must still observe a Flashblock whose pending state advances and a correlated log for an active pool.

pub async fn reconcile_interest_owner( &mut self, epoch: &SubscriberOwnerEpoch, through: BlockRef, ) -> Result<SubscriberOwnerProgress, SubscriberOwnerError>

where P: Clone,

Subscribe first, then catch an exact staged owner up through a verified canonical block.

This compatibility wrapper delegates to reconcile_interest_owners, so a driver adopting several owners should call the bulk API once rather than invoking this method in a loop.

Errors

Returns SubscriberOwnerError when the epoch is not staged, lacks a baseline, conflicts/regresses, provider certification or transport fails, returned logs are invalid, or subscriber resources are exhausted.

pub async fn reconcile_interest_owners( &mut self, epochs: &[SubscriberOwnerEpoch], through: BlockRef, ) -> Result<Vec<SubscriberOwnerProgress>, SubscriberOwnerError>

where P: Clone,

Subscribe first, then atomically catch staged owners up through one verified canonical block.

All epochs are preflighted before provider I/O. Live streams are reconciled once, compatible provider filters are merged into bounded chunks, and every historical request shares one double target-header certification. Provider-filter supersets are routed back through each owner’s exact interests, retaining owner-scoped delivery provenance. Duplicate epoch tokens in epochs are coalesced in first-seen order.

Live events are continuously drained while an independent provider clone performs catch-up. Fetched owner records and progress become visible only after every request and the final certification succeed. A failure leaves every target staged with its prior progress unchanged; live canonical delivery consumed during the attempt is preserved while excluding the failed target epochs from its staged-owner audience.

Errors

Returns SubscriberOwnerError when an epoch is not staged, lacks a baseline, conflicts/regresses, provider certification or transport fails, returned logs are invalid, or subscriber resources are exhausted. Target progress remains unchanged on error.

pub async fn next_scoped_batch_or<C, F>( &mut self, control: Pin<&mut F>, ) -> Result<SubscriberDriverPoll<C, N>, SubscriberError>

where C: Send, F: Future<Output = C> + Send,

Poll one driver control future with priority over the next scoped batch.

This is the supported control-interleaving primitive for a subscriber driver. control is borrowed rather than consumed, so a batch win leaves the caller’s pending control future alive. When control wins, the in-progress subscriber poll is cancelled at a documented safe boundary: queued records are removed only when a complete batch is returned, successful backfill steps are committed before the next await, provider streams created but not installed are dropped, and installed streams remain owned by the subscriber for the next call.

The control future is polled first. Therefore a ready shutdown/removal command cannot starve behind a continuously ready subscriber queue.

Errors

Returns SubscriberError when the subscriber poll encounters a transport, continuity, decoding, configuration, or resource failure.

pub fn next_scoped_batch(&mut self) -> SubscriberNextScopedBatch<'_, N>

Return the next subscriber batch while retaining staged-owner delivery provenance captured at enqueue time.

Transaction-aware drivers must use this method. The compatibility EventSubscriber::next_batch method flattens the same queue and keeps its historical behavior for existing callers.

For command interleaving, prefer next_scoped_batch_or, which preserves the cancellation-safety invariants of this poll and prioritizes ready control.

Trait Implementations

impl<P, N> EventSubscriber<N> for AlloySubscriber<P, N>

where P: Provider<N> + Send + Sync, N: Network + 'static, N::HeaderResponse: Send + 'static,

fn chain_id(&self) -> Option<u64>

Chain identity attached to emitted records, when it has been resolved.

fn capabilities(&self) -> SubscriberCapabilities

Behaviors this subscriber can uphold for topology validation.

fn register_interests( &mut self, interests: &[ReactiveInterest<N>], ) -> SubscriberOperation<'_, ()>

Replace all interests registered with the subscriber.

fn next_batch(&mut self) -> SubscriberNextBatch<'_, N>

Return the next input batch, or Ok(None) when the stream is exhausted.

fn restore_position( &mut self, _position: &SubscriberResumePosition, ) -> Result<(), SubscriberError>

Restore the subscriber’s committed position before polling resumes.

fn acknowledge_delivery( &mut self, _token: SubscriberDeliveryToken, ) -> SubscriberOperation<'_, ()>

Commit a subscriber-owned delivery token after runtime ingestion.

impl<P, N> InterestOwnerSubscriber<N> for AlloySubscriber<P, N>

where P: Provider<N> + Send + Sync, N: Network + 'static, N::HeaderResponse: Send + 'static,

fn upsert_interest_owners( &mut self, owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>, ) -> SubscriberOperation<'_, ()>

Atomically add or replace several owners in one desired-state revision.

fn replace_interest_owners( &mut self, owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>, ) -> SubscriberOperation<'_, ()>

Atomically replace the complete engine-managed owner topology without requesting history.

fn replace_interest_owners_with_global_backfill( &mut self, owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>, backfill: SubscriberBackfill, ) -> SubscriberOperation<'_, ()>

Atomically replace the complete owner set and schedule one global historical log backfill in the same desired-state revision.

fn add_interest_owner( &mut self, owner: HandlerId, interests: &[ReactiveInterest<N>], ) -> SubscriberOperation<'_, ()>

Add or replace the interests owned by owner, awaiting the subscriber’s commit boundary.

fn add_interest_owner_with_backfill( &mut self, owner: HandlerId, interests: &[ReactiveInterest<N>], backfill: SubscriberBackfill, ) -> SubscriberOperation<'_, ()>

Add or replace owner interests and schedule log backfill for that owner, awaiting the subscriber’s commit boundary.

fn add_interest_owner_with_canonical_catchup( &mut self, owner: HandlerId, interests: &[ReactiveInterest<N>], retained: BlockRef, ) -> SubscriberOperation<'_, ()>

Add a handler discovered at retained canonical block C without opening a gap while registration commits.

fn remove_interest_owner( &mut self, owner: &HandlerId, ) -> SubscriberOperation<'_, Option<Vec<ReactiveInterest<N>>>>

Remove one owner’s interests, preserving unrelated interests, and await acknowledgement that the removal committed.

fn owner_interests(&self, owner: &HandlerId) -> Option<&[ReactiveInterest<N>]>

Borrow the interests currently owned by owner.