ink_ir/ir/item_impl/
callable.rs

1// Copyright (C) Use Ink (UK) Ltd.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Utilities and helper routines that are useful for both ink! messages
16//! and ink! constructors.
17
18use crate::ir;
19use core::fmt;
20use proc_macro2::{
21    Ident,
22    Span,
23};
24use quote::ToTokens as _;
25use syn::spanned::Spanned as _;
26
27/// The kind of externally callable smart contract entity.
28#[derive(Debug, Copy, Clone)]
29pub enum CallableKind {
30    /// An ink! message externally callable.
31    Message,
32    /// An ink! constructor externally callable.
33    Constructor,
34}
35
36impl fmt::Display for CallableKind {
37    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
38        match self {
39            Self::Message => write!(f, "message"),
40            Self::Constructor => write!(f, "constructor"),
41        }
42    }
43}
44
45/// Wrapper for a callable that adds its composed selector.
46#[derive(Debug)]
47pub struct CallableWithSelector<'a, C> {
48    /// The composed selector computed by the associated implementation block
49    /// and the given callable.
50    composed_selector: ir::Selector,
51    /// The parent implementation block.
52    item_impl: &'a ir::ItemImpl,
53    /// The actual callable.
54    callable: &'a C,
55}
56
57impl<C> Copy for CallableWithSelector<'_, C> {}
58impl<C> Clone for CallableWithSelector<'_, C> {
59    fn clone(&self) -> Self {
60        *self
61    }
62}
63
64impl<'a, C> CallableWithSelector<'a, C>
65where
66    C: Callable,
67{
68    /// Creates a new wrapper around the given callable and parent `impl` block.
69    pub(super) fn new(item_impl: &'a ir::ItemImpl, callable: &'a C) -> Self {
70        Self {
71            composed_selector: compose_selector(item_impl, callable),
72            item_impl,
73            callable,
74        }
75    }
76}
77
78impl<'a, C> CallableWithSelector<'a, C> {
79    /// Returns the composed selector of the ink! callable the `impl` block.
80    pub fn composed_selector(&self) -> ir::Selector {
81        self.composed_selector
82    }
83
84    /// Returns a shared reference to the underlying callable.
85    pub fn callable(&self) -> &'a C {
86        self.callable
87    }
88
89    /// Returns the parent implementation block of the ink! callable.
90    pub fn item_impl(&self) -> &'a ir::ItemImpl {
91        self.item_impl
92    }
93}
94
95impl<C> Callable for CallableWithSelector<'_, C>
96where
97    C: Callable,
98{
99    fn kind(&self) -> CallableKind {
100        <C as Callable>::kind(self.callable)
101    }
102
103    fn ident(&self) -> &Ident {
104        <C as Callable>::ident(self.callable)
105    }
106
107    fn user_provided_selector(&self) -> Option<&ir::Selector> {
108        <C as Callable>::user_provided_selector(self.callable)
109    }
110
111    fn is_payable(&self) -> bool {
112        <C as Callable>::is_payable(self.callable)
113    }
114
115    fn is_default(&self) -> bool {
116        <C as Callable>::is_default(self.callable)
117    }
118
119    fn has_wildcard_selector(&self) -> bool {
120        <C as Callable>::has_wildcard_selector(self.callable)
121    }
122
123    fn has_wildcard_complement_selector(&self) -> bool {
124        <C as Callable>::has_wildcard_complement_selector(self.callable)
125    }
126
127    fn visibility(&self) -> Visibility {
128        <C as Callable>::visibility(self.callable)
129    }
130
131    fn inputs(&self) -> InputsIter {
132        <C as Callable>::inputs(self.callable)
133    }
134
135    fn inputs_span(&self) -> Span {
136        <C as Callable>::inputs_span(self.callable)
137    }
138
139    fn statements(&self) -> &[syn::Stmt] {
140        <C as Callable>::statements(self.callable)
141    }
142}
143
144impl<C> ::core::ops::Deref for CallableWithSelector<'_, C> {
145    type Target = C;
146
147    fn deref(&self) -> &Self::Target {
148        self.callable
149    }
150}
151
152/// An ink! callable.
153///
154/// This is either an ink! message or an ink! constructor.
155/// Used to share common behavior between different callable types.
156pub trait Callable {
157    /// Returns the kind of the ink! callable.
158    fn kind(&self) -> CallableKind;
159
160    /// Returns the identifier of the ink! callable.
161    fn ident(&self) -> &Ident;
162
163    /// Returns the selector of the ink! callable if any has been manually set.
164    fn user_provided_selector(&self) -> Option<&ir::Selector>;
165
166    /// Returns `true` if the ink! callable is flagged as payable.
167    ///
168    /// # Note
169    ///
170    /// Flagging as payable is done using the `#[ink(payable)]` attribute.
171    fn is_payable(&self) -> bool;
172
173    /// Returns `true` if the ink! callable is flagged as default.
174    ///
175    /// # Note
176    ///
177    /// Flagging as default is done using the `#[ink(default)]` attribute.
178    fn is_default(&self) -> bool;
179
180    /// Returns `true` if the ink! callable is flagged as a wildcard selector.
181    fn has_wildcard_selector(&self) -> bool;
182
183    /// Returns `true` if the ink! callable is flagged as a wildcard complement selector.
184    fn has_wildcard_complement_selector(&self) -> bool;
185
186    /// Returns the visibility of the ink! callable.
187    fn visibility(&self) -> Visibility;
188
189    /// Returns an iterator yielding all input parameters of the ink! callable.
190    fn inputs(&self) -> InputsIter;
191
192    /// Returns the span of the inputs of the ink! callable.
193    fn inputs_span(&self) -> Span;
194
195    /// Returns a slice over shared references to the statements of the callable.
196    fn statements(&self) -> &[syn::Stmt];
197}
198
199/// Returns the composed selector of the ink! callable.
200///
201/// Composition takes into account the given [`ir::ItemImpl`].
202///
203/// # Details
204///
205/// Given
206///
207/// - the identifier `i` of the callable
208/// - the optionally set selector `s` of the callable
209/// - the `impl` blocks trait path in case it implements a trait, `P`
210/// - 16 kB blocks optional user provided namespace `S`
211///
212/// Then the selector is composed in the following way:
213///
214/// - If `s` is given we simply return `s`.
215/// - Otherwise if `T` is not `None` (trait `impl` block) we concatenate `S`, `T` and `i`
216///   with `::` as separator if `T` refers to a full-path. If `T` refers to a relative
217///   path or is just an identifier we only take its last segment `p` (e.g. the trait's
218///   identifier) into consideration and use it instead of `P` in the above concatenation.
219///   In the following we refer to the resulting concatenation as `C`.
220/// - Now we take the BLAKE-2 hash of `C` which results in 32 bytes of output and take the
221///   first 4 bytes that are returned in order as the composed selector.
222///
223/// # Examples
224///
225/// ## Overriding the composed selector
226///
227/// Given
228///
229/// ```no_compile
230/// impl MyStorage {
231///     #[ink(message, selector = 0xDEADBEEF)]
232///     fn my_message(&self) {}
233/// }
234/// ```
235///
236/// …then the selector of `my_message` is simply `0xDEADBEEF` since it overrides
237/// the composed selector.
238///
239/// ## Inherent implementation block
240///
241/// Given
242///
243/// ```no_compile
244/// impl MyStorage {
245///     #[ink(message)]
246///     fn my_message(&self) {}
247/// }
248/// ```
249///
250/// …then the selector of `my_message` is composed such as:
251/// ```no_compile
252/// BLAKE2("my_message".to_string().as_bytes())[0..4]
253/// ```
254///
255/// ## Trait implementation block
256///
257/// Given
258///
259/// ```no_compile
260/// impl MyTrait for MyStorage {
261///     #[ink(message)]
262///     fn my_message(&self) {}
263/// }
264/// ```
265///
266/// …then the selector of `my_message` is composed such as:
267/// ```no_compile
268/// BLAKE2("MyTrait::my_message".to_string().as_bytes())[0..4]
269/// ```
270///
271/// ## Using full path for trait
272///
273/// Given
274///
275/// ```no_compile
276/// impl ::my_full::long_path::MyTrait for MyStorage {
277///     #[ink(message)]
278///     fn my_message(&self) {}
279/// }
280/// ```
281///
282/// …then the selector of `my_message` is composed such as:
283/// ```no_compile
284/// BLAKE2("::my_full::long_path::MyTrait::my_message".to_string().as_bytes())[0..4]
285/// ```
286///
287/// ## Using a namespace
288///
289/// Given
290///
291/// ```no_compile
292/// #[ink(namespace = "my_namespace")]
293/// impl MyTrait for MyStorage {
294///     #[ink(message)]
295///     fn my_message(&self) {}
296/// }
297/// ```
298///
299/// …then the selector of `my_message` is composed such as:
300/// ```no_compile
301/// BLAKE2("my_namespace::MyTrait::my_message".to_string().as_bytes())[0..4]
302/// ```
303///
304/// ## Note
305///
306/// All above examples work similarly for ink! constructors interchangeably.
307///
308/// ## Usage Recommendations
309///
310/// These recommendation mainly apply to trait implementation blocks:
311///
312/// - The recommendation by the ink! team is to use the full-path approach wherever
313///   possible; OR import the trait and use only its identifier with an additional
314///   namespace if required to disambiguate selectors.
315/// - Try not to intermix the above recommendations.
316/// - Avoid directly setting the selector of an ink! message or constructor. Only do this
317///   if nothing else helps and you need a very specific selector, e.g. in case of
318///   backwards compatibility.
319/// - Do not use the namespace unless required to disambiguate.
320pub fn compose_selector<C>(item_impl: &ir::ItemImpl, callable: &C) -> ir::Selector
321where
322    C: Callable,
323{
324    if let Some(selector) = callable.user_provided_selector() {
325        return *selector
326    }
327    let preimage = compose_selector_preimage(item_impl, callable);
328    ir::Selector::compute(&preimage)
329}
330
331fn compose_selector_preimage<C>(item_impl: &ir::ItemImpl, callable: &C) -> Vec<u8>
332where
333    C: Callable,
334{
335    let callable_ident = callable.ident().to_string().into_bytes();
336    let namespace_bytes = item_impl
337        .namespace()
338        .map(|namespace| namespace.as_bytes().to_vec())
339        .unwrap_or_default();
340    let separator = &b"::"[..];
341    match item_impl.trait_path() {
342        None => {
343            // Inherent implementation block:
344            if namespace_bytes.is_empty() {
345                callable_ident
346            } else {
347                [namespace_bytes, callable_ident].join(separator)
348            }
349        }
350        Some(path) => {
351            // Trait implementation block:
352            //
353            // We need to separate between full-path, e.g. `::my::full::Path`
354            // starting with `::` and relative paths for the composition.
355            let path_bytes = if path.leading_colon.is_some() {
356                let mut str_repr = path.to_token_stream().to_string();
357                str_repr.retain(|c| !c.is_whitespace());
358                str_repr.into_bytes()
359            } else {
360                path.segments
361                    .last()
362                    .expect("encountered empty trait path")
363                    .ident
364                    .to_string()
365                    .into_bytes()
366            };
367            if namespace_bytes.is_empty() {
368                [path_bytes, callable_ident].join(separator)
369            } else {
370                [namespace_bytes, path_bytes, callable_ident].join(separator)
371            }
372        }
373    }
374}
375
376/// Ensures that common invariants of externally callable ink! entities are met.
377///
378/// # Errors
379///
380/// In case any of the common externally callable invariants are not met:
381/// - This is `true` if the externally callable is:
382///  - generic
383///  - `const` (compile-time evaluable)
384///  - `async` (asynchronous WebAssembly smart contract calling is not allowed)
385///  - `unsafe` (caller provided assertions not yet stable)
386/// - Furthermore this is `true` if the externally callable is defined for a non default
387///   ABI (e.g. `extern "C"`) or does not have valid visibility.
388pub(super) fn ensure_callable_invariants(
389    method_item: &syn::ImplItemFn,
390    kind: CallableKind,
391) -> Result<(), syn::Error> {
392    let bad_visibility = match &method_item.vis {
393        syn::Visibility::Inherited => None,
394        syn::Visibility::Restricted(vis_restricted) => Some(vis_restricted.span()),
395        syn::Visibility::Public(_) => None,
396    };
397    if let Some(bad_visibility) = bad_visibility {
398        return Err(format_err!(
399            bad_visibility,
400            "ink! {}s must have public or inherited visibility",
401            kind
402        ))
403    }
404    if !method_item.sig.generics.params.is_empty() {
405        return Err(format_err_spanned!(
406            method_item.sig.generics.params,
407            "ink! {}s must not be generic",
408            kind,
409        ))
410    }
411    if method_item.sig.constness.is_some() {
412        return Err(format_err_spanned!(
413            method_item.sig.constness,
414            "ink! {}s must not be const",
415            kind,
416        ))
417    }
418    if method_item.sig.asyncness.is_some() {
419        return Err(format_err_spanned!(
420            method_item.sig.asyncness,
421            "ink! {}s must not be async",
422            kind,
423        ))
424    }
425    if method_item.sig.unsafety.is_some() {
426        return Err(format_err_spanned!(
427            method_item.sig.unsafety,
428            "ink! {}s must not be unsafe",
429            kind,
430        ))
431    }
432    if method_item.sig.abi.is_some() {
433        return Err(format_err_spanned!(
434            method_item.sig.abi,
435            "ink! {}s must not have explicit ABI",
436            kind,
437        ))
438    }
439    if method_item.sig.variadic.is_some() {
440        return Err(format_err_spanned!(
441            method_item.sig.variadic,
442            "ink! {}s must not be variadic",
443            kind,
444        ))
445    }
446
447    if let Some(arg) = method_item.sig.inputs.iter().find(|input| {
448        match input {
449            syn::FnArg::Typed(pat) => !matches!(*pat.pat, syn::Pat::Ident(_)),
450            _ => false,
451        }
452    }) {
453        return Err(format_err_spanned!(
454            arg,
455            "ink! {} arguments must have an identifier",
456            kind
457        ))
458    }
459    Ok(())
460}
461
462/// The visibility of an ink! message or constructor.
463#[derive(Debug, Clone)]
464pub enum Visibility {
465    Public(syn::Token![pub]),
466    Inherited,
467}
468
469impl quote::ToTokens for Visibility {
470    fn to_tokens(&self, tokens: &mut proc_macro2::TokenStream) {
471        match self {
472            Self::Public(vis_public) => vis_public.to_tokens(tokens),
473            Self::Inherited => (),
474        }
475    }
476}
477
478impl Visibility {
479    /// Returns `true` if the visibility of the ink! message of constructor is public
480    /// (`pub`).
481    ///
482    /// # Note
483    ///
484    /// Messages in normal implementation blocks must have public visibility.
485    pub fn is_pub(&self) -> bool {
486        matches!(self, Self::Public(_))
487    }
488
489    /// Returns `true` if the visibility of the ink! message of constructor is inherited.
490    ///
491    /// # Note
492    ///
493    /// Messages in trait implementation blocks must have inherited visibility.
494    pub fn is_inherited(&self) -> bool {
495        matches!(self, Self::Inherited)
496    }
497
498    /// Returns the associated span if any.
499    pub fn span(&self) -> Option<Span> {
500        match self {
501            Self::Public(vis_public) => Some(vis_public.span()),
502            Self::Inherited => None,
503        }
504    }
505}
506
507/// Iterator over the input parameters of an ink! message or constructor.
508///
509/// Does not yield the self receiver of ink! messages.
510pub struct InputsIter<'a> {
511    iter: syn::punctuated::Iter<'a, syn::FnArg>,
512}
513
514impl<'a> InputsIter<'a> {
515    /// Creates a new inputs iterator over the given `syn` punctuation.
516    pub(crate) fn new<P>(inputs: &'a syn::punctuated::Punctuated<syn::FnArg, P>) -> Self {
517        Self {
518            iter: inputs.iter(),
519        }
520    }
521}
522
523impl<'a> From<&'a ir::Message> for InputsIter<'a> {
524    fn from(message: &'a ir::Message) -> Self {
525        Self::new(&message.item.sig.inputs)
526    }
527}
528
529impl<'a> From<&'a ir::Constructor> for InputsIter<'a> {
530    fn from(constructor: &'a ir::Constructor) -> Self {
531        Self::new(&constructor.item.sig.inputs)
532    }
533}
534
535impl<'a> Iterator for InputsIter<'a> {
536    type Item = &'a syn::PatType;
537
538    fn next(&mut self) -> Option<Self::Item> {
539        'repeat: loop {
540            match self.iter.next() {
541                None => return None,
542                Some(syn::FnArg::Typed(pat_typed)) => return Some(pat_typed),
543                Some(syn::FnArg::Receiver(_)) => continue 'repeat,
544            }
545        }
546    }
547}
548
549impl ExactSizeIterator for InputsIter<'_> {
550    fn len(&self) -> usize {
551        self.iter.len()
552    }
553}
554
555#[cfg(test)]
556mod tests {
557    use super::*;
558    use core::fmt::Debug;
559
560    pub enum ExpectedSelector {
561        Raw([u8; 4]),
562        Blake2(Vec<u8>),
563    }
564
565    impl From<[u8; 4]> for ExpectedSelector {
566        fn from(raw_selector: [u8; 4]) -> Self {
567            ExpectedSelector::Raw(raw_selector)
568        }
569    }
570
571    impl From<Vec<u8>> for ExpectedSelector {
572        fn from(blake2_input: Vec<u8>) -> Self {
573            ExpectedSelector::Blake2(blake2_input)
574        }
575    }
576
577    impl ExpectedSelector {
578        pub fn expected_selector(self) -> ir::Selector {
579            match self {
580                Self::Raw(raw_selector) => ir::Selector::from(raw_selector),
581                Self::Blake2(blake2_input) => ir::Selector::compute(&blake2_input),
582            }
583        }
584    }
585
586    /// Asserts that the given ink! implementation block and the given ink!
587    /// message result in the same composed selector as the expected bytes.
588    fn assert_compose_selector<C, S>(
589        item_impl: syn::ItemImpl,
590        item_method: syn::ImplItemFn,
591        expected_selector: S,
592    ) where
593        C: Callable + TryFrom<syn::ImplItemFn>,
594        <C as TryFrom<syn::ImplItemFn>>::Error: Debug,
595        S: Into<ExpectedSelector>,
596    {
597        assert_eq!(
598            compose_selector(
599                &<ir::ItemImpl as TryFrom<syn::ItemImpl>>::try_from(item_impl).unwrap(),
600                &<C as TryFrom<syn::ImplItemFn>>::try_from(item_method).unwrap(),
601            ),
602            expected_selector.into().expected_selector(),
603        )
604    }
605
606    #[test]
607    fn compose_selector_works() {
608        assert_compose_selector::<ir::Message, _>(
609            syn::parse_quote! {
610                #[ink(impl)]
611                impl MyStorage {}
612            },
613            syn::parse_quote! {
614                #[ink(message)]
615                fn my_message(&self) {}
616            },
617            b"my_message".to_vec(),
618        );
619        assert_compose_selector::<ir::Message, _>(
620            syn::parse_quote! {
621                #[ink(impl)]
622                impl MyTrait for MyStorage {}
623            },
624            syn::parse_quote! {
625                #[ink(message)]
626                fn my_message(&self) {}
627            },
628            b"MyTrait::my_message".to_vec(),
629        );
630        assert_compose_selector::<ir::Message, _>(
631            syn::parse_quote! {
632                #[ink(impl)]
633                impl ::my::full::path::MyTrait for MyStorage {}
634            },
635            syn::parse_quote! {
636                #[ink(message)]
637                fn my_message(&self) {}
638            },
639            b"::my::full::path::MyTrait::my_message".to_vec(),
640        );
641        assert_compose_selector::<ir::Message, _>(
642            syn::parse_quote! {
643                #[ink(impl, namespace = "my_namespace")]
644                impl MyStorage {}
645            },
646            syn::parse_quote! {
647                #[ink(message)]
648                fn my_message(&self) {}
649            },
650            b"my_namespace::my_message".to_vec(),
651        );
652        assert_compose_selector::<ir::Message, _>(
653            syn::parse_quote! {
654                #[ink(impl)]
655                impl MyTrait for MyStorage {}
656            },
657            syn::parse_quote! {
658                #[ink(message, selector = 0xDEADBEEF)]
659                fn my_message(&self) {}
660            },
661            [0xDE, 0xAD, 0xBE, 0xEF],
662        );
663        assert_compose_selector::<ir::Message, _>(
664            syn::parse_quote! {
665                #[ink(impl)]
666                impl relative::path_to::MyTrait for MyStorage {}
667            },
668            syn::parse_quote! {
669                #[ink(message)]
670                fn my_message(&self) {}
671            },
672            b"MyTrait::my_message".to_vec(),
673        );
674    }
675}
ink_ir/ir/item_impl/callable.rs

ink_ir/ir/item_impl/
callable.rs
