Dados de Instruction (de)Serialização

Instruction data é o contrato entre clients e seu programa. Enums Borsh são padrão; opcodes manuais funcionam para controle fino. Ambos exigem disciplina de versionamento estável.

Receita

#[derive(BorshSerialize, BorshDeserialize)]
pub enum MarketInstruction {
    PlaceOrder { price: u64, qty: u64 },
}

Quando usar:

• Adicionar parâmetros a uma instruction.
• Gerar builders de client @solana/kit 7.0.0.
• Migrar formato de instruction entre upgrades.

Exemplo Funcional

#[derive(BorshSerialize, BorshDeserialize)]
pub enum MarketInstruction {
    PlaceOrder { price: u64, qty: u64 },
    CancelOrder { order_id: u64 },
}
 
pub fn parse(data: &[u8]) -> Result<MarketInstruction, ProgramError> {
    MarketInstruction::deserialize(&mut &data[..]).map_err(|_| ProgramError::InvalidInstructionData)
}

O que isso demonstra:

• Variantes carregam campos tipados.
• Função de parse única centraliza erros.
• Clients espelham enum com o mesmo derive.

Aprofundamento

Versionamento

• Prefixe version: u8 antes do body para mudanças breaking.
• Nunca reordene variantes de enum em programas de produção.

Paridade com Client

Publique um crate instructions compartilhado por programa e clients TS/Rust.

Notas Rust

let data = ix.try_to_vec()?; // off-chain builder

Erros Comuns

• String em ix data - Comprimento ilimitado do usuário. Correção: Limite bytes de string ou use keys fixas.
• Padding implícito - Structs manuais podem desalinhar. Correção: Prefira Borsh ou #[repr(C)] com cuidado.
• Drift de client - SDK antigo envia layout errado. Correção: Version gate e documente migração.
• Vec em instruction - Aloca no parse. Correção: Prefira arrays fixos para caminhos sensíveis a CU.
• Opcodes duplicados - Tabelas manuais com colisões. Correção: Centralize constantes.

Alternativas

FAQs

Relacionado

• Serialização Borsh - Formato
• O Entrypoint e o Dispatch - Roteamento
• Construindo Instructions - Clients

Versões do 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.