# `Cartouche.Filter`
[🔗](https://github.com/ZenHive/onchain-stack/blob/cartouche-v0.9.0/packages/cartouche/lib/cartouche/filter.ex#L1)

Poll an Ethereum node-side filter and deliver results to registered listeners.

Log filters (`kind: :log`, the default) decode matching logs and dispatch
`{:event, {name, params}, log}` plus `{:log, log}`. Block and pending-transaction
filters (`kind: :block` / `kind: :pending`) dispatch `{:hashes, hashes}` with
32-byte hash lists. The GenServer uninstalls its node-side filter on shutdown.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `listen`

```elixir
@spec listen(GenServer.server()) :: :ok
```

Registers the calling process as a listener on `filter`.

Log filters send `{:event, {name, params}, log}` for matched, decoded events
and `{:log, log}` for every raw log. Block and pending filters send
`{:hashes, hashes}` with a list of 32-byte hashes.

# `start_link`

```elixir
@spec start_link(Keyword.t()) :: GenServer.on_start()
```

Starts a `Cartouche.Filter` GenServer that polls an Ethereum node-side filter.

## Options

  * `:name` — registered name for the GenServer (defaults to `__MODULE__`)
  * `:kind` — `:log` (default), `:block`, or `:pending`
  * `:address` — contract address to filter on (log filters; omit to match any)
  * `:topics` — list of topic filters (log filters)
  * `:events` — list of `ABI.FunctionSelector.t()` or signature strings;
    events are decoded and dispatched as `{:event, {name, params}, log}`
  * `:rpc_opts` — keyword list forwarded to `Cartouche.RPC` calls
  * `:extra_data` — opaque value attached to every log/event message
  * `:check_delay` — milliseconds between filter polls (default 3000)

---

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