EVM filter reference

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

Related pages

• EVM block data reference

All filters have an associated ID. When the server filters a block, it will return a list of all filters that matched a piece of data with the data. You can use this ID to build powerful abstractions in your indexers.

Most types are compatible with viem. For example, you can generate log filters with the following code:

import { encodeEventTopics, parseAbi } from "viem";

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

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

Root

The root filter object contains a collection of filters. Notice that providing an empty filter object is an error.

export type Filter = {
  header?: HeaderFilter;
  logs?: LogFilter[];
  transactions?: TransactionFilter[];
  withdrawals?: WithdrawalFilter[];
};

Header

The HeaderFilter object controls when the block header is returned to the client.

export type HeaderFilter = "always" | "on_data" | "on_data_or_on_new_block";

The values have the following meaning:

• always: Always return the header, even if no other filter matches.
• on_data: Return the header only if any other filter matches. This is the default value.
• on_data_or_on_new_block: Return the header only if any other filter matches. If no other filter matches, return the header only if the block is a new block.

Logs are the most common type of DNA filters. Use this filter to get the logs and their associated data like transactions, receipts, and sibling logs.

export type LogFilter = {
  id?: number;
  address?: `0x${string}`;
  topics?: (`0x${string} | null`)[];
  strict?: boolean;
  transactionStatus?: "succeeded" | "reverted" | "all";
  includeTransaction?: boolean;
  includeReceipt?: boolean;
  includeSiblings?: boolean;
};

Properties

• address: filter by contract address. If empty, matches any contract address.
• topics: filter by topic. Use null to match any value.
• strict: return logs whose topics length matches the filter. By default, the filter does a prefix match on the topics.
• transactionStatus: return logs emitted by transactions with the provided status. Defaults to succeeded.
• includeTransaction: also return the transaction that emitted the log.
• includeReceipt: also return the receipt of the transaction that emitted the log.
• includeSiblings: also return all other logs emitted by the same transaction that emitted the matched log.

Examples

• All logs in a block emitted by successful transactions.

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

• All Transfer events emitted by successful transactions. Notice that this will match logs from ERC-20, ERC-721, and other contracts that emit Transfer.

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

• All Transfer events that follow the ERC-721 standard. Notice that this will not match logs from ERC-20 since the number of indexed parameters is different.

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

• All logs emitted by CONTRACT_A OR CONTRACT_B.

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

Request Ethereum transactions.

export type TransactionFilter = {
  id?: number;
  from?: `0x${string}`;
  to?: `0x${string}`;
  create?: true,
  transactionStatus?: "succeeded" | "reverted" | "all";
  includeReceipt?: boolean;
  includeLogs?: boolean;
};

Properties

• from: filter by sender address. If empty, matches any sender address.
• to: filter by receiver address. If empty, matches any receiver address.
• create: filter by whether the transaction is a create transaction.
• transactionStatus: return transactions with the provided status. Defaults to succeeded.
• includeReceipt: also return the receipt of the transaction.
• includeLogs: also return the logs emitted by the transaction.

Examples

• All transactions in a block.

const filter = {
  transactions: [{}],
};

• All transactions from 0xAB....

const filter = {
  transactions: [{
    from: "0xAB...",
  }],
};

• All create transactions.

const filter = {
  transactions: [{
    create: true,
  }],
};

Request Ethereum withdrawals.

export type WithdrawalFilter = {
  id?: number;
  validatorIndex?: number;
  address?: string;
};

Properties

• validatorIndex: filter by validator's index. If empty, matches any validator's index.
• address: filter by withdrawal address. If empty, matches any withdrawal address.

Examples

• All withdrawals

const filter = {
  withdrawals: [{}],
};

• All withdrawals from validator with index 1234.

const filter = {
  withdrawals: [{
    validatorIndex: 1234,
  }],
};

• All withdrawals from validators with index 1234 OR 7890.

const filter = {
  withdrawals: [{
    validatorIndex: 1234,
  }, {
    validatorIndex: 7890,
  }],
};

• All withdrawals to address 0xAB....

const filter = {
  withdrawals: [{
    address: "0xAB...",
  }],
};