Crate soroban_env_host

This crate mainly exists to provide the Soroban Host type, which is the implementation of the Env interface between guest contract code and the host it runs within.

This crate also re-exports all of the content of the soroban_env_common crate for use by host (or contract local-testing) code. Most of the type and module definitions visible here are actually defined in the common crate.

When unit-testing contracts natively (not using wasm), developers may also wish to enable the "testutils" feature, which enables an interface on Host for registering other test contracts by ID.

The Host type provides some facilities above and beyond just the Env trait, including:

• The budget module which is responsible for measuring and limiting execution costs in terms of CPU and memory.
• The storage module which is responsible for providing an interface between contracts and their durable storage.

Re-exports

• pub use vm::Vm;
• pub use budget::DEFAULT_HOST_DEPTH_LIMIT;
• pub use budget::DEFAULT_XDR_RW_LIMITS;
• pub use ledger_info::LedgerInfo;

Modules

• auth
  Auth conceptual overview
• budget
• e2e_invoke
• events
• fees
• ledger_info
• meta
  This module contains version constants (and other metadata) that are embedded in binaries (especially WASM binaries) compiled against a particular version of this crate. Versioning at this level provides an early diagnostic check for compatibility between a loaded WASM binary and the Env interface provided by the host, rather than a cryptic failure due to a runtime host function signature mismatch.
• num
• storage
  This module contains the Storage type and its supporting types, which provide the Host with access to durable ledger entries.
• vm
  This module primarily provides the Vm type and the necessary name-lookup and runtime-dispatch mechanisms needed to allow WASM modules to call into the Env interface implemented by Host.
• xdr

Macros

• err
  Helper for building multi-argument errors. For example:
• impl_bignum_host_fns
• impl_bignum_host_fns_rhs_u32
• impl_bls12_381_fr_arith_host_fns
• impl_wrapping_obj_from_num
• impl_wrapping_obj_to_num

Structs

• AddressObject
• Bool
• BytesObject
• ConversionError
  Error type indicating a failure to convert some type to another; details of the failed conversion may be written to the debug log, when possible.
• DurationObject
• DurationSmall
• DurationVal
• Error
  Wrapper for a Val that is tagged with [Tag::Error], interpreting the Val’s body as a pair of a 28-bit error-type code and a 32-bit error code. The error-type codes correspond to the enumerated cases of ScErrorType, and the error codes correspond to the code values stored in each variant of the ScError union.
• Host
• HostError
• I32Val
• I64Object
• I64Small
• I64Val
• I256
  A 256-bit signed integer type.
• I128Object
• I128Small
• I128Val
• I256Object
• I256Small
• I256Val
• MapObject
• MeteredOrdMap
• MeteredVector
• Object
  Wrapper for a Val that is tagged with one of the object types, interpreting the Val’s body as containing a 32-bit handle to a host object.
• ScValObjRef
• ScValObject
  ScValObject (and its reference-based type ScValObjRef) is a small wrapper type that does not have its own XDR definition, it just denotes (as a type) the subset of ScVal values that need to be represented in Val by one of the cases that can be an Object. In other words Val::try_from_val(&v, e).is_object() will be true iff ScValObject::classify(v) is Ok(ScValObject(v)).
• StringObject
• Symbol
• SymbolObject
• SymbolSmall
• SymbolSmallIter
  An iterator that decodes the individual bit-packed characters from a symbol and yields them as regular Rust char values.
• SymbolStr
  An expanded form of a Symbol that stores its characters as ASCII-range bytes in a u8 array – up to the maximum size of a large symbol object – rather than as packed 6-bit codes within a u64. Useful for interoperation with standard Rust string types.
• TimepointObject
• TimepointSmall
• TimepointVal
• U32Val
• U64Object
• U64Small
• U64Val
• U256
  A 256-bit unsigned integer type.
• U128Object
• U128Small
• U128Val
• U256Object
• U256Small
• U256Val
• Val
• VecObject
• Version
• VmCaller
  The VmCallerEnv trait is similar to the Env trait – it provides all the same-named methods – but they have a form that takes an initial VmCaller argument by &mut that may or may-not wrap a wasmi::Caller structure, depending on whether it was invoked from a wasmi host-function wrapper.
• Void

Enums

• ContractInvocationEvent
• DiagnosticLevel
• StorageType
  This is just a distinct enum local to the env interface that is used as an argument to storage functions. It doesn’t correspond to any [Val] types, and is passed by direct marshalling as a u64.
• SymbolError
  Errors related to operations on the SymbolObject and SymbolSmall types.
• Tag
  Code values for the 8 tag bits in the bit-packed representation of Val. These don’t coincide with tag numbers in the SCVal XDR but cover all those cases as well as some optimized refinements for special cases (boolean true and false, small-value forms).

Constants

• SEED_BYTES
• VERSION

Traits

• CheckedEnvArg
  This trait is used by macro-generated dispatch and forwarding functions to check arguments being passed to the Env. The default implementations call through to the Env integrity-checking functions.
• Compare
  General trait representing the ability to compare two values of some type. Similar to core::cmp::Cmp but with two key differences: the comparison is fallible, and is provided by some external type implementing Compare rather than the compared type itself.
• ContractFunctionSet
• Convert
  General trait representing a the ability of some object to perform a (possibly unsuccessful) conversion between two other types.
• Env
  This trait represents the interface between Host and Guest, used by client contract code and implemented (via Env) by the host. It consists of functions that take or return only 64-bit values such as Val or u64.
• EnvBase
  Base trait extended by the Env trait, providing various special-case functions that do not simply call across cross the guest/host interface.
• TryFromVal
  Trait for types that can be fallibly converted to another type V, analogous to the standard Rust type TryFrom, but making use of the provided Env implementation E in order to convert parts of the type that require it. Mainly this exists because Val types that contain object handles need to delegate to the environment to look up and extract the content of those handles.
• TryIntoVal
  The opposite trait to TryFromVal, analogous to the way that TryInto exists as an opposite to TryFrom. Exists only for convenience of doing conversions via .try_into_val(e) or specifying convertability with a bound like TryIntoVal<E,Other>.
• VmCallerEnv
  This trait is a variant of the Env trait used to define the interface implemented by Host. The wasmi VM dispatch functions (in soroban_env_host::dispatch) call methods on VmCallerEnv, passing a VmCaller that wraps the wasmi Caller context, and then convert any Result::Err(...) return value into a VM trap, halting VM execution.
• WasmiMarshal

Type Aliases

• Seed