Filter by program ID and account before you decode further
Most pipelines care about a handful of programs. This page puts the filter where it costs least and still never drops a match: program IDs straight from the static keys, accounts with a third answer for what lookup tables hide. Tested on two mainnet blocks against what the chain recorded.
Filter on program IDs right after decoding a transaction's message, using its static keys. Every program a transaction calls at the top level is a static key, so this filter needs no lookup tables and misses nothing at that level. Filter on accounts the same way, but treat a v0 transaction with lookups as unknown until you resolve them.
Three filter points and their trade-offs#
| Where | What you can filter on | Cost | What it can miss |
|---|---|---|---|
| On raw shreds | Nothing per transaction: a shred is a slice of a block, not of a transaction | None saved | Everything; there is no transaction here yet |
| After decoding the message (static keys) | Called programs; accounts listed as static keys | One message decode per transaction, no network | Accounts that a v0 transaction loads from lookup tables |
| After resolving lookup tables | Every account the transaction names | A lookup-table cache, kept current from RPC or from table instructions | Only what shreds never carry: inner calls and outcomes |
The middle row is where a program filter belongs. Run the expensive work, such as decoding instruction data or resolving tables, only for the transactions that pass it.
Steps#
- Build a set of the program IDs you care about, as base58 strings.
- For each transaction cut out of a block component, decode the message and read its static keys and its top-level instructions.
- Keep the transaction if any instruction's program index points at a key in your set. Nothing else is needed for programs.
- For account filters, check the static keys first. If the account is not there and the transaction has lookups, answer "unknown" and resolve the tables before you decide.
- Hand the transactions that pass to your decoders and storage, and drop the rest before they cost you anything.
filter.ts#
// D10: filter transactions by program and by account, at the cheapest stage that is still correct.import type { Loaded, TxView } from "./view.ts";/*** Program filter. Every top-level program is a static key: a v0 message whose program index points into a lookup* table is rejected by the runtime, and v1 has no lookup tables at all. So this needs no lookup resolution and,* for top-level calls, has no false negatives. Programs called through CPI are invisible in shreds either way.*/export function callsProgram(v: TxView, programs: Set<string>): boolean {return v.instructions.some((ix) => programs.has(v.staticKeys[ix.programIndex]));}export type Match = "yes" | "no" | "unknown";/*** Account filter. Static keys answer at once. A v0 transaction with lookups may still name the account through a* table, so without the table contents the answer is "unknown", never "no". Pass `resolve` (your lookup-table cache)* to settle those.*/export function touchesAccount(v: TxView, accounts: Set<string>, resolve?: (v: TxView) => Loaded | undefined): Match {if (v.staticKeys.some((k) => accounts.has(k))) return "yes";if (!v.lookups.length) return "no";const loaded = resolve?.(v);if (!loaded) return "unknown";return [...loaded.writable, ...loaded.readonly].some((k) => accounts.has(k)) ? "yes" : "no";}
view.ts#
// One shape for legacy, v0 and v1 transactions decoded by @solana/kit 8.6.0: static keys, lookups and top-level// instructions as (program index, account indexes, data). Shared by the D10, D13 and D14 recipes.import { getTransactionDecoder, getCompiledTransactionMessageDecoder, getBase58Decoder } from "@solana/kit";const txDecoder = getTransactionDecoder();const messageDecoder = getCompiledTransactionMessageDecoder();const base58 = getBase58Decoder();// data is kit's read-only byte view; these recipes only read itexport type Instruction = { programIndex: number; accounts: number[]; data: Uint8Array };export type Lookup = { table: string; writable: number[]; readonly: number[] };export type TxView = { signature: string; version: string; staticKeys: string[]; lookups: Lookup[]; instructions: Instruction[] };/** Decode one transaction (its exact bytes, see transactionLength in decoder.ts) into a TxView. */export function viewOf(bytes: Uint8Array): TxView {const tx = txDecoder.decode(bytes);const m = messageDecoder.decode(tx.messageBytes);const first = Object.values(tx.signatures)[0];const instructions: Instruction[] = "instructionHeaders" in m? m.instructionHeaders.map((h, i) => ({ programIndex: h.programAccountIndex, accounts: [...m.instructionPayloads[i].instructionAccountIndices], data: m.instructionPayloads[i].instructionData as Uint8Array })): m.instructions.map((ix) => ({ programIndex: ix.programAddressIndex, accounts: [...(ix.accountIndices ?? [])], data: (ix.data ?? new Uint8Array()) as Uint8Array }));const lookups: Lookup[] = "addressTableLookups" in m && m.addressTableLookups? m.addressTableLookups.map((l) => ({ table: l.lookupTableAddress, writable: [...l.writableIndexes], readonly: [...l.readonlyIndexes] })): [];return { signature: first ? base58.decode(first) : "", version: String(m.version), staticKeys: [...m.staticAccounts], lookups, instructions };}/** Looked-up addresses for a v0 transaction, in the order the runtime appends them: all writable, then all readonly. */export type Loaded = { writable: string[]; readonly: string[] };/** The full account list: static keys, then looked-up writable, then looked-up readonly (T-06). */export function allKeys(v: TxView, loaded?: Loaded): string[] {return loaded ? [...v.staticKeys, ...loaded.writable, ...loaded.readonly] : v.staticKeys;}
filter-worker.ts#
This worker plugs into the receiver from the TypeScript decoder, which reads shreds and assembles block components; transactionSlices there cuts out each transaction's exact bytes.
// Worker thread for receiver.ts: decode only the transactions that call one of the programs you list.// WORKER=./filter-worker.ts PROGRAMS=11111111111111111111111111111111,TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA node receiver.ts 8001import { parentPort } from "node:worker_threads";import { transactionSlices } from "./decoder.ts";import { viewOf } from "./view.ts";import { callsProgram } from "./filter.ts";const programs = new Set((process.env.PROGRAMS ?? "").split(",").filter(Boolean));parentPort!.on("message", ({ slot, component }: { slot: bigint; component: Uint8Array }) => {try {for (const bytes of transactionSlices(component)) {const tx = viewOf(bytes);if (!callsProgram(tx, programs)) continue; // cheap: static keys only, no lookup tables neededprocess.stdout.write(JSON.stringify({ slot: Number(slot), signature: tx.signature, version: tx.version }) + "\n");}} catch (err) {process.stderr.write(`slot ${slot}: skipped a component: ${(err as Error).message}\n`);}});
Why invoked programs are always static keys#
A v0 transaction can load accounts from lookup tables, so it is fair to ask whether a program could hide there. It cannot. When the runtime sanitizes a v0 message, it rejects any instruction whose program index points past the static keys, and a program can never sit at index 0, which is the fee payer. Version 1 transactions have no lookup tables at all.
The fixtures agree: across 3,754 top-level instructions in 781 mainnet transactions, not one program index pointed outside the static keys or at the fee payer. That is why the program filter needs no lookup resolution and why it has no false negatives for top-level calls.
Account filters#
Accounts are different. A v0 transaction lists its static keys, then the indexes of addresses inside one or more lookup tables, and the shreds carry only those indexes. An account you watch may be loaded that way, and you will not see its address until you read the table.
So touchesAccount returns three answers. "yes" and "no" are final; "unknown" means the transaction has lookups and you have not resolved them. Treat "unknown" as a candidate, never as a no. To settle it, keep a cache of lookup-table contents and pass it as resolve; resolving address lookup tables shows how to build and refresh one.
How this was tested#
Fixtures: two consecutive mainnet blocks, slots 470,901,815 and 470,901,816, 781 transactions, with the meta RPC returned for them. Tests: node test-recipes.ts on Node 24.14 with @solana/kit 8.6.0.
| Test | Result |
|---|---|
| Program index outside the static keys, or at the fee payer | 0 of 3,754 top-level instructions |
| System program filter against an independent hand-written decoder | 392 of 781 transactions, identical sets |
| Account filter on static keys only, for an address that appears only through lookup tables | 0 wrong "no" answers; 95 "unknown" covering all 6 real matches |
| Account filter with lookups resolved from the recorded loaded addresses | exact on all 781 transactions |
| Over UDP: receiver plus filter worker, shuffled datagrams with duplicates | 392 of 392 System transactions printed, nothing else |
What a filter here cannot see#
Programs called by other programs through cross-program invocation do not appear in the transaction you receive. A swap that moves tokens through the token program inside a router shows only the router at the top level. Inner instructions and CPI explains why shreds cannot show them.
A filter on shreds also passes transactions that later fail. The bytes are the same whether or not the transaction succeeds, so anything that matters for money waits for confirmation.
Questions#
Can program IDs come from a lookup table?#
No. A v0 message whose instruction points at a program loaded from a lookup table is rejected, and v1 transactions have no lookup tables. Every top-level program is a static key.
Should I filter before or after decoding?#
After decoding the message, before anything else. You need the message to know which programs a transaction calls, but you do not need to decode instruction data or resolve lookup tables to filter on programs.
Why do some transactions come back as unknown?#
They are v0 transactions with lookup tables, and the account you filter on is not among their static keys. The answer depends on addresses the shreds do not carry, so resolve the tables before you rule them out.
Next#
Filter early, filter cheap argues where the filter sits in a pipeline, and token transfers is a recipe that runs behind it. To find the ID of the program you want, see finding a program ID. When you are ready to run it on a live stream, see pricing.
Sources#
- anza-xyz/solana-sdk message/src/versions/v0/mod.rs: sanitize rejects program ids loaded from lookup tables (checked 2026-11-18)
- SIMD-0385 Transaction V1 Format: no address lookup tables in v1 (checked 2026-11-18)
- @solana/kit 8.6.0 (anza-xyz/kit): compiled transaction message decoder (checked 2026-11-18)
- Fixtures: mainnet blocks 470,901,815 and 470,901,816 with their getBlock meta (loaded addresses, balances) (checked 2026-11-18)
Raw shreds on your own server
Ultra Low Latency Shreds is $200 and Standard Shreds is $100. You pay in crypto, tell us which IPv4 address and UDP port should receive the stream, and we wire it up by hand.