soroban_env_common/
meta.rs

1//! This module contains version constants (and other metadata) that are
2//! embedded in binaries (especially WASM binaries) compiled against a
3//! particular version of this crate. Versioning at this level provides an early
4//! diagnostic check for compatibility between a loaded WASM binary and the
5//! [Env](crate::Env) interface provided by the host, rather than a cryptic failure
6//! due to a runtime host function signature mismatch.
7
8// Currently the only constant is `INTERFACE_VERSION` which is a struct
9// containing a 32-bit protocol version and 32-bit pre-release version. The
10// pre-release version should be zero any time you make a real release, and the
11// protocol version is the ledger version / protocol version (the two terms are
12// used interchangably in the stellar codebase), which should both match the
13// major release version of soroban and the major release version of
14// stellar-core that it's embedded within.
15//
16// Protocol numbers will be checked for ordered compatibility (a host will only
17// run contracts built for same-or-older protocol versions than its own) whereas
18// pre-release numbers will be checked for _exact_ identity. Any pre-release
19// number is considered incompatible with every other pre-release number,
20// requires recompiling contracts.
21//
22// Any change to the logical interface of a released version of soroban (with a
23// nonzero major version):
24//
25//   - Must be accompanied by a protocol-number increment, so the network
26//     switches behaviour in consensus, and can gate backward-compatibility code
27//     on protocol transitions during replay.
28//
29//   - Should in most cases made in a way that's backward compatible with old
30//     versions, so that an old contract can continue to run on a new host.
31//     Exceptions can be made for intentional breakage such as deprecating bad
32//     functionality or insecure functions, but keep in mind any code that was
33//     exercised in a recorded transaction _must_ stay around at least gated by
34//     protocol so it can replay correctly.
35//
36// When a release goes out, it should have pre-release version zero. During
37// development of a new release, or before the initial release of soroban, a
38// nonzero pre-release number can be used to force recompiles on interface
39// changes.
40
41use crate::xdr::ScEnvMetaEntryInterfaceVersion;
42
43pub const ENV_META_V0_SECTION_NAME: &str = "contractenvmetav0";
44
45// If the "next" feature is enabled, we're building from the "next" xdr
46// definitions branch and rust module, which contains experimental, unstable,
47// in-development definitions we aren't even close to ready to release to the
48// network. This is typically associated with a one-higher-than-released
49// protocol number for testing purposes.
50#[cfg(feature = "next")]
51soroban_env_macros::generate_env_meta_consts!(
52    ledger_protocol_version: 23,
53    pre_release_version: 1,
54);
55
56// If the "next" feature is _not_ enabled, it means we're building for a
57// nearly-current release to the network and are using the "curr" xdr branch and
58// module. This will therefore be associated with a current or nearly-current
59// network protocol number.
60#[cfg(not(feature = "next"))]
61soroban_env_macros::generate_env_meta_consts!(
62    ledger_protocol_version: 22,
63    pre_release_version: 0,
64);
soroban_env_common/meta.rs

soroban_env_common/
meta.rs
