Bump version to 0.9.0-alpha + add parallelism-related docs (#255)

Author: 0xNeshi

Cargo.lock

@@ -14,7 +14,7 @@ authors = ["OpenZeppelin"]
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/OpenZeppelin/Event-Scanner"
-version = "0.8.0-alpha"
+version = "0.9.0-alpha"
 
 [workspace.lints.clippy]
 pedantic = "warn"

Cargo.toml

@@ -53,7 +53,7 @@ Add `event-scanner` to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-event-scanner = "0.8.0-alpha"
+event-scanner = "0.9.0-alpha"
 ```
 
 Create an event stream for the given event filters registered with the `EventScanner`:

README.md

@@ -21,37 +21,42 @@ mod latest;
 mod live;
 mod sync;
 
-/// Maximum number of concurrent fetches for block ranges in the current scanner mode.
+/// Default number of maximum concurrent fetches for each scanner mode.
 pub const DEFAULT_MAX_CONCURRENT_FETCHES: usize = 24;
 
 #[derive(Default)]
 pub struct Unspecified;
 pub struct Historic {
     pub(crate) from_block: BlockId,
     pub(crate) to_block: BlockId,
+    /// Controls how many log-fetching RPC requests can run in parallel during the scan.
     pub(crate) max_concurrent_fetches: usize,
 }
 pub struct Live {
     pub(crate) block_confirmations: u64,
+    /// Controls how many log-fetching RPC requests can run in parallel during the scan.
     pub(crate) max_concurrent_fetches: usize,
 }
 pub struct LatestEvents {
     pub(crate) count: usize,
     pub(crate) from_block: BlockId,
     pub(crate) to_block: BlockId,
     pub(crate) block_confirmations: u64,
+    /// Controls how many log-fetching RPC requests can run in parallel during the scan.
     pub(crate) max_concurrent_fetches: usize,
 }
 #[derive(Default)]
 pub struct Synchronize;
 pub struct SyncFromLatestEvents {
     pub(crate) count: usize,
     pub(crate) block_confirmations: u64,
+    /// Controls how many log-fetching RPC requests can run in parallel during the scan.
     pub(crate) max_concurrent_fetches: usize,
 }
 pub struct SyncFromBlock {
     pub(crate) from_block: BlockId,
     pub(crate) block_confirmations: u64,
+    /// Controls how many log-fetching RPC requests can run in parallel during the scan.
     pub(crate) max_concurrent_fetches: usize,
 }
 
@@ -138,18 +143,24 @@ impl EventScannerBuilder<Unspecified> {
     ///
     /// The scanner streams events in chronological order (oldest to newest) within the specified
     /// block range. Events are delivered in batches as they are fetched from the provider, with
-    /// batch sizes controlled by the `max_block_range` configuration.
+    /// batch sizes controlled by the [`max_block_range`][max_block_range] configuration.
     ///
     /// # Key behaviors
     ///
     /// * **Continuous streaming**: Events are delivered in multiple messages as they are fetched
     /// * **Chronological order**: Events are always delivered oldest to newest
+    /// * **Concurrent log fetching**: Logs are fetched concurrently to reduce the execution time.
+    ///   The maximum number of concurrent RPC calls is controlled by
+    ///   [`max_concurrent_fetches`][max_concurrent_fetches]
     /// * **Default range**: By default, scans from `Earliest` to `Latest` block
-    /// * **Batch control**: Use `.max_block_range(n)` to control how many blocks are queried per
-    ///   RPC call
+    /// * **Batch control**: Use [`max_block_range`][max_block_range] to control how many blocks are
+    ///   queried per RPC call
     /// * **Reorg handling**: Performs reorg checks when streaming events from non-finalized blocks;
     ///   if a reorg is detected, streams events from the reorged blocks
     /// * **Completion**: The scanner completes when the entire range has been processed.
+    ///
+    /// [max_block_range]: crate::EventScannerBuilder::max_block_range
+    /// [max_concurrent_fetches]: crate::EventScannerBuilder::max_concurrent_fetches
     #[must_use]
     pub fn historic() -> EventScannerBuilder<Historic> {
         EventScannerBuilder::default()
@@ -308,6 +319,9 @@ impl EventScannerBuilder<Unspecified> {
     ///   message, chronologically ordered
     /// * **One-shot operation**: The scanner completes after delivering messages; it does not
     ///   continue streaming
+    /// * **Concurrent log fetching**: Logs are fetched concurrently to reduce the execution time.
+    ///   The maximum number of concurrent RPC calls is controlled by
+    ///   [`max_concurrent_fetches`][max_concurrent_fetches]
     /// * **Flexible count**: If fewer than `count` events exist in the range, returns all available
     ///   events
     /// * **Default range**: By default, scans from `Earliest` to `Latest` block
@@ -349,6 +363,7 @@ impl EventScannerBuilder<Unspecified> {
     /// [sync_from_latest]: EventScannerBuilder::from_latest
     /// [reorg]: crate::Notification::ReorgDetected
     /// [no_logs]: crate::Notification::NoPastLogsFound
+    /// [max_concurrent_fetches]: crate::EventScannerBuilder#method.max_concurrent_fetches-1
     #[must_use]
     pub fn latest(count: usize) -> EventScannerBuilder<LatestEvents> {
         EventScannerBuilder::<LatestEvents>::new(count)

src/event_scanner/scanner/mod.rs

@@ -73,6 +73,9 @@ impl EventScannerBuilder<Synchronize> {
     ///
     /// * **No duplicates**: Events are not delivered twice across the phase transition
     /// * **Flexible count**: If fewer than `count` events exist, returns all available events
+    /// * **Concurrent log fetching**: Logs are fetched concurrently to reduce the sync phase
+    ///   execution time. The maximum number of concurrent RPC calls is controlled by
+    ///   [`max_concurrent_fetches`][max_concurrent_fetches]
     /// * **Reorg handling**: Both phases handle reorgs appropriately:
     ///   - Latest events phase: resets and rescans on reorg detection
     ///   - Live phase: resets stream to the first post-reorg block that satisfies the configured
@@ -114,6 +117,7 @@ impl EventScannerBuilder<Synchronize> {
     /// [reorg]: crate::types::Notification::ReorgDetected
     /// [switch_to_live]: crate::types::Notification::SwitchingToLive
     /// [no_logs]: crate::types::Notification::NoPastLogsFound
+    /// [max_concurrent_fetches]: crate::EventScannerBuilder#method.block_confirmations-4
     #[must_use]
     pub fn from_latest(self, count: usize) -> EventScannerBuilder<SyncFromLatestEvents> {
         EventScannerBuilder::<SyncFromLatestEvents>::new(count)
@@ -199,6 +203,9 @@ impl EventScannerBuilder<Synchronize> {
     ///
     /// * **No duplicates**: Events are not delivered twice across the phase transition
     /// * **Chronological order**: Historical events are delivered oldest to newest
+    /// * **Concurrent log fetching**: Logs are fetched concurrently to reduce the sync phase
+    ///   execution time. The maximum number of concurrent RPC calls is controlled by
+    ///   [`max_concurrent_fetches`][max_concurrent_fetches]
     /// * **Seamless transition**: Automatically switches to live mode when caught up
     /// * **Continuous operation**: Live phase continues indefinitely until the scanner is dropped
     /// * **Reorg detection**: When a reorg is detected, [`Notification::ReorgDetected`][reorg] is
@@ -217,6 +224,7 @@ impl EventScannerBuilder<Synchronize> {
     /// [start]: crate::event_scanner::EventScanner::start
     /// [reorg]: crate::types::Notification::ReorgDetected
     /// [switch_to_live]: crate::types::Notification::SwitchingToLive
+    /// [max_concurrent_fetches]: crate::EventScannerBuilder#method.block_confirmations-3
     #[must_use]
     pub fn from_block(self, block_id: impl Into<BlockId>) -> EventScannerBuilder<SyncFromBlock> {
         EventScannerBuilder::<SyncFromBlock>::new(block_id.into())