Borsh Serialization

Borsh (Binary Object Representation Serializer for Hashing) is the canonical encoding for Solana instruction data and most account structs. It is deterministic, little-endian, and length-prefixed for collections.

Recipe

use borsh::{BorshDeserialize, BorshSerialize};
 
#[derive(BorshSerialize, BorshDeserialize)]
pub struct Deposit {
    pub amount: u64,
}
 
let ix_data = Deposit { amount: 1_000 }.try_to_vec()?;

When to reach for this:

• Defining instruction enums and payloads.
• Storing structured state in data accounts.
• Matching Anchor's default account serialization.

Working Example

use borsh::{BorshDeserialize, BorshSerialize};
use solana_program::{
    account_info::{next_account_info, AccountInfo},
    entrypoint::ProgramResult,
    program_error::ProgramError,
    pubkey::Pubkey,
};
 
#[derive(BorshSerialize, BorshDeserialize)]
pub enum VaultInstruction {
    Deposit { amount: u64 },
    Withdraw { amount: u64 },
}
 
#[derive(BorshSerialize, BorshDeserialize)]
pub struct VaultState {
    pub total: u64,
}
 
pub const VAULT_LEN: usize = 8;
 
pub fn process_deposit(
    accounts: &[AccountInfo],
    amount: u64,
) -> ProgramResult {
    let iter = &mut accounts.iter();
    let vault = next_account_info(iter)?;
    let mut state = VaultState::deserialize(&mut &vault.data.borrow()[..])
        .map_err(|_| ProgramError::InvalidAccountData)?;
    state.total = state
        .total
        .checked_add(amount)
        .ok_or(ProgramError::InvalidArgument)?;
    state.serialize(&mut &mut vault.data.borrow_mut()[..])?;
    Ok(())
}

What this demonstrates:

• Instruction enum variants encode as a leading u8 discriminant by default.
• Account data is read/written through the account byte slice.
• Checked arithmetic guards the state update before serialization.

Deep Dive

How It Works

• Primitives encode in little-endian fixed width.
• String and Vec<T> prefix with a u32 length.
• Deserialize consumes bytes sequentially - trailing bytes are ignored unless you validate length.

Size Planning

Rust Notes

// Use try_to_vec for instruction data; check account.data.len() >= size.
const STATE_LEN: usize = core::mem::size_of::<u64>();

Gotchas

• Account too small - Serialize panics or truncates if data.len() is insufficient.. Fix: Allocate exact space at account creation and store LEN constant.
• Schema drift - Adding fields breaks old accounts without migration.. Fix: Version byte or discriminator plus migration instruction.
• Enum reorder - Changing variant order changes discriminants.. Fix: Append new variants; never reorder.
• UTF-8 strings - Invalid UTF-8 fails deserialization.. Fix: Validate off-chain before sending or use fixed byte arrays.
• Borrow conflict - Serializing while another borrow is active panics.. Fix: Drop immutable borrows before borrow_mut.

Alternatives

FAQs

Related

• Account Discriminators - Type tagging
• Borsh Structs - Layout design
• Zero-Copy with bytemuck - Performance alternative

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.