Crate event_scanner 

Event-Scanner is a library made to stream EVM event logs.

The main entry point is EventScanner, built via EventScannerBuilder in one of the supported modes (e.g. Historic or Live).

Node compatibility

Event Scanner’s test suite and examples are exercised against Foundry’s anvil dev node.

While the library is intended to work with other EVM nodes and RPC providers, behaviour may vary across implementations. If you encounter errors when using a different node/provider, please report them at https://github.com/OpenZeppelin/Event-Scanner/issues.

After constructing a scanner, register one or more event subscriptions with EventScanner::subscribe, then call EventScanner::start to begin streaming.

Stream items

Each subscription yields an EventScannerResult. Successful items are Message values, which wrap either event batches or a Notification (see ScannerMessage).

Ordering

Ordering is preserved per subscription stream. There is no global ordering guarantee across different subscriptions.

Reorgs and finality

When scanning non-finalized blocks, the scanner may detect chain reorganizations and will emit Notification::ReorgDetected. Consumers should assume the same events might be delivered more than once around reorgs (i.e. benign duplicates are possible).

BlockNumberOrTag::Finalized is treated as the authoritative finality boundary when the scanner needs one. In live mode, block_confirmations delays emission to reduce the chance that already-emitted blocks are affected by shallow reorganizations.

Dedupe vs rollback

Event-Scanner does not include a built-in deduplication utility. Depending on your application, you can:

• Implement idempotency/deduplication (for example, keyed by transaction hash and log index, optionally including block hash).
• Handle reorgs by rollback: interpret Notification::ReorgDetected as a signal to revert application state for blocks after the reported common ancestor.

Backpressure and lag

Streams are buffered. If a consumer cannot keep up and an internal broadcast receiver lags, the subscription stream yields ScannerError::Lagged.

Re-exports

pub use block_range_scanner::BlockRangeScanner;

pub use block_range_scanner::BlockRangeScannerBuilder;

pub use block_range_scanner::BlockScannerResult;

pub use block_range_scanner::DEFAULT_BLOCK_CONFIRMATIONS;

pub use block_range_scanner::DEFAULT_MAX_BLOCK_RANGE;

pub use block_range_scanner::DEFAULT_STREAM_BUFFER_CAPACITY;

pub use block_range_scanner::ReorgHandler;

pub use block_range_scanner::RingBufferCapacity;

pub use block_range_scanner::RingBufferCapacity as PastBlocksStorageCapacity;

Modules

block_range_scanner

macros

Macros

assert_closed

assert_empty

assert_event_sequence

Asserts that a stream emits a specific sequence of events in order.

assert_event_sequence_final

Same as assert_event_sequence!, but invokes assert_empty! at the end.

assert_next

assert_range_coverage

Asserts that a stream of block ranges completely covers an expected block range.

Structs

EventFilter

Type representing filters to apply when fetching events from the chain.

EventScanner

An event scanner configured in mode Mode and bound to network N.

EventScannerBuilder

Builder for constructing an EventScanner in a particular mode.

EventSubscription

A subscription to scanner events that requires proof the scanner has started.

Historic

Mode marker for historical range scanning.

LatestEvents

Mode marker for latest-events collection.

LatestEventsHandler

Collects the latest count logs per listener before streaming them.

Live

Mode marker for live streaming.

StartProof

Proof that the scanner has been started.

StreamHandler

Streams logs to listeners as soon as each scanned block range is processed.

SyncFromBlock

Mode marker for scanning by syncing from the specified block and then switching to live mode.

SyncFromLatestEvents

Mode marker for scanning by syncing from the specified count of latest events and then switching to live mode.

Enums

Notification

Notifications emitted by the scanner to signal state changes or important events.

ScannerError

Errors emitted by the scanner.

ScannerMessage

Messages streamed by the scanner to subscribers.

Constants

DEFAULT_MAX_CONCURRENT_FETCHES

Default number of maximum concurrent fetches for each scanner mode.

Traits

BlockRangeHandler

Handles a stream of scanned block ranges.

Type Aliases

EventScannerResult

The Result type yielded by event subscription streams.

Message

The item type yielded by event subscription streams.