Serialização Borsh

Borsh (Binary Object Representation Serializer for Hashing) é a codificação canônica para dados de instrução Solana e a maioria das structs de conta. É determinístico, little-endian e com prefixo de comprimento para coleções.

Receita

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

Quando usar:

• Definir enums e payloads de instrução.
• Armazenar estado estruturado em contas de dados.
• Corresponder à serialização padrão de conta do Anchor.

Exemplo Funcional

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(())
}

O que isso demonstra:

• Variantes de enum de instrução codificam com discriminante u8 inicial por padrão.
• Dados de conta são lidos/escritos pelo slice de bytes da conta.
• Aritmética verificada protege a atualização de estado antes da serialização.

Aprofundamento

Como Funciona

• Primitivos codificam em largura fixa little-endian.
• String e Vec<T> prefixam com comprimento u32.
• Deserialize consome bytes sequencialmente - bytes trailing são ignorados a menos que você valide comprimento.

Planejamento de Tamanho

Notas Rust

// Use try_to_vec para dados de instrução; verifique account.data.len() >= size.
const STATE_LEN: usize = core::mem::size_of::<u64>();

Armadilhas

• Conta pequena demais - Serialize faz panic ou trunca se data.len() for insuficiente. Correção: Aloque espaço exato na criação da conta e armazene constante LEN.
• Deriva de schema - Adicionar campos quebra contas antigas sem migração. Correção: Byte de versão ou discriminador mais instrução de migração.
• Reordenar enum - Mudar ordem de variantes muda discriminantes. Correção: Acrescente novas variantes; nunca reordene.
• Strings UTF-8 - UTF-8 inválido falha deserialização. Correção: Valide off-chain antes de enviar ou use arrays de bytes fixos.
• Conflito de borrow - Serializar com outro borrow ativo faz panic. Correção: Solte borrows imutáveis antes de borrow_mut.

Alternativas

FAQs

Relacionado

• Account Discriminators - Tagging de tipo
• Borsh Structs - Design de layout
• Zero-Copy with bytemuck - Alternativa de performance

Versões da stack: Esta página foi escrita para 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 e LiteSVM 0.6.x.