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.
import { publicClient } from './client'
import { wagmiAbi } from './abi'
const filter = await publicClient.createContractEventFilter({
abi: wagmiAbi
})
/**
* {
* abi: [...],
* id: '0x345a6572337856574a76364e457a4366',
* type: 'event'
* }
*/
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;
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:
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, however, the args property will be undefined for non-conforming logs as we cannot deterministically decode them.
const filter = await publicClient.createContractEventFilter({
eventName: 'Transfer',
})
const logs = await publicClient.getFilterLogs({ filter })
logs[0].args
// ^? { address: Address, to: Address, value: bigint } | undefined
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
Parameters
abi
- Type:
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
})