Implement wildcard selector, add proxy example

README.md

@@ -221,6 +221,7 @@ In a module annotated with `#[ink::contract]` these attributes are available:
 | `#[ink(constructor)]` | Applicable to method. | Flags a method for the ink! storage struct as constructor making it available to the API for instantiating the contract. |
 | `#[ink(payable)]` | Applicable to ink! messages. | Allows receiving value as part of the call of the ink! message. ink! constructors are implicitly payable. |
 | `#[ink(selector = S:u32)]` | Applicable to ink! messages and ink! constructors. | Specifies a concrete dispatch selector for the flagged entity. This allows a contract author to precisely control the selectors of their APIs making it possible to rename their API without breakage. |
+| `#[ink(selector = "_")]` | Applicable to ink! messages. | Specifies a fallback message that is invoked if no other ink! message matches a selector. |
 | `#[ink(namespace = N:string)]` | Applicable to ink! trait implementation blocks. | Changes the resulting selectors of all the ink! messages and ink! constructors within the trait implementation. Allows to disambiguate between trait implementations with overlapping message or constructor names. Use only with great care and consideration! |
 | `#[ink(impl)]` | Applicable to ink! implementation blocks. | Tells the ink! codegen that some implementation block shall be granted access to ink! internals even without it containing any ink! messages or ink! constructors. |
 

RELEASES.md

@@ -7,6 +7,10 @@ This is the 7th release candidate for ink! 3.0.
     - Some of those traits and their carried information can be used for static reflection of ink!
       smart contracts. Those types and traits reside in the new `ink_lang::reflect` module and is
       publicly usable by ink! smart contract authors.
+- Added basic support for wildcard selectors ‒ [#1020](https://github.com/paritytech/ink/pull/1020).
+  - This enables writing upgradable smart contracts using the proxy pattern.
+    We added a new example illustrating this ‒ the [proxy](https://github.com/paritytech/ink/tree/master/examples/proxy) example.
+  - Annotating a wildcard selector in traits is not yet supported.
 
 ## Changed
 - Upgraded to the unstable `seal_call` API ‒ [#960](https://github.com/paritytech/ink/pull/960).

crates/lang/codegen/src/generator/dispatch.rs

@@ -24,6 +24,7 @@ use ir::{
     Callable,
     HexLiteral as _,
 };
+use itertools::Itertools;
 use proc_macro2::TokenStream as TokenStream2;
 use quote::{
     quote,
@@ -114,6 +115,23 @@ impl Dispatch<'_> {
             .count()
     }
 
+    /// Returns the index of the ink! message which has a wildcard selector, if existent.
+    fn query_wildcard_message(&self) -> Option<usize> {
+        let mut wildcard_selectors = self
+            .contract
+            .module()
+            .impls()
+            .map(|item_impl| item_impl.iter_messages())
+            .flatten()
+            .positions(|item| item.is_wildcard_selector());
+        let next = wildcard_selectors.next();
+        assert!(
+            wildcard_selectors.next().is_none(),
+            "found more than one wildcard selector, contracts must have at most one."
+        );
+        next
+    }
+
     /// Generates code for the [`ink_lang::ContractDispatchables`] trait implementation.
     ///
     /// This trait implementation stores information of how many dispatchable
@@ -631,6 +649,25 @@ impl Dispatch<'_> {
                 }
             )
         });
+        let possibly_wildcard_selector_message = match self.query_wildcard_message() {
+            Some(wildcard_index) => {
+                let message_span = message_spans[wildcard_index];
+                let message_ident = message_variant_ident(wildcard_index);
+                let message_input =
+                    expand_message_input(message_span, storage_ident, wildcard_index);
+                quote! {
+                    ::core::result::Result::Ok(Self::#message_ident(
+                        <#message_input as ::scale::Decode>::decode(input)
+                            .map_err(|_| ::ink_lang::reflect::DispatchError::InvalidParameters)?
+                    ))
+                }
+            }
+            None => {
+                quote! {
+                    ::core::result::Result::Err(::ink_lang::reflect::DispatchError::UnknownSelector)
+                }
+            }
+        };
         let any_message_accept_payment =
             self.any_message_accepts_payment_expr(message_spans);
         let message_execute = (0..count_messages).map(|index| {
@@ -713,9 +750,7 @@ impl Dispatch<'_> {
                             .map_err(|_| ::ink_lang::reflect::DispatchError::InvalidSelector)?
                         {
                             #( #message_match , )*
-                            _invalid => ::core::result::Result::Err(
-                                ::ink_lang::reflect::DispatchError::UnknownSelector
-                            )
+                            _invalid => #possibly_wildcard_selector_message
                         }
                     }
                 }

crates/lang/ir/src/ir/attrs.rs

@@ -280,6 +280,12 @@ impl InkAttribute {
             .any(|arg| matches!(arg.kind(), AttributeArg::Payable))
     }
 
+    /// Returns `true` if the ink! attribute contains the wildcard selector.
+    pub fn is_wildcard_selector(&self) -> bool {
+        self.args()
+            .any(|arg| matches!(arg.kind(), AttributeArg::WildcardSelector))
+    }
+
     /// Returns `true` if the ink! attribute contains the `anonymous` argument.
     pub fn is_anonymous(&self) -> bool {
         self.args()
@@ -342,6 +348,8 @@ pub enum AttributeArgKind {
     Constructor,
     /// `#[ink(payable)]`
     Payable,
+    /// `#[ink(selector = "_")]`
+    WildcardSelector,
     /// `#[ink(selector = 0xDEADBEEF)]`
     Selector,
     /// `#[ink(extension = N: u32)]`
@@ -395,6 +403,11 @@ pub enum AttributeArg {
     /// Applied on ink! constructors or messages in order to specify that they
     /// can receive funds from callers.
     Payable,
+    /// `#[ink(selector = "_")]`
+    ///
+    /// Applied on ink! messages to define a fallback messages that is invoked
+    /// if no other ink! message matches a given selector.
+    WildcardSelector,
     /// `#[ink(selector = 0xDEADBEEF)]`
     ///
     /// Applied on ink! constructors or messages to manually control their
@@ -451,6 +464,9 @@ impl core::fmt::Display for AttributeArgKind {
             Self::Selector => {
                 write!(f, "selector = S:[u8; 4]")
             }
+            Self::WildcardSelector => {
+                write!(f, "selector = \"_\"")
+            }
             Self::Extension => {
                 write!(f, "extension = N:u32)")
             }
@@ -476,6 +492,7 @@ impl AttributeArg {
             Self::Constructor => AttributeArgKind::Constructor,
             Self::Payable => AttributeArgKind::Payable,
             Self::Selector(_) => AttributeArgKind::Selector,
+            Self::WildcardSelector => AttributeArgKind::WildcardSelector,
             Self::Extension(_) => AttributeArgKind::Extension,
             Self::Namespace(_) => AttributeArgKind::Namespace,
             Self::Implementation => AttributeArgKind::Implementation,
@@ -498,6 +515,7 @@ impl core::fmt::Display for AttributeArg {
             Self::Selector(selector) => {
                 write!(f, "selector = {:?}", selector.to_bytes())
             }
+            Self::WildcardSelector => write!(f, "selector = \"_\""),
             Self::Extension(extension) => {
                 write!(f, "extension = {:?}", extension.into_u32())
             }
@@ -809,6 +827,21 @@ impl TryFrom<syn::NestedMeta> for AttributeFrag {
                 match &meta {
                     syn::Meta::NameValue(name_value) => {
                         if name_value.path.is_ident("selector") {
+                            if let syn::Lit::Str(lit_str) = &name_value.lit {
+                                let argument = lit_str.value();
+                                if argument != "_" {
+                                    return Err(format_err!(
+                                        name_value,
+                                        "#[ink(selector = ..)] attributes with string inputs are deprecated (except for the wildcard selector \"_\"). \
+                                        use an integer instead, e.g. #[ink(selector = 1)] or #[ink(selector = 0xC0DECAFE)]."
+                                    ))
+                                }
+                                return Ok(AttributeFrag {
+                                    ast: meta,
+                                    arg: AttributeArg::WildcardSelector,
+                                })
+                            }
+
                             if let syn::Lit::Int(lit_int) = &name_value.lit {
                                 let selector_u32 = lit_int.base10_parse::<u32>()
                                     .map_err(|error| {
@@ -824,13 +857,6 @@ impl TryFrom<syn::NestedMeta> for AttributeFrag {
                                     arg: AttributeArg::Selector(selector),
                                 })
                             }
-                            if let syn::Lit::Str(_) = &name_value.lit {
-                                return Err(format_err!(
-                                    name_value,
-                                    "#[ink(selector = ..)] attributes with string inputs are deprecated. \
-                                    use an integer instead, e.g. #[ink(selector = 1)] or #[ink(selector = 0xC0DECAFE)]."
-                                ))
-                            }
                             return Err(format_err!(name_value, "expecteded 4-digit hexcode for `selector` argument, e.g. #[ink(selector = 0xC0FEBABE]"))
                         }
                         if name_value.path.is_ident("namespace") {

crates/lang/ir/src/ir/item_impl/callable.rs

@@ -116,6 +116,10 @@ where
         <C as Callable>::is_payable(self.callable)
     }
 
+    fn is_wildcard_selector(&self) -> bool {
+        <C as Callable>::is_wildcard_selector(self.callable)
+    }
+
     fn visibility(&self) -> Visibility {
         <C as Callable>::visibility(self.callable)
     }
@@ -162,6 +166,9 @@ pub trait Callable {
     /// Flagging as payable is done using the `#[ink(payable)]` attribute.
     fn is_payable(&self) -> bool;
 
+    /// Returns `true` if the ink! callable is flagged as a wildcard selector.
+    fn is_wildcard_selector(&self) -> bool;
+
     /// Returns the visibility of the ink! callable.
     fn visibility(&self) -> Visibility;
 

crates/lang/ir/src/ir/item_impl/constructor.rs

@@ -158,6 +158,12 @@ impl Constructor {
                     ir::AttributeArg::Constructor | ir::AttributeArg::Selector(_) => {
                         Ok(())
                     }
+                    ir::AttributeArg::WildcardSelector => {
+                        Err(Some(format_err!(
+                            arg.span(),
+                            "wildcard selectors are not allowed for constructors"
+                        )))
+                    }
                     ir::AttributeArg::Payable => {
                         Err(Some(format_err!(
                             arg.span(),
@@ -207,6 +213,10 @@ impl Callable for Constructor {
         true
     }
 
+    fn is_wildcard_selector(&self) -> bool {
+        false
+    }
+
     fn visibility(&self) -> Visibility {
         match &self.item.vis {
             syn::Visibility::Public(vis_public) => Visibility::Public(vis_public.clone()),
@@ -578,4 +588,18 @@ mod tests {
             )
         }
     }
+
+    #[test]
+    fn try_from_wildcard_constructor_fails() {
+        let item: syn::ImplItemMethod = syn::parse_quote! {
+            #[ink(constructor, selector = "_")]
+            pub fn my_constructor() -> Self {}
+        };
+        let errs: syn::Error = <ir::Constructor as TryFrom<_>>::try_from(item)
+            .expect_err("must result in Err");
+        assert!(errs
+            .to_compile_error()
+            .to_string()
+            .contains("wildcard selectors are not allowed for constructors"));
+    }
 }

crates/lang/ir/src/ir/item_impl/message.rs

@@ -100,6 +100,8 @@ pub struct Message {
     pub(super) item: syn::ImplItemMethod,
     /// If the ink! message can receive funds.
     is_payable: bool,
+    /// If the ink! message is a wildcard selector.
+    is_wildcard_selector: bool,
     /// An optional user provided selector.
     ///
     /// # Note
@@ -187,6 +189,7 @@ impl Message {
                 match arg.kind() {
                     ir::AttributeArg::Message
                     | ir::AttributeArg::Payable
+                    | ir::AttributeArg::WildcardSelector
                     | ir::AttributeArg::Selector(_) => Ok(()),
                     _ => Err(None),
                 }
@@ -205,7 +208,15 @@ impl TryFrom<syn::ImplItemMethod> for Message {
         let (ink_attrs, other_attrs) = Self::sanitize_attributes(&method_item)?;
         let is_payable = ink_attrs.is_payable();
         let selector = ink_attrs.selector();
+        let is_wildcard_selector = ink_attrs.is_wildcard_selector();
+        if is_wildcard_selector && selector.is_some() {
+            return Err(format_err!(
+                method_item.span(),
+                "ink! message cannot contain wildcard selector and specified selector"
+            ))
+        }
         Ok(Self {
+            is_wildcard_selector,
             is_payable,
             selector,
             item: syn::ImplItemMethod {
@@ -233,6 +244,10 @@ impl Callable for Message {
         self.is_payable
     }
 
+    fn is_wildcard_selector(&self) -> bool {
+        self.is_wildcard_selector
+    }
+
     fn visibility(&self) -> Visibility {
         match &self.item.vis {
             syn::Visibility::Public(vis_public) => Visibility::Public(vis_public.clone()),