getLogs

Returns a list of event logs matching the provided parameters.

Usage

By default, getLogs returns all events. In practice, you must use scoping to filter for specific events.

example.ts

import { publicClient } from "./client";
 
const logs = await publicClient.getLogs(); 
Output: [{ ... }, { ... }, { ... }]

Scoping

You can also scope to a set of given attributes.

example.ts

import { parseAbiItem } from "cive";
import { publicClient } from "./client";
 
const logs = await publicClient.getLogs({

  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed, address indexed, uint256)"
  ),
  fromEpoch: 16330000n,
  toEpoch: 16330000n,
});

By default, event accepts the AbiEvent type:

example.ts

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

    type: "event",
    name: "Transfer",
    inputs: [
      { type: "address", indexed: true, name: "from" },
      { type: "address", indexed: true, name: "to" },
      { type: "uint256", indexed: false, name: "value" },
    ],
  },
  args: {
    from: "cfx:...",
    to: "cfx:...",
  },
  fromEpoch: 16330000n,
  toEpoch: 16330000n,
});

Address (Optional)

Logs can be scoped to an address:

const logs = await publicClient.getLogs({
  address: "cfx:...", 
});

Event (Optional)

Logs 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.

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

Arguments (Optional)

Logs can be scoped to given indexed arguments:

import { parseAbiItem } from "cive";
 
const logs = await publicClient.getLogs({
  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.

An argument can also be an array to indicate that other values can exist in the position:

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

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

Epoch Range (Optional)

Logs can be scoped to a epoch range:

import { parseAbiItem } from "cive";
 
const logs = await publicClient.getLogs({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
  fromEpoch: 16330000n, 
  toEpoch: 16330050n, 
});

Or Epoch tag

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

Block Range (Optional)

Logs can be scoped to a block range:

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

blockHashes (Optional)

Array of up to 128 block hashes that the search will be applied to. This will override from/to epoch fields if it's not null.

import { parseAbiItem } from "cive";
 
const logs = await publicClient.getLogs({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
  blockHashes: ["0x...", "0x..."],
});

Multiple Events

Logs can be scoped to multiple events:

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

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

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

Strict Mode

By default, getLogs 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 logs = await publicClient.getLogs({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
});
 
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 logs = await publicClient.getLogs({
  address: "cfx:...",
  event: parseAbiItem(
    "event Transfer(address indexed from, address indexed to, uint256 value)"
  ),
  strict: true,
});
 
logs[0].
args: {
    from: `0x${string}`;
    to: `0x${string}`;
    value: bigint;
}args;

Returns

Log[]

A list of event logs.

JSON-RPC Method

cfx_getLogs