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. 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 mode(&self) -> SubscriberMode

Subscriber mode.

pub fn config(&self) -> &SubscriberConfig

Subscriber config.

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.

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.

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 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).

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.

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 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.

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.

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.

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 register_interests( &mut self, interests: &[ReactiveInterest<N>], ) -> Result<(), SubscriberError>

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.

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

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

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

Add or replace the interests owned by owner.

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.

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

Remove one owner’s interests, preserving unrelated interests.

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

Borrow the interests currently owned by owner.