Crate soroban_env_common

source ·
Expand description

The environment-common crate contains three families of types:

  • The RawVal type, a 64-bit value type that is a union between several different types (numbers, booleans, symbols, object references), encoded via careful bit-packing.
  • Wrapper types (Object, Symbol, Status, Static, BitSet) that contain RawVal in a specific, known union state. These are also 64-bit values, but offer methods specific to the union state (eg. Symbol will interconvert with Rust strings).
  • The Env trait, which describes the interface between guest and host code. In other words, Env describes a set of host functions that must be implemented in a contract host, and can be called from a guest (or by the SDK). Methods on the Env trait can only pass 64-bit values, which are usually RawVal or one of the wrapper types.

The crate additionally contains functions for interconversion between the RawVal type and XDR types, and re-exports the XDR definitions from stellar_xdr under the module xdr.

Re-exports

pub use stellar_xdr as xdr;

Modules

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.

Structs

BitSet
Wrapper for a RawVal that is tagged with Tag::BitSet, interpreting the RawVal’s body as a small bitset (60-bits or fewer).
ConversionError
Error type indicating a failure to convert some type to another; details of the failed conversion will typically be written to the debug log.
Object
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.
RawVal
A 64-bit value encoding a bit-packed disjoint union between several different types (numbers, booleans, symbols, object handles, etc.)
Static
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.
Status
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
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.
SymbolIter
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, rather than as packed 6-bit codes within a u64. Useful for interoperation with standard Rust string types.
UnimplementedEnv
A dummy implementation of the Env trait that fails with unimplemented!() in all functions. Useful for certain testing scenarios.
Version
VmCaller
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

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

Constants

VERSION

Traits

CheckedEnv
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.
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.
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 CheckedEnv) by the host. It consists of functions that take or return only 64-bit values such as RawVal 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.
FromVal
IntoVal
RawValConvertible
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.
TryFromVal
TryIntoVal
Val
Val is either RawVal or one of the wrapper types, all of which can be AsRef/AsMut’ed to RawVal.
VmCallerCheckedEnv
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

require