EVM filter reference

This page contains reference about the available data filters for EVM DNA streams.

Typescript types

Some values are always expected hex-encoded:

/** A smart contract or EOA address. */
export type Address = `0x${string}`;
/** Fixed byte array: 32 bytes. */
export type B256 = `0x${string}`;
/** Unsigned integer: 32 bytes. */
export type U256 = `0x${string}`;

Filter types

Root

export type Filter = Partial<{
  /** Header information. */
  header: HeaderFilter;
  /** Include logs. */
  logs: LogFilter[];
  /** Include transactions. */
  transactions: TransactionFilter[];
  /** Include withdrawals. */
  withdrawals: WithdrawalFilter[];
}>;

Header

Block headers contain information about the block that produced other types of data (e.g. transactions, logs, etc). By default, the header is sent only if any other data is sent. If you need all headers, set always: true in your filter.

export type HeaderFilter = Partial<{
  /** Always include header data. Defaults to `false`. */
  always: boolean;
}>;

Logs

Logs are the most common way to index onchain data. You can filter by topics and/or address. A blank filter will return all events in a block.

Notice that by default the stream includes only the basic information (transaction index and hash) of the transaction that generated a log. If your indexer requires the full transaction and/or receipt, you can request that additional data.

By default the log's topic is matched based on its prefix: the filter with topics: ["0xdd..."] will match any log whose topic[0] equals "0xdd...". A topic value of null will match any value. Use strict: true to return a log only if the topics match in content and length.

export type LogFilter = Partial<{
  /** Filter based on the log's contract address. */
  address: Address;
  /** Filter based on the log's topics. */
  topics: (B256 | null)[];
  /** Only returns logs with topics of exactly the same length as the filter.
   *
   * Defaults to `false`.
   */
  strict: boolean;
  /** Flag to request the log's transaction. Defaults to `false`. */
  includeTransaction: boolean;
  /** Flag to request the log's receipt. Defaults to `false`. */
  includeReceipt: boolean;
}>;

Common patterns

All events from a specific smart contract.

const filter = {
  logs: [{ address: MY_ADDRESS }],
};

Multiple events from the same smart contract. Notice that unlike eth_getLogs, topics accepts either a single value or null.

const filter = {
  logs: [
    { address: MY_ADDRESS, topics: ["0xdd..."] },
    { address: MY_ADDRESS, topics: ["0x8c..."] },
  ],
};

An ERC-20 Transfer event, excluding ERC-721 transfers.

const filter = {
  logs: [
    {
      topics: [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        null,
        null,
      ],
      strict: true,
    },
  ],
};

Same as above, but using viem to generate the topics.

import {
  decodeEventLog,
  encodeEventTopics,
  parseAbi,
} from "https://esm.sh/viem";

const abi = parseAbi([
  "event Transfer(address indexed from, address indexed to, uint256 value)",
]);

const filter = {
  logs: [
    {
      strict: true,
      topics: encodeEventTopics({
        abi,
        eventName: "Transfer",
        args: [null, null],
      }),
    },
  ],
};

Transactions

export type TransactionFilter = Partial<{
  /** Filter based on the transaction's sender address. */
  from: Address;
  /** Filter based on the transaction's target address. */
  to: Address;
  /** Flag to request the transaction's receipt. Defaults to `false`. */
  includeReceipt: boolean;
  /** Flag to request the transaction's logs. Defaults to `false`. */
  includeLogs: boolean;
}>;