Canonical: https://solanashreds.xyz/learn/borsh-encoding

# Borsh, the byte layout behind most Solana instruction data

Borsh serialization on Solana, as a byte level reference: integers, strings, vectors, options, enums and public keys, with the rule for each.

Borsh serialization on Solana writes values in declaration order with no padding and no field names: fixed-width little-endian integers, a one-byte bool, a four-byte length before every string and vector, a one-byte tag before every option and enum, and public keys as their raw 32 bytes. Decoding it means knowing the type list in advance.

## The layout table

| Type | Bytes | Rule |
| --- | --- | --- |
| `u8`, `i8` | 1 | as is |
| `u16`, `i16` | 2 | little-endian |
| `u32`, `i32` | 4 | little-endian |
| `u64`, `i64` | 8 | little-endian |
| `u128`, `i128` | 16 | little-endian |
| `bool` | 1 | 0 is false, 1 is true |
| `Pubkey` | 32 | the raw key bytes, never base58 text |
| `[T; N]` fixed array | N times the size of T | no length prefix |
| `String` | 4 + length | `u32` byte length, then UTF-8 bytes |
| `Vec<T>` | 4 + items | `u32` item count, then each item |
| `Option<T>` | 1 or 1 + T | tag 0 for none, tag 1 then the value |
| enum | 1 + variant fields | `u8` variant index, then that variant's fields |
| struct | sum of fields | fields in declaration order, nothing between them |

Every value's size follows from its type and, for strings, vectors, options and enums, from bytes you have already read. Nothing in the data describes itself.

## Strings and vectors

Strings and vectors start with a four-byte little-endian count. For a string it counts bytes of UTF-8, not characters; for a vector it counts items, and each item is then laid out by its own type. A vector of a variable-size type cannot be skipped without decoding every item, because there is no total length anywhere.

That count is attacker-controlled input. A decoder that allocates memory for the claimed length before checking that the bytes exist will fall over on a malformed instruction, so check the remaining length first.

## Options and enums

An option is one tag byte, followed by the value only when the tag is 1. An enum is one byte giving the variant's position in the type's declaration, counting from zero, followed by that variant's fields, if any. The variant's name never appears in the bytes, so the order of variants in the IDL is part of the format. Jupiter's `Swap` enum has 211 variants in its current on-chain IDL; reading variant 47 with an older copy of the list gives you the wrong swap, or an error.

## A real Jupiter route, byte by byte

This `route` instruction from mainnet slot 470,901,816 is 37 bytes long and uses almost every rule in the table:

| Bytes | Hex | Type | Value |
| --- | --- | --- | --- |
| 0 to 7 | `e517cb977ae3ad2a` | discriminator | `route` |
| 8 to 11 | `01000000` | `u32` vector length | one route step |
| 12 | `2f` | enum tag | variant 47, `WhirlpoolSwapV2` |
| 13 | `01` | `bool` (variant field) | `a_to_b` is true |
| 14 | `00` | `Option` tag | `remaining_accounts_info` is none |
| 15 | `64` | `u8` | percent: 100 |
| 16 to 17 | `00 01` | two `u8` | input index 0, output index 1 |
| 18 to 25 | `6d3cf50000000000` | `u64` | in amount: 16,071,789 |
| 26 to 33 | `3bbecd0000000000` | `u64` | quoted out amount: 13,483,579 |
| 34 to 35 | `c800` | `u16` | slippage: 200 basis points |
| 36 | `00` | `u8` | platform fee: 0 basis points |

Nothing in those bytes says "WhirlpoolSwapV2" or "slippage". Every label came from the IDL.

## Programs that do not use Borsh

Borsh is Anchor's default, so most Anchor programs use it, but several of the busiest programs predate it or chose otherwise. SPL Token packs its instructions by hand: one tag byte, then fixed fields, with its own conventions for optional values. The System program starts with a four-byte tag. Raydium AMM v4 uses a one-byte tag and fixed little-endian fields. These layouts often look like Borsh for simple fields, which is why mistakes go unnoticed until a field with an optional value or a different tag width appears. The [token program's tags and account order](https://solanashreds.xyz/learn/spl-token-instructions) cover that program's layout.

## Reading Borsh straight out of shred-decoded transactions

A shred decoder hands you each instruction's data as raw bytes. The first eight bytes, for an Anchor program, select the instruction through its [discriminator](https://solanashreds.xyz/learn/anchor-discriminators); the rest is Borsh in the order the IDL lists the arguments. Decode only the programs you care about and stop at the first byte that does not fit, rather than guessing.

One real-world wrinkle: programs add arguments at the end over time, and older clients keep sending the shorter form. When the data ends exactly where an argument would begin, report that argument as absent rather than failing, and never fill in a default. [Common Borsh mistakes](https://solanashreds.xyz/blog/borsh-pitfalls) lists more.

## Questions about Borsh

### Is Borsh big-endian or little-endian?

Little-endian for every integer.

### How long is a Borsh string's length prefix?

Four bytes, an unsigned 32-bit count of UTF-8 bytes.

### Why does my decoder read garbage after one field?

Usually a wrong type for an earlier field: one byte too many or too few shifts everything after it. Check option tags and enum variants first, then integer widths.

## What Borsh alone cannot tell you

Borsh gives you values, not meaning. Without the program's type definitions you cannot even find where one field ends, and without its documentation you cannot know what a field does. Instruction data also records only what the sender asked for: the swap above quoted 13,483,579 as the expected output, not the amount it received.

## Decoding with an IDL

[Reading an IDL](https://solanashreds.xyz/learn/reading-an-idl) shows where the type list comes from, and the [Anchor decoding guide](https://solanashreds.xyz/docs/decode/anchor-instructions) has a working decoder for any IDL. The [Jupiter recipe](https://solanashreds.xyz/docs/programs/jupiter) goes further with this exact instruction, and [your first decode](https://solanashreds.xyz/docs/quickstart) runs on live shreds.
