Crate soroban_env_host

source ·
Expand description

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.

The Host can be configured with or without support for a vm::Vm, depending on the "vm" cargo feature. When enabled, the VM is currently a thin wrapper around the wasmi interpreter, though other VMs might be supported in the future.

It may seem unusual to configure a contract host without a VM, but this configuration makes more sense when considering that Soroban supports a “local testing” configuration where host and guest code are both compiled natively and linked together for a faster and richer debugging and testing experience. When testing this way, 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 im_rc;

Modules

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.
This module contains the Storage type and its supporting types, which provide the Host with access to durable ledger entries.
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.

Macros

Structs

Wrapper for a RawVal that is tagged with Tag::BitSet, interpreting the RawVal’s body as a small bitset (60-bits or fewer).
Error type indicating a failure to convert some type to another; details of the failed conversion will typically be written to the debug log.
Some type of value coupled to a specific instance of Env, which some of the value’s methods may call into to support some conversion and comparison functions.
Wrapper for a RawVal that is tagged with Tag::Object, interpreting the RawVal’s body as a pair of a 28-bit object-type code and a 32-bit handle to a host object of the object-type. The object-type codes correspond to the enumerated cases of ScObject, and the handle values are dynamically assigned by the host as new objects are allocated during execution.
A 64-bit value encoding a bit-packed disjoint union between several different types (numbers, booleans, symbols, object handles, etc.)
Wrapper for a RawVal that is tagged with Tag::Static, interpreting the RawVal’s body as a 32-bit value from a reserved set of “static” values corresponding to the enumerated cases of ScStatic.
Wrapper for a RawVal that is tagged with Tag::Status, interpreting the RawVal’s body as a pair of a 28-bit status-type code and a 32-bit status code. The status-type codes correspond to the enumerated cases of ScStatusType, and the status codes correspond to the code values stored in each variant of the ScStatus union.
Symbol reprents strings up to 10 characters long with a a-zA-Z0-9_ alphabet encoded into a 60-bit space between 10 characters long.
An iterator that decodes the individual bit-packed characters from a symbol and yields them as regular Rust char values.
An expanded form of a Symbol that stores its characters as ASCII-range bytes in a u8 array, rather than as packed 6-bit codes within a u64. Useful for interoperation with standard Rust string types.
A dummy implementation of the Env trait that fails with unimplemented!() in all functions. Useful for certain testing scenarios.
The VmCallerCheckedEnv trait is similar to the CheckedEnv 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.

Enums

Errors related to operations on the BitSet type.
Errors related to operations on the Symbol type.
Code values for the 3 “tag” bits in the bit-packed representation of RawVal.

Traits

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.
This trait represents the interface between Host and Guest, used by client contract code and implemented (via CheckedEnv) by the host. It consists of functions that take or return only 64-bit values such as RawVal or u64.
Base trait extended by the Env trait, providing various special-case functions that do not simply call across cross the guest/host interface.
Trait abstracting over types that can be converted into RawVal, similar to TryFrom but with a different signature that enables generating slightly more efficient conversion code. An implementation of TryFrom<RawVal> is also provided for any type that implements RawValConvertible.
General trait representing a the ability of some object to perform a (possibly unsuccessful) conversion between two other types.
Val is either RawVal or one of the wrapper types, all of which can be AsRef/AsMut’ed to RawVal.
This trait is a variant of the Env trait used to define the interface implemented by Host. The wasmi VM dispatch functions call methods on VmCallerCheckedEnv, passing a VmCaller that wraps the wasmi Caller context, and then convert any Result::Err(...) return value into a VM trap, halting VM execution.

Functions