9 unstable releases (4 breaking)

0.5.0 Jun 25, 2024
0.4.4 Jul 11, 2024
0.4.1 Apr 22, 2024
0.4.0 Mar 28, 2024
0.1.0 Jun 7, 2023

#1135 in Magic Beans

Download history 25351/week @ 2024-03-14 25486/week @ 2024-03-21 34336/week @ 2024-03-28 76301/week @ 2024-04-04 38934/week @ 2024-04-11 34729/week @ 2024-04-18 30757/week @ 2024-04-25 28278/week @ 2024-05-02 29416/week @ 2024-05-09 26886/week @ 2024-05-16 24470/week @ 2024-05-23 30984/week @ 2024-05-30 29792/week @ 2024-06-06 32070/week @ 2024-06-13 31734/week @ 2024-06-20 25388/week @ 2024-06-27

124,600 downloads per month
Used in 422 crates (7 directly)

Apache-2.0

13KB

SPL Program Error

Macros for implementing error-based traits on enums.

  • #[derive(IntoProgramError)]: automatically derives the trait From<Self> for solana_program::program_error::ProgramError.
  • #[derive(DecodeError)]: automatically derives the trait solana_program::decode_error::DecodeError<T>.
  • #[derive(PrintProgramError)]: automatically derives the trait solana_program::program_error::PrintProgramError.
  • #[spl_program_error]: Automatically derives all below traits:
    • Clone
    • Debug
    • Eq
    • DecodeError
    • IntoProgramError
    • PrintProgramError
    • thiserror::Error
    • num_derive::FromPrimitive
    • PartialEq

#[derive(IntoProgramError)]

This derive macro automatically derives the trait From<Self> for solana_program::program_error::ProgramError.

Your enum must implement the following traits in order for this macro to work:

  • Clone
  • Debug
  • Eq
  • thiserror::Error
  • num_derive::FromPrimitive
  • PartialEq

Sample code:

/// Example error
#[derive(
    Clone, Debug, Eq, IntoProgramError, thiserror::Error, num_derive::FromPrimitive, PartialEq,
)]
pub enum ExampleError {
    /// Mint has no mint authority
    #[error("Mint has no mint authority")]
    MintHasNoMintAuthority,
    /// Incorrect mint authority has signed the instruction
    #[error("Incorrect mint authority has signed the instruction")]
    IncorrectMintAuthority,
}

#[derive(DecodeError)]

This derive macro automatically derives the trait solana_program::decode_error::DecodeError<T>.

Your enum must implement the following traits in order for this macro to work:

  • Clone
  • Debug
  • Eq
  • IntoProgramError (above)
  • thiserror::Error
  • num_derive::FromPrimitive
  • PartialEq

Sample code:

/// Example error
#[derive(
    Clone,
    Debug,
    DecodeError,
    Eq,
    IntoProgramError,
    thiserror::Error,
    num_derive::FromPrimitive,
    PartialEq,
)]
pub enum ExampleError {
    /// Mint has no mint authority
    #[error("Mint has no mint authority")]
    MintHasNoMintAuthority,
    /// Incorrect mint authority has signed the instruction
    #[error("Incorrect mint authority has signed the instruction")]
    IncorrectMintAuthority,
}

#[derive(PrintProgramError)]

This derive macro automatically derives the trait solana_program::program_error::PrintProgramError.

Your enum must implement the following traits in order for this macro to work:

  • Clone
  • Debug
  • DecodeError<T> (above)
  • Eq
  • IntoProgramError (above)
  • thiserror::Error
  • num_derive::FromPrimitive
  • PartialEq

Sample code:

/// Example error
#[derive(
    Clone,
    Debug,
    DecodeError,
    Eq,
    IntoProgramError,
    thiserror::Error,
    num_derive::FromPrimitive,
    PartialEq,
)]
pub enum ExampleError {
    /// Mint has no mint authority
    #[error("Mint has no mint authority")]
    MintHasNoMintAuthority,
    /// Incorrect mint authority has signed the instruction
    #[error("Incorrect mint authority has signed the instruction")]
    IncorrectMintAuthority,
}

#[spl_program_error]

It can be cumbersome to ensure your program's defined errors - typically represented in an enum - implement the required traits and will print to the program's logs when they're invoked.

This procedural macro will give you all of the required implementations out of the box:

  • Clone
  • Debug
  • Eq
  • thiserror::Error
  • num_derive::FromPrimitive
  • PartialEq

It also imports the required crates so you don't have to in your program:

  • num_derive
  • num_traits
  • thiserror

Just annotate your enum...

use solana_program_error_derive::*;

/// Example error
#[solana_program_error]
pub enum ExampleError {
    /// Mint has no mint authority
    #[error("Mint has no mint authority")]
    MintHasNoMintAuthority,
    /// Incorrect mint authority has signed the instruction
    #[error("Incorrect mint authority has signed the instruction")]
    IncorrectMintAuthority,
}

...and get:

/// Example error
pub enum ExampleError {
    /// Mint has no mint authority
    #[error("Mint has no mint authority")]
    MintHasNoMintAuthority,
    /// Incorrect mint authority has signed the instruction
    #[error("Incorrect mint authority has signed the instruction")]
    IncorrectMintAuthority,
}
#[automatically_derived]
impl ::core::clone::Clone for ExampleError {
    #[inline]
    fn clone(&self) -> ExampleError {
        match self {
            ExampleError::MintHasNoMintAuthority => ExampleError::MintHasNoMintAuthority,
            ExampleError::IncorrectMintAuthority => ExampleError::IncorrectMintAuthority,
        }
    }
}
#[automatically_derived]
impl ::core::fmt::Debug for ExampleError {
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        ::core::fmt::Formatter::write_str(
            f,
            match self {
                ExampleError::MintHasNoMintAuthority => "MintHasNoMintAuthority",
                ExampleError::IncorrectMintAuthority => "IncorrectMintAuthority",
            },
        )
    }
}
#[automatically_derived]
impl ::core::marker::StructuralEq for ExampleError {}
#[automatically_derived]
impl ::core::cmp::Eq for ExampleError {
    #[inline]
    #[doc(hidden)]
    #[no_coverage]
    fn assert_receiver_is_total_eq(&self) -> () {}
}
#[allow(unused_qualifications)]
impl std::error::Error for ExampleError {}
#[allow(unused_qualifications)]
impl std::fmt::Display for ExampleError {
    fn fmt(&self, __formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
        #[allow(unused_variables, deprecated, clippy::used_underscore_binding)]
        match self {
            ExampleError::MintHasNoMintAuthority {} => {
                __formatter.write_fmt(format_args!("Mint has no mint authority"))
            }
            ExampleError::IncorrectMintAuthority {} => {
                __formatter
                    .write_fmt(
                        format_args!(
                            "Incorrect mint authority has signed the instruction"
                        ),
                    )
            }
        }
    }
}
#[allow(non_upper_case_globals, unused_qualifications)]
const _IMPL_NUM_FromPrimitive_FOR_ExampleError: () = {
    #[allow(clippy::useless_attribute)]
    #[allow(rust_2018_idioms)]
    extern crate num_traits as _num_traits;
    impl _num_traits::FromPrimitive for ExampleError {
        #[allow(trivial_numeric_casts)]
        #[inline]
        fn from_i64(n: i64) -> Option<Self> {
            if n == ExampleError::MintHasNoMintAuthority as i64 {
                Some(ExampleError::MintHasNoMintAuthority)
            } else if n == ExampleError::IncorrectMintAuthority as i64 {
                Some(ExampleError::IncorrectMintAuthority)
            } else {
                None
            }
        }
        #[inline]
        fn from_u64(n: u64) -> Option<Self> {
            Self::from_i64(n as i64)
        }
    }
};
#[automatically_derived]
impl ::core::marker::StructuralPartialEq for ExampleError {}
#[automatically_derived]
impl ::core::cmp::PartialEq for ExampleError {
    #[inline]
    fn eq(&self, other: &ExampleError) -> bool {
        let __self_tag = ::core::intrinsics::discriminant_value(self);
        let __arg1_tag = ::core::intrinsics::discriminant_value(other);
        __self_tag == __arg1_tag
    }
}
impl From<ExampleError> for solana_program::program_error::ProgramError {
    fn from(e: ExampleError) -> Self {
        solana_program::program_error::ProgramError::Custom(e as u32)
    }
}
impl<T> solana_program::decode_error::DecodeError<T> for ExampleError {
    fn type_of() -> &'static str {
        "ExampleError"
    }
}
impl solana_program::program_error::PrintProgramError for ExampleError {
    fn print<E>(&self)
    where
        E: 'static + std::error::Error + solana_program::decode_error::DecodeError<E>
            + solana_program::program_error::PrintProgramError
            + num_traits::FromPrimitive,
    {
        match self {
            ExampleError::MintHasNoMintAuthority => {
                ::solana_program::log::sol_log("Mint has no mint authority")
            }
            ExampleError::IncorrectMintAuthority => {
                ::solana_program::log::sol_log(
                    "Incorrect mint authority has signed the instruction",
                )
            }
        }
    }
}

Dependencies

~11–19MB
~261K SLoC