ink_primitives/reflect/trait_def/
info.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/// Stores information for every ink! trait message of an ink! trait definition.
16///
17/// This information includes if the ink! trait message is payable
18/// as well as its derived or manually specified selector.
19///
20/// In the future this info trait might be extended to contain
21/// more information about a single ink! trait message.
22///
23/// The information provided through this trait can be used on the
24/// implementer side of an ink! trait to check and guard certain
25/// properties on a Rust type system level. This is important since
26/// ink! cannot be guaranteed to have both the ink! trait definition
27/// and all of its implementers under its scope and radar.
28///
29/// # Note
30///
31/// - The `TraitMessageInfo<LOCAL_ID>` is implemented by the automatically generated ink!
32///   trait definition information object associated to the ink! trait definition at hand.
33/// - For every ink! trait message defined by the ink! trait definition the associated
34///   ink! trait definition information object implements this trait given the
35///   `TRAIT_LOCAL_MESSAGE_ID` of each ink! trait message respectively.
36/// - The local IDs uniquely identifying all the ink! trait messages of the ink! trait
37///   definition are computed solely using the Rust identifier of the ink! trait message
38///   which can be derived from ink! implementation blocks in order to query the
39///   information stored by this ink! trait information object trait implementation.
40///
41/// # Usage
42///
43/// ```
44/// #[ink::trait_definition]
45/// pub trait InkTrait {
46///     #[ink(message)]
47///     fn trait_message_1(&self);
48///
49///     #[ink(message, payable, selector = 0xC0DECAFE)]
50///     fn trait_message_2(&mut self);
51/// }
52///
53/// #[ink::trait_definition(namespace = "foo")]
54/// pub trait InkTrait2 {
55///     #[ink(message)]
56///     fn trait_message(&self);
57/// }
58///
59/// #[ink::contract]
60/// pub mod contract {
61///     use super::{InkTrait, InkTrait2};
62///
63///     #[ink(storage)]
64///     pub struct Contract {}
65///
66///     impl Contract {
67///         #[ink(constructor)]
68///         pub fn constructor() -> Self { Contract {} }
69///     }
70///
71///     impl InkTrait for Contract {
72///         #[ink(message)]
73///         fn trait_message_1(&self) {}
74///
75///         #[ink(message)]
76///         fn trait_message_2(&mut self) {}
77///     }
78///
79///     impl InkTrait2 for Contract {
80///         #[ink(message)]
81///         fn trait_message(&self) {}
82///     }
83/// }
84///
85/// # use ink::reflect::TraitDefinitionRegistry;
86/// # use ink::reflect::TraitMessageInfo;
87/// # use ink_env::DefaultEnvironment;
88/// # use ink::{selector_id, selector_bytes};
89///
90/// fn main() {
91///     assert_eq!(
92///         <<TraitDefinitionRegistry<DefaultEnvironment> as InkTrait>::__ink_TraitInfo
93///             as TraitMessageInfo<{selector_id!("trait_message_1")}>>::PAYABLE,
94///         false,
95///     );
96///     assert_eq!(
97///         <<TraitDefinitionRegistry<DefaultEnvironment> as InkTrait>::__ink_TraitInfo
98///             as TraitMessageInfo<{selector_id!("trait_message_2")}>>::PAYABLE,
99///         true,
100///     );
101///     assert_eq!(
102///         <<TraitDefinitionRegistry<DefaultEnvironment> as InkTrait2>::__ink_TraitInfo
103///             as TraitMessageInfo<{selector_id!("trait_message")}>>::PAYABLE,
104///         false,
105///     );
106///     assert_eq!(
107///         <<TraitDefinitionRegistry<DefaultEnvironment> as InkTrait>::__ink_TraitInfo
108///             as TraitMessageInfo<{selector_id!("trait_message_1")}>>::SELECTOR,
109///         selector_bytes!("InkTrait::trait_message_1")
110///     );
111///     assert_eq!(
112///         <<TraitDefinitionRegistry<DefaultEnvironment> as InkTrait>::__ink_TraitInfo
113///             as TraitMessageInfo<{selector_id!("trait_message_2")}>>::SELECTOR,
114///         [0xC0, 0xDE, 0xCA, 0xFE]
115///     );
116///     assert_eq!(
117///         <<TraitDefinitionRegistry<DefaultEnvironment> as InkTrait2>::__ink_TraitInfo
118///             as TraitMessageInfo<{selector_id!("trait_message")}>>::SELECTOR,
119///         selector_bytes!("foo::InkTrait2::trait_message")
120///     );
121/// }
122/// ```
123pub trait TraitMessageInfo<const TRAIT_LOCAL_MESSAGE_ID: u32> {
124    /// Is `true` if the ink! trait message has been annotated with `#[ink(payable)]`.
125    const PAYABLE: bool;
126
127    /// The unique selector of the ink! trait message.
128    ///
129    /// This might have been adjusted using `#[ink(selector = N:u32)]` at the
130    /// ink! trait definition site.
131    const SELECTOR: [u8; 4];
132}
133
134/// Captures info about an ink! trait definition.
135pub trait TraitInfo {
136    /// The unique id of the ink! trait definition.
137    const ID: u32;
138
139    /// The module path of the ink! trait definition.
140    ///
141    /// This is equivalent to Rust's builtin `module_path!` macro
142    /// invocation at the definition site of the ink! trait.
143    const PATH: &'static str;
144
145    /// The name of the ink! trait.
146    ///
147    /// This is just for convenience.
148    const NAME: &'static str;
149}
ink_primitives/reflect/trait_def/info.rs

ink_primitives/reflect/trait_def/
info.rs
