> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# solanaInstructionDecoder

> API reference for Solana instruction decoder

See the [Handling program instructions](../../guides/basic-development/handling-instructions) guide for usage examples and ABI generation.

Returns a query-transformer combo that instructs the [source](../basic-components/source) to fetch and decode Solana program instructions.

```ts theme={"system"}
solanaInstructionDecoder<T>(config: SolanaInstructionDecoderConfig<T>): Transformer
```

**Parameters:**

* `range`: Slot range `{ from: number | string | 'latest', to?: number }` (required)
* `programId`: Program address(es) `string | string[]` (required)
* `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: BatchCtx, error: any) => unknown | Promise<unknown>` (optional)

**Example:**

```ts theme={"system"}
const transformer = solanaInstructionDecoder({
  range: { from: 200000000, to: 201000000 },
  programId: orcaWhirlpool.programId,
  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 names indicate the number of hex characters returned:

| Name | Hex Characters | Bytes   | Common Use                    |
| ---- | -------------- | ------- | ----------------------------- |
| `d1` | 4 chars        | 2 bytes | Simple programs               |
| `d2` | 8 chars        | 4 bytes | Some native programs          |
| `d4` | 14 chars       | 7 bytes | Custom programs               |
| `d8` | 18 chars       | 9 bytes | Anchor programs (most common) |

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

## Multiple programs

Decode instructions from multiple programs:

```ts theme={"system"}
const decoder = solanaInstructionDecoder({
  range: { from: 200000000 },
  programId: [
    orcaWhirlpool.programId,
    raydiumAmm.programId,
  ],
  instructions: {
    orcaSwap: orcaWhirlpool.instructions.swap,
    raydiumSwap: raydiumAmm.instructions.swapBaseIn,
  },
});
```

## Error handling

Handle decoding errors:

```ts theme={"system"}
const decoder = solanaInstructionDecoder({
  range: { from: 200000000 },
  programId: programId,
  instructions: { swap: 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;
  },
});
```