Merge branch 'main' into reorg-live-mode

Author: LeoPatOZ

.github/CODEOWNERS

@@ -1 +1,2 @@
-*       @LeoPatOZ @0xNeshi @pepebndc
+* @LeoPatOZ @0xNeshi @pepebndc
+SECURITY.md @LeoPatOZ @0xNeshi @pepebndc @OpenZeppelin/product-security

.github/workflows/scorecard.yml

@@ -0,0 +1,57 @@
+---
+# This workflow uses actions that are not certified by GitHub. They are provided
+# by a third-party and are governed by separate terms of service, privacy
+# policy, and support documentation.
+name: Scorecard supply-chain security
+on:
+  # For Branch-Protection check. Only the default branch is supported. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
+  branch_protection_rule:
+  # To guarantee Maintained check is occasionally updated. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
+  schedule:
+    - cron: 15 21 * * 4
+  push:
+    branches:
+      - main
+# Declare default permissions as read only.
+permissions: read-all
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+      # comment the permissions below if installing in a public repository.
+      # contents: read
+      # actions: read
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49  # v2.12.2
+        with:
+          egress-policy: audit
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.5.4
+        with:
+          persist-credentials: false
+      - name: Run analysis
+        uses: ossf/scorecard-action@05b42c624433fc40578a4040d5cf5e36ddca8cde  # v2.4.2
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
+      # format to the repository Actions tab.
+      - name: Upload artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+      - name: Upload SARIF to GitHub Code Scanning
+        uses: github/codeql-action/upload-sarif@51f77329afa6477de8c49fc9c7046c15b9a4e79d  # v3.29.5
+        with:
+          sarif_file: results.sarif

CONTRIBUTING.md

@@ -6,7 +6,7 @@ Thanks for your interest in contributing! This guide explains how to set up your
 
 ## Project Overview
 
-`event-scanner` is a Rust library for monitoring EVM-based smart contract events. It is built on the `alloy` ecosystem and provides in-memory scanning with retry-aware callback execution. See `README.md` for features, usage, examples, and testing notes.
+`event-scanner` is a Rust library for monitoring and streaming EVM-based smart contract events. It is built on the `alloy` ecosystem and provides in-memory scanning. See `README.md` for features, usage, examples, and testing notes.
 
 - Workspace manifest: `Cargo.toml`
 - Library code: `src/`

Cargo.lock

@@ -1,5 +1,7 @@
 # Event Scanner
 
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/OpenZeppelin/event-scanner/badge)](https://api.securityscorecards.dev/projects/github.com/OpenZeppelin/event-scanner)
+
 > ⚠️ **WARNING: ACTIVE DEVELOPMENT** ⚠️
 >
 > This project is under active development and likely contains bugs. APIs and behaviour may change without notice. Use at your own risk.
@@ -79,12 +81,12 @@ async fn run_scanner(ws_url: alloy::transports::http::reqwest::Url, contract: al
         .with_event(MyContract::SomeEvent::SIGNATURE)
         .with_callback(Arc::new(CounterCallback { processed: Arc::new(AtomicUsize::new(0)) }));
 
-    let mut scanner = EventScannerBuilder::new()
+    let mut client = EventScannerBuilder::new()
         .with_event_filter(filter)
         .connect_ws::<Ethereum>(ws_url)
         .await?;
 
-    scanner.start(BlockNumberOrTag::Latest, None).await?;
+    client.start_scanner(BlockNumberOrTag::Latest, None).await?;
     Ok(())
 }
 ```

README.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+Security vulnerabilities should be [disclosed](#reporting-a-vulnerability) to the [project maintainers](./.github/CODEOWNERS), or alternatively by email to security@openzeppelin.com.
+
+## Supported Versions
+
+The following versions are currently supported and receive security updates. Alpha, Beta and Release candidates will not receive security updates.
+
+Security patches will be released for the latest minor of a given major release. For example, if an issue is found in versions >=1.13.0 and the latest is 1.14.0, the patch will be released only in version 1.14.1.
+
+Only critical severity bug fixes will be backported to past major releases.
+
+| Version   | Supported          |
+| --------- | ------------------ |
+| >= 0.1.x  | :white_check_mark: |
+| <= 0.0.9  | :x:                |
+
+## Reporting a Vulnerability
+
+We're extremely grateful for security researchers and users that report vulnerabilities to us.
+All reports are thoroughly investigated by the project's security team.
+
+Vulnerabilities are reported privately via GitHub's [Security Advisories](https://docs.github.com/en/code-security/security-advisories) feature.
+Please use the following link to submit your vulnerability: [Report a vulnerability](https://github.com/openzeppelin/event-scanner/security/advisories/new)
+
+Please see
+[Privately reporting a security vulnerability](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability)
+for more information on how to submit a vulnerability using GitHub's interface.
+
+## Legal
+
+OpenZeppelin Event Scanner is made available under the GNU AGPL 3.0 License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including OpenZeppelin. Your use of the project is also governed by the terms found at www.openzeppelin.com/tos (the "Terms"). As set out in the Terms, you are solely responsible for any use of OpenZeppelin Even Scanner and you assume all risks associated with any such use. This Security Policy in no way evidences or represents an on-going duty by any contributor, including OpenZeppelin, to correct any flaws or alert you to all or any of the potential risks of utilizing the project.
+

SECURITY.md

@@ -14,9 +14,8 @@ path = "main.rs"
 alloy.workspace = true
 alloy-node-bindings.workspace = true
 tokio.workspace = true
+tokio-stream.workspace = true
 anyhow.workspace = true
-async-trait.workspace = true
 tracing.workspace = true
 tracing-subscriber.workspace = true
-hex.workspace = true
 event-scanner = { path = "../.." }

examples/historical_scanning/Cargo.toml

@@ -1,27 +1,16 @@
-use std::{sync::Arc, time::Duration};
+use std::time::Duration;
 
 use alloy::{
-    eips::BlockNumberOrTag, network::Ethereum, providers::ProviderBuilder, rpc::types::Log, sol,
-    sol_types::SolEvent,
+    eips::BlockNumberOrTag, network::Ethereum, providers::ProviderBuilder, sol, sol_types::SolEvent,
 };
 use alloy_node_bindings::Anvil;
-use async_trait::async_trait;
-use event_scanner::{EventCallback, EventFilter, event_scanner::EventScannerBuilder};
+use event_scanner::{EventFilter, event_scanner::EventScanner};
 
 use tokio::time::sleep;
+use tokio_stream::StreamExt;
 use tracing::info;
 use tracing_subscriber::EnvFilter;
 
-struct CounterCallback;
-
-#[async_trait]
-impl EventCallback for CounterCallback {
-    async fn on_event(&self, log: &Log) -> anyhow::Result<()> {
-        info!("Callback successfully executed with event {:?}", log.inner.data);
-        Ok(())
-    }
-}
-
 sol! {
     #[allow(missing_docs)]
     #[sol(rpc, bytecode="608080604052346015576101b0908161001a8239f35b5f80fdfe6080806040526004361015610012575f80fd5b5f3560e01c90816306661abd1461016157508063a87d942c14610145578063d732d955146100ad5763e8927fbc14610048575f80fd5b346100a9575f3660031901126100a9575f5460018101809111610095576020817f7ca2ca9527391044455246730762df008a6b47bbdb5d37a890ef78394535c040925f55604051908152a1005b634e487b7160e01b5f52601160045260245ffd5b5f80fd5b346100a9575f3660031901126100a9575f548015610100575f198101908111610095576020817f53a71f16f53e57416424d0d18ccbd98504d42a6f98fe47b09772d8f357c620ce925f55604051908152a1005b60405162461bcd60e51b815260206004820152601860248201527f436f756e742063616e6e6f74206265206e6567617469766500000000000000006044820152606490fd5b346100a9575f3660031901126100a95760205f54604051908152f35b346100a9575f3660031901126100a9576020905f548152f3fea2646970667358221220b846b706f79f5ae1fc4a4238319e723a092f47ce4051404186424739164ab02264736f6c634300081e0033")]
@@ -61,18 +50,22 @@ async fn main() -> anyhow::Result<()> {
 
     let increase_filter = EventFilter::new()
         .with_contract_address(*contract_address)
-        .with_event(Counter::CountIncreased::SIGNATURE)
-        .with_callback(Arc::new(CounterCallback));
+        .with_event(Counter::CountIncreased::SIGNATURE);
 
     let _ = counter_contract.increase().send().await?.get_receipt().await?;
 
-    let mut scanner = EventScannerBuilder::new()
-        .with_event_filter(increase_filter)
-        .connect_ws::<Ethereum>(anvil.ws_endpoint_url())
-        .await?;
+    let mut client = EventScanner::new().connect_ws::<Ethereum>(anvil.ws_endpoint_url()).await?;
+
+    let mut stream = client.create_event_stream(increase_filter);
 
     sleep(Duration::from_secs(10)).await;
-    scanner.start(BlockNumberOrTag::Number(0), None).await.expect("failed to start scanner");
+    client.start_scanner(BlockNumberOrTag::Number(0), None).await.expect("failed to start scanner");
+
+    while let Some(Ok(logs)) = stream.next().await {
+        for log in logs {
+            info!("Callback successfully executed with event {:?}", log.inner.data);
+        }
+    }
 
     Ok(())
 }

examples/historical_scanning/main.rs

@@ -14,9 +14,8 @@ path = "main.rs"
 alloy.workspace = true
 alloy-node-bindings.workspace = true
 tokio.workspace = true
+tokio-stream.workspace = true
 anyhow.workspace = true
-async-trait.workspace = true
 tracing.workspace = true
 tracing-subscriber.workspace = true
-hex.workspace = true
 event-scanner = { path = "../.." }

examples/simple_counter/Cargo.toml

@@ -1,52 +1,42 @@
-use std::{sync::Arc, time::Duration};
+use std::time::Duration;
 
 use alloy::{
-    eips::BlockNumberOrTag, network::Ethereum, providers::ProviderBuilder, rpc::types::Log, sol,
-    sol_types::SolEvent,
+    eips::BlockNumberOrTag, network::Ethereum, providers::ProviderBuilder, sol, sol_types::SolEvent,
 };
 use alloy_node_bindings::Anvil;
-use async_trait::async_trait;
-use event_scanner::{EventCallback, EventFilter, event_scanner::EventScannerBuilder};
+use event_scanner::{EventFilter, event_scanner::EventScanner};
 
 use tokio::time::sleep;
+use tokio_stream::StreamExt;
 use tracing::info;
 use tracing_subscriber::EnvFilter;
 
-struct CounterCallback;
-
-#[async_trait]
-impl EventCallback for CounterCallback {
-    async fn on_event(&self, log: &Log) -> anyhow::Result<()> {
-        info!("Callback successfully executed with event {:?}", log.inner.data);
-        Ok(())
-    }
-}
-
 sol! {
     #[allow(missing_docs)]
     #[sol(rpc, bytecode="608080604052346015576101b0908161001a8239f35b5f80fdfe6080806040526004361015610012575f80fd5b5f3560e01c90816306661abd1461016157508063a87d942c14610145578063d732d955146100ad5763e8927fbc14610048575f80fd5b346100a9575f3660031901126100a9575f5460018101809111610095576020817f7ca2ca9527391044455246730762df008a6b47bbdb5d37a890ef78394535c040925f55604051908152a1005b634e487b7160e01b5f52601160045260245ffd5b5f80fd5b346100a9575f3660031901126100a9575f548015610100575f198101908111610095576020817f53a71f16f53e57416424d0d18ccbd98504d42a6f98fe47b09772d8f357c620ce925f55604051908152a1005b60405162461bcd60e51b815260206004820152601860248201527f436f756e742063616e6e6f74206265206e6567617469766500000000000000006044820152606490fd5b346100a9575f3660031901126100a95760205f54604051908152f35b346100a9575f3660031901126100a9576020905f548152f3fea2646970667358221220b846b706f79f5ae1fc4a4238319e723a092f47ce4051404186424739164ab02264736f6c634300081e0033")]
-contract Counter {
-    uint256 public count;
+    contract Counter {
+        uint256 public count;
 
-    event CountIncreased(uint256 newCount);
-    event CountDecreased(uint256 newCount);
+        event CountIncreased(uint256 newCount);
+        event CountDecreased(uint256 newCount);
 
-    function increase() public {
-        count += 1;
-        emit CountIncreased(count);
-    }
+        function increase() public {
+            count += 1;
+            emit CountIncreased(count);
+        }
 
-    function decrease() public {
-        require(count > 0, "Count cannot be negative");
-        count -= 1;
-        emit CountDecreased(count);
-    }
+        function decrease() public {
+            require(count > 0, "Count cannot be negative");
+            count -= 1;
+            emit CountDecreased(count);
+        }
 
-    function getCount() public view returns (uint256) {
-        return count;
+        function getCount() public view returns (uint256) {
+            return count;
+        }
     }
 }
-}
+
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
     let _ = tracing_subscriber::fmt().with_env_filter(EnvFilter::from_default_env()).try_init();
@@ -61,16 +51,17 @@ async fn main() -> anyhow::Result<()> {
 
     let increase_filter = EventFilter::new()
         .with_contract_address(*contract_address)
-        .with_event(Counter::CountIncreased::SIGNATURE)
-        .with_callback(Arc::new(CounterCallback));
+        .with_event(Counter::CountIncreased::SIGNATURE);
+
+    let mut client = EventScanner::new().connect_ws::<Ethereum>(anvil.ws_endpoint_url()).await?;
 
-    let mut scanner = EventScannerBuilder::new()
-        .with_event_filter(increase_filter)
-        .connect_ws::<Ethereum>(anvil.ws_endpoint_url())
-        .await?;
+    let mut stream = client.create_event_stream(increase_filter);
 
     let task_1 = tokio::spawn(async move {
-        scanner.start(BlockNumberOrTag::Latest, None).await.expect("failed to start scanner");
+        client
+            .start_scanner(BlockNumberOrTag::Latest, None)
+            .await
+            .expect("failed to start scanner");
     });
 
     let task_2 = tokio::spawn(async move {
@@ -83,6 +74,12 @@ async fn main() -> anyhow::Result<()> {
         }
     });
 
+    while let Some(Ok(logs)) = stream.next().await {
+        for log in logs {
+            info!("Callback successfully executed with event {:?}", log.inner.data);
+        }
+    }
+
     task_1.await.ok();
     task_2.await.ok();