soroban_env_common/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2//! The environment-common crate contains three families of types:
3//!
4//!   - The [Val] type, a 64-bit value type that is a union between several
5//!     different types (numbers, booleans, symbols, object references), encoded
6//!     via careful bit-packing.
7//!   - Wrapper types ([Object], [Symbol], [Error]) that contain [Val] in a
8//!     specific, known union state. These are also 64-bit values, but offer
9//!     methods specific to the union state (eg. [Symbol] will interconvert with
10//!     Rust string types).
11//!   - The [Env] trait, which describes the _interface_ between guest and host
12//!     code. In other words, `Env` describes a set of _host functions_ that
13//!     must be implemented in a contract host, and can be called from a guest
14//!     (or by the SDK). Methods on the [Env] trait can only pass 64-bit values,
15//!     which are usually [Val] or one of the wrapper types.
16//!
17//! The crate additionally contains functions for interconversion between the
18//! [Val] type and XDR types, and re-exports the XDR definitions from
19//! [stellar_xdr] under the module [xdr].
20
21#[allow(unused_macros)]
22#[cfg(all(not(target_family = "wasm"), feature = "tracy"))]
23macro_rules! tracy_span {
24    () => {
25        tracy_client::span!()
26    };
27    ($name:expr) => {
28        tracy_client::span!($name)
29    };
30}
31
32#[allow(unused_macros)]
33#[cfg(any(target_family = "wasm", not(feature = "tracy")))]
34macro_rules! tracy_span {
35    () => {
36        ()
37    };
38    ($name:expr) => {
39        ()
40    };
41}
42
43#[derive(Clone, Debug, Eq, PartialEq, PartialOrd, Ord, Hash)]
44#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
45pub struct Version<'a> {
46    pub pkg: &'a str,
47    pub rev: &'a str,
48    pub interface: xdr::ScEnvMetaEntryInterfaceVersion,
49    pub xdr: stellar_xdr::Version<'a>,
50}
51
52pub const VERSION: Version = Version {
53    pkg: env!("CARGO_PKG_VERSION"),
54    rev: env!("GIT_REVISION"),
55    interface: meta::INTERFACE_VERSION,
56    xdr: stellar_xdr::VERSION,
57};
58
59mod wrapper_macros;
60
61#[cfg(feature = "testutils")]
62mod arbitrary;
63mod bytes;
64mod compare;
65mod convert;
66mod env;
67mod error;
68
69// mod hash contains "shallow" impls of Hash for `Val` wrappers that are risky
70// to expose in general since they do not "look through" the env to their
71// underlying objects, instead hashing the object references themselves. This is
72// sufficiently dangerous that we guard it behind a specific feature that only
73// an informed consumer should enable.
74#[cfg(any(feature = "testutils", feature = "shallow-val-hash"))]
75mod hash;
76
77mod object;
78mod option;
79mod result;
80mod storage_type;
81mod string;
82mod symbol;
83mod tuple;
84mod val;
85mod vmcaller_env;
86
87// We have some modules that we don't re-export everything
88// from because only specific users are likely to use them.
89pub mod meta;
90pub mod num;
91pub use num::{
92    DurationObject, I128Object, I256Object, I64Object, TimepointObject, U128Object, U256Object,
93    U64Object,
94};
95pub use num::{
96    DurationSmall, I128Small, I256Small, I64Small, TimepointSmall, U128Small, U256Small, U64Small,
97};
98pub use num::{
99    DurationVal, I128Val, I256Val, I32Val, I64Val, TimepointVal, U128Val, U256Val, U32Val, U64Val,
100};
101pub use num::{I256, U256};
102
103pub use storage_type::StorageType;
104
105// Re-export the XDR definitions of a specific version -- curr or next -- of the xdr crate.
106#[cfg(not(feature = "next"))]
107pub use stellar_xdr::curr as xdr;
108#[cfg(feature = "next")]
109pub use stellar_xdr::next as xdr;
110
111// Val is the 64-bit transparent type.
112pub use val::{ConversionError, Tag, Val};
113
114#[cfg(feature = "wasmi")]
115pub use val::WasmiMarshal;
116pub use val::{AddressObject, MapObject, VecObject};
117pub use val::{Bool, Void};
118
119pub use compare::Compare;
120pub use convert::{Convert, TryFromVal, TryIntoVal};
121pub use env::{call_macro_with_all_host_functions, CheckedEnvArg, Env, EnvBase};
122pub use vmcaller_env::{VmCaller, VmCallerEnv};
123
124pub use bytes::BytesObject;
125pub use error::Error;
126pub use object::{Object, ScValObjRef, ScValObject};
127pub use string::StringObject;
128pub use symbol::{Symbol, SymbolError, SymbolObject, SymbolSmall, SymbolSmallIter, SymbolStr};
soroban_env_common/lib.rs

soroban_env_common/
lib.rs
