Ethers.CombinedEventFilter (Ethers v0.7.0)

A filter matching any of multiple events (OR semantics) in a single eth_getLogs request.

Combined event filters are created with Ethers.EventFilter.combine/1 and can be used anywhere a regular event filter is accepted (e.g. Ethers.get_logs/2 and Ethers.batch/2). To match all events of a contract, pass its EventFilters module directly to Ethers.get_logs/2 (or Ethers.EventFilter.combine/1) which internally translates it to a combined filter of all the contract events.

The topics of the combined filters are sent to the RPC endpoint as an OR-ed list of topic_0 values so filtering happens server side. Fetched logs are decoded using the event selector matching their first topic.

Limitations

Only filters with wildcard indexed arguments (all nil) can be combined. Combining filters with indexed-argument values would create cross-product OR semantics on the topics and match unintended logs.
All combined filters must belong to the same address. Filters with conflicting default addresses cannot be combined since eth_getLogs accepts a single address.

Examples

filter =
  Ethers.EventFilter.combine([
    Ethers.Contracts.ERC20.EventFilters.transfer(nil, nil),
    Ethers.Contracts.ERC20.EventFilters.approval(nil, nil)
  ])

Ethers.get_logs(filter, address: "0x...")
{:ok, [%Ethers.Event{...}, ...]}

# Or fetch all events of a contract by passing its EventFilters module
Ethers.get_logs(Ethers.Contracts.ERC20.EventFilters, address: "0x...")
{:ok, [%Ethers.Event{...}, ...]}

Summary

Types

t()

Holds the combined topics (a single OR-ed list of topic_0 values), the event selectors indexed by their topic_0 and the default address.

Functions

decode_logs(logs, combined_event_filter)

Decodes fetched logs using the matching event selectors of the combined filter.

Types

t()

@type t() :: %Ethers.CombinedEventFilter{
  default_address: nil | Ethers.Types.t_address(),
  selectors: %{required(binary()) => ABI.FunctionSelector.t()},
  topics: [[binary()]]
}

Holds the combined topics (a single OR-ed list of topic_0 values), the event selectors indexed by their topic_0 and the default address.

Functions

decode_logs(logs, combined_event_filter)

@spec decode_logs([map()], t()) :: [Ethers.Event.t()]

Decodes fetched logs using the matching event selectors of the combined filter.

Logs not matching any of the combined events are discarded. (Cannot happen with logs fetched using the combined filter itself, since the RPC endpoint only returns logs matching the requested topics)