Skip to content

createContractEventFilter

Creates a Filter to retrieve contract event logs.

Creates a Filter to retrieve event logs that can be used with getFilterChanges or getFilterLogs.

Usage

By default, an Event Filter with an ABI (abi) will retrieve events defined on the ABI.

example.ts
import { publicClient } from './client'
import { wagmiAbi } from './abi'
 
const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi
})
/**
 *  {
 *    abi: [...],
 *    id: '0x345a6572337856574a76364e457a4366',
 *    type: 'event'
 *  }
 */

Scoping

You can also scope a Filter to a set of given attributes (listed below).

Address

A Filter can be scoped to an address:

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2'
})

Event

A Filter can be scoped to an event:

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
  eventName: 'Transfer'
})

Arguments

A Filter can be scoped to given indexed arguments:

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
  eventName: 'Transfer',
  args: {  
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
  }
})

Only indexed arguments in event are candidates for args.

A Filter Argument can also be an array to indicate that other values can exist in the position:

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
  eventName: 'Transfer',
  args: { 
    // '0xd8da...' OR '0xa5cc...' OR '0xa152...'
    from: [
      '0xd8da6bf26964af9d7eed9e03e53415d37aa96045', 
      '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac',
      '0xa152f8bb749c55e9943a3a0a3111d18ee2b3f94e',
    ],
  }
})

Block Range

A Filter can be scoped to a block range:

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
  eventName: 'Transfer',
  fromBlock: 16330000n, 
  toBlock: 16330050n
})

Strict Mode

By default, createContractEventFilter will include logs that do not conform to the indexed & non-indexed arguments on the event. viem will not return a value for arguments that do not conform to the ABI, thus, some arguments on args may be undefined.

const filter = await publicClient.createContractEventFilter({
  eventName: 'Transfer',
})
const logs = await publicClient.getFilterLogs({ filter })
 
logs[0].args 
//      ^? { address?: Address, to?: Address, value?: bigint }

You can turn on strict mode to only return logs that conform to the indexed & non-indexed arguments on the event, meaning that args will always be defined. The trade-off is that non-conforming logs will be filtered out.

const filter = await publicClient.createContractEventFilter({
  eventName: 'Transfer',
  strict: true
})
const logs = await publicClient.getFilterLogs({ filter })
 
logs[0].args 
//      ^? { address: Address, to: Address, value: bigint }

Returns

Filter

Parameters

abi

The contract's ABI.

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi, 
})

address (optional)

  • Type: Address | Address[]

The contract address or a list of addresses from which Logs should originate. If no addresses are provided, then it will query all events matching the event signatures on the ABI.

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2'
})

eventName (optional)

  • Type: string

The event name.

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  eventName: 'Transfer'
})

args (optional)

  • Type: Inferred.

A list of indexed event arguments.

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  eventName: 'Transfer',
  args: { 
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
  }
})

fromBlock (optional)

  • Type: bigint

Block to start querying/listening from.

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  fromBlock: 69420n
})

toBlock (optional)

  • Type: bigint

Block to query/listen until.

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  toBlock: 70120n
})