Feature request: Expand event filters to support multiple events

[typedarray]

Today, the event filter methods (watchEvent, createEventFilter, getFilterLogs, getLogs) support only one kind of topic set: one event signature, (optional) indexed argument values.

There is another potentially useful kind of event filter - one that specifies many event signatures and no indexed argument values. For example, this could be used to filter for every ERC20 Transfer and Approval event on the network, regardless of contract address. The topic set sent to the RPC provider in this case looks like [ [TransferSigHash, ApprovalSigHash] ].

I can think of two ways Viem could add support for this:

1. Add a topics option to every public client method that builds an event filter. topics would be mutually exclusive with the current event/args options.

(pseudotype)

type EventLogFilterParameters<
  TAbiEvent extends AbiEvent | undefined = undefined,
  TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>
>= {
  address?: Address | Address[]
} & (
  | {
      event: TAbiEvent
      args?: MaybeExtractEventArgsFromAbi<[TAbiEvent], TEventName>
+     topics?: never  
    }
  | {
      event?: never
      args?: never
+     topics?: never  
    }
+ | {
+     event?: never
+     args?: never
+     topics: (Hex | Hex[] | null)[]
+   }
)

2. Add an events option to explicitly support the multiple events, no arguments pattern.

type EventLogFilterParameters<
  TAbiEvent extends AbiEvent | undefined = undefined,
  TEventName extends string | undefined = MaybeAbiEventName<TAbiEvent>
>= {
  address?: Address | Address[]
} & (
  | {
      event: TAbiEvent
      args?: MaybeExtractEventArgsFromAbi<[TAbiEvent], TEventName>
+     events?: never  
    }
  | {
      event?: never
      args?: never
+     events?: never  
    }
+ | {
+     event?: never
+     args?: never
+     events: TAbiEvent[]
+   }
)

I think it would be reasonable to also add these options to the Contract Instance event filter methods (createContractEventFilter, watchContractEvent).

cc @holic

[frolic]

What about a separate function, like createTopicFilter or just createFilter, that accepts topics as its primary argument? And then functions like createEventFilter are just a wrapper over createFilter that translates an event to topics.

Design-wise, I'm not sure what the viem team prefers.

[JoeyKhd]

+1 on this

[BravoNatalie]

Do we have any updates on this? Is it possible to get more complex filtering using viem?

For example, in ethers, we can do something like the code below using event filters.

// List all token transfers *to* either myAddress or myOtherAddress:
    const filter = {
      address: tokenAddress,
      topics: [
        utils.id("Transfer(address,address,uint256)"),
        null,
        [
          hexZeroPad(myAddress, 32),
          hexZeroPad(myOtherAddress, 32),
        ]
      ]
    };

How can we achieve the same thing using viem?

[jxom]

See the second snippet here: https://viem.sh/docs/actions/public/getLogs#arguments

[KartikSoneji]

+1, would being able to specify arbitrary log topics would allow multiple filters to be "collapsed" together.

For example, a contract with:

event AdminSet(address indexed user);
event AdminRevoked(address indexed user);

could filter events by [null, [user1, user2, ...], null, null] to get all admin events for a set of users.

A workaround is to "trick" the filter by using an anonymous event with four indexed bytes32 parameters, which allows full control over the topics array.
eg:

client.watchEvent({
  event: {
    name: 'RawEvent',
    type: 'event',
    anonymous: true,
    inputs: [
      { name: 'topic0', type: 'bytes32', indexed: true },
      { name: 'topic1', type: 'bytes32', indexed: true },
      { name: 'topic2', type: 'bytes32', indexed: true },
      { name: 'topic3', type: 'bytes32', indexed: true },
    ],
  },
  args: {
    topic1: [paddedUserAddress]
  },
  onLogs: console.log,
});

But that doesn't work in the current version (v2.47.10) because anonymous events aren't handled properly.