Skip to main content

​
Overview

The Env type provides access to the environment the contract is executing within. It provides access to information about the currently executing contract, who invoked it, contract data, functions for signing, hashing, and more. Most types require access to an Env to be constructed or converted.

​
Creating an Env

​
default()

Create a new default Env instance. 
let env = Env::default();

​
Core Methods

​
storage()

Get a Storage for accessing and updating persistent data owned by the currently executing contract. 
pub fn storage(&self) -> Storage
Example: 
let storage = env.storage();

​
events()

Get Events for publishing events associated with the currently executing contract. 
pub fn events(&self) -> Events
Example: 
let events = env.events();

​
ledger()

Get a Ledger for accessing the current ledger information. 
pub fn ledger(&self) -> Ledger
Example: 
let ledger = env.ledger();
let sequence = ledger.sequence();

​
deployer()

Get a Deployer for deploying contracts. 
pub fn deployer(&self) -> Deployer
Example: 
let deployer = env.deployer();

​
crypto()

Get a Crypto for accessing cryptographic functions. 
pub fn crypto(&self) -> Crypto
Example: 
let crypto = env.crypto();
let hash = crypto.sha256(&data);

​
prng()

Get a Prng for accessing pseudo-random number generation functions. 
pub fn prng(&self) -> Prng
The pseudo-random generator is not suitable for security-sensitive work.
Example: 
let prng = env.prng();
let random_bytes = prng.bytes(&env, 32);

​
logs()

Get the Logs for logging debug events. 
pub fn logs(&self) -> Logs
Example: 
env.logs().log(&"Debug message");

​
Contract Interaction

​
current_contract_address()

Get the Address object corresponding to the current executing contract. 
pub fn current_contract_address(&self) -> Address
Example: 
let contract_address = env.current_contract_address();

​
invoke_contract()

Invokes a function of a contract that is registered in the Env. 
pub fn invoke_contract<T>(
    &self,
    contract_address: &Address,
    func: &Symbol,
    args: Vec<Val>,
) -> T
where
    T: TryFromVal<Env, Val>
Panics:
  • If the contract_id does not match a registered contract
  • If func does not match a function of the referenced contract
  • If the number of args do not match the argument count
  • If the contract invocation fails or aborts
  • If the return value cannot be converted into type T
Example: 
let result: i128 = env.invoke_contract(
    &contract_address,
    &symbol_short!("transfer"),
    (from, to, amount).into_val(&env),
);

​
try_invoke_contract()

Invokes a function of a contract and returns an error if the invocation fails for any reason. 
pub fn try_invoke_contract<T, E>(
    &self,
    contract_address: &Address,
    func: &Symbol,
    args: Vec<Val>,
) -> Result<Result<T, T::Error>, Result<E, InvokeError>>
where
    T: TryFromVal<Env, Val>,
    E: TryFrom<Error>,
    E::Error: Into<InvokeError>

​
authorize_as_current_contract()

Authorizes sub-contract calls on behalf of the current contract. 
pub fn authorize_as_current_contract(&self, auth_entries: Vec<InvokerContractAuthEntry>)
All direct calls that the current contract performs are always considered authorized. This is only needed to authorize deeper calls that originate from the next contract call. Example: 
env.authorize_as_current_contract(auth_entries);

​
Test Utilities

​
register()

Register a contract with the Env for testing. 
pub fn register<'a, C, A>(&self, contract: C, constructor_args: A) -> Address
where
    C: Register,
    A: ConstructorArgs
Example: 
let contract_id = env.register(Contract, ());

​
register_at()

Register a contract at a specific address. 
pub fn register_at<C, A>(
    &self,
    contract_id: &Address,
    contract: C,
    constructor_args: A,
) -> Address
where
    C: Register,
    A: ConstructorArgs
Example: 
let contract_id = Address::generate(&env);
env.register_at(&contract_id, Contract, ());

​
mock_all_auths()

Mock all calls to Address::require_auth() and Address::require_auth_for_args(), having them succeed as if authorization was provided. 
pub fn mock_all_auths(&self)
Example: 
env.mock_all_auths();
client.transfer(&from, &to, &1000);

​
auths()

Returns a list of authorization trees that were seen during the last contract invocation. 
pub fn auths(&self) -> std::vec::Vec<(Address, AuthorizedInvocation)>
Example: 
let auths = env.auths();
assert_eq!(auths.len(), 1);

​
Error Handling

​
panic_with_error()

Panic with the given error value. 
pub fn panic_with_error(&self, error: impl Into<Error>) -> !
Equivalent to panic!, but with an error value instead of a string. Example: 
if balance < amount {
    env.panic_with_error(Error::InsufficientBalance);
}