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
| Alternativa | Use quando | Não use quando |
|---|---|---|
| Apenas ProgramError built-in | Programas internos | UX |
| Erros String | Não on-chain | N/A |
| Eventos para falhas | Ferramenta errada | Use erros |
FAQs
Atributo msg do Anchor?
Metadados para IDL.
IDL nativo?
Escreva à mão ou use Codama.
i18n?
Mapeie código para locale off-chain.
Simulação?
Retorna o mesmo código customizado.
Erro em CPI?
Pode ver código do callee nos logs.
u32 max?
Limite prático menor.
thiserror?
Testes em cfg host.
Fuzz?
Todos os branches retornam Err, não panic.
6000 reservado?
Convenção Anchor.
Múltiplos programas?
Tupla program id + código.
Versão IDL?
Marque releases.
Decoder Kit?
Helpers @solana/kit 7.0.0.
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.