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}