Manejo de Errores On-Chain

Los programas comunican fallos a través de ProgramResult (Result<(), ProgramError>) o enums de error personalizados mapeados a códigos. Los clientes decodifican estos códigos off-chain para la experiencia de usuario y la depuración.

Receta

use solana_program::program_error::ProgramError;
 
fn require_init(data_len: usize, need: usize) -> Result<(), ProgramError> {
    if data_len < need {
        return Err(ProgramError::InvalidAccountData);
    }
    Ok(())
}

Cuándo usar esto:

• Reemplazar panic con fallos de instrucción recuperables.
• Definir errores específicos del dominio (deslizamiento, expirado, no autorizado).
• Propagar errores de ayudantes con ?.

Ejemplo Funcional

use solana_program::program_error::ProgramError;
 
#[repr(u32)]
pub enum VaultError {
    InsufficientFunds = 6000,
    Unauthorized = 6001,
}
 
impl From<VaultError> for ProgramError {
    fn from(e: VaultError) -> Self {
        ProgramError::Custom(e as u32)
    }
}
 
pub fn withdraw(amount: u64, balance: u64) -> Result<(), ProgramError> {
    if amount > balance {
        return Err(VaultError::InsufficientFunds.into());
    }
    Ok(())
}

Qué demuestra esto:

• Los errores personalizados usan ProgramError::Custom(code).
• La implementación From habilita ? en los manejadores de instrucciones.
• Reservar rangos de códigos por programa para evitar colisiones con Anchor.

Análisis Profundo

Capas de Error

Mapeo Off-Chain

• La IDL de Anchor incrusta nombres de error.
• Los programas nativos documentan códigos en README o en el JSON de la IDL.

Notas de Rust

type VaultResult<T> = Result<T, ProgramError>;

Errores Comunes

• panic en expect - Aborta sin un código personalizado. Solución: Devolver Err con una variante explícita.
• Colisión de códigos - 6000 puede colisionar con otros programas en los mismos logs de transacciones. Solución: Nombrar códigos en espacio de nombres; documentar por programa.
• Fugas de detalles internos - Los logs detallados revelan pistas para exploits. Solución: Registrar un mensaje genérico públicamente; detallar en simulación privada.
• Ignorar errores de CPI - Se debe propagar el Result de invoke. Solución: Usar ? o mapear a tu enum.
• Demasiadas variantes - Los enums de error grandes siguen siendo baratos, pero mantén actualizado el mapeo del cliente. Solución: Versionar la IDL junto con el programa.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Manejo de Errores - Introducción a la sección
• Enums de Error Personalizados - Códigos compatibles con IDL
• Depuración de Transacciones Fallidas - Lectura de fallos

Versiones de Stack: Esta página fue 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, y LiteSVM 0.6.x.