Trait soroban_env_common::CheckedEnv

source · 
pub trait CheckedEnv {
    type Error: Debug;


Show 92 methods    fn escalate_error_to_panic(&self, e: Self::Error) -> !;
    fn log_value(&self, v: RawVal) -> Result<RawVal, Self::Error>;
    fn get_invoking_contract(&self) -> Result<Object, Self::Error>;
    fn obj_cmp(&self, a: RawVal, b: RawVal) -> Result<i64, Self::Error>;
    fn contract_event(
        &self,
        topics: Object,
        data: RawVal
    ) -> Result<RawVal, Self::Error>;
    fn get_current_contract(&self) -> Result<Object, Self::Error>;
    fn get_ledger_version(&self) -> Result<RawVal, Self::Error>;
    fn get_ledger_sequence(&self) -> Result<RawVal, Self::Error>;
    fn get_ledger_timestamp(&self) -> Result<Object, Self::Error>;
    fn get_ledger_network_passphrase(&self) -> Result<Object, Self::Error>;
    fn get_current_call_stack(&self) -> Result<Object, Self::Error>;
    fn fail_with_status(&self, status: Status) -> Result<RawVal, Self::Error>;
    fn log_fmt_values(
        &self,
        fmt: Object,
        args: Object
    ) -> Result<RawVal, Self::Error>;
    fn get_invoker_type(&self) -> Result<u64, Self::Error>;
    fn get_invoking_account(&self) -> Result<Object, Self::Error>;
    fn get_ledger_network_id(&self) -> Result<Object, Self::Error>;
    fn obj_from_u64(&self, v: u64) -> Result<Object, Self::Error>;
    fn obj_to_u64(&self, obj: Object) -> Result<u64, Self::Error>;
    fn obj_from_i64(&self, v: i64) -> Result<Object, Self::Error>;
    fn obj_to_i64(&self, obj: Object) -> Result<i64, Self::Error>;
    fn obj_from_u128_pieces(
        &self,
        lo: u64,
        hi: u64
    ) -> Result<Object, Self::Error>;
    fn obj_to_u128_lo64(&self, obj: Object) -> Result<u64, Self::Error>;
    fn obj_to_u128_hi64(&self, obj: Object) -> Result<u64, Self::Error>;
    fn obj_from_i128_pieces(
        &self,
        lo: u64,
        hi: u64
    ) -> Result<Object, Self::Error>;
    fn obj_to_i128_lo64(&self, obj: Object) -> Result<u64, Self::Error>;
    fn obj_to_i128_hi64(&self, obj: Object) -> Result<u64, Self::Error>;
    fn map_new(&self) -> Result<Object, Self::Error>;
    fn map_put(
        &self,
        m: Object,
        k: RawVal,
        v: RawVal
    ) -> Result<Object, Self::Error>;
    fn map_get(&self, m: Object, k: RawVal) -> Result<RawVal, Self::Error>;
    fn map_del(&self, m: Object, k: RawVal) -> Result<Object, Self::Error>;
    fn map_len(&self, m: Object) -> Result<RawVal, Self::Error>;
    fn map_has(&self, m: Object, k: RawVal) -> Result<RawVal, Self::Error>;
    fn map_prev_key(&self, m: Object, k: RawVal) -> Result<RawVal, Self::Error>;
    fn map_next_key(&self, m: Object, k: RawVal) -> Result<RawVal, Self::Error>;
    fn map_min_key(&self, m: Object) -> Result<RawVal, Self::Error>;
    fn map_max_key(&self, m: Object) -> Result<RawVal, Self::Error>;
    fn map_keys(&self, m: Object) -> Result<Object, Self::Error>;
    fn map_values(&self, m: Object) -> Result<Object, Self::Error>;
    fn vec_new(&self, c: RawVal) -> Result<Object, Self::Error>;
    fn vec_put(
        &self,
        v: Object,
        i: RawVal,
        x: RawVal
    ) -> Result<Object, Self::Error>;
    fn vec_get(&self, v: Object, i: RawVal) -> Result<RawVal, Self::Error>;
    fn vec_del(&self, v: Object, i: RawVal) -> Result<Object, Self::Error>;
    fn vec_len(&self, v: Object) -> Result<RawVal, Self::Error>;
    fn vec_push_front(&self, v: Object, x: RawVal) -> Result<Object, Self::Error>;
    fn vec_pop_front(&self, v: Object) -> Result<Object, Self::Error>;
    fn vec_push_back(&self, v: Object, x: RawVal) -> Result<Object, Self::Error>;
    fn vec_pop_back(&self, v: Object) -> Result<Object, Self::Error>;
    fn vec_front(&self, v: Object) -> Result<RawVal, Self::Error>;
    fn vec_back(&self, v: Object) -> Result<RawVal, Self::Error>;
    fn vec_insert(
        &self,
        v: Object,
        i: RawVal,
        x: RawVal
    ) -> Result<Object, Self::Error>;
    fn vec_append(&self, v1: Object, v2: Object) -> Result<Object, Self::Error>;
    fn vec_slice(
        &self,
        v: Object,
        start: RawVal,
        end: RawVal
    ) -> Result<Object, Self::Error>;
    fn vec_first_index_of(
        &self,
        v: Object,
        x: RawVal
    ) -> Result<RawVal, Self::Error>;
    fn vec_last_index_of(
        &self,
        v: Object,
        x: RawVal
    ) -> Result<RawVal, Self::Error>;
    fn vec_binary_search(&self, v: Object, x: RawVal) -> Result<u64, Self::Error>;
    fn put_contract_data(
        &self,
        k: RawVal,
        v: RawVal
    ) -> Result<RawVal, Self::Error>;
    fn has_contract_data(&self, k: RawVal) -> Result<RawVal, Self::Error>;
    fn get_contract_data(&self, k: RawVal) -> Result<RawVal, Self::Error>;
    fn del_contract_data(&self, k: RawVal) -> Result<RawVal, Self::Error>;
    fn create_contract_from_contract(
        &self,
        wasm_hash: Object,
        salt: Object
    ) -> Result<Object, Self::Error>;
    fn create_token_from_contract(
        &self,
        salt: Object
    ) -> Result<Object, Self::Error>;
    fn call(
        &self,
        contract: Object,
        func: Symbol,
        args: Object
    ) -> Result<RawVal, Self::Error>;
    fn try_call(
        &self,
        contract: Object,
        func: Symbol,
        args: Object
    ) -> Result<RawVal, Self::Error>;
    fn serialize_to_bytes(&self, v: RawVal) -> Result<Object, Self::Error>;
    fn deserialize_from_bytes(&self, b: Object) -> Result<RawVal, Self::Error>;
    fn bytes_copy_to_linear_memory(
        &self,
        b: Object,
        b_pos: RawVal,
        lm_pos: RawVal,
        len: RawVal
    ) -> Result<RawVal, Self::Error>;
    fn bytes_copy_from_linear_memory(
        &self,
        b: Object,
        b_pos: RawVal,
        lm_pos: RawVal,
        len: RawVal
    ) -> Result<Object, Self::Error>;
    fn bytes_new_from_linear_memory(
        &self,
        lm_pos: RawVal,
        len: RawVal
    ) -> Result<Object, Self::Error>;
    fn bytes_new(&self) -> Result<Object, Self::Error>;
    fn bytes_put(
        &self,
        b: Object,
        i: RawVal,
        u: RawVal
    ) -> Result<Object, Self::Error>;
    fn bytes_get(&self, b: Object, i: RawVal) -> Result<RawVal, Self::Error>;
    fn bytes_del(&self, b: Object, i: RawVal) -> Result<Object, Self::Error>;
    fn bytes_len(&self, b: Object) -> Result<RawVal, Self::Error>;
    fn bytes_push(&self, b: Object, u: RawVal) -> Result<Object, Self::Error>;
    fn bytes_pop(&self, b: Object) -> Result<Object, Self::Error>;
    fn bytes_front(&self, b: Object) -> Result<RawVal, Self::Error>;
    fn bytes_back(&self, b: Object) -> Result<RawVal, Self::Error>;
    fn bytes_insert(
        &self,
        b: Object,
        i: RawVal,
        u: RawVal
    ) -> Result<Object, Self::Error>;
    fn bytes_append(&self, b1: Object, b2: Object) -> Result<Object, Self::Error>;
    fn bytes_slice(
        &self,
        b: Object,
        start: RawVal,
        end: RawVal
    ) -> Result<Object, Self::Error>;
    fn hash_from_bytes(&self, x: Object) -> Result<Object, Self::Error>;
    fn hash_to_bytes(&self, x: Object) -> Result<Object, Self::Error>;
    fn public_key_from_bytes(&self, x: Object) -> Result<Object, Self::Error>;
    fn public_key_to_bytes(&self, x: Object) -> Result<Object, Self::Error>;
    fn compute_hash_sha256(&self, x: Object) -> Result<Object, Self::Error>;
    fn verify_sig_ed25519(
        &self,
        x: Object,
        k: Object,
        s: Object
    ) -> Result<RawVal, Self::Error>;
    fn account_get_low_threshold(&self, a: Object) -> Result<RawVal, Self::Error>;
    fn account_get_medium_threshold(
        &self,
        a: Object
    ) -> Result<RawVal, Self::Error>;
    fn account_get_high_threshold(
        &self,
        a: Object
    ) -> Result<RawVal, Self::Error>;
    fn account_get_signer_weight(
        &self,
        a: Object,
        s: Object
    ) -> Result<RawVal, Self::Error>;
    fn account_exists(&self, a: Object) -> Result<RawVal, Self::Error>;
    fn dummy0(&self) -> Result<RawVal, Self::Error>;

}
Expand description

This trait is a variant of the Env trait used to define the interface implemented by Host. The WASM VM dispatch functions call methods on CheckedEnv and convert any Result::Err(...) return value into a VM trap, halting VM execution.

There is also a blanket impl<T:CheckedEnv> Env for T that implements the Env interface directly for CheckedEnv by unwrapping all results, in other words “panicking on error”. This is used in local testing mode to adapt the Host to mimic the (non-Result, halt-on-error) interface and behavior of Guest when linking a contract to Host natively, for local testing.

Required Associated Types§

Required Methods§

Get the contractID Bytes of the contract which invoked the running contract. Traps if the running contract was not invoked by a contract.

Records a contract event. topics is expected to be a SCVec with length <= 4 that cannot contain Vec, Map, or Bytes with length > 32 On success, returns an SCStatus::Ok.

Get the contractID Bytes of the contract which invoked the running contract. Traps if the running contract was not invoked by a contract.

Return the protocol version of the current ledger as a u32.

Return the sequence number of the current ledger as a u32.

Return the timestamp number of the current ledger as a u64.

Return the network passphrase of the current ledger as Bytes.

Returns the full call stack from the first contract call to the current one as a vector of vectors, where the inside vector contains the contract id as Hash, and a function as a Symbol.

Causes the currently executing contract to fail immediately with a provided status code, which must be of error-type ScStatusType::ContractError. Does not actually return.

Get whether the contract invocation is from an account or another contract. Returns 0 for account, 1 for contract.

Get the AccountID object type of the account which invoked the running contract. Traps if the running contract was not invoked by an account.

Return the network id (sha256 hash of network passphrase) of the current ledger as Bytes. The value is always 32 bytes in length.

Convert a u64 to an object containing a u64.

Convert an object containing a i64 to a u64.

Convert an i64 to an object containing an i64.

Convert an object containing an i64 to an i64.

Convert the low and high 64-bit words of a u128 to an object containing a u128.

Extract the low 64 bits from an object containing a u128.

Extract the high 64 bits from an object containing a u128.

Convert the lo and hi 64-bit words of an i128 to an object containing an i128.

Extract the low 64 bits from an object containing an i128.

Extract the high 64 bits from an object containing an i128.

Create an empty new map.

Insert a key/value mapping into an existing map, and return the map object handle. If the map already has a mapping for the given key, the previous value is overwritten.

Get the value for a key from a map. Traps if key is not found.

Remove a key/value mapping from a map if it exists, traps if doesn’t.

Get the size of a map.

Test for the presence of a key in a map. Returns (SCStatic) TRUE/FALSE.

Given a key, find the first key less than itself in the map’s sorted order. If such a key does not exist, return an SCStatus containing the error code (TBD).

Given a key, find the first key greater than itself in the map’s sorted order. If such a key does not exist, return an SCStatus containing the error code (TBD).

Find the minimum key from a map. If the map is empty, return an SCStatus containing the error code (TBD).

Find the maximum key from a map. If the map is empty, return an SCStatus containing the error code (TBD).

Return a new vector containing all the keys in a map. The new vector is ordered in the original map’s key-sorted order.

Return a new vector containing all the values in a map. The new vector is ordered in the original map’s key-sorted order.

Creates a new vector with an optional capacity hint c. If c is ScStatic::Void, no hint is assumed and the new vector is empty. Otherwise, c is parsed as an u32 that represents the initial capacity of the new vector.

Update the value at index i in the vector. Return the new vector. Trap if the index is out of bounds.

Returns the element at index i of the vector. Traps if the index is out of bound.

Delete an element in a vector at index i, shifting all elements after it to the left. Return the new vector. Traps if the index is out of bound.

Returns length of the vector.

Push a value to the front of a vector.

Removes the first element from the vector and returns the new vector. Traps if original vector is empty.

Appends an element to the back of the vector.

Removes the last element from the vector and returns the new vector. Traps if original vector is empty.

Return the first element in the vector. Traps if the vector is empty

Return the last element in the vector. Traps if the vector is empty

Inserts an element at index i within the vector, shifting all elements after it to the right. Traps if the index is out of bound

Clone the vector v1, then moves all the elements of vector v2 into it. Return the new vector. Traps if number of elements in the vector overflows a u32.

Copy the elements from start index until end index, exclusive, in the vector and create a new vector from it. Return the new vector. Traps if the index is out of bound.

Get the index of the first occurrence of a given element in the vector. Returns the u32 index of the value if it’s there. Otherwise, it returns ScStatic::Void.

Get the index of the last occurrence of a given element in the vector. Returns the u32 index of the value if it’s there. Otherwise, it returns ScStatic::Void.

Binary search a sorted vector for a given element. If it exists, the high-32 bits of the return value is 0x0001 and the low-32 bits contain the u32 index of the element. If it does not exist, the high-32 bits of the return value is 0x0000 and the low-32 bits contain the u32 index at which the element would need to be inserted into the vector to maintain sorted order.

Deploys a contract from the current contract. wasm_hash must be a hash of the contract code that has already been installed on this network. salt is used to create a unique contract id.

Deploys a built-in token contract from the current contract. salt is used to create a unique contract id for the token.

Calls a function in another contract with arguments contained in vector args. If the call is successful, forwards the result of the called function. Traps otherwise.

Calls a function in another contract with arguments contained in vector args. Returns:

  • if successful, result of the called function.
  • otherwise, an SCStatus containing the error status code.

Serializes an (SC)Val into XDR opaque Bytes object.

Deserialize a Bytes object to get back the (SC)Val.

Copies a slice of bytes from a Bytes object specified at offset b_pos with length len into the linear memory at position lm_pos. Traps if either the Bytes object or the linear memory doesn’t have enough bytes.

Copies a segment of the linear memory specified at position lm_pos with length len, into a Bytes object at offset b_pos. The Bytes object may grow in size to accommodate the new bytes. Traps if the linear memory doesn’t have enough bytes.

Constructs a new Bytes object initialized with bytes copied from a linear memory slice specified at position lm_pos with length len.

Create an empty new Bytes object.

Update the value at index i in the Bytes object. Return the new Bytes. Trap if the index is out of bounds.

Returns the element at index i of the Bytes object. Traps if the index is out of bound.

Delete an element in a Bytes object at index i, shifting all elements after it to the left. Return the new Bytes. Traps if the index is out of bound.

Returns length of the Bytes object.

Appends an element to the back of the Bytes object.

Removes the last element from the Bytes object and returns the new Bytes. Traps if original Bytes is empty.

Return the first element in the Bytes object. Traps if the Bytes is empty

Return the last element in the Bytes object. Traps if the Bytes is empty

Inserts an element at index i within the Bytes object, shifting all elements after it to the right. Traps if the index is out of bound

Clone the Bytes object b1, then moves all the elements of Bytes object b2 into it. Return the new Bytes. Traps if its length overflows a u32.

Copies the elements from start index until end index, exclusive, in the Bytes object and creates a new Bytes from it. Returns the new Bytes. Traps if the index is out of bound.

Get the low threshold for the account with ID a (a is AccountId). Traps if no such account exists.

Get the medium threshold for the account with ID a (a is AccountId). Traps if no such account exists.

Get the high threshold for the account with ID a (a is AccountId). Traps if no such account exists.

Get the signer weight for the signer with ed25519 public key s (s is Bytes) on the account with ID a (a is AccountId). Returns the master weight if the signer is the master, and returns 0 if no such signer exists. Traps if no such account exists.

Given an ID a (a is AccountId) of an account, check if it exists. Returns (SCStatic) TRUE/FALSE.

A dummy function taking 0 arguments and performs no-op. This function is for test purpose only, for measuring the roundtrip cost of invoking a host function, i.e. host->Vm->host.

Implementors§