Struct Filter 

pub struct Filter {
    pub block_option: FilterBlockOption,
    pub address: FilterSet<Address>,
    pub topics: [FilterSet<FixedBytes<32>>; 4],
}

Filter for logs.

Fields

block_option: FilterBlockOption

Filter block options, specifying on which blocks the filter should match.

address: FilterSet<Address>

A filter set for matching contract addresses in log queries.

This field determines which contract addresses the filter applies to. It supports:

• A single address to match logs from that address only.
• Multiple addresses to match logs from any of them.

Notes:

• An empty array ([]) may result in no logs being returned.
• Some RPC providers handle empty arrays differently than None.
• Large address lists may affect performance or hit provider limits.

topics: [FilterSet<FixedBytes<32>>; 4]

Topics (maximum of 4)

Implementations

impl Filter

pub fn new() -> Filter

Creates a new, empty filter

pub fn select(self, filter: impl Into<FilterBlockOption>) -> Filter

Sets the inner filter object

NOTE: ranges are always inclusive

Examples

Match only a specific block

let filter = Filter::new().select(69u64);

This is the same as Filter::new().from_block(1337u64).to_block(1337u64)

Match the latest block only

let filter = Filter::new().select(BlockNumberOrTag::Latest);

Match a block by its hash

let filter = Filter::new().select(B256::ZERO);

This is the same as at_block_hash

Match a range of blocks

let filter = Filter::new().select(0u64..=100u64);

Match all blocks in range (1337..BlockNumberOrTag::Latest)

let filter = Filter::new().select(1337u64..);

Match all blocks in range (BlockNumberOrTag::Earliest..1337)

let filter = Filter::new().select(..=1337u64);

pub fn from_block<T>(self, block: T) -> Filter

where T: Into<BlockNumberOrTag>,

Sets the from block number

pub fn to_block<T>(self, block: T) -> Filter

where T: Into<BlockNumberOrTag>,

Sets the to block number

pub fn is_pending_block_filter(&self) -> bool

Return true if filter configured to match pending block. This means that both from_block and to_block are set to the pending tag.

pub fn extract_block_range(&self) -> (Option<u64>, Option<u64>)

Extracts the block number range from the filter, if applicable.

Returns a tuple of (from_block, to_block) where each element is Some(block_number) if the corresponding block in the filter is a specific number, or None otherwise.

This method only works with FilterBlockOption::Range variants. For FilterBlockOption::AtBlockHash variants, it returns (None, None).

Block numbers are extracted only from BlockNumberOrTag::Number(_) variants. Other variants like BlockNumberOrTag::Latest, BlockNumberOrTag::Pending, etc. are treated as None.

pub fn at_block_hash<T>(self, hash: T) -> Filter

where T: Into<FixedBytes<32>>,

Pins the block hash for the filter

pub fn address<T>(self, address: T) -> Filter

where T: Into<ValueOrArray<Address>>,

Sets the address to query with this filter.

Examples

Match only a specific address ("0xAc4b3DacB91461209Ae9d41EC517c2B9Cb1B7DAF")

let filter = Filter::new()
    .address("0xAc4b3DacB91461209Ae9d41EC517c2B9Cb1B7DAF".parse::<Address>().unwrap());

Match all addresses in array (vec!["0xAc4b3DacB91461209Ae9d41EC517c2B9Cb1B7DAF", "0x8ad599c3A0ff1De082011EFDDc58f1908eb6e6D8"])

let addresses = vec![
    "0xAc4b3DacB91461209Ae9d41EC517c2B9Cb1B7DAF".parse::<Address>().unwrap(),
    "0x8ad599c3A0ff1De082011EFDDc58f1908eb6e6D8".parse::<Address>().unwrap(),
];
let filter = Filter::new().address(addresses);

pub fn event(self, event_name: &str) -> Filter

Given the event signature in string form, it hashes it and adds it to the topics to monitor

pub fn events( self, events: impl IntoIterator<Item = impl AsRef<[u8]>>, ) -> Filter

Hashes all event signatures and sets them as array to event_signature(topic0)

pub fn event_signature<T>(self, topic: T) -> Filter

where T: Into<FilterSet<FixedBytes<32>>>,

Sets event_signature(topic0) (the event name for non-anonymous events)

pub fn topic1<T>(self, topic: T) -> Filter

where T: Into<FilterSet<FixedBytes<32>>>,

Sets the 1st indexed topic

pub fn topic2<T>(self, topic: T) -> Filter

where T: Into<FilterSet<FixedBytes<32>>>,

Sets the 2nd indexed topic

pub fn topic3<T>(self, topic: T) -> Filter

where T: Into<FilterSet<FixedBytes<32>>>,

Sets the 3rd indexed topic

pub fn is_paginatable(&self) -> bool

Returns true if this is a range filter and has a from block

pub fn get_to_block(&self) -> Option<u64>

Returns the numeric value of the toBlock field

pub fn get_from_block(&self) -> Option<u64>

Returns the numeric value of the fromBlock field

pub const fn get_block_hash(&self) -> Option<FixedBytes<32>>

Returns the value of the blockHash field

pub fn has_topics(&self) -> bool

Returns true if at least one topic is set

pub fn address_bloom_filter(&self) -> Cow<'_, BloomFilter>

Create the BloomFilter for the addresses.

pub fn topics_bloom_filter(&self) -> [Cow<'_, BloomFilter>; 4]

Create a BloomFilter for each topic filter.

pub fn matches_bloom(&self, bloom: Bloom) -> bool

Check whether the provided bloom contains all topics and the address we wish to filter on.

pub fn matches_topics(&self, topics: &[FixedBytes<32>]) -> bool

Returns true if the filter matches the given topics.

pub fn matches_address(&self, address: Address) -> bool

Returns true if the filter matches the given address.

pub const fn matches_block_range(&self, block_number: u64) -> bool

Returns true if the block matches the filter.

pub fn matches_block_hash(&self, block_hash: FixedBytes<32>) -> bool

Returns true if the filter matches the given block hash.

pub fn matches_block(&self, block: &NumHash) -> bool

Returns true if the filter matches the given block. Checks both the block number and hash.

pub fn matches_log_block<T>(&self, log: &Log<T>) -> bool

Returns true if either of the following is true:

• the filter and log are both pending
• the filter matches the block in the log. I.e. Self::matches_block returns true when called with the block number and hash from the log.

pub fn matches(&self, log: &Log) -> bool

Check if a Log matches the filter. This will check topics and address.

This checks Log<LogData>, the raw, primitive type carrying un-parsed LogData.

• For un-parsed RPC logs crate::Log<LogData>, see Self::rpc_matches and Self::rpc_matches_parsed.
• For parsed Logs (e.g. those returned by a contract), see Self::matches_parsed.

pub fn rpc_matches(&self, log: &Log) -> bool

Check if a crate::Log matches the filter. This will check topics, address, and block option.

This function checks crate::Log<LogData>, the RPC type carrying un-parsed LogData.

• For parsed Log<T>s (e.g. those returned by a contract), see Self::matches_parsed.
• For parsed crate::Log<T>s (e.g. those returned by a contract), see Self::rpc_matches.

pub fn matches_parsed<T, U>(&self, log: &T) -> bool

where T: AsRef<Log<U>>, &'a U: for<'a> Into<LogData>,

Check if a parsed Log<T> matches the filter. This will check topics and address.

This function checks Log<T>, the primitive Log type carrying some parsed T, usually implementing SolEvent.

• For un-parsed Log<LogData> see Self::matches.
• For un-parsed RPC logs crate::Log<LogData> see Self::rpc_matches.
• For parsed RPC crate::Log<T>s (e.g. those returned by a contract), see Self::rpc_matches_parsed.

pub fn rpc_matches_parsed<U>(&self, log: &Log<U>) -> bool

where &'a U: for<'a> Into<LogData>,

Check if a parsed rpc log crate::Log<T> matches the filter. This will check topics, address, and block option.

If the RPC log block hash or number is None (indicating an uncled block), this function will return false.

This function checks crate::Log<T>, the RPC type carrying some parsed T, usually implementing SolEvent.

• For un-parsed Log<LogData> see Self::matches.
• For parsed Log<T>s (e.g. those returned by a contract), see Self::matches_parsed.
• For un-parsed RPC logs crate::Log<LogData> see Self::rpc_matches.

pub fn append_matching_block_logs<'a, I, R>( &self, all_logs: &mut Vec<Log>, block_num_hash: NumHash, block_timestamp: u64, tx_hashes_and_receipts: I, removed: bool, )

where I: IntoIterator<Item = (FixedBytes<32>, &'a R)>, R: TxReceipt<Log = Log> + 'a,

Appends logs matching the filter from a block’s receipts.

Iterates through receipts, filters logs, and appends them with block metadata. Includes block number/hash matching.

Arguments

• all_logs - Vector to append matching logs to
• block_num_hash - Block number and hash of the block
• block_timestamp - Block timestamp
• tx_hashes_and_receipts - Iterator of (transaction_hash, receipt) pairs
• removed - Whether logs are from a removed block (reorg)

pub fn matching_block_logs<'a, I, R>( &self, block_num_hash: NumHash, block_timestamp: u64, tx_hashes_and_receipts: I, removed: bool, ) -> Vec<Log>

where I: IntoIterator<Item = (FixedBytes<32>, &'a R)>, R: TxReceipt<Log = Log> + 'a,

Returns matching logs from a block’s receipts grouped by transaction hashes.

Arguments

• block_num_hash - Block number and hash of the block
• block_timestamp - Block timestamp
• tx_hashes_and_receipts - Iterator of (transaction_hash, receipt) pairs
• removed - Whether logs are from a removed block (reorg)

pub fn filter_receipts<I, R>( &self, receipts: I, ) -> FilterReceiptsIter<'_, <I as IntoIterator>::IntoIter, R>

where I: IntoIterator, <I as IntoIterator>::Item: IntoIterator<Item = R>, R: TxReceipt<Log = Log>,

Creates an iterator that filters receipts for matching logs.

This method takes an iterator of blocks (where each block is an iterator of receipts) and returns an iterator that yields all logs matching this filter.

Example

let filter = Filter::new()
    .address("0x1234...".parse::<Address>().unwrap())
    .event_signature(B256::from([0x01; 32]));

let logs: Vec<Log> = filter.filter_receipts(receipts).collect();

Trait Implementations

impl Clone for Filter

fn clone(&self) -> Filter

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Filter

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Filter

fn default() -> Filter

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Filter

Available on crate feature serde only.

fn deserialize<D>( deserializer: D, ) -> Result<Filter, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Hash for Filter

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Filter

fn eq(&self, other: &Filter) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Filter

Available on crate feature serde only.

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Filter

impl StructuralPartialEq for Filter