event_scanner/lib.rs
1//! Event-Scanner is a library made to stream EVM event logs.
2//!
3//! The main entry point is [`EventScanner`], built via [`EventScannerBuilder`] in one of the
4//! supported modes (e.g. [`Historic`] or [`Live`]).
5//!
6//! # Node compatibility
7//!
8//! Event Scanner's test suite and examples are exercised against Foundry's [anvil][anvil] dev node.
9//!
10//! While the library is intended to work with other EVM nodes and RPC providers, behaviour may
11//! vary across implementations. If you encounter errors when using a different node/provider,
12//! please report them at <https://github.com/OpenZeppelin/Event-Scanner/issues>.
13//!
14//! After constructing a scanner, register one or more event subscriptions with
15//! [`EventScanner::subscribe`], then call [`EventScanner::start`] to begin streaming.
16//!
17//! # Stream items
18//!
19//! Each subscription yields an [`EventScannerResult`]. Successful items are [`Message`] values,
20//! which wrap either event batches or a [`Notification`] (see [`ScannerMessage`]).
21//!
22//! # Ordering
23//!
24//! Ordering is preserved *per subscription stream*. There is no global ordering guarantee across
25//! different subscriptions.
26//!
27//! # Reorgs and finality
28//!
29//! When scanning non-finalized blocks, the scanner may detect chain reorganizations and will emit
30//! [`Notification::ReorgDetected`]. Consumers should assume the same events might be delivered more
31//! than once around reorgs (i.e. benign duplicates are possible).
32//!
33//! [`BlockNumberOrTag::Finalized`][finalized] is treated as the authoritative finality boundary
34//! when the scanner needs one. In live mode, `block_confirmations` delays emission to reduce the
35//! chance that already-emitted blocks are affected by shallow reorganizations.
36//!
37//! # Dedupe vs rollback
38//!
39//! Event-Scanner does not include a built-in deduplication utility. Depending on your
40//! application, you can:
41//!
42//! - **Implement idempotency/deduplication** (for example, keyed by transaction hash and log index,
43//! optionally including block hash).
44//! - **Handle reorgs by rollback**: interpret [`Notification::ReorgDetected`] as a signal to revert
45//! application state for blocks after the reported common ancestor.
46//!
47//! # Backpressure and lag
48//!
49//! Streams are buffered. If a consumer cannot keep up and an internal broadcast receiver lags,
50//! the subscription stream yields [`ScannerError::Lagged`].
51//!
52//! [finalized]: alloy::eips::BlockNumberOrTag::Finalized
53//! [anvil]: https://github.com/foundry-rs/foundry?tab=readme-ov-file#anvil
54
55#[macro_use]
56pub mod macros;
57
58pub mod block_range_scanner;
59
60mod error;
61mod event_scanner;
62mod types;
63
64pub use block_range_scanner::{
65 BlockRangeScanner, BlockRangeScannerBuilder, BlockScannerResult, DEFAULT_BLOCK_CONFIRMATIONS,
66 DEFAULT_MAX_BLOCK_RANGE, DEFAULT_STREAM_BUFFER_CAPACITY, ReorgHandler, RingBufferCapacity,
67 RingBufferCapacity as PastBlocksStorageCapacity,
68};
69
70pub use error::ScannerError;
71pub use types::{Notification, ScannerMessage};
72
73pub use event_scanner::{
74 DEFAULT_MAX_CONCURRENT_FETCHES, EventFilter, EventScanner, EventScannerBuilder,
75 EventScannerResult, EventSubscription, Historic, LatestEvents, Live, Message, StartProof,
76 SyncFromBlock, SyncFromLatestEvents,
77 block_range_handler::{BlockRangeHandler, LatestEventsHandler, StreamHandler},
78};