watchContractEvents

Watches and returns emitted contract event logs.

This Action will batch up all the event logs found within the pollingInterval, and invoke them via onLogs.

Import

import { watchContractEvents } from 'viem'

Usage

example.tsclient.ts

import { watchContractEvents } from 'viem'
import { publicClient } from './client'
import { wagmiAbi } from './abi'

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  onLogs: logs => console.log(logs)
})
// > [{ ... }, { ... }, { ... }]
// > [{ ... }, { ... }]
// > [{ ... }, { ... }, { ... }, { ... }]

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

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

Scoping to an Event Name

You can scope to an event on the given ABI.

example.tsabi.tsclient.ts

import { watchContractEvents } from 'viem'
import { publicClient } from './client'
import { wagmiAbi } from './abi'

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  eventName: 'Transfer',
  onLogs: logs => console.log(logs)
})
// > [{ ... }, { ... }, { ... }]
// > [{ ... }, { ... }]
// > [{ ... }, { ... }, { ... }, { ... }]

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 to Event Arguments

You can scope to given indexed event arguments.

In the example below, we want to filter out Transfers that were sent by the address "0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b".

Only indexed arguments on the event ABI are candidates for args (see abi.ts).

example.tsabi.tsclient.ts

import { watchContractEvents } from 'viem'
import { publicClient } from './client'
import { wagmiAbi } from './abi'

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  eventName: 'Transfer',
  args: ['0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b'],
  onLogs: logs => console.log(logs)
})
// > [{ ... }, { ... }, { ... }]
// > [{ ... }, { ... }]
// > [{ ... }, { ... }, { ... }, { ... }]

export const wagmiAbi = [
  ...
  {
    inputs: [
      {
        indexed: true,
        name: "from",
        type: "address",
      },
      { 
        indexed: true, 
        name: "to", 
        type: "address" 
      },
      {
        indexed: false,
        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()
})

Returns

UnwatchFn

A function that can be invoked to stop watching for new event logs.

Arguments

address

Type: Address

The contract address.

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', 
  abi: wagmiAbi,
  onLogs: logs => console.log(logs)
})

abi

Type: Abi

The contract's ABI.

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi, 
  onLogs: logs => console.log(logs)
})

onLogs

Type: (Log[]) => void

The new event logs.

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  onLogs: logs => console.log(logs) 
})

args (optional)

Type: Inferred from ABI.

Event arguments to filter logs.

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  eventName: 'Transfer', 
  args: ['0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b'], 
  onLogs: logs => console.log(logs)
})

eventName (optional)

Type: string

An event name to filter logs.

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  eventName: 'Transfer', 
  onLogs: logs => console.log(logs)
})

batch (optional)

Type: boolean
Default: true

Whether or not to batch logs between polling intervals.

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  batch: false, 
  onLogs: logs => console.log(logs)
})

onError (optional)

Type: (error: Error) => void

Error thrown from listening for new event logs.

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  onError: error => console.log(error), 
  onLogs: logs => console.log(logs)
})

pollingInterval (optional)

Type: number

Polling frequency (in ms). Defaults to the Client's pollingInterval config.

const unwatch = await watchContractEvents(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  pollingInterval: 1_000, 
  onLogs: logs => console.log(logs)
})

watchContractEvents #

Import #

Usage #

Scoping to an Event Name #

Scoping to Event Arguments #

Returns #

Arguments #

address #

abi #

onLogs #

args (optional) #

eventName (optional) #

batch (optional) #

onError (optional) #

pollingInterval (optional) #