👓Instruction Filters

All filter types that can be applied to instruction query 'filter' objects

Overview

Several of Carpool's instruction queries accept a filter object in the POST body. This is an abstraction on top of Elasticsearch and is made to help users perform powerful aggregations and searches. Below you can find all possible filters for instruction queries

Instruction Filters

📒 INSTRUCTION_ACCOUNT

Description:

Filter for instructions that contain a specific account

Schema fields:

• type*

• accountPubKey*

• accountName

Schema

"filter": {
    "type": "INSTRUCTION_ACCOUNT",
    "accountPubKey": "string",
    "accountName": "string" // A specific account in an instruction's args (via IDL). Leave blank to match any account in the instruction.
}

Example

"filter": {
    "type": "INSTRUCTION_ACCOUNT",
    "accountPubKey": "8mpTNU6vpLSD9mWx4BQt2S6sz2yP39ZhQ9TuMXY4MgUz",
    "accountName": "authority"
}

📛 INSTRUCTION_NAME

Description:

Filter for instructions that contain a specific instruction name

Schema fields:

• type*

• instructionName*

Schema

"filter": {
    "type": "INSTRUCTION_NAME",
    "instructionName": "string"
}

Example

"filter": {
    "type": "INSTRUCTION_NAME",
    "instructionName": "depositFunds"
}

🪵 INSTRUCTION_LOGS

Description:

Filter for instructions that contain the searched text in the their logs

Schema fields:

• type*

• searchText*

Schema

"filter": {
    "type": "INSTRUCTION_LOGS",
    "searchText": "string"
}

Example

"filter": {
    "type": "INSTRUCTION_LOGS",
    "searchText": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
}

1️⃣ INSTRUCTION_ARG_NUMERIC

Description:

Search for instructions with specific numeric arguments present

Schema fields:

• type*

• path*

• range*

Schema

"filter": {
    "type": "INSTRUCTION_ARG_NUMERIC",
    "path": "string", // Dot-delimited for nested fields
    "range": NumericRange
}

NumericRange type

// Either an equality check, or GTE/LTE range, one of which must be set.
export type NumericRange = XOR<XOR<{
  gte: number;
  lte?: number;
}, {
  gte?: number;
  lte: number;
}>, { eq: number }>;

Example - 1

"filter": {
    "type": "INSTRUCTION_ARG_NUMERIC",
    "path": "args.clientOrderId",
    "range": {
        "gte": 2
    }
}

Example - 2

"filter": {
    "type": "INSTRUCTION_ARG_NUMERIC",
    "path": "data.creators.percentageShare",
    "range": {
        "eq": 100
    }
}

💭 INSTRUCTION_ARG_KEYWORD

Description:

Search for instructions with specific string keyword arguments present

Schema fields:

• type*

• path*

• value*

Schema

"filter": {
    "type": "INSTRUCTION_ARG_KEYWORD",
    "path": "string", // Dot-delimited for nested fields
    "value": "string"
}

Example - 1

"filter": {
    "type": "INSTRUCTION_ARG_KEYWORD",
    "path": "newAuthority",
    "value": "ggkMbwPY67ctc1UhETtfvAxzHqV3NJX1ESpPoMhUni3"
}

Example - 2

"filter": {
    "type": "INSTRUCTION_ARG_KEYWORD",
    "path": "data.creators.address",
    "value": "HrBfXpVbojurL5sUJGV7N2WuQDrvSKRFAiwFgpNHHxD3"
}

✅ INSTRUCTION_ARG_EXISTS

Description:

Search for instructions where a specific argument key is present

Schema fields:

• type*

• path*

Schema

"filter": {
    "type": "INSTRUCTION_ARG_EXISTS",
    "path": "string" // Dot-delimited for nested fields
}

Example

"filter": {
    "type": "INSTRUCTION_ARG_EXISTS",
    "path": "data.creators.address"
}

⚠️ INSTRUCTION_ERROR_CODE

Description:

Search for failed instructions where an errorCode is present. Note - you must have "failures" set to true within your query object in your POST body

Schema fields:

• type*

• errorCode

Schema

"filter": {
    "type": "INSTRUCTION_ERROR_CODE",
    "errorCode": number // search all if left blank
}

Example

"filter": {
    "type": "INSTRUCTION_ERROR_CODE",
    "errorCode": 7
}

☎️ INSTRUCTION_CPI_INVOKER

Description:

Search for instructions where a CPI has been invoked

Schema fields:

• type*

• cpiProgramId

Schema

"filter": {
    "type": "INSTRUCTION_CPI_INVOKER",
    "cpiProgramId": "string" // Not set means ANY CPI (you should negate this to remove CPIs).
}

Example

"filter": {
    "type": "INSTRUCTION_CPI_INVOKER"
}

💰 INSTRUCTION_BALANCES

Description:

Search for instructions that match a specified balance or range.

Schema fields:

• type*

• accountPubKey

• token

• delta

Schema

"filter": {
    "type": "INSTRUCTION_BALANCES",
    "accountPubKey": "string", // Scope balance changes to a particular account.
    "token": { // Not setting token will search lamports instead.
        "mint": "string", // The specific token mint
        "owner": "string" // The token account owner
    },
    "delta": NumericRange
}

NumericRange Type

// Either an equality check, or GTE/LTE range, one of which must be set.
export type NumericRange = XOR<XOR<{
  gte: number;
  lte?: number;
}, {
  gte?: number;
  lte: number;
}>, { eq: number }>;

Example - 1

"filter": {
    "type": "INSTRUCTION_BALANCES",
    "accountPubKey": "ykjAirXX9GxX8FF9RdhvfqX5v2cKqABrpafhjkASoaa"
}

Example - 2

This example can be used to find an instance(s) where a particular accountPubKey paid an exact amount of SOL.

"filter": {
    "type": "INSTRUCTION_BALANCES",
    "accountPubKey": "ykjAirXX9GxX8FF9RdhvfqX5v2cKqABrpafhjkASoaa", 
    "delta": {
        "eq": -525478160
    }
}

📅 INSTRUCTION_EVENT_EXISTS

Description:

Search for instructions where a specific Anchor event name is present

Schema fields:

• type*

• eventName*

Schema

"filter": {
    "type": "INSTRUCTION_EVENT_EXISTS",
    "path": "string" // Dot-delimited for nested fields
}

Example

"filter": {
    "type": "INSTRUCTION_EVENT_EXISTS",
    "path": "MovieCreationEvent"
}

2️⃣ INSTRUCTION_EVENT_DATA_NUMERIC

Description:

Search for instructions with specific event numeric values present

Schema fields:

• type*

• eventName*

• path*

• range*

Schema

"filter": {
    "type": "INSTRUCTION_EVENT_DATA_NUMERIC",
    "eventName": "string",
    "path": "string", // Dot-delimited for nested fields
    "range": NumericRange
}

NumericRange type

// Either an equality check, or GTE/LTE range, one of which must be set.
export type NumericRange = XOR<XOR<{
  gte: number;
  lte?: number;
}, {
  gte?: number;
  lte: number;
}>, { eq: number }>;

Example - 1

"filter": {
    "type": "INSTRUCTION_EVENT_DATA_NUMERIC",
    "eventName": "CounterEvent",
    "path": "data",
    "range": {
        "eq": 1
    }
}

Example - 2

"filter": {
    "type": "INSTRUCTION_EVENT_DATA_NUMERIC",
    "eventName": "CounterEvent",
    "path": "data",
    "range": {
        "gte": 10
    }
}

🔤 INSTRUCTION_EVENT_DATA_KEYWORD

Description:

Search for instructions with specific string keywords present in the events

Schema fields:

• type*

• eventName*

• path*

• value*

Schema

"filter": {
    "type": "INSTRUCTION_EVENT_DATA_KEYWORD",
    "eventName": "string",
    "path": "string", // Dot-delimited for nested fields
    "value": "string"
}

Example -

"filter": {
    "type": "INSTRUCTION_EVENT_DATA_KEYWORD",
    "eventName": "MovieCreationEvent",
    "path": "title",
    "value": "Shawshank Redemption"
}

📊 INSTRUCTION_EVENT_DATA_EXISTS

Description:

Search for instructions where a specific Anchor event data fields is present

Schema fields:

• type*

• eventName*

• path*

Schema

"filter": {
    "type": "INSTRUCTION_EVENT_EXISTS",
    "eventName": "string",
    "path": "string" // Dot-delimited for nested fields
}

Example

"filter": {
    "type": "INSTRUCTION_EVENT_EXISTS",
    "eventName": "MovieCreationEvent",
    "path": "title"
}

🔁 INSTRUCTION_TRANSFERS

Description:

Search for instructions with specific transfers done on an instruction level

Schema fields:

• type*

• from

• to

• fromOwner

• toOwner

• mint

• amount

Schema

"filter": {
    "type": "INSTRUCTION_TRANSFERS",
    "from": "string",
    "to": "string",
    "fromOwner": "string", // Only different for Token transfers.
    "toOwner": "string", // Only different for Token transfers.
    "mint": "string", // Only applies to Token transfers - empty for SOL.
    "amount": NumericRange // The amount transferred.
}

NumericRange Type

// Either an equality check, or GTE/LTE range, one of which must be set.
export type NumericRange = XOR<XOR<{
  gte: number;
  lte?: number;
}, {
  gte?: number;
  lte: number;
}>, { eq: number }>;

Example - 1

"filter": {
    "type": "INSTRUCTION_TRANSFERS"
}

Example - 2

"filter": {
    "type": "INSTRUCTION_TRANSFERS",
    "from": "",
    "to": "Cy8WZzQC8QuGPBAFR3XUprJL4G6xYHir1CT3d17vGA4n",
    "fromOwner": "",
    "toOwner": "FyHDZjeK8xqcCidCDwPMLpomRmQT8HrM5dD1U5yFKJv3",
    "mint": "Fx17xv1KJipenEMRrPsX3soJujReNTDN7d4Tqw55q9Zf",
    "amount": {
        "gte": 50
    }
}

Combining Filters

It is important to note that you can also combine any of the above filters within a single query. You can return results based on an AND or OR condition.

AND

Schema

"filter": {
    "and": [
        {
            "type": "FILTER_TYPE",
            ...
        },
        {
            "type": "FILTER_TYPE",
            ...
        },
        ...
    ]
}

Example

"filter": {
    "and": [
        {
            "type": "INSTRUCTION_ARG_EXISTS",
            "path": "data.creators.address"
        },
        {
            "type": "INSTRUCTION_ARG_NUMERIC",
            "path": "data.creators.percentageShare",
            "range": {
                "eq": 100
            }
        }
    ]
}

OR

Schema

"filter": {
    "or": [
        {
            "type": "FILTER_TYPE",
            ...
        },
        {
            "type": "FILTER_TYPE",
            ...
        },
        ...
    ]
}

Example

"filter": {
    "or": [
        {
            "type": "INSTRUCTION_ARG_EXISTS",
            "path": "data.creators.address"
        },
        {
            "type": "INSTRUCTION_ARG_NUMERIC",
            "path": "data.creators.percentageShare",
            "range": {
                "eq": 100
            }
        }
    ]
}

Negating Filters

You can also negate filters if you'd like to look for all instructions that do not match the filter criteria. To negate, simply add "negate": true to the top level of the filter.

Example

"filter": {
    "type": "INSTRUCTION_ARG_EXISTS",
    "path": "data.creators.address",
    "negate": true
}