Appearance

createContractEventFilter ​

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.

ts
import { publicClient } from './client'
import { wagmiAbi } from './abi'

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

const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi
})
/**
 *  {
 *    abi: [...],
 *    id: '0x345a6572337856574a76364e457a4366',
 *    type: 'event'
 *  }
 */
ts
export const wagmiAbi = [
  ...
  {
    inputs: [
      {
        indexed: true,
        name: "from",
        type: "address",
      },
      { indexed: true, name: "to", type: "address" },
      {
        indexed: true,
        name: "tokenId",
        type: "uint256",
      },
    ],
    name: "Transfer",
    type: "event",
  },
  ...
] as const;
export const wagmiAbi = [
  ...
  {
    inputs: [
      {
        indexed: true,
        name: "from",
        type: "address",
      },
      { indexed: true, name: "to", type: "address" },
      {
        indexed: true,
        name: "tokenId",
        type: "uint256",
      },
    ],
    name: "Transfer",
    type: "event",
  },
  ...
] as const;
ts
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

export const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
})
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

export const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
})

Scoping ​

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

Address ​

A Filter can be scoped to an address:

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

Event ​

A Filter can be scoped to an event:

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

Arguments ​

A Filter can be scoped to given indexed arguments:

ts
const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
  eventName: 'Transfer',
  args: {  
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
  }
})
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:

ts
const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
  eventName: 'Transfer',
  args: { 
    // '0xd8da...' OR '0xa5cc...' OR '0xa152...'
    from: [
      '0xd8da6bf26964af9d7eed9e03e53415d37aa96045', 
      '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac',
      '0xa152f8bb749c55e9943a3a0a3111d18ee2b3f94e',
    ],
  }
})
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:

ts
const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi,
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
  eventName: 'Transfer',
  fromBlock: 16330000n, 
  toBlock: 16330050n 
})
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.

ts
const filter = await publicClient.createContractEventFilter({
  eventName: 'Transfer',
})
const logs = await publicClient.getFilterLogs({ filter })

logs[0].args
//      ^? { address?: Address, to?: Address, value?: bigint }
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.

ts
const filter = await publicClient.createContractEventFilter({
  eventName: 'Transfer',
  strict: true
})
const logs = await publicClient.getFilterLogs({ filter })

logs[0].args
//      ^? { address: Address, to: Address, value: bigint }
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.

ts
const filter = await publicClient.createContractEventFilter({
  abi: wagmiAbi, 
})
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.

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

eventName (optional) ​

  • Type: string

The event name.

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

args (optional) ​

  • Type: Inferred.

A list of indexed event arguments.

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

fromBlock (optional) ​

  • Type: bigint

Block to start querying/listening from.

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

toBlock (optional) ​

  • Type: bigint

Block to query/listen until.

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

Released under the MIT License.

Copyright © 2023-present weth, LLC