feat: support event sig hashes in filter

Author: 0xNeshi

src/event_filter.rs

@@ -1,6 +1,9 @@
 use std::fmt::{Debug, Display};
 
-use alloy::primitives::Address;
+use alloy::{
+    primitives::{Address, keccak256},
+    rpc::types::{Topic, ValueOrArray},
+};
 
 /// Type representing filters to apply when fetching events from the chain.
 ///
@@ -23,19 +26,34 @@ use alloy::primitives::Address;
 pub struct EventFilter {
     /// Contract address to filter events from. If None, events from all contracts will be tracked.
     pub(crate) contract_address: Option<Address>,
-    /// Human-readable event signature, e.g. "Transfer(address,address,uint256)".
-    /// If None, all events from the specified contract(s) will be tracked.
+    /// Human-readable event signatures, e.g. "Transfer(address,address,uint256)".
     pub(crate) events: Vec<String>,
+    /// Event signature hashes, e.g. `0x123...`.
+    pub(crate) event_signatures: Topic,
 }
 
 impl Display for EventFilter {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        let address =
-            self.contract_address.map_or("all contracts".to_string(), |addr| format!("{addr:?}"));
-        let events =
-            if self.events.is_empty() { "all events".to_string() } else { self.events.join(", ") };
+        let mut content = vec![];
+        if let Some(address) = &self.contract_address {
+            content.push(format!("contract: {address}"));
+        }
+        if !self.events.is_empty() {
+            content.push(format!("events: [{}]", self.events.join(", ")));
+        }
+        if !self.event_signatures.is_empty() {
+            // No guarantee the order of values returned by `Topic`
+            let value_or_array = self.event_signatures.to_value_or_array().unwrap();
+            let event_signatures = match value_or_array {
+                ValueOrArray::Value(value) => format!("{value}"),
+                ValueOrArray::Array(arr) => {
+                    arr.iter().map(|t| format!("{t}")).collect::<Vec<_>>().join(", ")
+                }
+            };
+            content.push(format!("event_signatures: [{event_signatures}]"));
+        }
 
-        write!(f, "EventFilter(contract: {address}, events: {events})")
+        write!(f, "EventFilter({})", content.join(", "))
     }
 }
 
@@ -61,106 +79,220 @@ impl EventFilter {
     }
 
     /// Sets the event signature to filter specific events.
-    /// If not set, all events from the specified contract(s) will be tracked.
+    /// If neither events nor event signature hashes are set, all events from the specified contract(s) will be tracked.
     #[must_use]
     pub fn with_event(mut self, event: impl Into<String>) -> Self {
-        self.events.push(event.into());
+        let event = event.into();
+        if !event.is_empty() {
+            self.events.push(event);
+        }
         self
     }
 
-    /// Sets the event signature to filter specific events.
-    /// If not set, all events from the specified contract(s) will be tracked.
+    /// Sets the event signatures to filter specific events.
+    /// If neither events nor event signature hashes are set, all events from the specified contract(s) will be tracked.
+    #[must_use]
+    pub fn with_events(mut self, events: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.events.extend(events.into_iter().map(Into::into));
+        self
+    }
+
+    /// Sets the event signature hash to filter specific events.
+    /// If neither event signature hashes nor events are set, all events from the specified contract(s) will be tracked.
     #[must_use]
-    pub fn with_events(mut self, events: impl IntoIterator<Item = String>) -> Self {
-        self.events.extend(events);
+    pub fn with_event_signature(mut self, event_signature: impl Into<Topic>) -> Self {
+        self.event_signatures = self.event_signatures.extend(event_signature.into());
         self
     }
+
+    /// Sets the event signature hashes to filter specific events.
+    /// If neither event signature hashes nor events are set, all events from the specified contract(s) will be tracked.
+    #[must_use]
+    pub fn with_event_signatures(
+        mut self,
+        event_signatures: impl IntoIterator<Item = impl Into<Topic>>,
+    ) -> Self {
+        for event_signature in event_signatures {
+            self.event_signatures = self.event_signatures.extend(event_signature);
+        }
+        self
+    }
+
+    /// Returns a [`Topic`] containing all event signature hashes.
+    /// If neither events nor event signature hashes are set, an empty [`Topic`] is returned.
+    #[must_use]
+    pub fn all_events(&self) -> Topic {
+        let events = self.events.iter().map(|e| keccak256(e.as_bytes())).collect::<Vec<_>>();
+        let sigs = self.event_signatures.clone();
+        let sigs = sigs.extend(events);
+        sigs
+    }
 }
 
 #[cfg(test)]
 mod tests {
     use super::EventFilter;
-    use alloy::primitives::{Address, address};
+    use alloy::{primitives::address, sol, sol_types::SolEvent};
 
-    fn addr_str(addr: Address) -> String {
-        format!("{:?}", addr)
+    sol! {
+        contract SomeContract {
+            event EventOne();
+            event EventTwo();
+        }
     }
 
     #[test]
     fn display_default_no_address_no_events() {
         let filter = EventFilter::new();
-        let got = format!("{}", filter);
-        let expected = "EventFilter(contract: all contracts, events: all events)";
+        let got = format!("{filter}");
+        let expected = "EventFilter()";
         assert_eq!(got, expected);
 
         // Debug should equal Display
-        assert_eq!(format!("{:?}", filter), got);
+        assert_eq!(format!("{filter:?}"), got);
     }
 
     #[test]
-    fn display_with_address_no_events() {
-        let address = address!("0xd8dA6BF26964af9d7eed9e03e53415d37aa96045");
+    fn display_with_address() {
+        let address = address!("0x000000000000000000000000000000000000dEaD");
         let filter = EventFilter::new().with_contract_address(address);
-        let got = format!("{}", filter);
-        let expected = format!("EventFilter(contract: {}, events: all events)", addr_str(address));
+        let got = format!("{filter}");
+        let expected = format!("EventFilter(contract: 0x000000000000000000000000000000000000dEaD)");
         assert_eq!(got, expected);
 
         // Debug should equal Display
-        assert_eq!(format!("{:?}", filter), got);
+        assert_eq!(format!("{filter:?}"), got);
     }
 
     #[test]
-    fn display_single_event_no_address() {
-        let event = "Transfer(address,address,uint256)";
+    fn display_single_event() {
+        let event = SomeContract::EventOne::SIGNATURE;
         let filter = EventFilter::new().with_event(event);
-        let got = format!("{}", filter);
-        let expected = format!("EventFilter(contract: all contracts, events: {})", event);
+        let got = format!("{filter}");
+        let expected = format!("EventFilter(events: [EventOne()])");
+        assert_eq!(got, expected);
+
+        // Debug should equal Display
+        assert_eq!(format!("{filter:?}"), got);
+    }
+
+    #[test]
+    fn display_single_event_signature() {
+        let event_signature = SomeContract::EventOne::SIGNATURE_HASH;
+        let filter = EventFilter::new().with_event_signature(event_signature);
+        let got = format!("{filter}");
+        let expected = format!(
+            "EventFilter(event_signatures: [0xa08dd6fd0d644da5df33d075cb9256203802f6948ab81b87079960711810dc91])"
+        );
         assert_eq!(got, expected);
 
         // Debug should equal Display
-        assert_eq!(format!("{:?}", filter), got);
+        assert_eq!(format!("{filter:?}"), got);
     }
 
     #[test]
     fn display_multiple_events_with_address() {
         let address = address!("0x000000000000000000000000000000000000dEaD");
-        let events = vec![
-            "Transfer(address,address,uint256)".to_string(),
-            "Approval(address,address,uint256)".to_string(),
-            "Sync(uint112,uint112)".to_string(),
-        ];
+        let events = vec![SomeContract::EventOne::SIGNATURE, SomeContract::EventTwo::SIGNATURE];
         let filter = EventFilter::new().with_contract_address(address).with_events(events.clone());
 
-        let got = format!("{}", filter);
-        let expected =
-            format!("EventFilter(contract: {}, events: {})", addr_str(address), events.join(", "));
+        let got = format!("{filter}");
+        let expected = format!(
+            "EventFilter(contract: 0x000000000000000000000000000000000000dEaD, events: [EventOne(), EventTwo()])"
+        );
         assert_eq!(got, expected);
 
         // Debug should equal Display
-        assert_eq!(format!("{:?}", filter), got);
+        assert_eq!(format!("{filter:?}"), got);
     }
 
     #[test]
-    fn display_with_empty_events_vector_noop() {
-        // Providing an empty events vector should behave as if no events were set.
-        let filter = EventFilter::new().with_events(Vec::<String>::new());
-        let got = format!("{}", filter);
-        let expected = "EventFilter(contract: all contracts, events: all events)";
-        assert_eq!(got, expected);
+    fn display_multiple_event_signatures_with_address() {
+        let address = address!("0x000000000000000000000000000000000000dEaD");
+        let event_signatures =
+            vec![SomeContract::EventOne::SIGNATURE_HASH, SomeContract::EventTwo::SIGNATURE_HASH];
+        let filter = EventFilter::new()
+            .with_contract_address(address)
+            .with_event_signatures(event_signatures.clone());
+
+        let got = format!("{filter}");
+        // `Topic` doesn't guarantee the order of values it returns
+        let expected_1 = format!(
+            "EventFilter(contract: 0x000000000000000000000000000000000000dEaD, event_signatures: [0x16eb4fc7651e068f1c31303645026f82d5fced11a8d5209bbf272072be23ddff, 0xa08dd6fd0d644da5df33d075cb9256203802f6948ab81b87079960711810dc91])"
+        );
+        let expected_2 = format!(
+            "EventFilter(contract: 0x000000000000000000000000000000000000dEaD, event_signatures: [0xa08dd6fd0d644da5df33d075cb9256203802f6948ab81b87079960711810dc91, 0x16eb4fc7651e068f1c31303645026f82d5fced11a8d5209bbf272072be23ddff])"
+        );
+        assert!(
+            got == expected_1 || got == expected_2,
+            "got: {got},\nexpected_1: {expected_1},\nexpected_2: {expected_2}"
+        );
+
+        // Debug should equal Display
+        assert_eq!(format!("{filter:?}"), got);
+    }
+
+    #[test]
+    fn display_multiple_events_and_event_signatures() {
+        let events = vec![SomeContract::EventOne::SIGNATURE, SomeContract::EventTwo::SIGNATURE];
+        let event_signatures =
+            vec![SomeContract::EventOne::SIGNATURE_HASH, SomeContract::EventTwo::SIGNATURE_HASH];
+        let filter = EventFilter::new()
+            .with_events(events.clone())
+            .with_event_signatures(event_signatures.clone());
+
+        let got = format!("{filter}");
+        let expected_1 = format!(
+            "EventFilter(events: [EventOne(), EventTwo()], event_signatures: [0x16eb4fc7651e068f1c31303645026f82d5fced11a8d5209bbf272072be23ddff, 0xa08dd6fd0d644da5df33d075cb9256203802f6948ab81b87079960711810dc91])",
+        );
+        let expected_2 = format!(
+            "EventFilter(events: [EventOne(), EventTwo()], event_signatures: [0xa08dd6fd0d644da5df33d075cb9256203802f6948ab81b87079960711810dc91, 0x16eb4fc7651e068f1c31303645026f82d5fced11a8d5209bbf272072be23ddff])",
+        );
+        assert!(
+            got == expected_1 || got == expected_2,
+            "got: {got},\nexpected_1: {expected_1},\nexpected_2: {expected_2}"
+        );
 
         // Debug should equal Display
-        assert_eq!(format!("{:?}", filter), got);
+        assert_eq!(format!("{filter:?}"), got);
     }
 
     #[test]
-    fn display_with_empty_event_string_prints_empty() {
-        // An explicitly empty event string results in an empty events field when joined.
-        let filter = EventFilter::new().with_event("");
-        let got = format!("{}", filter);
-        let expected = "EventFilter(contract: all contracts, events: )";
+    fn display_multiple_events_and_event_signatures_with_address() {
+        let address = address!("0x000000000000000000000000000000000000dEaD");
+        let events = vec![SomeContract::EventOne::SIGNATURE, SomeContract::EventTwo::SIGNATURE];
+        let event_signatures =
+            vec![SomeContract::EventOne::SIGNATURE_HASH, SomeContract::EventTwo::SIGNATURE_HASH];
+        let filter = EventFilter::new()
+            .with_contract_address(address)
+            .with_events(events.clone())
+            .with_event_signatures(event_signatures.clone());
+
+        let got = format!("{filter}");
+        let expected_1 = format!(
+            "EventFilter(contract: 0x000000000000000000000000000000000000dEaD, events: [EventOne(), EventTwo()], event_signatures: [0x16eb4fc7651e068f1c31303645026f82d5fced11a8d5209bbf272072be23ddff, 0xa08dd6fd0d644da5df33d075cb9256203802f6948ab81b87079960711810dc91])",
+        );
+        let expected_2 = format!(
+            "EventFilter(contract: 0x000000000000000000000000000000000000dEaD, events: [EventOne(), EventTwo()], event_signatures: [0xa08dd6fd0d644da5df33d075cb9256203802f6948ab81b87079960711810dc91, 0x16eb4fc7651e068f1c31303645026f82d5fced11a8d5209bbf272072be23ddff])",
+        );
+        assert!(
+            got == expected_1 || got == expected_2,
+            "got: {got},\nexpected_1: {expected_1},\nexpected_2: {expected_2}"
+        );
+
+        // Debug should equal Display
+        assert_eq!(format!("{filter:?}"), got);
+    }
+
+    #[test]
+    fn display_with_empty_events_vector_noop() {
+        // Providing an empty events vector should behave as if no events were set.
+        let filter = EventFilter::new().with_events(Vec::<String>::new());
+        let got = format!("{filter}");
+        let expected = "EventFilter()";
         assert_eq!(got, expected);
 
         // Debug should equal Display
-        assert_eq!(format!("{:?}", filter), got);
+        assert_eq!(format!("{filter:?}"), got);
     }
 }

src/event_scanner.rs

@@ -168,20 +168,23 @@ impl<N: Network> ConnectedEventScanner<N> {
             let sender = listener.sender.clone();
             let mut sub = range_tx.subscribe();
 
+            let mut log_filter = Filter::new();
+            if let Some(contract_address) = filter.contract_address {
+                log_filter = log_filter.address(contract_address);
+            }
+            let events = filter.all_events();
+            if !events.is_empty() {
+                log_filter = log_filter.event_signature(events);
+            }
+
             tokio::spawn(async move {
                 loop {
                     match sub.recv().await {
                         Ok(Ok(range)) => {
                             let (from_block, to_block) = (*range.start(), *range.end());
 
-                            let mut log_filter = Filter::new()
-                                .from_block(from_block)
-                                .to_block(to_block)
-                                .events(filter.events.clone());
-
-                            if let Some(contract_address) = filter.contract_address {
-                                log_filter = log_filter.address(contract_address);
-                            }
+                            let log_filter =
+                                log_filter.clone().from_block(from_block).to_block(to_block);
 
                             match provider.get_logs(&log_filter).await {
                                 Ok(logs) => {