solanaInstructionDecoder

See the Handling program instructions guide for usage examples and ABI generation. Returns a query-transformer combo that instructs the source to fetch and decode Solana program instructions.

solanaInstructionDecoder<T>(config: SolanaInstructionDecoderConfig<T>): Transformer

Parameters:

range: Slot range { from: number | string | 'latest', to?: number } (required)
program: The program the instructions belong to, usually its typegen module with programId and instructions (required). The decoder reads one address, program.programId. Every entry in instructions must be one of program.instructions.
programId: Deprecated, use program. Program address(es) string | string[], accepted in place of program. The decoder then checks discriminators only, so an instruction from another program with the same discriminator can decode under the wrong key.
instructions: Map of instruction names to ABI instruction objects (required)
profiler: Profiler config shard that’ll be used for labeling the transformer in profiling data { name: string } (optional)
onError: Error handler (ctx: BatchContext, error: any) => unknown | Promise<unknown> (optional)

Example:

const transformer = solanaInstructionDecoder({
  range: { from: 200000000, to: 201000000 },
  program: orcaWhirlpool,
  instructions: {
    swap: orcaWhirlpool.instructions.swap,
    swapV2: orcaWhirlpool.instructions.swapV2,
  },
});

Decoded instruction structure

Each entry in the output arrays is a DecodedInstruction object:

Field	Type	Description
`instruction`	`{ accounts, data }`	Decoded accounts (by name) and instruction data fields
`block`	`{ number: number, hash: string }`	Slot number and block hash
`timestamp`	`Date`	Block timestamp
`transaction`	`Transaction`	Parent transaction (index, signatures)
`innerInstructions`	`Instruction[]`	CPI calls made by this instruction
`rawInstruction`	`Instruction`	Raw instruction as received from the portal, including `programId`
`tokenBalances`	`TokenBalance[]`	Token balance changes in the parent transaction
`blockNumber`	`number`	Deprecated alias for `block.number`

Instruction discriminators

Instructions are filtered by discriminators (prefix bytes of instruction data). The discriminator name indicates how many leading bytes of the instruction data it covers:

Name	Bytes	Hex string length (with `0x` prefix)	Common Use
`d1`	1 byte	4 chars	Simple programs
`d2`	2 bytes	6 chars	Some native programs
`d4`	4 bytes	10 chars	Custom programs
`d8`	8 bytes	18 chars	Anchor programs (most common)

The decoder automatically extracts the appropriate discriminator from the ABI instruction definition.

Multiple programs

A decoder covers one program. Anchor derives an instruction’s discriminator from its name alone, so two programs that each have a swap share a discriminator, and one decoder could not tell them apart. Give each program its own decoder and pass both as outputs:

const stream = solanaPortalStream({
  portal: 'https://portal.sqd.dev/datasets/solana-mainnet',
  outputs: {
    orca: solanaInstructionDecoder({
      range: { from: 200000000 },
      program: orcaWhirlpool,
      instructions: { swap: orcaWhirlpool.instructions.swap },
    }),
    raydium: solanaInstructionDecoder({
      range: { from: 200000000 },
      program: raydiumAmm,
      instructions: { swapBaseIn: raydiumAmm.instructions.swapBaseIn },
    }),
  },
});

To decode the same program deployed at another address, pass a copy of the module with that address: program: { ...orcaWhirlpool, programId: '<address>' }. The decoder checks this when it starts. An instruction that is not one of program.instructions, a program with an empty address, an instruction with no discriminator or more than one, discriminators of mixed widths, or two instructions that share a discriminator fail with E0003.

Error handling

Handle decoding errors:

const decoder = solanaInstructionDecoder({
  range: { from: 200000000 },
  program: orcaWhirlpool,
  instructions: { swap: orcaWhirlpool.instructions.swap },
  onError: (ctx, error) => {
    ctx.logger.warn(`Failed to decode instruction: ${error.message}`);
    // Return null to skip this instruction, or throw to stop processing
    return null;
  },
});

Pipes SDK

Squid SDK

Decoded instruction structure

Instruction discriminators

Multiple programs

Error handling

​Decoded instruction structure

​Instruction discriminators

​Multiple programs

​Error handling

Decoded instruction structure

Instruction discriminators

Multiple programs

Error handling