types.rs 10.6 KB
Newer Older
1
// Copyright 2018-2021 Parity Technologies (UK) Ltd.
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
//
// 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.

//! Types for the default environment.
//!
17
//! These are simple mirrored types from the default substrate FRAME configuration.
18
19
//! Their interfaces and functionality might not be complete.
//!
20
//! Users are required to provide their own type definitions and `Environment`
21
//! implementations in order to write ink! contracts for other chain configurations.
22
23
24
//!
//! # Note
//!
25
//! When authoring a contract, the concrete `Environment` are available via aliases
26
27
28
29
//! generated by the `lang` macro. Therefore all functionality of the concrete
//! types is accessible in the contract, not constrained by the required trait
//! bounds.
//!
30
//! Outside the contract and its tests (e.g. in the off-chain environment), where
31
//! there is no knowledge of the concrete types, the functionality is restricted to
32
//! the trait bounds on the `Environment` trait types.
33

34
use super::arithmetic::AtLeast32BitUnsigned;
35
36
37
38
39
use core::{
    array::TryFromSliceError,
    convert::TryFrom,
};
use derive_more::From;
40
41
42
43
44
use scale::{
    Decode,
    Encode,
};
#[cfg(feature = "std")]
45
use scale_info::TypeInfo;
46
47
use sp_arithmetic::PerThing;
pub use sp_arithmetic::Perbill;
48
49

/// The environmental types usable by contracts defined with ink!.
50
pub trait Environment {
51
52
53
54
55
    /// The maximum number of supported event topics provided by the runtime.
    ///
    /// The value must match the maximum number of supported event topics of the used runtime.
    const MAX_EVENT_TOPICS: usize;

56
    /// The address type.
57
    type AccountId: 'static + scale::Codec + Clone + PartialEq + Eq + Ord;
58

59
60
61
62
63
64
65
    /// The type of balances.
    type Balance: 'static
        + scale::Codec
        + Copy
        + Clone
        + PartialEq
        + Eq
66
        + AtLeast32BitUnsigned;
67

68
69
70
71
72
73
74
75
76
77
78
    /// The type of hash.
    type Hash: 'static
        + scale::Codec
        + Copy
        + Clone
        + Clear
        + PartialEq
        + Eq
        + Ord
        + AsRef<[u8]>
        + AsMut<[u8]>;
79

80
81
82
83
84
85
86
    /// The type of timestamps.
    type Timestamp: 'static
        + scale::Codec
        + Copy
        + Clone
        + PartialEq
        + Eq
87
        + AtLeast32BitUnsigned;
88

89
90
91
92
93
94
95
    /// The type of block number.
    type BlockNumber: 'static
        + scale::Codec
        + Copy
        + Clone
        + PartialEq
        + Eq
96
        + AtLeast32BitUnsigned;
97
98
99

    /// The chain extension for the environment.
    ///
100
    /// This is a type that is defined through the `#[ink::chain_extension]` procedural macro.
101
102
103
104
    /// For more information about usage and definition click [this][chain_extension] link.
    ///
    /// [chain_extension]: https://paritytech.github.io/ink/ink_lang/attr.chain_extension.html
    type ChainExtension;
105
106
107

    /// The fraction of the deposit costs that should be used as rent per block.
    type RentFraction: 'static + scale::Codec + Clone + PartialEq + Eq + Ord + PerThing;
108
109
}

110
111
112
/// Placeholder for chains that have no defined chain extension.
pub enum NoChainExtension {}

113
114
/// The fundamental types of the default configuration.
#[derive(Debug, Clone, PartialEq, Eq)]
115
#[cfg_attr(feature = "std", derive(TypeInfo))]
116
pub enum DefaultEnvironment {}
117

118
impl Environment for DefaultEnvironment {
119
120
    const MAX_EVENT_TOPICS: usize = 4;

121
122
123
124
125
    type AccountId = AccountId;
    type Balance = Balance;
    type Hash = Hash;
    type Timestamp = Timestamp;
    type BlockNumber = BlockNumber;
126
    type ChainExtension = NoChainExtension;
127
    type RentFraction = RentFraction;
128
129
130
131
132
133
134
135
136
}

/// The default balance type.
pub type Balance = u128;

/// The default timestamp type.
pub type Timestamp = u64;

/// The default block number type.
137
pub type BlockNumber = u32;
138

139
140
141
/// The default rent fraction type.
pub type RentFraction = Perbill;

142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
/// The default environment `AccountId` type.
///
/// # Note
///
/// This is a mirror of the `AccountId` type used in the default configuration
/// of PALLET contracts.
#[derive(
    Debug,
    Copy,
    Clone,
    PartialEq,
    Eq,
    Ord,
    PartialOrd,
    Hash,
    Encode,
    Decode,
    From,
    Default,
)]
162
#[cfg_attr(feature = "std", derive(TypeInfo))]
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
pub struct AccountId([u8; 32]);

impl<'a> TryFrom<&'a [u8]> for AccountId {
    type Error = TryFromSliceError;

    fn try_from(bytes: &'a [u8]) -> Result<Self, TryFromSliceError> {
        let address = <[u8; 32]>::try_from(bytes)?;
        Ok(Self(address))
    }
}

/// The default environment `Hash` type.
///
/// # Note
///
/// This is a mirror of the `Hash` type used in the default configuration
/// of PALLET contracts.
#[derive(
    Debug,
    Copy,
    Clone,
    PartialEq,
    Eq,
    Ord,
    PartialOrd,
    Hash,
    Encode,
    Decode,
    From,
    Default,
)]
194
#[cfg_attr(feature = "std", derive(TypeInfo))]
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
pub struct Hash([u8; 32]);

impl<'a> TryFrom<&'a [u8]> for Hash {
    type Error = TryFromSliceError;

    fn try_from(bytes: &'a [u8]) -> Result<Self, TryFromSliceError> {
        let address = <[u8; 32]>::try_from(bytes)?;
        Ok(Self(address))
    }
}

impl AsRef<[u8]> for Hash {
    fn as_ref(&self) -> &[u8] {
        &self.0[..]
    }
}

impl AsMut<[u8]> for Hash {
    fn as_mut(&mut self) -> &mut [u8] {
        &mut self.0[..]
    }
}

/// The equivalent of `Zero` for hashes.
///
/// A hash that consists only of 0 bits is clear.
pub trait Clear {
    /// Returns `true` if the hash is clear.
    fn is_clear(&self) -> bool;

    /// Returns a clear hash.
    fn clear() -> Self;
}

229
impl Clear for [u8; 32] {
230
231
232
233
234
    fn is_clear(&self) -> bool {
        self.as_ref().iter().all(|&byte| byte == 0x00)
    }

    fn clear() -> Self {
235
236
237
238
239
240
241
242
243
244
245
        [0x00; 32]
    }
}

impl Clear for Hash {
    fn is_clear(&self) -> bool {
        <[u8; 32] as Clear>::is_clear(&self.0)
    }

    fn clear() -> Self {
        Self(<[u8; 32] as Clear>::clear())
246
247
    }
}
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296

/// Information needed for rent calculations that can be requested by a contract.
#[derive(scale::Decode)]
#[cfg_attr(test, derive(Debug, PartialEq))]
pub struct RentParams<T: Environment> {
    /// The total balance of the contract. Includes the balance transferred from the caller.
    pub total_balance: T::Balance,

    /// The free balance of the contract, i.e. the portion of the contract's balance
    /// that is not reserved. Includes the balance transferred from the caller.
    pub free_balance: T::Balance,

    /// Subsistence threshold is the extension of the minimum balance (aka existential deposit)
    /// by the tombstone deposit, required for leaving a tombstone.
    ///
    /// Rent or any contract initiated balance transfer mechanism cannot make the balance lower
    /// than the subsistence threshold in order to guarantee that a tombstone is created.
    ///
    /// The only way to completely kill a contract without a tombstone is calling `seal_terminate`.
    pub subsistence_threshold: T::Balance,

    /// The balance every contract needs to deposit to stay alive indefinitely.
    ///
    /// This is different from the tombstone deposit because this only needs to be
    /// deposited while the contract is alive. Costs for additional storage are added to
    /// this base cost.
    ///
    /// This is a simple way to ensure that contracts with empty storage eventually get deleted by
    /// making them pay rent. This creates an incentive to remove them early in order to save rent.
    pub deposit_per_contract: T::Balance,

    /// The balance a contract needs to deposit per storage byte to stay alive indefinitely.
    ///
    /// Let's suppose the deposit is 1,000 BU (balance units)/byte and the rent is 1 BU/byte/day,
    /// then a contract with 1,000,000 BU that uses 1,000 bytes of storage would pay no rent.
    /// But if the balance reduced to 500,000 BU and the storage stayed the same at 1,000,
    /// then it would pay 500 BU/day.
    pub deposit_per_storage_byte: T::Balance,

    /// The balance a contract needs to deposit per storage item to stay alive indefinitely.
    ///
    /// It works as [`Self::deposit_per_storage_byte`] but for storage items.
    pub deposit_per_storage_item: T::Balance,

    /// The contract's rent allowance, the rent mechanism cannot consume more than this.
    pub rent_allowance: T::Balance,

    /// The fraction of the deposit costs that should be used as rent per block.
    ///
297
    /// When a contract does not have enough balance deposited to stay alive indefinitely
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
    /// it needs to pay per block for the storage it consumes that is not covered by the
    /// deposit. This determines how high this rent payment is per block as a fraction
    /// of the deposit costs.
    pub rent_fraction: T::RentFraction,

    /// The total number of bytes used by this contract.
    ///
    /// It is a sum of each key-value pair stored by this contract.
    pub storage_size: u32,

    /// Sum of instrumented and pristine code length.
    pub code_size: u32,

    /// The number of contracts using this executable.
    pub code_refcount: u32,

    /// Reserved for backwards compatible changes to this data structure.
    pub _reserved: Option<()>,
}
317
318
319
320
321
322
323
324

/// Information about the required deposit and resulting rent.
///
/// The easiest way to guarantee that a contract stays alive is to assert that
/// `max_rent == 0` at the **end** of a contract's execution.
///
/// # Note
///
325
326
/// The `current_*` fields do **not** consider changes to the code's `refcount`
/// made during the currently running call.
327
328
329
330
331
332
#[derive(scale::Decode)]
#[cfg_attr(test, derive(Debug, PartialEq))]
pub struct RentStatus<T: Environment> {
    /// Required deposit assuming that this contract is the only user of its code.
    pub max_deposit: T::Balance,

333
    /// Required deposit assuming the code's current `refcount`.
334
335
    pub current_deposit: T::Balance,

336
    /// Required deposit assuming the specified `refcount` (`None` if `0` is supplied).
337
338
339
340
341
342
343
344
345
346
347
348
349
350
    pub custom_refcount_deposit: Option<T::Balance>,

    /// Rent that is paid assuming that the contract is the only user of its code.
    pub max_rent: T::Balance,

    /// Rent that is paid given the code's current refcount.
    pub current_rent: T::Balance,

    /// Rent that is paid assuming the specified refcount (`None` if `0` is supplied).
    pub custom_refcount_rent: Option<T::Balance>,

    /// Reserved for backwards compatible changes to this data structure.
    pub _reserved: Option<()>,
}