Struct soroban_env_host::Host

pub struct Host(_);

Implementations

impl Host

pub fn err<T>(&self, src: T) -> HostError where
    DebugError: From<T>, 

Records a debug-event from its input in as much detail as possible, then converts its input to a (often coarser-granularity) Status code, and then forms a HostError with it (which also captures a backtrace::Backtrace). This is the method you want to call any time there’s a finer-granularity error type that you want to log the details of and then downgrade fail with.

pub fn err_status<T>(&self, status: T) -> HostError where
    Status: From<T>, 

Helper for the simplest status-only error path.

pub fn err_general(&self, msg: &'static str) -> HostError

Helper for the simplest string + general-error path.

pub fn err_status_msg<T>(&self, status: T, msg: &'static str) -> HostError where
    Status: From<T>, 

Helper for the next-simplest status-and-extended-debug-message error path.

pub fn err_conversion_into_rawval<T>(&self, rv: RawVal) -> HostError

pub fn err_conversion_general(&self, msg: &'static str) -> HostError

pub fn map_err<T, E>(&self, res: Result<T, E>) -> Result<T, HostError> where
    DebugError: From<E>, 

Given a result carrying some error type that can be converted to a DebugError, calls self.err with it when there’s an error. Returns a result over HostError.

If you have an error type T you want to record as a detailed debug event and a less-detailed Status code embedded in a HostError, add an impl From<T> for DebugError over in the events module and call this where the error is generated.

Note: we do not want to impl From<T> for HostError for such types, as doing so will avoid routing them through the host in order to record their extended diagnostic information into the debug buffer. This means you will wind up writing host.map_err(...)? a bunch in code that you used to be able to get away with just writing ...?, there’s no way around this if we want to record the diagnostic information.

impl Host

pub fn with_storage(storage: Storage) -> Self

Constructs a new Host that will use the provided Storage for contract-data access functions such as CheckedEnv::get_contract_data.

pub fn get_budget_mut<T, F>(&self, f: F) -> T where
    F: FnOnce(&mut Budget) -> T, 

Helper for mutating the Budget held in this Host, either to allocate it on contract creation or to deplete it on callbacks from the VM or host functions.

pub fn get_budget<T, F>(&self, f: F) -> T where
    F: FnOnce(&Budget) -> T, 

pub fn charge_budget(&self, ty: CostType, input: u64) -> Result<(), HostError>

pub fn debug_event<T>(&self, src: T) -> Result<(), HostError> where
    DebugEvent: From<T>, 

Records a debug event. This in itself is not necessarily an error; it might just be some contextual event we want to put in a debug log for diagnostic purpopses. The return value from this is therefore () when the event is recorded successfully, even if the event itself represented some other error. This function only returns Err(…) when there was a failure to record the event, such as when budget is exceeded.

pub fn recover_storage(self) -> Result<Storage, Self>

pub fn inject_val(&self, v: &ScVal) -> Result<RawVal, HostError>

pub fn get_events(&self) -> Events

pub fn invoke_function_raw(
    &self,
    hf: HostFunction,
    args: ScVec
) -> Result<RawVal, HostError>

pub fn invoke_function(
    &self,
    hf: HostFunction,
    args: ScVec
) -> Result<ScVal, HostError>

pub fn register_test_contract(
    &self,
    contract_id: Object,
    contract_fns: Rc<dyn ContractFunctionSet>
) -> Result<(), HostError>

Trait Implementations

impl CheckedEnv for Host

type Error = HostError

fn log_value(&self, v: RawVal) -> Result<RawVal, HostError>

fn get_invoking_contract(&self) -> Result<Object, HostError>

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

fn obj_cmp(&self, a: RawVal, b: RawVal) -> Result<i64, HostError>

fn contract_event(&self, v: RawVal) -> Result<RawVal, HostError>

fn system_event(&self, v: RawVal) -> Result<RawVal, HostError>

fn get_current_contract(&self) -> Result<Object, HostError>

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

fn obj_from_u64(&self, u: u64) -> Result<Object, HostError>

fn obj_to_u64(&self, obj: Object) -> Result<u64, HostError>

fn obj_from_i64(&self, i: i64) -> Result<Object, HostError>

Convert an i64 to an object containing an i64.

fn obj_to_i64(&self, obj: Object) -> Result<i64, HostError>

Convert an object containing an i64 to an i64.

fn map_new(&self) -> Result<Object, HostError>

Create an empty new map.

fn map_put(&self, m: Object, k: RawVal, v: RawVal) -> Result<Object, HostError>

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.

fn map_get(&self, m: Object, k: RawVal) -> Result<RawVal, HostError>

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

fn map_del(&self, m: Object, k: RawVal) -> Result<Object, HostError>

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

fn map_len(&self, m: Object) -> Result<RawVal, HostError>

Get the size of a map.

fn map_has(&self, m: Object, k: RawVal) -> Result<RawVal, HostError>

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

fn map_prev_key(&self, m: Object, k: RawVal) -> Result<RawVal, HostError>

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).

fn map_next_key(&self, m: Object, k: RawVal) -> Result<RawVal, HostError>

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).

fn map_min_key(&self, m: Object) -> Result<RawVal, HostError>

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

fn map_max_key(&self, m: Object) -> Result<RawVal, HostError>

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

fn map_keys(&self, m: Object) -> Result<Object, HostError>

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

fn map_values(&self, m: Object) -> Result<Object, HostError>

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

fn vec_new(&self, c: RawVal) -> Result<Object, HostError>

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.

fn vec_put(&self, v: Object, i: RawVal, x: RawVal) -> Result<Object, HostError>

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

fn vec_get(&self, v: Object, i: RawVal) -> Result<RawVal, HostError>

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

fn vec_del(&self, v: Object, i: RawVal) -> Result<Object, HostError>

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.

fn vec_len(&self, v: Object) -> Result<RawVal, HostError>

Returns length of the vector.

fn vec_push(&self, v: Object, x: RawVal) -> Result<Object, HostError>

Appends an element to the back of the vector.

fn vec_pop(&self, v: Object) -> Result<Object, HostError>

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

fn vec_front(&self, v: Object) -> Result<RawVal, HostError>

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

fn vec_back(&self, v: Object) -> Result<RawVal, HostError>

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

fn vec_insert(&self, v: Object, i: RawVal, x: RawVal) -> Result<Object, HostError>

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

fn vec_append(&self, v1: Object, v2: Object) -> Result<Object, HostError>

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.

fn vec_slice(
    &self,
    v: Object,
    start: RawVal,
    end: RawVal
) -> Result<Object, HostError>

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.

fn put_contract_data(&self, k: RawVal, v: RawVal) -> Result<RawVal, HostError>

fn has_contract_data(&self, k: RawVal) -> Result<RawVal, HostError>

fn get_contract_data(&self, k: RawVal) -> Result<RawVal, HostError>

fn del_contract_data(&self, k: RawVal) -> Result<RawVal, HostError>

fn create_contract_from_ed25519(
    &self,
    v: Object,
    salt: Object,
    key: Object,
    sig: Object
) -> Result<Object, HostError>

fn create_contract_from_contract(
    &self,
    v: Object,
    salt: Object
) -> Result<Object, HostError>

fn call(
    &self,
    contract: Object,
    func: Symbol,
    args: Object
) -> Result<RawVal, HostError>

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.

fn try_call(
    &self,
    contract: Object,
    func: Symbol,
    args: Object
) -> Result<RawVal, HostError>

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

fn bigint_from_u64(&self, x: u64) -> Result<Object, HostError>

Constructs a BigInt from an u64.

fn bigint_to_u64(&self, x: Object) -> Result<u64, HostError>

Converts a BigInt to an u64. Traps if the value cannot fit into u64.

fn bigint_from_i64(&self, x: i64) -> Result<Object, HostError>

Constructs a BigInt from an i64.

fn bigint_to_i64(&self, x: Object) -> Result<i64, HostError>

Converts a BigInt to an i64. Traps if the value cannot fit into i64.

fn bigint_add(&self, x: Object, y: Object) -> Result<Object, HostError>

Performs the + operation.

fn bigint_sub(&self, x: Object, y: Object) -> Result<Object, HostError>

Performs the - operation.

fn bigint_mul(&self, x: Object, y: Object) -> Result<Object, HostError>

Performs the * operation.

fn bigint_div(&self, x: Object, y: Object) -> Result<Object, HostError>

Performs the / operation. Traps if y is zero.

fn bigint_rem(&self, x: Object, y: Object) -> Result<Object, HostError>

Performs the % operation. Traps if y is zero.

fn bigint_and(&self, x: Object, y: Object) -> Result<Object, HostError>

Performs the & operation.

fn bigint_or(&self, x: Object, y: Object) -> Result<Object, HostError>

Performs the | operation.

fn bigint_xor(&self, x: Object, y: Object) -> Result<Object, HostError>

Performs the ^ operation.

fn bigint_shl(&self, x: Object, y: Object) -> Result<Object, HostError>

Performs the << operation. Traps if y is negative or larger than the size of u64.

fn bigint_shr(&self, x: Object, y: Object) -> Result<Object, HostError>

Performs the >> operation. Traps if y is negative or larger than the size of u64.

fn bigint_cmp(&self, x: Object, y: Object) -> Result<RawVal, HostError>

Returns an ordering between x and y: -1 (less), 0 (equal) or 1 (greater).

fn bigint_is_zero(&self, x: Object) -> Result<RawVal, HostError>

Returns true if x is equal to the additive identity.

fn bigint_neg(&self, x: Object) -> Result<Object, HostError>

Performs the unary - operation.

fn bigint_not(&self, x: Object) -> Result<Object, HostError>

Performs the unary ! operation.

fn bigint_gcd(&self, x: Object, y: Object) -> Result<Object, HostError>

Calculates the Greatest Common Divisor (GCD) of x and y.

fn bigint_lcm(&self, x: Object, y: Object) -> Result<Object, HostError>

Calculates the Lowest Common Multiple (LCM) of x and y.

fn bigint_pow(&self, x: Object, y: Object) -> Result<Object, HostError>

Calculates x to the power y. Traps if y is negative or larger than the size of u64.

fn bigint_pow_mod(
    &self,
    p: Object,
    q: Object,
    m: Object
) -> Result<Object, HostError>

Calculates (p ^ q) mod m. Note that this rounds like mod_floor, not like the % operator, which makes a difference when given a negative p or m. The result will be in the interval [0, m) for m > 0, or in the interval (m, 0] for m < 0. Traps if the q is negative or the m is zero.

fn bigint_sqrt(&self, x: Object) -> Result<Object, HostError>

Calculates the truncated principal square root of x. Traps if x is negative.

fn bigint_bits(&self, x: Object) -> Result<u64, HostError>

Determines the fewest bits necessary to express x, not including the sign.

fn bigint_to_bytes_be(&self, x: Object) -> Result<Object, Self::Error>

Outputs the BigInt’s magnitude in big-endian byte order into a binary array. The sign is dropped.

fn bigint_to_radix_be(
    &self,
    x: Object,
    radix: RawVal
) -> Result<Object, Self::Error>

Outputs the BigInt’s magnitude in the requested base in big-endian digit order into a binary array. The sign is dropped. Radix must be in the range 2…256.

fn serialize_to_binary(&self, v: RawVal) -> Result<Object, HostError>

Serializes an (SC)Val into XDR opaque binary array.

fn deserialize_from_binary(&self, b: Object) -> Result<RawVal, HostError>

Deserialize a binary array to get back the (SC)Val.

fn binary_copy_to_linear_memory(
    &self,
    b: Object,
    b_pos: RawVal,
    lm_pos: RawVal,
    len: RawVal
) -> Result<RawVal, HostError>

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

fn binary_copy_from_linear_memory(
    &self,
    b: Object,
    b_pos: RawVal,
    lm_pos: RawVal,
    len: RawVal
) -> Result<Object, HostError>

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

fn binary_new_from_linear_memory(
    &self,
    lm_pos: RawVal,
    len: RawVal
) -> Result<Object, HostError>

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

fn binary_new(&self) -> Result<Object, HostError>

Create an empty new binary.

fn binary_put(&self, b: Object, i: RawVal, u: RawVal) -> Result<Object, HostError>

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

fn binary_get(&self, b: Object, i: RawVal) -> Result<RawVal, HostError>

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

fn binary_del(&self, b: Object, i: RawVal) -> Result<Object, HostError>

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

fn binary_len(&self, b: Object) -> Result<RawVal, HostError>

Returns length of the binary.

fn binary_push(&self, b: Object, u: RawVal) -> Result<Object, HostError>

Appends an element to the back of the binary.

fn binary_pop(&self, b: Object) -> Result<Object, HostError>

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

fn binary_front(&self, b: Object) -> Result<RawVal, HostError>

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

fn binary_back(&self, b: Object) -> Result<RawVal, HostError>

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

fn binary_insert(
    &self,
    b: Object,
    i: RawVal,
    u: RawVal
) -> Result<Object, HostError>

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

fn binary_append(&self, b1: Object, b2: Object) -> Result<Object, HostError>

Clone the binary b1, then moves all the elements of binary b2 into it. Return the new binary. Traps if number of elements in the binary overflows a u32.

fn binary_slice(
    &self,
    b: Object,
    start: RawVal,
    end: RawVal
) -> Result<Object, HostError>

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

fn hash_from_binary(&self, x: Object) -> Result<Object, HostError>

fn hash_to_binary(&self, x: Object) -> Result<Object, HostError>

fn public_key_from_binary(&self, x: Object) -> Result<Object, HostError>

fn public_key_to_binary(&self, x: Object) -> Result<Object, HostError>

fn compute_hash_sha256(&self, x: Object) -> Result<Object, HostError>

fn verify_sig_ed25519(
    &self,
    x: Object,
    k: Object,
    s: Object
) -> Result<RawVal, HostError>

fn account_get_low_threshold(&self, a: Object) -> Result<RawVal, Self::Error>

Get the low threshold for the account with ed25519 public key a (a is binary). Traps if no such account exists.

fn account_get_medium_threshold(&self, a: Object) -> Result<RawVal, Self::Error>

Get the medium threshold for the account with ed25519 public key a (a is binary). Traps if no such account exists.

fn account_get_high_threshold(&self, a: Object) -> Result<RawVal, Self::Error>

Get the high threshold for the account with ed25519 public key a (a is binary). Traps if no such account exists.

fn account_get_signer_weight(
    &self,
    a: Object,
    s: Object
) -> Result<RawVal, Self::Error>

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

impl Clone for Host

fn clone(&self) -> Host

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Host

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

Formats the value using the given formatter.

impl Default for Host

fn default() -> Host

Returns the “default value” for a type.

impl EnvBase for Host

fn as_mut_any(&mut self) -> &mut dyn Any

Used for recovering the concrete type of the Host.

fn check_same_env(&self, other: &Self)

Used to check two environments are the same, trapping if not.

fn deep_clone(&self) -> Self

Used to clone an environment deeply, not just a handle to it.

fn binary_copy_from_slice(&self, b: Object, b_pos: RawVal, mem: &[u8]) -> Object

Copy a slice of bytes from the caller’s memory into an existing Binary object the host, returning a new Binary.

fn binary_copy_to_slice(&self, b: Object, b_pos: RawVal, mem: &mut [u8])

Copy a slice of bytes from a Binary in the host into the caller’s memory.

fn binary_new_from_slice(&self, mem: &[u8]) -> Object

For a new Binary in the host from a slice of memory in the caller.

fn log_static_fmt_val(&self, fmt: &'static str, v: RawVal)

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and a single RawVal argument that will be inserted at the marker in the format string.

fn log_static_fmt_static_str(&self, fmt: &'static str, s: &'static str)

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and a single string-slice argument that will be inserted at the marker in the format string.

fn log_static_fmt_val_static_str(
    &self,
    fmt: &'static str,
    v: RawVal,
    s: &'static str
)

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and both a RawVal and a string-slice argument, that will each be inserted at markers in the format string.

fn log_static_fmt_general(
    &self,
    fmt: &'static str,
    vals: &[RawVal],
    strs: &[&'static str]
)

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and both a slice of RawVals and a slice of string-slice argument, that will be sequentially inserted at markers in the format string.

impl Externals for Host

fn invoke_index(
    &mut self,
    index: usize,
    args: RuntimeArgs<'_>
) -> Result<Option<RuntimeValue>, Trap>

Perform invoke of a host function by specified index.

fn max_insn_step(&self) -> u64

The maximum number of instructions to run between calls to charge_cpu.

fn charge_cpu(&mut self, insns: u64) -> Result<(), TrapCode>

Charge the externals for a given block of instructions having executed.

fn charge_mem(&mut self, bytes: u64) -> Result<(), TrapCode>

Charge the externals for a given amount of linear memory being allocated.

impl ImportResolver for Host

fn resolve_func(
    &self,
    module_name: &str,
    field_name: &str,
    signature: &Signature
) -> Result<FuncRef, Error>

Resolve a function.

fn resolve_global(
    &self,
    module_name: &str,
    field_name: &str,
    _descriptor: &GlobalDescriptor
) -> Result<GlobalRef, Error>

Resolve a global variable.

fn resolve_memory(
    &self,
    module_name: &str,
    field_name: &str,
    _descriptor: &MemoryDescriptor
) -> Result<MemoryRef, Error>

Resolve a memory.

fn resolve_table(
    &self,
    module_name: &str,
    field_name: &str,
    _descriptor: &TableDescriptor
) -> Result<TableRef, Error>

Resolve a table.

impl TryConvert<&Object, ScObject> for Host

type Error = HostError

fn convert(&self, ob: &Object) -> Result<ScObject, Self::Error>

impl TryConvert<&ScObject, Object> for Host

type Error = HostError

fn convert(&self, ob: &ScObject) -> Result<Object, Self::Error>

impl TryConvert<Object, ScObject> for Host

type Error = HostError

fn convert(&self, ob: Object) -> Result<ScObject, Self::Error>

impl TryConvert<ScObject, Object> for Host

type Error = HostError

fn convert(&self, ob: ScObject) -> Result<Object, Self::Error>