#val #environment #env #object #host #interface #contract

no-std soroban-env-common

Soroban contract environment common types and functionality

25 releases (stable)

new 22.0.0 Nov 6, 2024
21.2.2 Oct 24, 2024
21.2.0 Jul 16, 2024
20.3.0 Mar 15, 2024
0.0.3 Jul 29, 2022

#868 in Magic Beans

Download history 2817/week @ 2024-07-17 2757/week @ 2024-07-24 3417/week @ 2024-07-31 2195/week @ 2024-08-07 2259/week @ 2024-08-14 2726/week @ 2024-08-21 3144/week @ 2024-08-28 2409/week @ 2024-09-04 2083/week @ 2024-09-11 2310/week @ 2024-09-18 2254/week @ 2024-09-25 2613/week @ 2024-10-02 2814/week @ 2024-10-09 1490/week @ 2024-10-16 2656/week @ 2024-10-23 2227/week @ 2024-10-30

9,505 downloads per month
Used in 63 crates (4 directly)

Apache-2.0

195KB
4K SLoC

rs-soroban-env

Rust contract-environment interface and (optional) host implementation for Soroban.

The soroban-env-common crate contains elements of the shared environment-interface between smart contract guest and host: the Env trait that defines the set of available environment functions as well as the Val type that can pass back and forth through the WASM calling convention. Additionally small wrappers around subtypes of Val are included: Object, Symbol, Error, etc.

The soroban-env-guest crate contains the guest-side stub implementation of the environment interface called Guest dependent on extern fns provided by the host implementation. This can be used in a WASM runtime that provides the extern fns.

The soroban-env-host crate contains the host-side full implementation of the environment interface called Host. This can be used either in the real blockchain host, or for local testing in the SDK.


lib.rs:

The environment-common crate contains three families of types:

  • The [Val] 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], [Error]) that contain [Val] 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 string types).
  • 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 [Val] or one of the wrapper types.

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

Dependencies

~6–32MB
~523K SLoC