@@ -20,35 +20,14 @@ impl SyncScannerBuilder {
2020/// transitions to live streaming mode.
2121///
2222/// This method combines two scanning phases into a single operation:
23+ ///
2324/// 1. **Latest events phase**: Collects up to `count` most recent events by scanning backwards
2425/// from the current chain tip
25- /// 2. **Automatic transition**: Emits [`ScannerStatus::SwitchingToLive`] to signal the mode
26- /// change
26+ /// 2. **Automatic transition**: Emits [`ScannerStatus::SwitchingToLive`][switch_to_live] to
27+ /// signal the mode change
2728/// 3. **Live streaming phase**: Continuously monitors and streams new events as they arrive
2829/// on-chain
2930///
30- /// # How it works
31- ///
32- /// The scanner captures the latest block number before starting to establish a clear boundary
33- /// between phases. The historical phase scans from `Earliest` to `latest_block`, while the
34- /// live phase starts from `latest_block + 1`. This design prevents duplicate events and
35- /// handles race conditions where new blocks arrive during setup.
36- ///
37- /// # Key behaviors
38- ///
39- /// - **No duplicates**: Events are not delivered twice across the phase transition
40- /// - **Flexible count**: If fewer than `count` events exist, returns all available events
41- /// - **Reorg handling**: Both phases handle reorgs appropriately:
42- /// - Historical phase: resets and rescans on reorg detection
43- /// - Live phase: resets stream to the first post-reorg block that satisfies the block
44- /// confirmations set via [`block_confirmations`](Self::block_confirmations)
45- /// - **Continuous operation**: Live phase continues indefinitely until the scanner is dropped
46- ///
47- /// # Arguments
48- ///
49- /// * `count` - Maximum number of recent events to collect per listener before switching to live
50- /// streaming
51- ///
5231/// # Example
5332///
5433/// ```no_run
@@ -88,26 +67,50 @@ impl SyncScannerBuilder {
8867/// # }
8968/// ```
9069///
70+ /// # How it works
71+ ///
72+ /// The scanner captures the latest block number before starting to establish a clear boundary
73+ /// between phases. The historical phase scans from genesis block to the current latest block,
74+ /// while the live phase starts from the block after the latest block. This design prevents
75+ /// duplicate events and handles race conditions where new blocks arrive during setup.
76+ ///
77+ /// # Key behaviors
78+ ///
79+ /// - **No duplicates**: Events are not delivered twice across the phase transition
80+ /// - **Flexible count**: If fewer than `count` events exist, returns all available events
81+ /// - **Reorg handling**: Both phases handle reorgs appropriately:
82+ /// - Historical phase: resets and rescans on reorg detection
83+ /// - Live phase: resets stream to the first post-reorg block that satisfies the configured
84+ /// block confirmations
85+ /// - **Continuous operation**: Live phase continues indefinitely until the scanner is dropped
86+ ///
87+ /// # Arguments
88+ ///
89+ /// * `count` - Maximum number of recent events to collect per listener before switching to live
90+ /// streaming
91+ ///
9192/// # Important notes
9293///
93- /// - Register event streams via [`subscribe`](Self::subscribe) **before** calling
94- /// [`start`](Self::start)
95- /// - The [`start`](Self::start) method returns immediately; events are delivered asynchronously
94+ /// - Register event streams via [`scanner.subscribe(filter)`][subscribe] **before** calling
95+ /// [`scanner.start()`][start]
96+ /// - The [`scanner.start()`][start] method returns immediately; events are delivered
97+ /// asynchronously
9698/// - The live phase continues indefinitely until the scanner is dropped or encounters an error
9799///
98100/// # Detailed reorg behavior
99101///
100- /// - **Historical rewind phase**: Reverse-ordered rewind over `Earliest..=latest_block`. On
101- /// detecting a reorg, emits [`ScannerStatus::ReorgDetected`], resets the rewind start to the
102- /// new tip, and continues until collectors accumulate `count` logs. Final delivery to
103- /// listeners preserves chronological order.
104- /// - **Live streaming phase**: Starts from `latest_block + 1` and respects block confirmations
105- /// configured via [`block_confirmations`](Self::block_confirmations). On reorg, emits
106- /// [`ScannerStatus::ReorgDetected`], adjusts the next confirmed window (possibly re-emitting
107- /// confirmed portions), and continues streaming.
108- ///
109- /// [`ScannerStatus::ReorgDetected`]: crate::types::ScannerStatus::ReorgDetected
110- /// [`ScannerStatus::SwitchingToLive`]: crate::types::ScannerStatus::SwitchingToLive
102+ /// - **Historical rewind phase**: Restart the scanner. On detecting a reorg, emits
103+ /// [`ScannerStatus::ReorgDetected`][reorg], resets the rewind start to the new tip, and
104+ /// continues until collectors accumulate `count` logs. Final delivery to listeners preserves
105+ /// chronological order.
106+ /// - **Live streaming phase**: Starts from `latest_block + 1` and respects the configured block
107+ /// confirmations. On reorg, emits [`ScannerStatus::ReorgDetected`][reorg], adjusts the next
108+ /// confirmed window (possibly re-emitting confirmed portions), and continues streaming.
109+ ///
110+ /// [subscribe]: from_latest::SyncFromLatestEventScanner::subscribe
111+ /// [start]: from_latest::SyncFromLatestEventScanner::start
112+ /// [reorg]: crate::types::ScannerStatus::ReorgDetected
113+ /// [switch_to_live]: crate::types::ScannerStatus::SwitchingToLive
111114#[ must_use]
112115 pub fn from_latest ( self , count : usize ) -> SyncFromLatestScannerBuilder {
113116 SyncFromLatestScannerBuilder :: new ( count)
0 commit comments