Crate soroban_env_guest
source · [−]Expand description
This crate provides the Guest type, the “stub” implementation of the Env interface used for communicating between a contract guest and its host.
It also re-exports all of the content of the soroban_env_common crate for use by guest code. Most of the type and module definitions visible here are actually defined in the common crate.
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.
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.
The Guest is the implementation of the Env interface seen and used by
contracts built into WASM for execution within a WASM VM. It is a 0-sized
“stub” type implementation of the Env interface that forwards each Env
method to an external function, imported from its runtime environment. This
implementation is automatically generated and has no interesting content.
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.
A dummy implementation of the Env trait that fails with
unimplemented!() in
all functions. Useful for certain testing scenarios.Enums
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.
General trait representing a the ability of some object to perform a
(possibly unsuccessful) conversion between two other types.
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.