EVM filter reference
This page contains reference about the available data filters for EVM DNA streams.
Related pages
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 ornull
.
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;
}>;
Common patterns
- Stream all transactions.
const filter = {
transactions: [{}],
};
Withdrawals
export type WithdrawalFilter = Partial<{
/** Filter based on the validator index. */
validatorIndex: number;
/** Filter based on the withdrawal address. */
address: Address;
}>;