Merge branch 'main' into remove-config-params

Author: LeoPatOZ

.github/workflows/check.yml

@@ -100,4 +100,4 @@ jobs:
         uses: actions/checkout@ff7abcd0c3c05ccf6adc123a8cd1fd4fb30fb493
 
       - name: Check spelling of files in the workspace
-        uses: crate-ci/typos@7436548694def3314aacd93ed06c721b1f91ea04 # v1.37.2
+        uses: crate-ci/typos@80c8a4945eec0f6d464eaf9e65ed98ef085283d1 # v1.38.1

.github/workflows/scorecard.yml

@@ -52,6 +52,6 @@ jobs:
           path: results.sarif
           retention-days: 5
       - name: Upload SARIF to GitHub Code Scanning
-        uses: github/codeql-action/upload-sarif@64d10c13136e1c5bce3e5fbde8d4906eeaafc885  # v3.29.5
+        uses: github/codeql-action/upload-sarif@f443b600d91635bebf5b0d9ebc620189c0d6fba5  # v3.29.5
         with:
           sarif_file: results.sarif

.github/workflows/test.yml

@@ -34,7 +34,7 @@ jobs:
         uses: actions-rust-lang/setup-rust-toolchain@1780873c7b576612439a134613cc4cc74ce5538c # v1.15.2
 
       - name: Install Foundry
-        uses: foundry-rs/foundry-toolchain@82dee4ba654bd2146511f85f0d013af94670c4de # v1.4.0
+        uses: foundry-rs/foundry-toolchain@50d5a8956f2e319df19e6b57539d7e2acb9f8c1e # v1.5.0
 
       - name: Cache cargo-nextest binary
         id: cache-cargo-nextest
@@ -45,7 +45,7 @@ jobs:
 
       - name: Install cargo-nextest
         if: steps.cache-cargo-nextest.outputs.cache-hit != 'true'
-        uses: taiki-e/install-action@522492a8c115f1b6d4d318581f09638e9442547b # v2.62.21
+        uses: taiki-e/install-action@e7ef886cf8f69c25ecef6bbc2858a42e273496ec # v2.62.28
         with:
           tool: cargo-nextest
 

.gitignore

@@ -1,4 +1,3 @@
 /target
 /examples/**/target
 .DS_Store
-.vscode

.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "rust-analyzer.cargo.features": ["test-utils"],
+  "rust-analyzer.rustfmt.extraArgs": ["+nightly"]
+}

CONTRIBUTING.md

@@ -60,9 +60,9 @@ cargo build --locked --all-targets --all-features
 Run the test suite (we recommend nextest):
 
 ```bash
-cargo nextest run
+cargo nextest run --features test-utils
 # or
-cargo test
+cargo test --features test-utils
 ```
 
 Run examples:
@@ -123,7 +123,7 @@ cargo clippy --all-targets --all-features -- -D warnings -D clippy::pedantic
 typos
 
 # Tests (prefer nextest)
-cargo nextest run
+cargo nextest run --features test-utils
 ```
 
 ---
@@ -160,7 +160,7 @@ Key implementation details, trade-offs, and alternatives considered.
 - [ ] `cargo +nightly fmt --all --check`
 - [ ] `cargo clippy --all-targets --all-features -- -D warnings -D clippy::pedantic`
 - [ ] `typos`
-- [ ] Tests pass (`cargo nextest run`)
+- [ ] Tests pass (`cargo nextest run --features test-utils`)
 - [ ] Docs/README/examples updated (if applicable)
 ```
 

Cargo.lock

@@ -1,13 +1,18 @@
 [workspace]
-members = [".", "examples/historical_scanning", "examples/simple_counter"]
+members = [
+    ".",
+    "examples/historical_scanning",
+    "examples/simple_counter",
+    "examples/latest_events_scanning",
+]
 resolver = "2"
 
 [workspace.package]
 authors = ["OpenZeppelin"]
 edition = "2024"
 license = "AGPL-3.0-only"
 repository = "https://github.com/OpenZeppelin/Event-Scanner"
-version = "0.2.1-alpha"
+version = "0.3.0-alpha"
 
 [workspace.lints.clippy]
 pedantic = "warn"
@@ -63,3 +68,6 @@ tracing-subscriber.workspace = true
 
 [lints]
 workspace = true
+
+[features]
+test-utils = []

Cargo.toml

@@ -11,6 +11,7 @@
 Event Scanner is a Rust library for streaming EVM-based smart contract events. It is built on top of the [`alloy`](https://github.com/alloy-rs/alloy) ecosystem and focuses on in-memory scanning without a backing database. Applications provide event filters; the scanner takes care of fetching historical ranges, bridging into live streaming mode, all whilst delivering the events as streams of data.
 
 ---
+ 
 
 ## Table of Contents
 
@@ -21,7 +22,7 @@ Event Scanner is a Rust library for streaming EVM-based smart contract events. I
   - [Building a Scanner](#building-a-scanner)
   - [Defining Event Filters](#defining-event-filters)
   - [Scanning Modes](#scanning-modes)
-  - [Working with Callbacks](#working-with-callbacks)
+  - [Scanning Latest Events](#scanning-latest-events)
 - [Examples](#examples)
 - [Testing](#testing)
 
@@ -32,6 +33,7 @@ Event Scanner is a Rust library for streaming EVM-based smart contract events. I
 - **Historical replay** – stream events from past block ranges.
 - **Live subscriptions** – stay up to date with latest events via WebSocket or IPC transports.
 - **Hybrid flow** – automatically transition from historical catch-up into streaming mode.
+- **Latest events fetch** – one-shot rewind to collect the most recent matching logs.
 - **Composable filters** – register one or many contract + event signature pairs.
 - **No database** – processing happens in-memory; persistence is left to the host application.
 
@@ -52,7 +54,7 @@ Add `event-scanner` to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-event-scanner = "0.2.1-alpha"
+event-scanner = "0.3.0-alpha"
 ```
 
 Create an event stream for the given event filters registered with the `EventScanner`:
@@ -181,12 +183,63 @@ The flexibility provided by `EventFilter` allows you to build sophisticated even
 
 See integration tests under `tests/live_mode`, `tests/historic_mode`, and `tests/historic_to_live` for concrete examples.
 
+### Scanning Latest Events
+
+`scan_latest` collects the most recent matching events for each registered stream.
+
+- It does not enter live mode; it scans a block range and then returns.
+- Each registered stream receives at most `count` logs in a single message, chronologically ordered.
+
+Basic usage:
+
+```rust
+use alloy::{eips::BlockNumberOrTag, network::Ethereum};
+use event_scanner::{EventFilter, event_scanner::{EventScanner, EventScannerMessage}};
+use tokio_stream::StreamExt;
+
+async fn latest_example(ws_url: alloy::transports::http::reqwest::Url, addr: alloy::primitives::Address) -> eyre::Result<()> {
+    let mut client = EventScanner::new().connect_ws::<Ethereum>(ws_url).await?;
+
+    let filter = EventFilter::new().with_contract_address(addr);
+    let mut stream = client.create_event_stream(filter);
+
+    // Collect the latest 10 events across Earliest..=Latest
+    client.scan_latest(10).await?;
+
+    // Expect a single message with up to 10 logs, then the stream ends
+    while let Some(msg) = stream.next().await {
+        if let EventScannerMessage::Data(logs) = msg {
+            println!("Latest logs: {}", logs.len());
+        }
+    }
+
+    Ok(())
+}
+```
+
+Restricting to a specific block range:
+
+```rust
+// Collect the latest 5 events between blocks [1_000_000, 1_100_000]
+client
+    .scan_latest_in_range(5, BlockNumberOrTag::Number(1_000_000), BlockNumberOrTag::Number(1_100_000))
+    .await?;
+```
+
+The scanner periodically checks the tip to detect reorgs. On reorg, the scanner emits `ScannerStatus::ReorgDetected`, resets to the updated tip, and restarts the scan. Final delivery to log listeners is in chronological order.
+
+Notes:
+
+- Ensure you create streams via `create_event_stream()` before calling `scan_latest*` so listeners are registered.
+<!-- TODO: uncomment once implemented - The function returns after delivering the messages; to continuously stream new blocks, use `scan_latest_then_live`. -->
+
 ---
 
 ## Examples
 
 - `examples/simple_counter` – minimal live-mode scanner using `EventScanner::live()`
 - `examples/historical_scanning` – demonstrates replaying historical data using `EventScanner::historic()`
+- `examples/latest_events_scanning` – demonstrates scanning the latest events using `EventScanner::latest()`
 
 Run an example with:
 
@@ -202,10 +255,11 @@ Both examples spin up a local `anvil` instance, deploy a demo counter contract,
 
 ## Testing
 
-Integration tests cover live, historical, and hybrid flows:
 (We recommend using [nextest](https://crates.io/crates/cargo-nextest) to run the tests)
 
+Integration tests cover all modes:
+
 ```bash
-cargo nextest run
+cargo nextest run --features test-utils
 ```
 

README.md

@@ -0,0 +1,21 @@
+[package]
+name = "latest_events_scanning"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+publish = false
+
+[[bin]]
+name = "latest_events_scanning"
+path = "main.rs"
+
+[dependencies]
+alloy.workspace = true
+alloy-node-bindings.workspace = true
+tokio.workspace = true
+tokio-stream.workspace = true
+anyhow.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true
+event-scanner = { path = "../.." }