Noções básicas de tratamento de erros
10 exemplos para começar com Erros e Logs - 7 básicos e 3 intermediários.
Pré-requisitos
- Handlers de instrução retornam
ProgramResultde Rust para Solana.
Exemplos básicos
1. ProgramResult
Instruções retornam Result<(), ProgramError>.
use solana_program::entrypoint::ProgramResult;
pub fn handler() -> ProgramResult { Ok(()) }- Err falha a transação inteira.
- Ok confirma estado atomicamente com outras ix.
- Use
?em helpers.
2. Erros built-in
O runtime fornece códigos de erro padrão.
return Err(ProgramError::InvalidArgument);- Portáteis entre programas.
- Expressividade limitada para UX.
- Bons para falhas de invariante internas.
3. Código de erro customizado
Códigos u32 específicos do domínio.
return Err(ProgramError::Custom(6001));- Clientes mapeiam para mensagens.
- Documente por programa.
- Anchor faz offset automático na IDL.
4. Mapear a partir de enum
From impl estilo thiserror.
impl From<MyError> for ProgramError {
fn from(e: MyError) -> Self { ProgramError::Custom(e as u32) }
}- Habilita ergonomia de
?. - Mantenha códigos estáveis.
- Exporte enum para SDK.
5. Sem panic
Nunca faça unwrap em caminhos de input do usuário.
// BAD: data[0]; // GOOD: data.get(0).ok_or(...)?- Panic aborta a instrução.
- Retorne erros tipados.
- Faça fuzz para encontrar panics.
6. Erros de CPI
Propague falhas do callee.
invoke(&ix, accounts)?;- ? propaga ProgramError.
- Mapeie se precisar de código customizado.
- Logs podem mostrar programa interno.
7. O que o cliente vê
Tx falha com código nos metadados.
// off-chain: parse logs + err code- Simulação mostra os mesmos códigos.
- Carteiras mostram falha genérica.
- Seu dApp mapeia códigos customizados.
Exemplos intermediários
8. Erros Anchor
Atributo error_code no 0.32.1.
#[error_code]
pub enum Error { InsufficientFunds }- Exportação automática na IDL.
- Offset a partir de 6000.
- Compatível com decoders @solana/kit.
Relacionado: Enums de erro customizados
9. Log no caminho de erro
msg curto para debug - atenção ao CU.
solana_program::msg!("reject: insufficient");- Logs públicos - sem segredos.
- Prefira erro customizado para UX.
- Remova em hot paths de produção.
Relacionado: Logging com msg!
10. Decodificar off-chain
Combine código Custom com enum.
// TS: parse simulation err- IDL fornece mapeamento de nomes.
- Nativo precisa de tabela publicada.
- IDL JSON anchor-lang 0.32.1.
Relacionado: Decodificando erros off-chain
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.