backend.rs 9.86 KB
Newer Older
1
// Copyright 2018-2020 Parity Technologies (UK) Ltd.
2
3
4
5
6
7
8
9
10
11
12
13
14
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

15
use crate::{
16
    call::{
17
        utils::ReturnType,
18
        CallParams,
19
        CreateParams,
20
    },
21
22
23
24
    hash::{
        CryptoHash,
        HashOutput,
    },
25
    topics::Topics,
26
    Environment,
27
28
29
30
    Result,
};
use ink_primitives::Key;

Hero Bird's avatar
Hero Bird committed
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
/// The flags to indicate further information about the end of a contract execution.
pub struct ReturnFlags {
    value: u32,
}

impl Default for ReturnFlags {
    fn default() -> Self {
        Self { value: 0 }
    }
}

impl ReturnFlags {
    /// Sets the bit to indicate that the execution is going to be reverted.
    pub fn set_reverted(mut self, has_reverted: bool) -> Self {
        match has_reverted {
            true => self.value |= has_reverted as u32,
            false => self.value &= !has_reverted as u32,
        }
        self
    }

    /// Returns the underlying `u32` representation.
    pub(crate) fn into_u32(self) -> u32 {
        self.value
    }
}

58
59
/// Environmental contract functionality that does not require `Environment`.
pub trait EnvBackend {
60
    /// Writes the value to the contract storage under the given key.
61
    fn set_contract_storage<V>(&mut self, key: &Key, value: &V)
62
63
64
65
66
67
68
69
    where
        V: scale::Encode;

    /// Returns the value stored under the given key in the contract's storage if any.
    ///
    /// # Errors
    ///
    /// - If the decoding of the typed value failed
Hero Bird's avatar
Hero Bird committed
70
    fn get_contract_storage<R>(&mut self, key: &Key) -> Result<Option<R>>
71
72
73
74
    where
        R: scale::Decode;

    /// Clears the contract's storage key entry.
75
    fn clear_contract_storage(&mut self, key: &Key);
76

77
    /// Returns the execution input to the executed contract and decodes it as `T`.
78
79
80
81
82
    ///
    /// # Note
    ///
    /// - The input is the 4-bytes selector followed by the arguments
    ///   of the called function in their SCALE encoded representation.
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    /// - No prior interaction with the environment must take place before
    ///   calling this procedure.
    ///
    /// # Usage
    ///
    /// Normally contracts define their own `enum` dispatch types respective
    /// to their exported contructors and messages that implement `scale::Decode`
    /// according to the contructors or messages selectors and their arguments.
    /// These `enum` dispatch types are then given to this procedure as the `T`.
    ///
    /// When using ink! users do not have to construct those enum dispatch types
    /// themselves as they are normally generated by the ink! code generation
    /// automatically.
    ///
    /// # Errors
    ///
    /// If the given `T` cannot be properly decoded from the expected input.
    fn decode_input<T>(&mut self) -> Result<T>
    where
        T: scale::Decode;
103
104
105
106
107

    /// Returns the value back to the caller of the executed contract.
    ///
    /// # Note
    ///
Hero Bird's avatar
Hero Bird committed
108
109
110
111
112
113
    /// Calling this method will end contract execution immediately.
    /// It will return the given return value back to its caller.
    ///
    /// The `flags` parameter can be used to revert the state changes of the
    /// entire execution if necessary.
    fn return_value<R>(&mut self, flags: ReturnFlags, return_value: &R) -> !
114
115
116
117
118
    where
        R: scale::Encode;

    /// Prints the given contents to the console log.
    fn println(&mut self, content: &str);
119

120
121
122
123
    /// Conducts the crypto hash of the given input and stores the result in `output`.
    fn hash_bytes<H>(&mut self, input: &[u8], output: &mut <H as HashOutput>::Type)
    where
        H: CryptoHash;
124

125
126
127
128
129
    /// Conducts the crypto hash of the given encoded input and stores the result in `output`.
    fn hash_encoded<H, T>(&mut self, input: &T, output: &mut <H as HashOutput>::Type)
    where
        H: CryptoHash,
        T: scale::Encode;
Hero Bird's avatar
Hero Bird committed
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

    /// Calls the chain extension with the given ID and inputs.
    ///
    /// Returns the output of the chain extension of the specified type.
    ///
    /// # Errors
    ///
    /// - If the chain extension with the given ID does not exist.
    /// - If the inputs had an unexpected encoding.
    /// - If the output could not be properly decoded.
    /// - If some extension specific condition has not been met.
    #[cfg(feature = "ink-unstable-chain-extensions")]
    fn call_chain_extension<I, O>(&mut self, func_id: u32, input: &I) -> Result<O>
    where
        I: scale::Codec + 'static,
        O: scale::Codec + 'static;
146
147
148
}

/// Environmental contract functionality.
149
pub trait TypedEnvBackend: EnvBackend {
150
151
152
153
    /// Returns the address of the caller of the executed contract.
    ///
    /// # Note
    ///
154
    /// For more details visit: [`ink_env::caller`]
155
    fn caller<T: Environment>(&mut self) -> Result<T::AccountId>;
156
157
158
159
160

    /// Returns the transferred balance for the contract execution.
    ///
    /// # Note
    ///
161
    /// For more details visit: [`ink_env::transferred_balance`]
162
    fn transferred_balance<T: Environment>(&mut self) -> Result<T::Balance>;
163

164
    /// Returns the price for the specified amount of gas.
165
166
167
    ///
    /// # Note
    ///
168
    /// For more details visit: [`ink_env::gas_price`]
169
    fn weight_to_fee<T: Environment>(&mut self, gas: u64) -> Result<T::Balance>;
170
171
172
173
174

    /// Returns the amount of gas left for the contract execution.
    ///
    /// # Note
    ///
175
    /// For more details visit: [`ink_env::gas_left`]
176
    fn gas_left<T: Environment>(&mut self) -> Result<T::Balance>;
177
178
179
180
181

    /// Returns the timestamp of the current block.
    ///
    /// # Note
    ///
182
    /// For more details visit: [`ink_env::block_timestamp`]
183
    fn block_timestamp<T: Environment>(&mut self) -> Result<T::Timestamp>;
184
185
186
187
188

    /// Returns the address of the executed contract.
    ///
    /// # Note
    ///
189
    /// For more details visit: [`ink_env::account_id`]
190
    fn account_id<T: Environment>(&mut self) -> Result<T::AccountId>;
191
192
193
194
195

    /// Returns the balance of the executed contract.
    ///
    /// # Note
    ///
196
    /// For more details visit: [`ink_env::balance`]
197
    fn balance<T: Environment>(&mut self) -> Result<T::Balance>;
198
199
200
201
202

    /// Returns the current rent allowance for the executed contract.
    ///
    /// # Note
    ///
203
    /// For more details visit: [`ink_env::rent_allowance`]
204
    fn rent_allowance<T: Environment>(&mut self) -> Result<T::Balance>;
205
206
207
208
209

    /// Returns the current block number.
    ///
    /// # Note
    ///
210
    /// For more details visit: [`ink_env::block_number`]
211
    fn block_number<T: Environment>(&mut self) -> Result<T::BlockNumber>;
212
213
214
215
216

    /// Returns the minimum balance of the contracts chain.
    ///
    /// # Note
    ///
217
    /// For more details visit: [`ink_env::minimum_balance`]
218
    fn minimum_balance<T: Environment>(&mut self) -> Result<T::Balance>;
219
220
221
222
223

    /// Returns the tombstone deposit of the contract chain.
    ///
    /// # Note
    ///
224
    /// For more details visit: [`ink_env::tombstone_deposit`]
225
    fn tombstone_deposit<T: Environment>(&mut self) -> Result<T::Balance>;
226
227
228
229
230

    /// Emits an event with the given event data.
    ///
    /// # Note
    ///
231
    /// For more details visit: [`ink_env::emit_event`]
232
233
    fn emit_event<T, Event>(&mut self, event: Event)
    where
234
        T: Environment,
235
        Event: Topics + scale::Encode;
236
237
238
239
240

    /// Sets the rent allowance of the executed contract to the new value.
    ///
    /// # Note
    ///
241
    /// For more details visit: [`ink_env::set_rent_allowance`]
242
243
    fn set_rent_allowance<T>(&mut self, new_value: T::Balance)
    where
244
        T: Environment;
245
246
247
248
249

    /// Invokes a contract message.
    ///
    /// # Note
    ///
250
    /// For more details visit: [`ink_env::invoke_contract`]
251
252
253
254
    fn invoke_contract<T, Args>(
        &mut self,
        call_data: &CallParams<T, Args, ()>,
    ) -> Result<()>
255
    where
256
        T: Environment,
257
        Args: scale::Encode;
258
259
260
261
262

    /// Evaluates a contract message and returns its result.
    ///
    /// # Note
    ///
263
    /// For more details visit: [`ink_env::eval_contract`]
264
    fn eval_contract<T, Args, R>(
265
        &mut self,
266
        call_data: &CallParams<T, Args, ReturnType<R>>,
267
268
    ) -> Result<R>
    where
269
        T: Environment,
270
        Args: scale::Encode,
271
272
273
274
275
276
        R: scale::Decode;

    /// Instantiates another contract.
    ///
    /// # Note
    ///
277
    /// For more details visit: [`ink_env::instantiate_contract`]
278
    fn instantiate_contract<T, Args, C>(
279
        &mut self,
280
        params: &CreateParams<T, Args, C>,
281
282
    ) -> Result<T::AccountId>
    where
283
        T: Environment,
284
        Args: scale::Encode;
285
286
287
288
289

    /// Restores a smart contract tombstone.
    ///
    /// # Note
    ///
290
    /// For more details visit: [`ink_env::restore_contract`]
291
292
293
294
295
296
297
    fn restore_contract<T>(
        &mut self,
        account_id: T::AccountId,
        code_hash: T::Hash,
        rent_allowance: T::Balance,
        filtered_keys: &[Key],
    ) where
298
        T: Environment;
299

300
301
302
303
    /// Terminates a smart contract.
    ///
    /// # Note
    ///
304
    /// For more details visit: [`ink_env::terminate_contract`]
305
306
    fn terminate_contract<T>(&mut self, beneficiary: T::AccountId) -> !
    where
307
        T: Environment;
308

309
310
311
312
    /// Transfers value from the contract to the destination account ID.
    ///
    /// # Note
    ///
313
    /// For more details visit: [`ink_env::transfer`]
314
315
    fn transfer<T>(&mut self, destination: T::AccountId, value: T::Balance) -> Result<()>
    where
316
        T: Environment;
317

318
319
320
321
    /// Returns a random hash seed.
    ///
    /// # Note
    ///
322
    /// For more details visit: [`ink_env::random`]
323
324
    fn random<T>(&mut self, subject: &[u8]) -> Result<T::Hash>
    where
325
        T: Environment;
326
}