Add custom errors to Solidity compatible metadata (#2583)

davidsemakula · web-flow · commit 9cc7d5659bc7 · 2025-08-12T23:04:34.000+02:00
* doc: Update `SolErrorEncode` and `SolErrorDecode` derive macro docs

* Derive `SolErrorMetadata` and collect Solidity custom error metadata

* tests: Solidity error metadata

* Update changelog

* chore: Fix tests
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Implement `SolEncode` and `SolDecode` for `Option<T>` - [#2545](https://github.com/use-ink/ink/pull/2545)
 - Allow writing E2E fuzz tests for contracts - [#2570](https://github.com/use-ink/ink/pull/2570)
 - Item name/identifier overrides for overloading, selector computation and metadata - [#2577](https://github.com/use-ink/ink/pull/2577)
+- Add custom errors to Solidity compatible metadata - [#2583](https://github.com/use-ink/ink/pull/2583)
 
 ### Changed
 - Use marker trait for finding ink! storage `struct` during code analysis - [2499](https://github.com/use-ink/ink/pull/2499)
diff --git a/crates/ink/codegen/src/generator/sol/metadata.rs b/crates/ink/codegen/src/generator/sol/metadata.rs
@@ -56,6 +56,7 @@ impl GenerateCode for SolidityMetadata<'_> {
                         constructors: vec![ #( #ctors ),* ],
                         functions: vec![ #( #msgs ),* ],
                         events: ::ink::collect_events_sol(),
+                        errors: ::ink::collect_errors_sol(),
                         docs: #docs.into(),
                     }
                 }
diff --git a/crates/ink/macro/src/lib.rs b/crates/ink/macro/src/lib.rs
@@ -1783,26 +1783,36 @@ synstructure::decl_derive!(
     ///
     /// # Note
     ///
-    /// All field types (if any) must implement [`ink::SolDecode`].
+    /// - All field types (if any) must implement [`ink::SolDecode`].
+    /// - The error representation derived is a [Solidity custom error][sol-error]
+    ///   (or multiple Solidity custom error in the case of an enum,
+    ///   i.e. one for each enum variant).
+    ///
+    /// [sol-error]: https://soliditylang.org/blog/2021/04/21/custom-errors/
     ///
     /// # Example
     ///
     /// ```
     /// use ink_macro::SolErrorDecode;
     ///
+    /// // Represented as a Solidity custom error with no parameters
     /// #[derive(SolErrorDecode)]
     /// struct UnitError;
     ///
+    /// // Represented as a Solidity custom error with parameters
     /// #[derive(SolErrorDecode)]
     /// struct ErrorWithParams(bool, u8, String);
     ///
+    /// // Represented as a Solidity custom error with named parameters
     /// #[derive(SolErrorDecode)]
     /// struct ErrorWithNamedParams {
     ///     status: bool,
     ///     count: u8,
     ///     reason: String,
     /// }
     ///
+    /// // Represented as multiple Solidity custom errors
+    /// // (i.e. each variant represents a Solidity custom error)
     /// #[derive(SolErrorDecode)]
     /// enum MultipleErrors {
     ///     UnitError,
@@ -1824,26 +1834,36 @@ synstructure::decl_derive!(
     ///
     /// # Note
     ///
-    /// All field types (if any) must implement [`ink::SolEncode`].
+    /// - All field types (if any) must implement [`ink::SolEncode`].
+    /// - The error representation derived is a [Solidity custom error][sol-error]
+    ///   (or multiple Solidity custom error in the case of an enum,
+    ///   i.e. one for each enum variant).
+    ///
+    /// [sol-error]: https://soliditylang.org/blog/2021/04/21/custom-errors/
     ///
     /// # Example
     ///
     /// ```
     /// use ink_macro::SolErrorEncode;
     ///
+    /// // Represented as a Solidity custom error with no parameters
     /// #[derive(SolErrorEncode)]
     /// struct UnitError;
     ///
+    /// // Represented as a Solidity custom error with parameters
     /// #[derive(SolErrorEncode)]
     /// struct ErrorWithParams(bool, u8, String);
     ///
+    /// // Represented as a Solidity custom error with named parameters
     /// #[derive(SolErrorEncode)]
     /// struct ErrorWithNamedParams {
     ///     status: bool,
     ///     count: u8,
     ///     reason: String,
     /// }
     ///
+    /// // Represented as multiple Solidity custom errors
+    /// // (i.e. each variant represents a Solidity custom error)
     /// #[derive(SolErrorEncode)]
     /// enum MultipleErrors {
     ///     UnitError,
@@ -1858,5 +1878,56 @@ synstructure::decl_derive!(
     sol::sol_error_encode_derive
 );
 
+synstructure::decl_derive!(
+    [SolErrorMetadata] =>
+    /// Derives an implementation of `ink::metadata::sol::SolErrorMetadata`
+    /// for the given `struct` or `enum`.
+    ///
+    /// # Note
+    ///
+    /// - All field types (if any) must implement [`ink::SolEncode`].
+    /// - The error representation derived is a [Solidity custom error][sol-error]
+    ///   (or multiple Solidity custom error in the case of an enum,
+    ///   i.e. one for each enum variant).
+    ///
+    /// [sol-error]: https://soliditylang.org/blog/2021/04/21/custom-errors/
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use ink_macro::SolErrorMetadata;
+    ///
+    /// // Represented as a Solidity custom error with no parameters
+    /// #[derive(SolErrorMetadata)]
+    /// struct UnitError;
+    ///
+    /// // Represented as a Solidity custom error with parameters
+    /// #[derive(SolErrorMetadata)]
+    /// struct ErrorWithParams(bool, u8, String);
+    ///
+    /// // Represented as a Solidity custom error with named parameters
+    /// #[derive(SolErrorMetadata)]
+    /// struct ErrorWithNamedParams {
+    ///     status: bool,
+    ///     count: u8,
+    ///     reason: String,
+    /// }
+    ///
+    /// // Represented as multiple Solidity custom errors
+    /// // (i.e. each variant represents a Solidity custom error)
+    /// #[derive(SolErrorMetadata)]
+    /// enum MultipleErrors {
+    ///     UnitError,
+    ///     ErrorWithParams(bool, u8, String),
+    ///     ErrorWithNamedParams {
+    ///         status: bool,
+    ///         count: u8,
+    ///         reason: String,
+    ///     }
+    /// }
+    /// ```
+    sol::sol_error_metadata_derive
+);
+
 #[cfg(test)]
 pub use contract::generate_or_err;
diff --git a/crates/ink/macro/src/sol.rs b/crates/ink/macro/src/sol.rs
@@ -24,5 +24,6 @@ pub use self::{
     error::{
         sol_error_decode_derive,
         sol_error_encode_derive,
+        sol_error_metadata_derive,
     },
 };
diff --git a/crates/ink/macro/src/sol/error.rs b/crates/ink/macro/src/sol/error.rs
@@ -12,13 +12,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use proc_macro2::TokenStream as TokenStream2;
+use ink_ir::IsDocAttribute;
+use proc_macro2::{
+    Ident,
+    TokenStream as TokenStream2,
+};
 use quote::{
     format_ident,
     quote,
 };
 use syn::{
     spanned::Spanned,
+    Attribute,
+    Field,
     Fields,
 };
 
@@ -62,6 +68,27 @@ pub fn sol_error_encode_derive(s: synstructure::Structure) -> TokenStream2 {
     }
 }
 
+/// Derives the `ink::metadata::sol::SolErrorMetadata` trait for the given `struct` or
+/// `enum`.
+pub fn sol_error_metadata_derive(s: synstructure::Structure) -> TokenStream2 {
+    match s.ast().data {
+        syn::Data::Struct(_) => {
+            sol_error_metadata_derive_struct(s)
+                .unwrap_or_else(|err| err.to_compile_error())
+        }
+        syn::Data::Enum(_) => {
+            sol_error_metadata_derive_enum(s).unwrap_or_else(|err| err.to_compile_error())
+        }
+        _ => {
+            syn::Error::new(
+                s.ast().span(),
+                "can only derive `SolErrorEncode` for Rust `struct` and `enum` items",
+            )
+            .to_compile_error()
+        }
+    }
+}
+
 /// Derives the `ink::sol::SolErrorDecode` trait for the given `struct`.
 fn sol_error_decode_derive_struct(
     s: synstructure::Structure,
@@ -149,6 +176,43 @@ fn sol_error_encode_derive_struct(
     ))
 }
 
+/// Derives the `ink::metadata::sol::SolErrorMetadata` trait for the given `struct`.
+fn sol_error_metadata_derive_struct(
+    s: synstructure::Structure,
+) -> syn::Result<TokenStream2> {
+    ensure_no_generics(&s, "SolErrorMetadata")?;
+
+    let Some(variant) = s.variants().first() else {
+        return Err(syn::Error::new(
+            s.ast().span(),
+            "can only derive `SolErrorMetadata` for Rust `struct` items",
+        ));
+    };
+
+    let ident = &s.ast().ident;
+    let name = ident.to_string();
+    let params = variant.ast().fields.iter().map(param_metadata_from_field);
+    let docs = extract_docs(s.ast().attrs.as_slice());
+    let metadata_linker = register_metadata(ident);
+
+    Ok(s.bound_impl(
+        quote!(::ink::metadata::sol::SolErrorMetadata),
+        quote! {
+            fn error_specs() -> ::ink::prelude::vec::Vec<::ink::metadata::sol::ErrorMetadata> {
+                #metadata_linker
+
+                vec![
+                    ::ink::metadata::sol::ErrorMetadata {
+                        name: #name.into(),
+                        params: vec![ #( #params ),* ],
+                        docs: #docs.into(),
+                    }
+                ]
+            }
+        },
+    ))
+}
+
 /// Derives the `ink::sol::SolErrorDecode` trait for the given `enum`.
 fn sol_error_decode_derive_enum(s: synstructure::Structure) -> syn::Result<TokenStream2> {
     ensure_no_generics(&s, "SolErrorDecode")?;
@@ -297,6 +361,41 @@ fn sol_error_encode_derive_enum(s: synstructure::Structure) -> syn::Result<Token
     ))
 }
 
+/// Derives the `ink::metadata::sol::SolErrorMetadata` trait for the given `enum`.
+fn sol_error_metadata_derive_enum(
+    s: synstructure::Structure,
+) -> syn::Result<TokenStream2> {
+    ensure_no_generics(&s, "SolErrorMetadata")?;
+    utils::ensure_non_empty_enum(&s, "SolErrorMetadata")?;
+
+    let error_variants = s.variants().iter().map(|variant| {
+        let variant_ident = variant.ast().ident;
+        let variant_name = variant_ident.to_string();
+        let params = variant.ast().fields.iter().map(param_metadata_from_field);
+        let docs = extract_docs(variant.ast().attrs);
+
+        quote! {
+            ::ink::metadata::sol::ErrorMetadata {
+                name: #variant_name.into(),
+                params: vec![ #( #params ),* ],
+                docs: #docs.into(),
+            }
+        }
+    });
+    let metadata_linker = register_metadata(&s.ast().ident);
+
+    Ok(s.bound_impl(
+        quote!(::ink::metadata::sol::SolErrorMetadata),
+        quote! {
+            fn error_specs() -> ::ink::prelude::vec::Vec<::ink::metadata::sol::ErrorMetadata> {
+                #metadata_linker
+
+                vec![ #( #error_variants ),* ]
+            }
+        },
+    ))
+}
+
 /// Ensures that the given item has no generics.
 fn ensure_no_generics(s: &synstructure::Structure, trait_name: &str) -> syn::Result<()> {
     if s.ast().generics.params.is_empty() {
@@ -311,3 +410,44 @@ fn ensure_no_generics(s: &synstructure::Structure, trait_name: &str) -> syn::Res
         ))
     }
 }
+
+/// Register an error metadata function in the distributed slice for combining all
+/// errors referenced in the contract binary.
+fn register_metadata(ident: &Ident) -> TokenStream2 {
+    quote! {
+       #[::ink::linkme::distributed_slice(::ink::CONTRACT_ERRORS_SOL)]
+       #[linkme(crate = ::ink::linkme)]
+       static ERROR_METADATA: fn() -> ::ink::prelude::vec::Vec<::ink::metadata::sol::ErrorMetadata> =
+           <#ident as ::ink::metadata::sol::SolErrorMetadata>::error_specs;
+    }
+}
+
+/// Returns the error parameter from the given field.
+fn param_metadata_from_field(field: &Field) -> TokenStream2 {
+    let ty = &field.ty;
+    let name = field
+        .ident
+        .as_ref()
+        .map(ToString::to_string)
+        .unwrap_or_default();
+    let docs = extract_docs(field.attrs.as_slice());
+    let sol_ty = quote! {
+        <#ty as ::ink::SolEncode>::SOL_NAME
+    };
+    quote! {
+        ::ink::metadata::sol::ErrorParamMetadata {
+            name: #name.into(),
+            ty: #sol_ty.into(),
+            docs: #docs.into(),
+        }
+    }
+}
+
+/// Returns the rustdoc string from the given item attributes.
+fn extract_docs(attrs: &[Attribute]) -> String {
+    attrs
+        .iter()
+        .filter_map(|attr| attr.extract_docs())
+        .collect::<Vec<_>>()
+        .join("\n")
+}
diff --git a/crates/ink/src/lib.rs b/crates/ink/src/lib.rs
@@ -98,6 +98,7 @@ pub use ink_macro::{
     SolEncode,
     SolErrorDecode,
     SolErrorEncode,
+    SolErrorMetadata,
 };
 pub use ink_primitives::{
     Address,
@@ -149,3 +150,20 @@ pub fn collect_events_sol() -> Vec<ink_metadata::sol::EventMetadata> {
         .map(|event| event())
         .collect()
 }
+
+/// Any error which derives `#[derive(ink::SolErrorMetadata)]` and is used in the contract
+/// binary will have its implementation added to this distributed slice at linking time.
+#[cfg(feature = "std")]
+#[linkme::distributed_slice]
+#[linkme(crate = linkme)]
+pub static CONTRACT_ERRORS_SOL: [fn() -> Vec<ink_metadata::sol::ErrorMetadata>] = [..];
+
+/// Collect the Solidity ABI compatible metadata of all error definitions encoded as
+/// Solidity custom errors that are linked and used in the binary.
+#[cfg(feature = "std")]
+pub fn collect_errors_sol() -> Vec<ink_metadata::sol::ErrorMetadata> {
+    crate::CONTRACT_ERRORS_SOL
+        .iter()
+        .flat_map(|event| event())
+        .collect()
+}
diff --git a/crates/ink/tests/ui/abi/sol/pass/custom-error-encoding.rs b/crates/ink/tests/ui/abi/sol/pass/custom-error-encoding.rs
@@ -4,14 +4,17 @@ use ink::sol::{SolErrorEncode, SolErrorDecode};
 
 // Equivalent to a Solidity custom error with no params.
 #[derive(Debug, PartialEq, Eq, ink::SolErrorDecode, ink::SolErrorEncode)]
+#[cfg_attr(feature = "std", derive(ink::SolErrorMetadata))]
 pub struct UnitError;
 
 // Equivalent to a Solidity custom error with params.
 #[derive(Debug, PartialEq, Eq, ink::SolErrorDecode, ink::SolErrorEncode)]
+#[cfg_attr(feature = "std", derive(ink::SolErrorMetadata))]
 struct ErrorWithParams(bool);
 
 // Equivalent to multiple Solidity custom errors, one for each variant.
 #[derive(Debug, PartialEq, Eq, ink::SolErrorDecode, ink::SolErrorEncode)]
+#[cfg_attr(feature = "std", derive(ink::SolErrorMetadata))]
 pub enum MultipleErrors {
     UnitError,
     ErrorWithParams(bool)
@@ -54,4 +57,15 @@ fn main() {
     assert_eq!(SolErrorEncode::encode(&error), encoded);
     let decoded: MultipleErrors = SolErrorDecode::decode(&encoded).unwrap();
     assert_eq!(error, decoded);
+
+    // Ensures Solidity error metadata is collected.
+    let error_specs = ink::collect_errors_sol();
+    // NOTE: 4 errors, because `MultipleErrors` actually represents 2 errors
+    // (i.e. one for each variant).
+    // We don't deduplicate matching Solidity custom error definitions,
+    // this matches the behavior of `solc`.
+    // Ref: <https://docs.soliditylang.org/en/latest/abi-spec.html#json>
+    assert_eq!(error_specs.len(), 4);
+    assert!(error_specs.iter().any(|error| error.name == "UnitError"));
+    assert!(error_specs.iter().any(|error| error.name == "ErrorWithParams"));
 }
diff --git a/crates/metadata/src/sol.rs b/crates/metadata/src/sol.rs
diff --git a/integration-tests/solidity-abi/fallible-setter/lib.rs b/integration-tests/solidity-abi/fallible-setter/lib.rs

Original file line number	Diff line number	Diff line change
`@@ -56,6 +56,7 @@ impl GenerateCode for SolidityMetadata<'_> {`
`56`	`56`	`constructors: vec![ #( #ctors ),* ],`
`57`	`57`	`functions: vec![ #( #msgs ),* ],`
`58`	`58`	`events: ::ink::collect_events_sol(),`
	`59`	`+ errors: ::ink::collect_errors_sol(),`
`59`	`60`	`docs: #docs.into(),`
`60`	`61`	`}`
`61`	`62`	`}`