Fundamentos del manejo de errores
10 ejemplos para empezar con Errores y Registros: 7 básicos y 3 intermedios.
Prerrequisitos
- Los manejadores de instrucciones devuelven
ProgramResultde Rust para Solana.
Ejemplos básicos
1. ProgramResult
Las instrucciones devuelven Result<(), ProgramError>.
use solana_program::entrypoint::ProgramResult;
pub fn handler() -> ProgramResult { Ok(()) }Errfalla toda la transacción.Okconfirma el estado atómicamente con otras instrucciones.- Usa
?en ayudantes.
2. Errores integrados
El runtime proporciona códigos de error estándar.
return Err(ProgramError::InvalidArgument);- Portátil entre programas.
- Expresividad limitada para la experiencia del usuario (UX).
- Bueno para fallos de invariantes internas.
3. Código de error personalizado
Códigos u32 específicos del dominio.
return Err(ProgramError::Custom(6001));- Los clientes mapean a mensajes.
- Documentar por programa.
- Los offsets de Anchor se auto-generan en el IDL.
4. Mapeo desde enum
Implementación From estilo thiserror.
impl From<MyError> for ProgramError {
fn from(e: MyError) -> Self { ProgramError::Custom(e as u32) }
}- Habilita la ergonomía de
?. - Mantener los códigos estables.
- Exportar el enum para el SDK.
5. Sin panic
Nunca uses unwrap en rutas de entrada del usuario.
// MAL: data[0]; // BIEN: data.get(0).ok_or(...)?Panicaborta la instrucción.- Devuelve errores tipados.
- Usa fuzzing para encontrar panics.
6. Errores de CPI
Propaga los fallos del llamado.
invoke(&ix, accounts)?;?propagaProgramError.- Mapea si necesitas un código personalizado.
- Los registros pueden mostrar el programa interno.
7. El cliente ve
Transacción fallida con código en metadatos.
// fuera de cadena: parsear registros + código de error- La simulación previsualiza los mismos códigos.
- Las billeteras muestran un fallo genérico.
- Tu dApp mapea los códigos personalizados.
Ejemplos intermedios
8. Errores de Anchor
Atributo error_code en 0.32.1.
#[error_code]
pub enum Error { InsufficientFunds }- Exportación automática de IDL.
- Offset a partir de 6000.
- Compatible con decodificadores de
@solana/kit.
Relacionado: Enums de error personalizados
9. Registrar en la ruta de error
Mensaje corto para depuración - ten en cuenta las CU.
solana_program::msg!("reject: insufficient");- Registros públicos - sin secretos.
- Prefiere errores personalizados para la UX.
- Eliminar en rutas críticas de producción.
Relacionado: Registro con msg!
10. Decodificar fuera de cadena
Emparejar código personalizado con enum.
// TS: parsear error de simulación- El IDL proporciona el mapeo de nombres.
- El nativo necesita una tabla publicada.
- IDL JSON de Anchor lang 0.32.1.
Relacionado: Decodificación de errores fuera de cadena
Versiones de la pila: Esta página se escribió 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.