Transaction Filter

When handling transaction streams across various APIs, including webhooks and backfilling operations, we consistently employ the TransactionFilter specification to ensure that filters are set up uniformly. This specification outlines the data structures and criteria used to select the desired transactions.

Using a standardized TransactionFilter across different API interfaces streamlines the process and avoids redundancy. Below is the JSON representation of the complete TransactionFilter structure for reference. Developers can adapt this template to meet the specific filtering requirements of their individual use cases.

TransactionFilter Overview

Our TransactionFilter currently supports granular instruction filtering based on program or individual instruction parameters. In upcoming releases, we plan to expand its functionality to include filters for events and accounts. To facilitate the discovery of programs and instruction activities, we recommend utilizing our Programs API, which provides the necessary discriminators.

TransactionFilter JSON Schema

Below is the TransactionFilter structure in its JSON format. Note the inclusion of optional parameters id and name, which can aid in event stream identification if needed.

[
  {
    "id": "",
    "name": "",
    "include": {
      "instructions": [
        {
          "address": "",
          "discriminator": "",
          "discriminatorType": ""
        }
      ]
    }
  }
]

Key Definitions

• id: (optional) A unique identifier for the transaction filter.

• name: (optional) A descriptive name for the transaction filter.

• include: Defines the rules for matching transactions.

  • instructions: An array of objects to specify instruction filters.

    • address: The address of the program (required).

    • discriminator: The unique identifier for the instruction (optional).

    • discriminatorType: The type of discriminator, such as u8, u16, u32, or anchor (optional).

Leverage this TransactionFilter structure to customize your filtering needs according to the specifications of the individual use cases. Keep an eye out for our updates, which will enhance the filtering capabilities with additional features.

Examples

Example 1: Basic Program Address Filter

To track transactions associated with a specific program, you can set the address field in the instructions array:

[
  {
    "id": "metaplex-program-filter",
    "name": "All Metaplex Transactions",
    "include": {
      "instructions": [
        {
          "address": "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s"
        }
      ]
    }
  }
]

Example 2: Instruction Discriminator Filter

To filter transactions based on a particular type of instruction within a program, include the discriminator:

[
  {
    "include": {
      "instructions": [
        {
          // filter calls to CreateMetadaAccountV2 from Metaplex program
          "address": "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s",
          "discriminator": "10",
          "discriminatorType": "u8"
        }
      ]
    }
  }
]

Example 3: Combining Multiple Required instructions

For more complex filtering, you can combine multiple instruction criteria in the instructions array:

[
  {
    "include": {
      "instructions": [
        {
          // filter calls to CreateMasterEditionV3 from Metaplex program
          "address": "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s",
          "discriminator": "11",
          "discriminatorType": "u8"
        },
        {
          // filter calls to CreateMetadaAccountV3 from Metaplex program
          "address": "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s",
          "discriminator": "21",
          "discriminatorType": "u8"
        }
      ]
    }
  }
]

Example 4: Combining Multiple Filters

Want to monitor several instruction types? Simply stack your filters in one go like this:

[
  // Your first instruction filter
  {
    "include": {
      "instructions": [
        {
          // Details for the first instruction
        }
      ]
    }
  },
  // Your second instruction filter
  {
    "include": {
      "instructions": [
        {
          // Details for the second instruction
        }
      ]
    }
  },
  // Add more filters as needed
]

Customize each filter block with the specific instruction details. This way, you capture all relevant instruction types in a single filter configuration. Something like this:

[
  {
    "include": {
      "instructions": [
        {
          // filter calls to CreateMetadaAccountV2 from Metaplex program
          "address": "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s",
          "discriminator": "10",
          "discriminatorType": "u8"
        }
      ]
    }
  },
  {
    "include": {
      "instructions": [
        {
          // filter calls to CreateMetadaAccountV3 from Metaplex program
          "address": "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s",
          "discriminator": "21",
          "discriminatorType": "u8"
        }
      ]
    }
  },
  {
    "include": {
      "instructions": [
        {
          // filter calls to CreateMetadaAccount from Metaplex program
          "address": "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s",
          "discriminator": "00",
          "discriminatorType": "u8"
        }
      ]
    }
  }
]

These examples should get you started on using TransactionFilter to track transactions that are most relevant to your application logic. Adjust the filters to your specific needs by tweaking the parameters provided.