> ## 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: BatchContext, 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 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

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;
  },
});
```


## Related topics

- [Handling program instructions](/en/sdk/pipes-sdk/solana/guides/basic-development/handling-instructions.md)
- [Quickstart](/en/sdk/pipes-sdk/solana/quickstart.md)
- [Pipes SDK 1.0](/announcements/pipes-sdk-1-0.md)
- [Query builder](/en/sdk/pipes-sdk/solana/reference/basic-components/query-builder.md)
- [Migrate to 1.0](/en/sdk/pipes-sdk/solana/migration.md)