feat: erc165 support interface (#281)

Adds erc165 standard altogether with a proc macro, that lets to compute
interface id in a simple way.

<!-- Fill in with issue number -->
Resolves #33

#### PR Checklist

- [x] Tests
- [x] Documentation

---------

Co-authored-by: Daniel Bigos <daniel.bigos@icloud.com>

.github/workflows/check-publish.yml

@@ -37,6 +37,9 @@ jobs:
  - name: check openzeppelin-crypto
  run: cargo publish -p openzeppelin-crypto --target wasm32-unknown-unknown --dry-run
 
+ - name: check openzeppelin-stylus-proc
+ run: cargo publish -p openzeppelin-stylus-proc --target wasm32-unknown-unknown --dry-run
+
  # TODO: https://github.com/OpenZeppelin/rust-contracts-stylus/issues/291
  # - name: check openzeppelin-stylus
  # run: cargo publish -p openzeppelin-stylus --target wasm32-unknown-unknown --dry-run

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 members = [
  "contracts",
+ "contracts-proc",
  "lib/crypto",
  "lib/motsu",
  "lib/motsu-proc",
@@ -21,6 +22,7 @@ members = [
 ]
 default-members = [
  "contracts",
+ "contracts-proc",
  "lib/crypto",
  "lib/motsu",
  "lib/motsu-proc",
@@ -98,6 +100,7 @@ quote = "1.0.35"
 
 # members
 openzeppelin-stylus = { path = "contracts" }
+openzeppelin-stylus-proc = { path = "contracts-proc" }
 openzeppelin-crypto = { path = "lib/crypto" }
 motsu = { path = "lib/motsu"}
 motsu-proc = { path = "lib/motsu-proc", version = "0.1.0" }

contracts-proc/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "openzeppelin-stylus-proc"
+description = "Procedural macros for OpenZeppelin Stylus contracts"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+keywords.workspace = true
+repository.workspace = true
+
+
+[dependencies]
+proc-macro2.workspace = true
+quote.workspace = true
+syn.workspace = true
+convert_case = "0.6.0"
+
+[lints]
+workspace = true
+
+[lib]
+proc-macro = true

contracts-proc/src/interface_id.rs

@@ -0,0 +1,102 @@
+//! Defines the `#[interface_id]` procedural macro.
+
+use std::mem;
+
+use convert_case::{Case, Casing};
+use proc_macro::TokenStream;
+use proc_macro2::Ident;
+use quote::quote;
+use syn::{
+ parse::{Parse, ParseStream},
+ parse_macro_input, FnArg, ItemTrait, LitStr, Result, Token, TraitItem,
+};
+
+/// Computes an interface id as an associated constant for the trait.
+pub(crate) fn interface_id(
+ _attr: &TokenStream,
+ input: TokenStream,
+) -> TokenStream {
+ let mut input = parse_macro_input!(input as ItemTrait);
+
+ let mut selectors = Vec::new();
+ for item in &mut input.items {
+ let TraitItem::Fn(func) = item else {
+ continue;
+ };
+
+ let mut override_fn_name = None;
+ for attr in mem::take(&mut func.attrs) {
+ if attr.path().is_ident("selector") {
+ if override_fn_name.is_some() {
+ error!(attr.path(), "more than one selector attribute");
+ }
+ let args: SelectorArgs = match attr.parse_args() {
+ Ok(args) => args,
+ Err(error) => error!(attr.path(), "{}", error),
+ };
+ override_fn_name = Some(args.name);
+ } else {
+ // Put back any other attributes.
+ func.attrs.push(attr);
+ }
+ }
+
+ let solidity_fn_name = override_fn_name.unwrap_or_else(|| {
+ let rust_fn_name = func.sig.ident.to_string();
+ rust_fn_name.to_case(Case::Camel)
+ });
+
+ let arg_types = func.sig.inputs.iter().filter_map(|arg| match arg {
+ FnArg::Typed(t) => Some(t.ty.clone()),
+ // Opt out any `self` arguments.
+ FnArg::Receiver(_) => None,
+ });
+
+ // Store selector expression from every function in the trait.
+ selectors.push(
+ quote! { u32::from_be_bytes(stylus_sdk::function_selector!(#solidity_fn_name #(, #arg_types )*)) }
+ );
+ }
+
+ let name = input.ident;
+ let vis = input.vis;
+ let attrs = input.attrs;
+ let trait_items = input.items;
+ let (_impl_generics, ty_generics, where_clause) =
+ input.generics.split_for_impl();
+
+ // Keep the same trait with an additional associated constant
+ // `INTERFACE_ID`.
+ quote! {
+ #(#attrs)*
+ #vis trait #name #ty_generics #where_clause {
+ #(#trait_items)*
+
+ #[doc = concat!("Solidity interface id associated with ", stringify!(#name), " trait.")]
+ #[doc = "Computed as a XOR of selectors for each function in the trait."]
+ const INTERFACE_ID: u32 = {
+ #(#selectors)^*
+ };
+ }
+ }
+ .into()
+}
+
+/// Contains arguments of the `#[selector(..)]` attribute.
+struct SelectorArgs {
+ name: String,
+}
+
+impl Parse for SelectorArgs {
+ fn parse(input: ParseStream) -> Result<Self> {
+ let ident: Ident = input.parse()?;
+
+ if ident == "name" {
+ let _: Token![=] = input.parse()?;
+ let lit: LitStr = input.parse()?;
+ Ok(SelectorArgs { name: lit.value() })
+ } else {
+ error!(@ident, "expected identifier 'name'")
+ }
+ }
+}

contracts-proc/src/lib.rs

@@ -0,0 +1,64 @@
+//! Procedural macro definitions used in `openzeppelin-stylus` smart contracts
+//! library.
+
+extern crate proc_macro;
+use proc_macro::TokenStream;
+
+/// Shorthand to print nice errors.
+///
+/// Note that it's defined before the module declarations.
+macro_rules! error {
+ ($tokens:expr, $($msg:expr),+ $(,)?) => {{
+ let error = syn::Error::new(syn::spanned::Spanned::span(&$tokens), format!($($msg),+));
+ return error.to_compile_error().into();
+ }};
+ (@ $tokens:expr, $($msg:expr),+ $(,)?) => {{
+ return Err(syn::Error::new(syn::spanned::Spanned::span(&$tokens), format!($($msg),+)))
+ }};
+}
+
+mod interface_id;
+
+/// Computes the interface id as an associated constant `INTERFACE_ID` for the
+/// trait that describes contract's abi.
+///
+/// Selector collision should be handled with
+/// macro `#[selector(name = "actualSolidityMethodName")]` on top of the method.
+///
+/// # Examples
+///
+/// ```rust,ignore
+/// #[interface_id]
+/// pub trait IErc721 {
+/// fn balance_of(&self, owner: Address) -> Result<U256, Vec<u8>>;
+///
+/// fn owner_of(&self, token_id: U256) -> Result<Address, Vec<u8>>;
+///
+/// fn safe_transfer_from(
+/// &mut self,
+/// from: Address,
+/// to: Address,
+/// token_id: U256,
+/// ) -> Result<(), Vec<u8>>;
+///
+/// #[selector(name = "safeTransferFrom")]
+/// fn safe_transfer_from_with_data(
+/// &mut self,
+/// from: Address,
+/// to: Address,
+/// token_id: U256,
+/// data: Bytes,
+/// ) -> Result<(), Vec<u8>>;
+/// }
+///
+/// impl IErc165 for Erc721 {
+/// fn supports_interface(interface_id: FixedBytes<4>) -> bool {
+/// <Self as IErc721>::INTERFACE_ID == u32::from_be_bytes(*interface_id)
+/// || Erc165::supports_interface(interface_id)
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn interface_id(attr: TokenStream, input: TokenStream) -> TokenStream {
+ interface_id::interface_id(&attr, input)
+}

contracts/Cargo.toml

@@ -15,6 +15,7 @@ stylus-sdk.workspace = true
 stylus-proc.workspace = true
 mini-alloc.workspace = true
 keccak-const.workspace = true
+openzeppelin-stylus-proc.workspace = true
 
 [dev-dependencies]
 alloy-primitives = { workspace = true, features = ["arbitrary"] }

contracts/src/token/erc20/extensions/metadata.rs

@@ -2,8 +2,12 @@
 
 use alloc::string::String;
 
+use alloy_primitives::FixedBytes;
+use openzeppelin_stylus_proc::interface_id;
 use stylus_proc::{public, sol_storage};
 
+use crate::utils::introspection::erc165::IErc165;
+
 /// Number of decimals used by default on implementors of [`Metadata`].
 pub const DEFAULT_DECIMALS: u8 = 18;
 
@@ -20,6 +24,7 @@ sol_storage! {
 }
 
 /// Interface for the optional metadata functions from the ERC-20 standard.
+#[interface_id]
 pub trait IErc20Metadata {
  /// Returns the name of the token.
  ///
@@ -76,3 +81,22 @@ impl IErc20Metadata for Erc20Metadata {
  DEFAULT_DECIMALS
  }
 }
+
+impl IErc165 for Erc20Metadata {
+ fn supports_interface(interface_id: FixedBytes<4>) -> bool {
+ <Self as IErc20Metadata>::INTERFACE_ID
+ == u32::from_be_bytes(*interface_id)
+ }
+}
+
+#[cfg(all(test, feature = "std"))]
+mod tests {
+ use crate::token::erc20::extensions::{Erc20Metadata, IErc20Metadata};
+
+ #[motsu::test]
+ fn interface_id() {
+ let actual = <Erc20Metadata as IErc20Metadata>::INTERFACE_ID;
+ let expected = 0xa219a025;
+ assert_eq!(actual, expected);
+ }
+}

contracts/src/token/erc20/mod.rs

@@ -4,15 +4,18 @@
 //! revert instead of returning `false` on failure. This behavior is
 //! nonetheless conventional and does not conflict with the expectations of
 //! [`Erc20`] applications.
-use alloy_primitives::{Address, U256};
+use alloy_primitives::{Address, FixedBytes, U256};
 use alloy_sol_types::sol;
+use openzeppelin_stylus_proc::interface_id;
 use stylus_proc::SolidityError;
 use stylus_sdk::{
  call::MethodError,
  evm, msg,
  stylus_proc::{public, sol_storage},
 };
 
+use crate::utils::introspection::erc165::{Erc165, IErc165};
+
 pub mod extensions;
 
 sol! {
@@ -111,6 +114,7 @@ sol_storage! {
 }
 
 /// Required interface of an [`Erc20`] compliant contract.
+#[interface_id]
 pub trait IErc20 {
  /// The error type associated to this ERC-20 trait implementation.
  type Error: Into<alloc::vec::Vec<u8>>;
@@ -286,6 +290,13 @@ impl IErc20 for Erc20 {
  }
 }
 
+impl IErc165 for Erc20 {
+ fn supports_interface(interface_id: FixedBytes<4>) -> bool {
+ <Self as IErc20>::INTERFACE_ID == u32::from_be_bytes(*interface_id)
+ || Erc165::supports_interface(interface_id)
+ }
+}
+
 impl Erc20 {
  /// Sets a `value` number of tokens as the allowance of `spender` over the
  /// caller's tokens.
@@ -550,6 +561,10 @@ mod tests {
  use stylus_sdk::msg;
 
  use super::{Erc20, Error, IErc20};
+ use crate::{
+ token::erc721::{Erc721, IErc721},
+ utils::introspection::erc165::IErc165,
+ };
 
  #[motsu::test]
  fn reads_balance(contract: Erc20) {
@@ -882,4 +897,15 @@ mod tests {
  let result = contract.approve(Address::ZERO, one);
  assert!(matches!(result, Err(Error::InvalidSpender(_))));
  }
+
+ #[motsu::test]
+ fn interface_id() {
+ let actual = <Erc20 as IErc20>::INTERFACE_ID;
+ let expected = 0x36372b07;
+ assert_eq!(actual, expected);
+
+ let actual = <Erc20 as IErc165>::INTERFACE_ID;
+ let expected = 0x01ffc9a7;
+ assert_eq!(actual, expected);
+ }
 }