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 ProgramResult de 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.