ink_primitives/
contract.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 crate::types::Environment;
16
17/// Stores the used host environment type of the ink! smart contract.
18///
19/// # Note
20///
21/// The used host environment can be altered using the `env` configuration
22/// parameter in the `#[ink::contract]` parameters. For example if the user
23/// wanted to use an environment type definition called `MyEnvironment` they
24/// issue the ink! smart contract as follows:
25///
26/// ```no_compile
27/// #[ink::contract(env = MyEnvironment)]
28/// ```
29///
30/// # Usage: Default Environment
31///
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///             Self {}
42///         }
43///
44///         #[ink(message)]
45///         pub fn message(&self) {}
46///     }
47/// }
48///
49/// use contract::Contract;
50///
51/// # use ink::env::ContractEnv;
52/// # use ink::codegen::utils::IsSameType;
53///
54/// // The following line only compiles successfully if both
55/// // `ink_env::DefaultEnvironment` and `<Contract as ContractEnv>::Env`
56/// // are of the same type.
57/// const _: IsSameType<<Contract as ContractEnv>::Env> =
58///     <IsSameType<ink_env::DefaultEnvironment>>::new();
59/// ```
60///
61/// # Usage: Custom Environment
62///
63/// ```
64/// # use ink_env::{Environment, DefaultEnvironment};
65/// #[derive(Clone)]
66/// pub struct CustomEnvironment {}
67///
68/// impl Environment for CustomEnvironment {
69///     const MAX_EVENT_TOPICS: usize = 4;
70///     const NATIVE_TO_ETH_RATIO: u32 =
71///         <DefaultEnvironment as Environment>::NATIVE_TO_ETH_RATIO;
72///
73///     type AccountId = <DefaultEnvironment as Environment>::AccountId;
74///     type Balance = u64;
75///     type Hash = <DefaultEnvironment as Environment>::Hash;
76///     type BlockNumber = u32;
77///     type Timestamp = u64;
78///     type ChainExtension = <DefaultEnvironment as Environment>::ChainExtension;
79///     type EventRecord = <DefaultEnvironment as Environment>::EventRecord;
80/// }
81///
82/// #[ink::contract(env = super::CustomEnvironment)]
83/// pub mod contract {
84///     #[ink(storage)]
85///     pub struct Contract {}
86///
87///     impl Contract {
88///         #[ink(constructor)]
89///         pub fn constructor() -> Self {
90///             Self {}
91///         }
92///
93///         #[ink(message)]
94///         pub fn message(&self) {}
95///     }
96/// }
97///
98/// use contract::Contract;
99/// # use ink::env::ContractEnv;
100/// # use ink::codegen::utils::IsSameType;
101///
102/// // The following line only compiles successfully if both
103/// // `CustomEnvironment` and `<Contract as ContractEnv>::Env`
104/// // are of the same type.
105/// const _: IsSameType<<Contract as ContractEnv>::Env> =
106///     <IsSameType<CustomEnvironment>>::new();
107///
108/// fn main() {}
109/// ```
110pub trait ContractEnv {
111    /// The environment type.
112    type Env: Environment;
113}
114
115/// Refers to the generated ink! smart contract reference type.
116///
117/// # Note
118///
119/// Given an ink! storage struct with identifier `Contract` the ink! codegen produces
120/// the ink! root type `Contract` and the ink! reference type `ContractRef`.
121///
122/// This trait exists so that users can avoid using a generated identifier to refer to
123/// the generated reference type of the ink! smart contract.
124///
125/// # Usage
126///
127/// ```
128/// #[ink::contract]
129/// pub mod contract {
130///     #[ink(storage)]
131///     pub struct Contract {}
132///
133///     impl Contract {
134///         #[ink(constructor)]
135///         pub fn constructor() -> Self {
136///             Self {}
137///         }
138///
139///         #[ink(message)]
140///         pub fn message(&self) {}
141///     }
142/// }
143///
144/// use contract::{
145///     Contract,
146///     ContractRef,
147/// };
148/// # use ink::codegen::utils::IsSameType;
149/// # use ink::env::ContractReference;
150///
151/// // The following line only compiles successfully if both
152/// // `ContractReference` and `<Contract as ContractReference>::Type`
153/// // are of the same type.
154/// const _: IsSameType<<Contract as ContractReference>::Type> =
155///     <IsSameType<ContractRef>>::new();
156/// ```
157pub trait ContractReference {
158    /// The generated contract reference type.
159    type Type;
160}
161
162/// Refers back to the original contract from the generated ink! smart contract
163/// reference type.
164pub trait ContractReverseReference {
165    /// The original contract type.
166    type Type;
167}