ink_primitives/reflect/
dispatch.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
15use alloy_sol_types::SolValue;
16use ink_prelude::vec::Vec;
17use pallet_revive_uapi::ReturnFlags;
18
19/// Stores various information of the respective dispatchable ink! message.
20///
21/// # Note
22///
23/// This trait is implemented by ink! for every dispatchable ink! message
24/// of the root ink! smart contract. The `ID` used in the trait reflects the
25/// chosen or derived selector of the dispatchable ink! message.
26///
27/// # Usage
28///
29/// ```
30/// # use ink::reflect::DispatchableMessageInfo;
31/// # use ink::{selector_id, selector_bytes};
32///
33/// #[ink::contract]
34/// pub mod contract {
35///     #[ink(storage)]
36///     pub struct Contract {}
37///
38///     impl Contract {
39///         #[ink(constructor)]
40///         pub fn constructor() -> Self {
41///             Contract {}
42///         }
43///
44///         #[ink(message)]
45///         pub fn message1(&self) {}
46///
47///         #[ink(message, payable, selector = 0xC0DECAFE)]
48///         pub fn message2(&mut self, input1: i32, input2: i64) -> (bool, i32) {
49///             unimplemented!()
50///         }
51///     }
52/// }
53///
54/// use contract::Contract;
55///
56/// /// Asserts that the message with the selector `ID` has the following properties.
57/// ///
58/// /// # Note
59/// ///
60/// /// The `In` and `Out` generic parameters describe the input and output types.
61/// fn assert_message_info<In, Out, const ID: u32>(
62///     mutates: bool,
63///     payable: bool,
64///     selector: [u8; 4],
65///     label: &str,
66/// ) where
67///     Contract: DispatchableMessageInfo<{ ID }, Input = In, Output = Out>,
68/// {
69///     assert_eq!(
70///         <Contract as DispatchableMessageInfo<{ ID }>>::MUTATES,
71///         mutates
72///     );
73///     assert_eq!(
74///         <Contract as DispatchableMessageInfo<{ ID }>>::PAYABLE,
75///         payable
76///     );
77///     assert_eq!(
78///         <Contract as DispatchableMessageInfo<{ ID }>>::SELECTOR,
79///         selector,
80///     );
81///     assert_eq!(<Contract as DispatchableMessageInfo<{ ID }>>::LABEL, label,);
82/// }
83///
84/// fn main() {
85///     assert_message_info::<(), (), { selector_id!("message1") }>(
86///         false,
87///         false,
88///         selector_bytes!("message1"),
89///         "message1",
90///     );
91///     assert_message_info::<(i32, i64), (bool, i32), 0xC0DECAFE_u32>(
92///         true,
93///         true,
94///         [0xC0, 0xDE, 0xCA, 0xFE],
95///         "message2",
96///     );
97/// }
98/// ```
99pub trait DispatchableMessageInfo<const ID: u32> {
100    /// Reflects the input types of the dispatchable ink! message.
101    type Input;
102    /// Reflects the output type of the dispatchable ink! message.
103    type Output;
104    /// The ink! storage struct type.
105    type Storage;
106
107    /// The closure that can be used to dispatch into the dispatchable ink! message.
108    ///
109    /// # Note
110    ///
111    /// We unify `&self` and `&mut self` ink! messages here and always take a `&mut self`.
112    /// This is mainly done for simplification but also because we can easily convert from
113    /// `&mut self` to `&self` with our current dispatch codegen architecture.
114    const CALLABLE: fn(&mut Self::Storage, Self::Input) -> Self::Output;
115
116    /// closure for decoding
117    const DECODE: fn(
118        &mut &[::core::primitive::u8],
119    ) -> Result<Self::Input, DispatchError>;
120
121    /// closure for returning per encoding todo: docs
122    #[cfg(not(feature = "std"))]
123    const RETURN: fn(ReturnFlags, Self::Output) -> !;
124
125    /// closure for returning per encoding todo: docs
126    #[cfg(feature = "std")]
127    const RETURN: fn(ReturnFlags, Self::Output) -> ();
128
129    /// Yields `true` if the dispatchable ink! message mutates the ink! storage.
130    const MUTATES: bool;
131    /// Yields `true` if the dispatchable ink! message is payable.
132    const PAYABLE: bool;
133    /// The selectors of the dispatchable ink! message.
134    const SELECTOR: [u8; 4];
135    /// The label of the dispatchable ink! message.
136    const LABEL: &'static str;
137    /// The encoding of input and output data for the message
138    const ENCODING: Encoding;
139}
140
141/// Stores various information of the respective dispatchable ink! constructor.
142///
143/// # Note
144///
145/// This trait is implemented by ink! for every dispatchable ink! constructor
146/// of the root ink! smart contract. The `ID` used in the trait reflects the
147/// chosen or derived selector of the dispatchable ink! constructor.
148///
149/// # Usage
150///
151/// ```
152/// # use ink::reflect::DispatchableConstructorInfo;
153/// # use ink::{selector_id, selector_bytes};
154///
155/// #[ink::contract]
156/// pub mod contract {
157///     #[ink(storage)]
158///     pub struct Contract {}
159///
160///     impl Contract {
161///         #[ink(constructor)]
162///         pub fn constructor1() -> Self {
163///             Contract {}
164///         }
165///
166///         #[ink(constructor, selector = 0xC0DECAFE)]
167///         pub fn constructor2(input1: i32, input2: i64) -> Self {
168///             Contract {}
169///         }
170///
171///         #[ink(message)]
172///         pub fn message(&self) {}
173///     }
174/// }
175///
176/// use contract::Contract;
177///
178/// /// Asserts that the constructor with the selector `ID` has the following properties.
179/// ///
180/// /// # Note
181/// ///
182/// /// The `In` and `Out` generic parameters describe the input and output types.
183/// fn assert_constructor_info<In, const ID: u32>(selector: [u8; 4], label: &str)
184/// where
185///     Contract: DispatchableConstructorInfo<{ ID }, Input = In>,
186/// {
187///     assert_eq!(
188///         <Contract as DispatchableConstructorInfo<{ ID }>>::SELECTOR,
189///         selector,
190///     );
191///     assert_eq!(
192///         <Contract as DispatchableConstructorInfo<{ ID }>>::LABEL,
193///         label,
194///     );
195/// }
196///
197/// fn main() {
198///     assert_constructor_info::<(), { selector_id!("constructor1") }>(
199///         selector_bytes!("constructor1"),
200///         "constructor1",
201///     );
202///     assert_constructor_info::<(i32, i64), 0xC0DECAFE_u32>(
203///         [0xC0, 0xDE, 0xCA, 0xFE],
204///         "constructor2",
205///     );
206/// }
207/// ```
208pub trait DispatchableConstructorInfo<const ID: u32> {
209    /// Reflects the input types of the dispatchable ink! constructor.
210    type Input;
211    /// The ink! storage struct type.
212    type Storage;
213    /// Reflects the output type of the dispatchable ink! constructor.
214    type Output;
215    /// The type of the error returned from the constructor.
216    /// Infallible constructors will have `()` as the error type.
217    type Error;
218
219    /// True if the constructor returns a `Result`.
220    const IS_RESULT: bool;
221
222    /// The closure that can be used to dispatch into the dispatchable ink! constructor.
223    const CALLABLE: fn(Self::Input) -> Self::Output;
224
225    /// Yields `true` if the dispatchable ink! constructor is payable.
226    const PAYABLE: bool;
227
228    /// The selectors of the dispatchable ink! constructor.
229    const SELECTOR: [u8; 4];
230
231    /// The label of the dispatchable ink! constructor.
232    const LABEL: &'static str;
233}
234
235/// todo: comment
236pub enum Encoding {
237    Scale,
238    Solidity,
239}
240
241/// Marker type for SCALE encoding. Used with [`AbiEncodeWith`], [`AbiDecodeWith`] and
242/// `DecodeMessageResult`.
243#[derive(Default, Clone)]
244pub struct ScaleEncoding;
245/// Marker type for Solidity ABI encoding. Used with [`AbiEncodeWith`],
246/// [`AbiDecodeWith`] and `DecodeMessageResult`.
247#[derive(Default, Clone)]
248pub struct SolEncoding;
249
250/// Trait for ABI-specific encoding with support for both slice and vector buffers.
251pub trait AbiEncodeWith<Abi> {
252    /// Encodes the data into a fixed-size buffer, returning the number of bytes written.
253    fn encode_to_slice(&self, buffer: &mut [u8]) -> usize;
254
255    /// Encodes the data into a dynamically resizing vector.
256    fn encode_to_vec(&self, buffer: &mut Vec<u8>);
257}
258
259/// Trait for ABI-specific decoding.
260pub trait AbiDecodeWith<Abi>: Sized {
261    /// The error type that can occur during decoding.
262    type Error: core::fmt::Debug;
263    /// Decodes the data from a buffer using the provided ABI.
264    fn decode_with(buffer: &[u8]) -> Result<Self, Self::Error>;
265}
266
267impl<T: scale::Encode> AbiEncodeWith<ScaleEncoding> for T {
268    fn encode_to_slice(&self, buffer: &mut [u8]) -> usize {
269        let encoded = scale::Encode::encode(self);
270        let len = encoded.len();
271        debug_assert!(
272            len <= buffer.len(),
273            "encode scope buffer overflowed, encoded len is {} but buffer len is {}",
274            len,
275            buffer.len()
276        );
277        buffer[..len].copy_from_slice(&encoded);
278        len
279    }
280
281    fn encode_to_vec(&self, buffer: &mut Vec<u8>) {
282        scale::Encode::encode_to(self, buffer);
283    }
284}
285
286impl<T: scale::Decode> AbiDecodeWith<ScaleEncoding> for T {
287    type Error = scale::Error;
288    fn decode_with(buffer: &[u8]) -> Result<Self, Self::Error> {
289        scale::Decode::decode(&mut &buffer[..])
290    }
291}
292
293impl<T: SolValue> AbiEncodeWith<SolEncoding> for T {
294    fn encode_to_slice(&self, buffer: &mut [u8]) -> usize {
295        let encoded = T::abi_encode(self);
296        let len = encoded.len();
297        debug_assert!(
298            len <= buffer.len(),
299            "encode scope buffer overflowed, encoded len is {} but buffer len is {}",
300            len,
301            buffer.len()
302        );
303        buffer[..len].copy_from_slice(&encoded);
304        len
305    }
306
307    fn encode_to_vec(&self, buffer: &mut Vec<u8>) {
308        buffer.extend_from_slice(&T::abi_encode(self));
309    }
310}
311
312impl<T: SolValue> AbiDecodeWith<SolEncoding> for T
313where
314    T: From<<<T as SolValue>::SolType as alloy_sol_types::SolType>::RustType>,
315{
316    type Error = alloy_sol_types::Error;
317    fn decode_with(buffer: &[u8]) -> Result<Self, Self::Error> {
318        // Don't validate decoding. Validating results in encoding and decoding again.
319        T::abi_decode(buffer, false)
320    }
321}
322
323mod private {
324    /// Seals the implementation of `ConstructorReturnType`.
325    pub trait Sealed {}
326}
327
328/// Guards against using invalid contract initializer types.
329///
330/// # Note
331///
332/// Currently the only allowed types are `()` and `Result<(), E>`
333/// where `E` is some unspecified error type.
334/// If the contract initializer returns `Result::Err` the utility
335/// method that is used to initialize an ink! smart contract will
336/// revert the state of the contract instantiation.
337pub trait ConstructorOutput<C>: private::Sealed {
338    /// Is `true` if `Self` is `Result<C, E>`.
339    const IS_RESULT: bool = false;
340
341    /// The error type of the constructor return type.
342    ///
343    /// # Note
344    ///
345    /// For infallible constructors this is `()` whereas for fallible
346    /// constructors this is the actual return error type. Since we only ever
347    /// return a value in case of `Result::Err` the `Result::Ok` value type
348    /// does not matter.
349    type Error;
350
351    /// Converts the return value into a `Result` instance.
352    ///
353    /// # Note
354    ///
355    /// For infallible constructor returns this always yields `Ok`.
356    fn as_result(&self) -> Result<&C, &Self::Error>;
357}
358
359/// Stores the actual value of the constructor return type.
360///
361/// # Note
362///
363/// Currently the only allowed types are `()` and `Result<(), E>`
364/// where `E` is some unspecified error type.
365/// If the contract initializer returns `Result::Err` the utility
366/// method that is used to initialize an ink! smart contract will
367/// revert the state of the contract instantiation.
368pub struct ConstructorOutputValue<T>(T);
369
370impl<T> ConstructorOutputValue<T> {
371    /// Stores the actual value of the constructor return type.
372    pub fn new(val: T) -> Self {
373        Self(val)
374    }
375}
376
377impl<T> private::Sealed for ConstructorOutputValue<T> {}
378
379impl<C> ConstructorOutput<C> for ConstructorOutputValue<C> {
380    type Error = &'static ();
381
382    #[inline(always)]
383    fn as_result(&self) -> Result<&C, &Self::Error> {
384        Ok(&self.0)
385    }
386}
387
388impl<C, E> ConstructorOutput<C> for ConstructorOutputValue<Result<C, E>> {
389    const IS_RESULT: bool = true;
390    type Error = E;
391
392    #[inline(always)]
393    fn as_result(&self) -> Result<&C, &Self::Error> {
394        self.0.as_ref()
395    }
396}
397
398/// Generated type used to decode all dispatchable ink! messages of the ink! smart
399/// contract.
400///
401/// # Note
402///
403/// The decoder follows the ink! calling ABI where all ink! message calls start with
404/// 4 bytes dedicated to the ink! message selector followed by the SCALE encoded
405/// parameters.
406///
407/// # Usage
408///
409/// ```
410/// # use ink::reflect::ContractMessageDecoder;
411/// # use ink::selector_bytes;
412/// # use scale::{Encode, Decode};
413///
414/// #[ink::contract]
415/// pub mod contract {
416///     #[ink(storage)]
417///     pub struct Contract {}
418///
419///     impl Contract {
420///         #[ink(constructor)]
421///         pub fn constructor() -> Self {
422///             Self {}
423///         }
424///
425///         #[ink(message)]
426///         pub fn message1(&self) {}
427///
428///         #[ink(message)]
429///         pub fn message2(&self, input1: bool, input2: i32) {}
430///     }
431/// }
432///
433/// use contract::Contract;
434/// use ink::env::DecodeDispatch;
435///
436/// fn main() {
437///     // Call to `message1` without input parameters.
438///     {
439///         let mut input_bytes = Vec::new();
440///         input_bytes.extend(selector_bytes!("message1"));
441///         assert!(
442///             <<Contract as ContractMessageDecoder>::Type as DecodeDispatch>::decode_dispatch(
443///                 &mut &input_bytes[..]
444///             )
445///             .is_ok()
446///         );
447///     }
448///     // Call to `message2` with 2 parameters.
449///     {
450///         let mut input_bytes = Vec::new();
451///         input_bytes.extend(selector_bytes!("message2"));
452///         input_bytes.extend(true.encode());
453///         input_bytes.extend(42i32.encode());
454///         assert!(
455///             <<Contract as ContractMessageDecoder>::Type as DecodeDispatch>::decode_dispatch(
456///                 &mut &input_bytes[..]
457///             )
458///             .is_ok()
459///         );
460///     }
461///     // Call with invalid ink! message selector.
462///     {
463///         let mut input_bytes = Vec::new();
464///         input_bytes.extend(selector_bytes!("non_existing_message"));
465///         assert!(
466///             <<Contract as ContractMessageDecoder>::Type as DecodeDispatch>::decode_dispatch(
467///                 &mut &input_bytes[..]
468///             )
469///             .is_err()
470///         );
471///     }
472///     // Call with invalid ink! message parameters.
473///     {
474///         let mut input_bytes = Vec::new();
475///         input_bytes.extend(selector_bytes!("message2"));
476///         assert!(
477///             <<Contract as ContractMessageDecoder>::Type as DecodeDispatch>::decode_dispatch(
478///                 &mut &input_bytes[..]
479///             )
480///             .is_err()
481///         );
482///     }
483/// }
484/// ```
485pub trait ContractMessageDecoder {
486    /// The ink! smart contract message decoder type.
487    type Type: DecodeDispatch + ExecuteDispatchable;
488}
489
490/// Generated type used to decode all dispatchable ink! constructors of the ink! smart
491/// contract.
492///
493/// # Note
494///
495/// The decoder follows the ink! calling ABI where all ink! constructor calls start with
496/// 4 bytes dedicated to the ink! constructor selector followed by the SCALE encoded
497/// parameters.
498///
499/// # Usage
500///
501/// ```
502/// # use ink::reflect::ContractConstructorDecoder;
503/// # use ink::selector_bytes;
504/// # use scale::{Encode, Decode};
505///
506/// #[ink::contract]
507/// pub mod contract {
508///     #[ink(storage)]
509///     pub struct Contract {}
510///
511///     impl Contract {
512///         #[ink(constructor)]
513///         pub fn constructor1() -> Self {
514///             Self {}
515///         }
516///
517///         #[ink(constructor)]
518///         pub fn constructor2(input1: bool, input2: i32) -> Self {
519///             Self {}
520///         }
521///
522///         #[ink(message)]
523///         pub fn message(&self) {}
524///     }
525/// }
526///
527/// use contract::Contract;
528/// use ink::env::DecodeDispatch;
529///
530/// fn main() {
531///     // Call to `constructor1` without input parameters.
532///     {
533///         let mut input_bytes = Vec::new();
534///         input_bytes.extend(selector_bytes!("constructor1"));
535///         assert!(
536///             <<Contract as ContractConstructorDecoder>::Type as DecodeDispatch>::decode_dispatch(
537///                 &mut &input_bytes[..]
538///             )
539///             .is_ok()
540///         );
541///     }
542///     // Call to `constructor2` with 2 parameters.
543///     {
544///         let mut input_bytes = Vec::new();
545///         input_bytes.extend(selector_bytes!("constructor2"));
546///         input_bytes.extend(true.encode());
547///         input_bytes.extend(42i32.encode());
548///         assert!(
549///             <<Contract as ContractConstructorDecoder>::Type as DecodeDispatch>::decode_dispatch(
550///                 &mut &input_bytes[..]
551///             )
552///             .is_ok()
553///         );
554///     }
555///     // Call with invalid ink! constructor selector.
556///     {
557///         let mut input_bytes = Vec::new();
558///         input_bytes.extend(selector_bytes!("non_existing_constructor"));
559///         assert!(
560///             <<Contract as ContractConstructorDecoder>::Type as DecodeDispatch>::decode_dispatch(
561///                 &mut &input_bytes[..]
562///             )
563///             .is_err()
564///         );
565///     }
566///     // Call with invalid ink! constructor parameters.
567///     {
568///         let mut input_bytes = Vec::new();
569///         input_bytes.extend(selector_bytes!("constructor2"));
570///         assert!(
571///             <<Contract as ContractConstructorDecoder>::Type as DecodeDispatch>::decode_dispatch(
572///                 &mut &input_bytes[..]
573///             )
574///             .is_err()
575///         );
576///     }
577/// }
578/// ```
579pub trait ContractConstructorDecoder {
580    /// The ink! smart contract constructor decoder type.
581    type Type: DecodeDispatch + ExecuteDispatchable;
582}
583
584/// Starts the execution of the respective ink! message or constructor call.
585///
586/// # Note
587///
588/// Implemented by the ink! smart contract message or constructor decoder.
589pub trait ExecuteDispatchable {
590    /// Executes the ink! smart contract message or constructor.
591    fn execute_dispatchable(self) -> Result<(), DispatchError>;
592}
593
594/// An error that can occur during dispatch of ink! dispatchables.
595/// todo: add tests for other errors beside `PaidUnpayableMessage`
596#[derive(Debug, Copy, Clone, PartialEq, Eq)]
597pub enum DispatchError {
598    /// Failed to decode into a valid dispatch selector.
599    InvalidSelector,
600    /// The decoded selector is not known to the dispatch decoder.
601    UnknownSelector,
602    /// Failed to decode the parameters for the selected dispatchable.
603    InvalidParameters,
604    /// Failed to read execution input for the dispatchable.
605    CouldNotReadInput,
606    /// Invalidly paid an unpayable dispatchable.
607    PaidUnpayableMessage,
608}
609
610impl core::fmt::Display for DispatchError {
611    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
612        write!(f, "{}", self.as_str())
613    }
614}
615
616impl DispatchError {
617    /// Returns a string representation of the error.
618    #[inline]
619    fn as_str(&self) -> &'static str {
620        match self {
621            Self::InvalidSelector => "unable to decode selector",
622            Self::UnknownSelector => "encountered unknown selector",
623            Self::InvalidParameters => "unable to decode input",
624            Self::CouldNotReadInput => "could not read input",
625            Self::PaidUnpayableMessage => "paid an unpayable message",
626        }
627    }
628}
629
630impl From<DispatchError> for scale::Error {
631    #[inline]
632    fn from(error: DispatchError) -> Self {
633        Self::from(error.as_str())
634    }
635}
636
637/// Decodes an ink! dispatch input into a known selector and its expected parameters.
638///
639/// # Note
640///
641/// This trait is automatically implemented for ink! message and constructor decoders.
642///
643/// # Errors
644///
645/// Returns an error if any of the decode steps failed:
646///
647/// - `InvalidSelector`: The first four bytes could not properly decoded into the
648///   selector.
649/// - `UnknownSelector`: The decoded selector did not match any of the expected ones.
650/// - `InvalidParameters`: Failed to decoded the parameters for the selected dispatchable.
651///
652/// The other dispatch errors are handled by other structures usually.
653///
654/// # Usage
655///
656/// todo: previous doc test used a contract instance, it was in the `ink!` crate.
657pub trait DecodeDispatch: Sized {
658    /// todo: docs
659    fn decode_dispatch(input: &mut &[u8]) -> Result<Self, DispatchError>;
660}
ink_primitives/reflect/dispatch.rs

ink_primitives/reflect/
dispatch.rs
