createEventFilter

Creates a Filter to listen for new events that can be used with getFilterChanges.

Usage

By default, an Event Filter with no arguments will query for/listen to all events.

example.ts

import { publicClient } from "./client";
 
const filter = await publicClient.createEventFilter();
{ id: "0xbfb021a4ab99e28173cb75bffbda39fc", 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:

example.ts

import { publicClient } from "./client";
 
const filter = await publicClient.createEventFilter({
  address: "cfx:...", 
});

Event

A Filter can be scoped to an event.

The event argument takes in an event in ABI format – we have a parseAbiItem utility that you can use to convert from a human-readable event signature → ABI.

example.ts

import { parseAbiItem } from "cive"; 
import { publicClient } from "./client";
 
const filter = await publicClient.createEventFilter({
  address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  event: parseAbiItem(

    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ), 
});

By default, event accepts the AbiEvent type:

example.ts

import { publicClient } from "./client";
 
const filter = await publicClient.createEventFilter(publicClient, {
  address: "cfx:...",
  event: {

    name: "Transfer",
    inputs: [
      { type: "address", indexed: true, name: "from" },
      { type: "address", indexed: true, name: "to" },
      { type: "uint256", indexed: false, name: "value" },
    ],
  },
});

Arguments

A Filter can be scoped to given indexed arguments:

import { parseAbiItem } from "cive";
 
const filter = await publicClient.createEventFilter({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
  args: {

    from: "cfx:...",
    to: "cfx:...",
  },
});

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:

import { parseAbiItem } from "cive";
 
const filter = await publicClient.createEventFilter({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
  args: {

    from: ["cfx:...", "cfx:...", "cfx:..."],
  },
});

Epoch Tag

A Filter can be scoped to a epochTag range:

import { parseAbiItem } from "cive";
 
const filter = await publicClient.createEventFilter({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
  fromEpoch: "earliest", 
  toEpoch: "latest_state", 
});

Epoch number

A Filter can be scoped to a epoch number range:

import { parseAbiItem } from "cive";
 
const filter = await publicClient.createEventFilter({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
  fromEpoch: 1n, 
  toEpoch: 19n, 
});

Block Range

A Filter can be scoped to a block range:

import { parseAbiItem } from "cive";
 
const filter = await publicClient.createEventFilter({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
  fromBlock: 16330000n, 
  toBlock: 16330050n, 
});

Multiple Events

A Filter can be scoped to multiple events:

import { parseAbi } from "cive";
 
const filter = await publicClient.createEventFilter({
  events: parseAbi([

    "event Approval(address indexed owner, address indexed sender, uint256 value)",
    "event Transfer(address indexed from, address indexed to, uint256 value)",
  ]),
});

Note: A Filter scoped to multiple events cannot be also scoped with indexed arguments (args).

Strict Mode

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

import { parseAbiItem } from "cive";
 
const filter = await publicClient.createEventFilter({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
});
const logs = await publicClient.getFilterLogs({ filter });
 
logs[0].
args: {
    from?: `0x${string}` | undefined;
    to?: `0x${string}` | undefined;
    value?: bigint | undefined;
}args;

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.

import { parseAbiItem } from "cive";
 
const filter = await publicClient.createEventFilter({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
  strict: true,
});
const logs = await publicClient.getFilterLogs({ filter });
 
logs[0].
args: {
    from: `0x${string}`;
    to: `0x${string}`;
    value: bigint;
}args;

Returns

Filter

Parameters

address (optional)

Type: Address | Address[]

The contract address or a list of addresses from which Logs should originate.

const filter = await publicClient.createEventFilter({
  address: "cfx:...", 
});

event (optional)

Type: AbiEvent

The event in ABI format.

A parseAbiItem utility is exported from cive that converts from a human-readable event signature → ABI.

import { parseAbiItem } from "cive"; 
 
const filter = await publicClient.createEventFilter({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ), 
});

args (optional)

Type: Inferred.

A list of indexed event arguments.

import { parseAbiItem } from "cive";
 
const filter = await publicClient.createEventFilter({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
  args: {

    from: "cfx:...",
    to: "cfx:...",
  },
});

Epoch number (Optional)

Logs can be scoped to a epoch range:

 
const filter = await publicClient.createEventFilter({
  fromEpoch: 16330000n, 
  toEpoch: 16330050n, 
});

Epoch tag (Optional)

 
const filter = await publicClient.createEventFilter({
  fromEpoch: "earliest", 
  toEpoch: "latest_state", 
});

fromBlock (optional)

Type: bigint

Block to start querying/listening from.

const filter = await publicClient.createEventFilter({
  fromBlock: 69420n, 
});

toBlock (optional)

Type: bigint

Block to query/listen until.

const filter = await publicClient.createEventFilter({
  toBlock: 70120n, 
});

JSON-RPC Methods

cfx_newFilter