Noções Básicas de Serialização

10 exemplos para você começar com a Serialização de Contas - 7 básicos e 3 intermediários.

Pré-requisitos

• Familiaridade com Borsh de Rust para Solana.

Exemplos Básicos

1. Struct de conta Borsh

Serializa o estado estruturado em dados da conta.

#[derive(BorshSerialize, BorshDeserialize)]
pub struct Config { pub fee_bps: u16 }

• Escolha padrão para estado pequeno/médio.
• Versionamento fácil com campos extras no final.
• Custo de computação escala com o tamanho.

2. Constante de tamanho da conta

Declara o espaço antecipadamente para create_account.

impl Config { pub const LEN: usize = 2; }

• Incompatibilidade causa falha na serialização.
• Inclui bytes do discriminador no total.
• InitSpace do Anchor calcula automaticamente.

3. Prefixo discriminador

Marca o tipo da conta para evitar confusão.

pub const DISCRIMINATOR: [u8; 8] = [0xC0, 0xFF, 0xEE, 0x00, 0x00, 0x00, 0x00, 0x01];

• Anchor usa discriminadores de hash de 8 bytes.
• Verifica antes de desserializar.
• Tipos diferentes devem ser distintos.

4. Guarda de desserialização

Valida o comprimento e o discriminador primeiro.

if data.len() < Config::LEN { return Err(ProgramError::InvalidAccountData); }

• Nunca desserialize contas não confiáveis.
• Mapeia erros para InvalidAccountData.
• Rejeita lixo de cauda para layouts fixos.

5. Zero-copy quando grande

Use Pod para grandes arrays fixos.

#[repr(C)]
#[derive(Pod, Zeroable, Clone, Copy)]
pub struct Book { pub bids: [u64; 256] }

• Evita CUs de loop de análise.
• Requer disciplina repr(C).
• Veja a página de contas zero-copy.

6. Instrução vs. conta

Instruções geralmente são Borsh; contas podem ser híbridas.

// ix: enum Instruction { Update { val: u64 } }

• Dados de Ix são efêmeros por transação.
• Dados da conta persistem na chain.
• Mantenha os esquemas separados.

7. Rent e tamanho

Contas maiores precisam de mais lamports.

let rent = Rent::get()?.minimum_balance(Config::LEN);

• Mínimo isento de rent exigido.
• realloc aumenta o rent necessário.
• Usuários pagam na criação/realloc.

Exemplos Intermediários

8. Migração de byte de versão

O primeiro byte indica a versão do esquema.

pub enum Version { V1 = 1, V2 = 2 }

• A ix de migração lê V1 e escreve V2.
• Nunca assuma que todas as contas foram atualizadas.
• Suporte a ambos durante a implantação.

Relacionado: Versionamento e Migração de Dados

9. realloc para crescer

Expande a conta quando o esquema cresce.

// CPI realloc + transferência de rent e depois novos campos

• Precisa de lamports do pagador.
• Zero novos bytes ou inicialização explícita.
• Veja o artigo sobre realloc.

Relacionado: realloc e Contas em Crescimento

10. Cálculo de espaço

Soma discriminador + campos + preenchimento.

pub const SPACE: usize = 8 + Config::LEN;

• Documenta a fórmula no código.
• Testa no host com serialização.
• Macro init space do Anchor.

Relacionado: Cálculo de Espaço

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.