# `Ethers.CombinedEventFilter`
[🔗](https://github.com/ExWeb3/elixir_ethers/blob/v0.8.0/lib/ethers/combined_event_filter.ex#L1)

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

```elixir
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{...}, ...]}
```

# `t`

```elixir
@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.

# `decode_logs`

```elixir
@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)

---

*Consult [api-reference.md](api-reference.md) for complete listing*