Enums de erro customizados

Enums de erro customizados traduzem falhas de negócio em códigos u32 estáveis. Anchor publica na IDL; programas nativos devem enviar JSON equivalente para clientes @solana/kit 7.0.0.

Receita

#[repr(u32)]
pub enum VaultError {
    InsufficientFunds = 6000,
    SlippageExceeded = 6001,
}

Quando usar:

• Construir dApps voltados ao usuário que mostram erros específicos.
• Suportar mensagens de erro i18n off-chain.
• Auditar modos de falha.

Exemplo prático

#[error_code]
pub enum Error {
    #[msg("Insufficient funds")]
    InsufficientFunds,
    #[msg("Slippage exceeded")]
    SlippageExceeded,
}

O que isso demonstra:

• Atributo Anchor gera códigos + IDL.
• Strings msg são dicas off-chain.
• Ordem estável importa.

Mergulho profundo

Faixas de código

• Anchor: 6000+
• Nativo: escolha faixa não usada por programa

Exportação IDL

Clientes decodificam nome + código.

Notas Rust

return Err(Error::InsufficientFunds.into());

Erros comuns

• Reordenar enum - Muda códigos - quebra clientes. Correção: apenas append.
• Códigos duplicados entre programas - Confusão em tx multi-CPI. Correção: namespace na UI por program id.
• Vazar dicas de exploit em msg - Strings msg detalhadas são públicas. Correção: texto genérico off-chain.
• Granularidade excessiva - Centenas de códigos difíceis de manter. Correção: agrupe logicamente.
• Sem publicação de IDL - Clientes mostram erro desconhecido. Correção: publique artefato IDL no CI.

Alternativas

FAQs

Relacionados

• Tratamento de erros on-chain - Padrões
• Decodificando erros off-chain - Clientes
• Error Code & require! - Erros Anchor

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.