Struct EnvAccess 

pub struct EnvAccess<'a, E> { /* private fields */ }

The API behind the self.env() and Self::env() syntax in ink!.

This allows ink! messages to make use of the environment efficiently and user-friendly while also maintaining access invariants.

Implementations

impl<E> EnvAccess<'_, E>

where E: Environment,

pub fn caller(self) -> Address

Returns the address of the caller of the executed contract.

Example

#[ink(message)]
pub fn call_me(&self) {
    let caller = self.env().caller();
}

Note

For more details visit: ink_env::caller

pub fn gas_limit(self) -> u64

Returns the block ref_time limit.

Example

#[ink::contract]
mod my_contract {
    #[ink(storage)]
    pub struct MyContract;

    impl MyContract {
        #[ink(constructor)]
        pub fn new() -> Self {
            Self {}
        }

        #[ink(message)]
        pub fn get_limit(&self) -> u64 {
            self.env().gas_limit()
        }
    }
}

Note

For more details visit: ink_env::gas_limit

pub fn transferred_value(self) -> U256

Returns the transferred value for the contract execution.

Example

/// Allows funding the contract. Prints a debug message with the transferred value.
#[ink(message, payable)]
pub fn fund(&mut self) {
    let caller = self.env().caller();
    let value = self.env().transferred_value();
}

Note

For more details visit: ink_env::transferred_value

pub fn weight_to_fee(self, gas: u64) -> U256

Returns the price for the specified amount of gas.

Example

#[ink(message)]
pub fn foo(&self) {}

// todo
// /// Returns a tuple of
// ///   - the result of adding the `rhs` to the `lhs`
// ///   - the gas costs of this addition operation
// ///   - the price for the gas
// #[ink(message)]
// pub fn addition_gas_cost(&self, rhs: i32, lhs: i32) -> (i32, u64, Balance) {
//    let before = self.env().gas_left();
//    let result = rhs + lhs;
//    let after = self.env().gas_left();
//    let gas_used = after - before;
//    let gas_cost = self.env().weight_to_fee(gas_used);
//    (result, gas_used, gas_cost)
//}

Note

For more details visit: ink_env::weight_to_fee

pub fn block_timestamp(self) -> E::Timestamp

Returns the timestamp of the current block.

Example

#[ink::contract]
pub mod my_contract {
    #[ink(storage)]
    pub struct MyContract {
        last_invocation: Timestamp,
    }

    impl MyContract {
        #[ink(constructor)]
        pub fn new() -> Self {
            Self {
                last_invocation: Self::env().block_timestamp(),
            }
        }

        /// Records the last time the message was invoked.
        #[ink(message)]
        pub fn execute_me(&mut self) {
            self.last_invocation = self.env().block_timestamp();
        }
    }
}

Note

The Substrate default for the timestamp type is the milliseconds since the Unix epoch. However, this is not guaranteed: the specific timestamp is defined by the chain environment on which this contract runs.

For more details visit: ink_env::block_timestamp

pub fn to_account_id(self, addr: Address) -> E::AccountId

Retrieves the account id for a specified address.

Example

#[ink::contract]
pub mod only_owner {
    #[ink(storage)]
    pub struct OnlyOwner {
        owner: AccountId,
        value: u32,
    }

    impl OnlyOwner {
        #[ink(constructor)]
        pub fn new(owner: AccountId) -> Self {
            Self { owner, value: 0 }
        }

        /// Allows incrementing the contract's `value` only
        /// for the owner.
        ///
        /// The contract panics if the caller is not the owner.
        #[ink(message)]
        pub fn increment(&mut self) {
            let caller = self.env().address();
            let caller_acc = self.env().to_account_id(caller);
            assert!(self.owner == caller_acc);
            self.value = self.value + 1;
        }
    }
}

Note

For more details visit: ink_env::to_account_id

pub fn account_id(self) -> E::AccountId

Returns the account ID of the executed contract.

Example

#[ink::contract]
pub mod only_owner {
    #[ink(storage)]
    pub struct OnlyOwner {
        owner: AccountId,
        value: u32,
    }

    impl OnlyOwner {
        #[ink(constructor)]
        pub fn new() -> Self {
            Self {
                owner: Self::env().account_id(),
                value: 0,
            }
        }

        /// Allows incrementing the contract's `value` only
        /// for the owner.
        ///
        /// The contract panics if the caller is not the owner.
        #[ink(message)]
        pub fn increment(&mut self) {
            let caller = self.env().account_id();
            assert!(self.owner == caller);
            self.value = self.value + 1;
        }
    }
}

Note

For more details visit: ink_env::account_id

pub fn address(self) -> Address

Returns the address of the executed contract.

For more details visit: ink_env::address

pub fn balance(self) -> U256

Returns the balance of the executed contract.

Example

/// Returns the contract's balance.
#[ink(message)]
pub fn my_balance(&self) -> ink::U256 {
    self.env().balance()
}

Note

For more details visit: ink_env::balance

pub fn block_number(self) -> E::BlockNumber

Returns the current block number.

Example

#[ink::contract]
pub mod my_contract {
    #[ink(storage)]
    pub struct MyContract {
        last_invocation: BlockNumber,
    }

    impl MyContract {
        #[ink(constructor)]
        pub fn new() -> Self {
            Self {
                last_invocation: Self::env().block_number(),
            }
        }

        /// The function can be executed at most once every 100 blocks.
        #[ink(message)]
        pub fn execute_me(&mut self) {
            let now = self.env().block_number();
            assert!(now - self.last_invocation > 100);
            self.last_invocation = now;
        }
    }
}

Note

For more details visit: ink_env::block_number

pub fn minimum_balance(self) -> U256

Returns the minimum balance that is required for creating an account (i.e. the chain’s existential deposit).

Example

#[ink(message)]
pub fn minimum_balance(&self) -> ink::U256 {
    self.env().minimum_balance()
}

Note

For more details visit: ink_env::minimum_balance

pub fn emit_event<Evt>(self, event: Evt)

where Evt: Event<DefaultAbi>,

Emits an event.

Note

In “all” ABI mode, both an ink! and Solidity ABI event are emitted.

pub fn emit_event_ink<Evt>(self, event: Evt)

where Evt: Event<Ink>,

Emits an event using the ink! ABI encoding (i.e. with SCALE codec for event data encode/decode).

pub fn emit_event_sol<Evt>(self, event: Evt)

where Evt: Event<Sol>,

Emits an event using the Solidity ABI encoding.

pub fn instantiate_contract<ContractRef, Args, R, Abi>( self, params: &CreateParams<E, ContractRef, LimitParamsV2, Args, R, Abi>, ) -> Result<ConstructorResult<<R as ConstructorReturnType<ContractRef, Abi>>::Output>>

where ContractRef: FromAddr + ContractReverseReference, <ContractRef as ContractReverseReference>::Type: ContractConstructorDecoder, Args: EncodeArgsWith<Abi>, R: ConstructorReturnType<ContractRef, Abi>,

Instantiates another contract using the supplied code hash.

Invokes the instantiate_v2 host function which allows passing all weight and storage limit parameters.

Example

use ink::env::{
    call::{
        build_create,
        ExecutionInput,
        Selector,
    },
    DefaultEnvironment,
};
use other_contract::OtherContractRef;

/// Instantiates another contract.
#[ink(message)]
pub fn instantiate_contract(&self) -> MyContractRef {
    let create_params = build_create::<OtherContractRef>()
        .code_hash(ink::H256::from([0x42; 32]))
        .ref_time_limit(500_000_000)
        .proof_size_limit(100_000)
        .storage_deposit_limit(ink::U256::from(500_000_000_000u64))
        .endowment(25.into())
        .exec_input(
            ExecutionInput::new(Selector::new(ink::selector_bytes!("new")))
                .push_arg(42)
                .push_arg(true)
                .push_arg(&[0x10u8; 32]),
        )
        .salt_bytes(Some([0x13; 32]))
        .returns::<OtherContractRef>()
        .params();
    self.env()
        .instantiate_contract(&create_params)
        .unwrap_or_else(|error| {
            panic!(
                "Received an error from `pallet-revive` while instantiating: {error:?}"
            )
        })
        .unwrap_or_else(|error| {
            panic!("Received a `LangError` while instantiating: {error:?}")
        })
}

See our delegator example for a complete contract example.

Note

For more details visit: ink_env::instantiate_contract

pub fn invoke_contract<Args, R, Abi>( self, params: &CallParams<E, Call, Args, R, Abi>, ) -> Result<MessageResult<R>>

where Args: EncodeArgsWith<Abi>, R: DecodeMessageResult<Abi>,

Invokes a contract message and returns its result.

Example

use ink::env::{
    DefaultEnvironment,
    call::{
        ExecutionInput,
        Selector,
        build_call,
    },
};

/// Invokes a contract message and fetches the result.
#[ink(message)]
pub fn invoke_contract(&self) -> i32 {
    let call_params = build_call::<DefaultEnvironment>()
        .call(ink::Address::from([0x42; 20]))
        .ref_time_limit(500_000_000)
        .proof_size_limit(100_000)
        .storage_deposit_limit(1_000_000_000.into())
        .exec_input(
            ExecutionInput::new(Selector::new([0xCA, 0xFE, 0xBA, 0xBE]))
                .push_arg(42u8)
                .push_arg(true)
                .push_arg(&[0x10u8; 32]),
        )
        .returns::<i32>()
        .params();

    self.env()
        .invoke_contract(&call_params)
        .unwrap_or_else(|env_err| {
            panic!("Received an error from the Environment: {:?}", env_err)
        })
        .unwrap_or_else(|lang_err| panic!("Received a `LangError`: {:?}", lang_err))
}

Note

For more details visit: ink_env::invoke_contract

pub fn invoke_contract_delegate<Args, R, Abi>( self, params: &CallParams<E, DelegateCall, Args, R, Abi>, ) -> Result<MessageResult<R>>

where Args: EncodeArgsWith<Abi>, R: DecodeMessageResult<Abi>,

Invokes in delegate manner a code message and returns its result.

Example

use ink::env::{
    DefaultEnvironment,
    call::{
        DelegateCall,
        ExecutionInput,
        Selector,
        build_call,
        utils::ReturnType,
    },
};
use ink_primitives::Clear;

/// Invokes in delegate manner a contract message and fetches the result.
#[ink(message)]
pub fn invoke_contract_delegate(&self) -> i32 {
    let call_params = build_call::<DefaultEnvironment>()
        .call_type(DelegateCall::new(ink::Address::zero()))
        .exec_input(
            ExecutionInput::new(Selector::new([0xCA, 0xFE, 0xBA, 0xBE]))
                .push_arg(42u8)
                .push_arg(true)
                .push_arg(&[0x10u8; 32]),
        )
        .returns::<i32>()
        .params();
    self.env()
        .invoke_contract_delegate(&call_params)
        .unwrap_or_else(|env_err| {
            panic!("Received an error from the Environment: {:?}", env_err)
        })
        .unwrap_or_else(|lang_err| panic!("Received a `LangError`: {:?}", lang_err))
}

Note

For more details visit: ink_env::invoke_contract_delegate

pub fn transfer(self, destination: Address, value: U256) -> Result<()>

pub fn hash_bytes<H>(self, input: &[u8]) -> <H as HashOutput>::Type

where H: CryptoHash,

Computes the hash of the given bytes using the cryptographic hash H.

Example

use ink_env::hash::{
    HashOutput,
    Sha2x256,
};

let input: &[u8] = &[13, 14, 15];
let mut output = <Sha2x256 as HashOutput>::Type::default(); // 256-bit buffer
let hash = ink_env::hash_bytes::<Sha2x256>(input, &mut output);

Note

For more details visit: ink_env::hash_bytes

pub fn hash_encoded<H, V>(self, value: &V) -> <H as HashOutput>::Type

where H: CryptoHash, V: Encode,

Computes the hash of the given SCALE encoded value using the cryptographic hash H.

Example

use ink_env::hash::{
    HashOutput,
    Sha2x256,
};

let encodable = (42, "foo", true); // Implements `scale::Encode`
let mut output = <Sha2x256 as HashOutput>::Type::default(); // 256-bit buffer
ink_env::hash_encoded::<Sha2x256, _>(&encodable, &mut output);

const EXPECTED: [u8; 32] = [
    243, 242, 58, 110, 205, 68, 100, 244, 187, 55, 188, 248, 29, 136, 145, 115, 186,
    134, 14, 175, 178, 99, 183, 21, 4, 94, 92, 69, 199, 207, 241, 179,
];
assert_eq!(output, EXPECTED);

Note

For more details visit: ink_env::hash_encoded

pub fn ecdsa_recover( self, signature: &[u8; 65], message_hash: &[u8; 32], ) -> Result<[u8; 33]>

Recovers the compressed ECDSA public key for given signature and message_hash, and stores the result in output.

Example

/// Recovery from pre-defined signature and message hash
#[ink(message)]
pub fn ecdsa_recover(&self) {
    const signature: [u8; 65] = [
        195, 218, 227, 165, 226, 17, 25, 160, 37, 92, 142, 238, 4, 41, 244, 211, 18,
        94, 131, 116, 231, 116, 255, 164, 252, 248, 85, 233, 173, 225, 26, 185, 119,
        235, 137, 35, 204, 251, 134, 131, 186, 215, 76, 112, 17, 192, 114, 243, 102,
        166, 176, 140, 180, 124, 213, 102, 117, 212, 89, 89, 92, 209, 116, 17, 28,
    ];
    const message_hash: [u8; 32] = [
        167, 124, 116, 195, 220, 156, 244, 20, 243, 69, 1, 98, 189, 205, 79, 108,
        213, 78, 65, 65, 230, 30, 17, 37, 184, 220, 237, 135, 1, 209, 101, 229,
    ];
    const EXPECTED_COMPRESSED_PUBLIC_KEY: [u8; 33] = [
        3, 110, 192, 35, 209, 24, 189, 55, 218, 250, 100, 89, 40, 76, 222, 208, 202,
        127, 31, 13, 58, 51, 242, 179, 13, 63, 19, 22, 252, 164, 226, 248, 98,
    ];
    let result = self.env().ecdsa_recover(&signature, &message_hash);
    assert!(result.is_ok());
    assert_eq!(
        result.unwrap().as_ref(),
        EXPECTED_COMPRESSED_PUBLIC_KEY.as_ref()
    );

    // Pass invalid zero message hash
    let failed_result = self.env().ecdsa_recover(&signature, &[0; 32]);
    assert!(failed_result.is_err());
    if let Err(e) = failed_result {
        assert_eq!(e, ink::env::ReturnErrorCode::EcdsaRecoveryFailed.into());
    }
}

pub fn is_contract(self, addr: &Address) -> bool

Checks whether addr is a contract.

Notes

If addr references a precompile address, the return value will be true.

The function Self::caller_is_origin performs better when checking whether your contract is being called by a contract or an account. It performs better for this case as it does not require any storage lookups.

Example

#[ink(message)]
pub fn is_contract(&mut self, addr: ink::Address) -> bool {
    self.env().is_contract(&addr)
}

#[ink(message)]
pub fn check(&mut self) {
    let this_contract = self.env().address();
    assert!(self.env().is_contract(&this_contract));
    assert!(!self.env().is_contract(&self.env().caller()));
}

Note

For more details visit: ink_env::is_contract

pub fn caller_is_origin(self) -> bool

Checks whether the caller of the current contract is the origin of the whole call stack.

Example

#[ink(message)]
pub fn caller_is_origin(&mut self) -> bool {
    self.env().caller_is_origin()
}

Note

For more details visit: ink_env::caller_is_origin

pub fn caller_is_root(self) -> bool

Checks whether the caller of the current contract is root.

Example

#[ink(message)]
pub fn caller_is_root(&mut self) -> bool {
    self.env().caller_is_root()
}

Note

For more details visit: ink_env::caller_is_root

pub fn code_hash(self, addr: &Address) -> Result<H256, CodeHashErr>

Returns the code hash of the contract at the given account id.

Example

#[ink(message)]
// todo
pub fn code_hash(&mut self, addr: ink::Address) -> Option<ink::H256> {
    self.env().code_hash(&addr).ok()
}

Note

For more details visit: ink_env::code_hash

pub fn own_code_hash(self) -> H256

Returns the code hash of the contract at the given account id.

Example

#[ink(message)]
pub fn own_code_hash(&mut self) -> ink::H256 {
    self.env().own_code_hash()
}

Note

For more details visit: ink_env::own_code_hash

Trait Implementations

impl<'a, E: Clone> Clone for EnvAccess<'a, E>

fn clone(&self) -> EnvAccess<'a, E>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<E> Debug for EnvAccess<'_, E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E> Default for EnvAccess<'_, E>

fn default() -> Self

Returns the “default value” for a type.

impl<'a, E: Copy> Copy for EnvAccess<'a, E>