traits.rs 6.15 KB
Newer Older
1
// Copyright 2018-2019 Parity Technologies (UK) Ltd.
2
// This file is part of ink!.
3
//
4
// ink! is free software: you can redistribute it and/or modify
5 6 7 8
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
9
// ink! is distributed in the hope that it will be useful,
10 11 12 13 14
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
15
// along with ink!.  If not, see <http://www.gnu.org/licenses/>.
16

17 18 19 20
use crate::{
    memory::vec::Vec,
    storage::Key,
};
taskooh's avatar
taskooh committed
21 22 23 24
use scale::{
    Codec,
    Decode,
};
25

26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
/// Error encountered by calling a remote contract.
///
/// # Note
///
/// This is currently just a placeholder for potential future error codes.
#[derive(Debug, Copy, Clone)]
pub struct CallError;

/// Error encountered upon creating and instantiation a new smart contract.
///
/// # Note
///
/// This is currently just a placeholder for potential future error codes.
#[derive(Debug, Copy, Clone)]
pub struct CreateError;

Andrew Jones's avatar
Andrew Jones committed
42 43
#[cfg(not(feature = "test-env"))]
/// The environmental types usable by contracts defined with ink!.
44 45
pub trait EnvTypes {
    /// The type of an address.
Andrew Jones's avatar
Andrew Jones committed
46
    type AccountId: Codec + Clone + PartialEq + Eq;
47
    /// The type of balances.
Andrew Jones's avatar
Andrew Jones committed
48
    type Balance: Codec + Clone + PartialEq + Eq;
49
    /// The type of hash.
Andrew Jones's avatar
Andrew Jones committed
50
    type Hash: Codec + Clone + PartialEq + Eq;
51
    /// The type of timestamps.
Andrew Jones's avatar
Andrew Jones committed
52
    type Moment: Codec + Clone + PartialEq + Eq;
53 54
    /// The type of block number.
    type BlockNumber: Codec + Clone + PartialEq + Eq;
55
    /// The type of a call into the runtime
56
    type Call: scale::Encode;
Andrew Jones's avatar
Andrew Jones committed
57 58 59 60
}

#[cfg(feature = "test-env")]
/// The environmental types usable by contracts defined with ink!.
61
/// For the test environment extra trait bounds are required for using the types in unit tests.
Andrew Jones's avatar
Andrew Jones committed
62 63 64 65 66 67 68 69 70
pub trait EnvTypes {
    /// The type of an address.
    type AccountId: Codec + Clone + PartialEq + Eq + core::fmt::Debug;
    /// The type of balances.
    type Balance: Codec + Clone + PartialEq + Eq + core::fmt::Debug;
    /// The type of hash.
    type Hash: Codec + Clone + PartialEq + Eq + core::fmt::Debug;
    /// The type of timestamps.
    type Moment: Codec + Clone + PartialEq + Eq + core::fmt::Debug;
71 72
    /// The type of block number.
    type BlockNumber: Codec + Clone + PartialEq + Eq + core::fmt::Debug;
73 74 75
    /// The type of a call into the runtime.
    /// Requires Decode for inspecting raw dispatched calls in the test environment.
    type Call: Codec + Clone + PartialEq + Eq + core::fmt::Debug;
76 77 78 79 80
}

/// Types implementing this can act as contract storage.
pub trait EnvStorage {
    /// Stores the given value under the given key.
81 82 83
    ///
    /// # Safety
    ///
84
    /// This operation is unsafe because it does not check for key integrity.
85
    /// Users can compare this operation with a raw pointer dereferencing in Rust.
86 87 88
    unsafe fn store(key: Key, value: &[u8]);

    /// Clears the value stored under the given key.
89 90 91
    ///
    /// # Safety
    ///
92
    /// This operation is unsafe because it does not check for key integrity.
93
    /// Users can compare this operation with a raw pointer dereferencing in Rust.
94 95 96
    unsafe fn clear(key: Key);

    /// Loads data stored under the given key.
97 98 99
    ///
    /// # Safety
    ///
100
    /// This operation is unsafe because it does not check for key integrity.
101
    /// Users can compare this operation with a raw pointer dereferencing in Rust.
102 103 104
    unsafe fn load(key: Key) -> Option<Vec<u8>>;
}

105
/// The environment API usable by contracts defined with pDSL.
Andrew Jones's avatar
Andrew Jones committed
106
pub trait Env: EnvTypes {
107 108 109 110 111 112
    /// Returns the chain address of the contract.
    fn address() -> <Self as EnvTypes>::AccountId;

    /// Returns the chain balance of the contract.
    fn balance() -> <Self as EnvTypes>::Balance;

113
    /// Returns the chain address of the caller.
114
    fn caller() -> <Self as EnvTypes>::AccountId;
115 116 117 118

    /// Loads input data for contract execution.
    fn input() -> Vec<u8>;

Shawn Tabrizi's avatar
Shawn Tabrizi committed
119
    /// Get the random seed from the latest block.
120
    fn random_seed() -> <Self as EnvTypes>::Hash;
121

122 123 124
    /// Get the timestamp of the latest block.
    fn now() -> <Self as EnvTypes>::Moment;

125
    /// Get the block number of the latest block.
126
    fn block_number() -> <Self as EnvTypes>::BlockNumber;
127

128 129 130 131 132 133 134 135 136
    /// Returns the current gas price.
    fn gas_price() -> <Self as EnvTypes>::Balance;

    /// Returns the gas left for this contract execution.
    fn gas_left() -> <Self as EnvTypes>::Balance;

    /// Returns the amount of value that has been transferred.
    fn value_transferred() -> <Self as EnvTypes>::Balance;

137
    /// Returns from the contract execution with the given value.
138 139 140 141 142 143
    ///
    /// # Safety
    ///
    /// The external callers rely on the correct type of the encoded
    /// returned value. This API is unsafe because it does not provide
    /// guarantees on its own to always encode the expected type.
144
    fn return_data(data: &[u8]);
145 146 147 148 149 150 151

    /// Prints the given content to Substrate output.
    ///
    /// # Note
    ///
    /// Usable only in development (`--dev`) chains.
    fn println(content: &str);
152 153

    /// Deposits raw event data through Contracts module.
154
    fn deposit_raw_event(topics: &[<Self as EnvTypes>::Hash], data: &[u8]);
155 156 157

    /// Dispatches a call into the Runtime.
    fn dispatch_raw_call(data: &[u8]);
taskooh's avatar
taskooh committed
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173

    /// Calls a remote smart contract without returning data
    fn call_invoke(
        callee: <Self as EnvTypes>::AccountId,
        gas: u64,
        value: <Self as EnvTypes>::Balance,
        input_data: &[u8],
    ) -> Result<(), CallError>;

    /// Calls a remote smart contract and return encoded data
    fn call_evaluate<T: Decode>(
        callee: <Self as EnvTypes>::AccountId,
        gas: u64,
        value: <Self as EnvTypes>::Balance,
        input_data: &[u8],
    ) -> Result<T, CallError>;
174 175 176 177 178 179 180 181

    /// Creates and instantiates a new smart contract.
    fn create(
        code_hash: <Self as EnvTypes>::Hash,
        gas_limit: u64,
        value: <Self as EnvTypes>::Balance,
        input_data: &[u8],
    ) -> Result<<Self as EnvTypes>::AccountId, CreateError>;
182
}