Starknet filter reference

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

Related pages

• Starknet 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.

Apibara represents Starknet field elements as hex-encode strings.

export type FieldElement = `0x${string}`;

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;
  transactions?: TransactionFilter[];
  events?: EventFilter[];
  messages?: MessageToL1Filter[];
  storageDiffs?: StorageDiffFilter[];
  contractChanges?: ContractChangeFilter[];
  nonceUpdates?: NonceUpdateFilter[];
};

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.

Events

Events are the most common filter used by Apibara users. You can filter by smart contract or event selector.

export type EventFilter = {
  id?: number;
  address?: FieldElement;
  keys?: (FieldElement | null)[];
  strict?: boolean;
  transactionStatus?: "succeeded" | "reverted" | "all";
  includeTransaction?: boolean;
  includeReceipt?: boolean;
  includeMessages?: boolean;
  includeSiblings?: boolean;
};

Properties

• address: filter by contract address. If empty, matches any contract address.
• keys: filter by keys. Use null to match any value. The server will filter based only the first four elements of the array.
• strict: return events whose keys length matches the filter. By default, the filter does a prefix match on the keys.
• transactionStatus: return events emitted by transactions with the provided status. Defaults to succeeded.
• includeTransaction: also return the transaction that emitted the event.
• includeReceipt: also return the receipt of the transaction that emitted the event.
• includeMessages: also return all messages to L1 sent by the transaction that emitted the event.
• includeSiblings: also return all other events emitted by the same transaction that emitted the matched event.

Examples

• All events from a specific smart contract.

const filter = {
  events: [{ address: MY_CONTRACT }],
};

• Multiple events from the same smart contract.

const filter = {
  events: [
    {
      address: MY_CONTRACT,
      keys: [APPROVE_SELECTOR],
    },
    {
      address: MY_CONTRACT,
      keys: [TRANSFER_SELECTOR],
    },
  ],
};

• Multiple events from different smart contracts.

const filter = {
  events: [
    {
      address: CONTRACT_A,
      keys: [TRANSFER_SELECTOR],
    },
    {
      address: CONTRACT_B,
      keys: [TRANSFER_SELECTOR],
      includeReceipt: false,
    },
    {
      address: CONTRACT_C,
      keys: [TRANSFER_SELECTOR],
    },
  ],
};

Transactions

Transactions on Starknet can be of different type (invoke, declare contract, deploy contract or account, handle L1 message). Clients can request all transactions or filter by transaction type.

export type InvokeTransactionV0Filter = {
  _tag: "invokeV0";
  invokeV0: {};
};

export type InvokeTransactionV1Filter = {
  _tag: "invokeV1";
  invokeV1: {};
};

export type InvokeTransactionV3Filter = {
  _tag: "invokeV3";
  invokeV3: {};
};

export type DeployTransactionFilter = {
  _tag: "deploy";
  deploy: {};
};

export type DeclareV0TransactionFilter = {
  _tag: "declareV0";
  declareV0: {};
};

export type DeclareV1TransactionFilter = {
  _tag: "declareV1";
  declareV1: {};
};

export type DeclareV2TransactionFilter = {
  _tag: "declareV2";
  declareV2: {};
};

export type DeclareV3TransactionFilter = {
  _tag: "declareV3";
  declareV3: {};
};

export type L1HandlerTransactionFilter = {
  _tag: "l1Handler";
  l1Handler: {};
};

export type DeployAccountV1TransactionFilter = {
  _tag: "deployAccountV1";
  deployAccountV1: {};
};

export type DeployAccountV3TransactionFilter = {
  _tag: "deployAccountV3";
  deployAccountV3: {};
};

export type TransactionFilter = {
  id?: number;
  transactionStatus?: "succeeded" | "reverted" | "all";
  includeReceipt?: boolean;
  includeMessages?: boolean;
  includeEvents?: boolean;
  transactionType?: 
      | InvokeTransactionV0Filter
      | InvokeTransactionV1Filter
      | InvokeTransactionV3Filter
      | DeployTransactionFilter
      | DeclareV0TransactionFilter
      | DeclareV1TransactionFilter
      | DeclareV2TransactionFilter
      | DeclareV3TransactionFilter
      | L1HandlerTransactionFilter
      | DeployAccountV1TransactionFilter
      | DeployAccountV3TransactionFilter;
};

Properties

• transactionStatus: return transactions with the provided status. Defaults to succeeded.
• includeReceipt: also return the receipt of the transaction.
• includeMessages: also return the messages to L1 sent by the transaction.
• includeEvents: also return the events emitted by the transaction.
• transactionType: filter by transaction type.

Examples

• Request all transactions in a block. Notice the empty transaction filter object, this filter will match any transaction.

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

• Request all transactions of a specific type, e.g. deploy account. In this case we specify the deployAccountV3 variant.

const filter = {
  transactions: [{
    transactionType: { _tag: "deployAccountV3", deployAccountV3: {} }
  }]
};

Messages

Filter messages from L1 to Starknet.

export type MessageToL1Filter = {
  id?: number;
  fromAddress?: FieldElement;
  toAddress?: FieldElement;
  transactionStatus?: "succeeded" | "reverted" | "all";
  includeTransaction?: boolean;
  includeReceipt?: boolean;
  includeEvents?: boolean;
};

Properties

• fromAddress: filter by sender address. If empty, matches any sender address.
• toAddress: filter by receiver address. If empty, matches any receiver address.
• transactionStatus: return messages with the provided status. Defaults to succeeded.
• includeTransaction: also return the transaction that sent the message.
• includeReceipt: also return the receipt of the transaction that sent the message.
• includeEvents: also return the events emitted by the transaction that sent the message.

Storage diff

Request changes to the storage of one or more contracts.

export type StorageDiffFilter = {
  id?: number;
  contractAddress?: FieldElement;
};

Properties

• contractAddress: filter by contract address. If empty, matches any contract address.

Contract change

Request changes to the declared or deployed contracts.

export type DeclaredClassFilter = {
  _tag: "declaredClass";
  declaredClass: {};
};

export type ReplacedClassFilter = {
  _tag: "replacedClass";
  replacedClass: {};
};

export type DeployedContractFilter = {
  _tag: "deployedContract";
  deployedContract: {};
};

export type ContractChangeFilter = {
  id?: number;
  change?: DeclaredClassFilter | ReplacedClassFilter | DeployedContractFilter;
};

Properties

• change: filter by change type.
  • declaredClass: receive declared classes.
  • replacedClass: receive replaced classes.
  • deployedContract: receive deployed contracts.

Nonce update

Request changes to the nonce of one or more contracts.

export type NonceUpdateFilter = {
  id?: number;
  contractAddress?: FieldElement;
};

Properties

• contractAddress: filter by contract address. If empty, matches any contract.