CAP-85: Externally managed contract executables (productionization)

Cargo.toml

@@ -21,23 +21,25 @@ exclude = ["soroban-test-wasms/wasm-workspace"]
 # NB: When bumping the major version make sure to clean up the
 # code guarded by `unstable-*` features to make it enabled
 # unconditionally.
-version = "28.0.0"
+version = "27.0.0"
 rust-version = "1.84.0"
 
 [workspace.dependencies]
-soroban-env-common = { version = "=28.0.0", path = "soroban-env-common", default-features = false }
-soroban-env-guest = { version = "=28.0.0", path = "soroban-env-guest" }
-soroban-env-host = { version = "=28.0.0", path = "soroban-env-host" }
-soroban-env-macros = { version = "=28.0.0", path = "soroban-env-macros" }
-soroban-builtin-sdk-macros = { version = "=28.0.0", path = "soroban-builtin-sdk-macros" }
+soroban-env-common = { version = "=27.0.0", path = "soroban-env-common", default-features = false }
+soroban-env-guest = { version = "=27.0.0", path = "soroban-env-guest" }
+soroban-env-host = { version = "=27.0.0", path = "soroban-env-host" }
+soroban-env-macros = { version = "=27.0.0", path = "soroban-env-macros" }
+soroban-builtin-sdk-macros = { version = "=27.0.0", path = "soroban-builtin-sdk-macros" }
 # NB: this must match the wasmparser version wasmi is using
 wasmparser = "=0.116.1"
 
 # NB: When updating, also update the version in rs-soroban-env dev-dependencies
 [workspace.dependencies.stellar-xdr]
 version = "=27.0.0"
-#git = "https://github.com/stellar/rs-stellar-xdr"
-#rev = "156759ab322dda6976d07435c6f5b70f98e9fd0c"
+# SPIKE: rs-stellar-xdr#553 (CAP-0085). Fork-hosted branch p28-cap-0085.
+# Productionize -> stellar/rs-stellar-xdr merged SHA (or crates.io) once #553 lands.
+git = "https://github.com/sisuresh/rs-stellar-xdr"
+rev = "e1170cd9abb9d1d10cf4a3b7ed4091a109f56b71"
 default-features = false
 
 [workspace.dependencies.wasmi]

soroban-env-common/Cargo.toml

@@ -37,7 +37,12 @@ std = ["stellar-xdr/std", "stellar-xdr/base64"]
 serde = ["dep:serde", "stellar-xdr/serde"]
 wasmi = ["dep:wasmi", "dep:wasmparser"]
 testutils = ["dep:arbitrary", "stellar-xdr/arbitrary"]
-next = ["soroban-env-macros/next"]
+next = ["soroban-env-macros/next", "cap_0085_executable_ref"]
+# CAP-0085 (externally managed contract executables). Leaf feature pulling only
+# its gated XDR variants from stellar-xdr; the umbrella `next` aggregates it
+# (above). Must NOT pull in `next` (that would make `next` <-> cap a cycle).
+# Fold into the base XDR / make unconditional at the protocol bump.
+cap_0085_executable_ref = ["stellar-xdr/cap_0085_executable_ref"]
 tracy = ["dep:tracy-client"]
 shallow-val-hash = []
 

soroban-env-common/env.json

@@ -1708,6 +1708,65 @@
                     "return": "Void",
                     "docs": "Extend the contract instance and/or corresponding code entry TTL to be up to `extend_to` ledgers, where TTL is defined as `entry_live_until_ledger_seq - current_ledger_seq`. `extension_scope` defines whether contract instance, code, or both will be extended. The TTL extension only actually happens if it is at least `min_extension`, otherwise this function is a no-op. The amount of extension ledgers will not exceed `max_extension` ledgers. If attempting to extend an entry past the maximum allowed value (defined as the current ledger + `max_entry_ttl` - 1), its new `live_until_ledger_seq` will be clamped to the max.",
                     "min_supported_protocol": 26
+                },
+                {
+                    "export": "h",
+                    "name": "create_executable_tag",
+                    "args": [
+                        {
+                            "name": "tag_string",
+                            "type": "StringObject"
+                        }
+                    ],
+                    "return": "ExecutableTagObject",
+                    "docs": "Creates a new `ExecutableTag` object holding the contents of the provided string. The tag acts as a key identifying an executable reference contract data entry. Executable reference entries may be used by other contracts to fetch their executable.",
+                    "min_supported_protocol": 28
+                },
+                {
+                    "export": "i",
+                    "name": "create_external_ref_contract",
+                    "args": [
+                        {
+                            "name": "deployer",
+                            "type": "AddressObject"
+                        },
+                        {
+                            "name": "executable_owner",
+                            "type": "AddressObject"
+                        },
+                        {
+                            "name": "tag",
+                            "type": "ExecutableTagObject"
+                        },
+                        {
+                            "name": "salt",
+                            "type": "BytesObject"
+                        },
+                        {
+                            "name": "constructor_args",
+                            "type": "VecObject"
+                        }
+                    ],
+                    "return": "AddressObject",
+                    "docs": "Creates the contract instance on behalf of `deployer`. `deployer` must authorize this call via Soroban auth framework, i.e. this calls `deployer.require_auth` with respective arguments. Executable is read from the `executable_owner` contract storage entry keyed by `tag`. Currently the only supported external executable kind is hash of an existing Wasm. `salt` is used to create a unique contract id. `constructor_args` are forwarded into created contract's constructor (`__constructor`) function. Returns the address of the created contract.",
+                    "min_supported_protocol": 28
+                },
+                {
+                    "export": "j",
+                    "name": "update_current_contract_executable_ref",
+                    "args": [
+                        {
+                            "name": "executable_owner",
+                            "type": "AddressObject"
+                        },
+                        {
+                            "name": "tag",
+                            "type": "ExecutableTagObject"
+                        }
+                    ],
+                    "return": "Void",
+                    "docs": "Replaces the executable of the current contract with the provided executable reference. Executable is read from the `executable_owner` contract storage entry keyed by `tag`. Currently the only supported external executable kind is hash of an existing Wasm. The update happens only after the current contract invocation has successfully finished, so this can be safely called in the middle of a function.",
+                    "min_supported_protocol": 28
                 }
             ]
         },

soroban-env-common/src/compare.rs

@@ -195,7 +195,8 @@ impl<E: Env> Compare<Val> for E {
                 | Tag::VecObject
                 | Tag::MapObject
                 | Tag::AddressObject
-                | Tag::MuxedAddressObject => Err(self.error_from_error_val(
+                | Tag::MuxedAddressObject
+                | Tag::ExecutableTagObject => Err(self.error_from_error_val(
                     Error::from_type_and_code(ScErrorType::Context, ScErrorCode::InternalError),
                 )),
 

soroban-env-common/src/convert.rs

@@ -500,6 +500,7 @@ where
             | Tag::MapObject
             | Tag::AddressObject
             | Tag::MuxedAddressObject
+            | Tag::ExecutableTagObject
             | Tag::SmallCodeUpperBound
             | Tag::ObjectCodeLowerBound
             | Tag::ObjectCodeUpperBound
@@ -596,6 +597,8 @@ where
             | ScVal::LedgerKeyNonce(_)
             | ScVal::LedgerKeyContractInstance
             | ScVal::ContractInstance(_) => return Err(ConversionError.into()),
+            #[cfg(feature = "cap_0085_executable_ref")]
+            ScVal::ExecutableTag(_) => return Err(ConversionError.into()),
         })
     }
 }

soroban-env-common/src/env.rs

@@ -4,10 +4,10 @@ use crate::Object;
 
 use super::Symbol;
 use super::{
-    AddressObject, Bool, BytesObject, ContractTtlExtension, DurationObject, Error, I128Object,
-    I256Object, I256Val, I64Object, MapObject, MuxedAddressObject, StorageType, StringObject,
-    SymbolObject, TimepointObject, U128Object, U256Object, U256Val, U32Val, U64Object, U64Val, Val,
-    VecObject, Void,
+    AddressObject, Bool, BytesObject, ContractTtlExtension, DurationObject, Error,
+    ExecutableTagObject, I128Object, I256Object, I256Val, I64Object, MapObject, MuxedAddressObject,
+    StorageType, StringObject, SymbolObject, TimepointObject, U128Object, U256Object, U256Val,
+    U32Val, U64Object, U64Val, Val, VecObject, Void,
 };
 use crate::xdr::{ScErrorCode, ScErrorType};
 
@@ -271,6 +271,7 @@ impl_checkedenvarg_for_val_or_wrapper!(DurationObject);
 impl_checkedenvarg_for_val_or_wrapper!(TimepointObject);
 impl_checkedenvarg_for_val_or_wrapper!(SymbolObject);
 impl_checkedenvarg_for_val_or_wrapper!(StringObject);
+impl_checkedenvarg_for_val_or_wrapper!(ExecutableTagObject);
 
 impl_checkedenvarg_for_val_or_wrapper!(VecObject);
 impl_checkedenvarg_for_val_or_wrapper!(MapObject);

soroban-env-common/src/lib.rs

@@ -109,7 +109,7 @@ pub use val::{ConversionError, Tag, Val};
 
 #[cfg(feature = "wasmi")]
 pub use val::WasmiMarshal;
-pub use val::{AddressObject, MapObject, MuxedAddressObject, VecObject};
+pub use val::{AddressObject, ExecutableTagObject, MapObject, MuxedAddressObject, VecObject};
 pub use val::{Bool, Void};
 
 pub use compare::Compare;

soroban-env-common/src/object.rs

@@ -143,6 +143,8 @@ impl<'a> ScValObjRef<'a> {
             | ScVal::Vec(_)
             | ScVal::Map(_)
             | ScVal::Address(_) => Some(ScValObjRef(value)),
+            #[cfg(feature = "cap_0085_executable_ref")]
+            ScVal::ExecutableTag(_) => Some(ScValObjRef(value)),
 
             // Other values are small or large depending on
             // their actual scalar value.

soroban-env-common/src/val.rs

@@ -151,8 +151,12 @@ pub enum Tag {
 
     MuxedAddressObject = 78,
 
+    /// Tag for a [Val] that refers to a host-side executable tag: a key
+    /// identifying an executable reference (see [`ExecutableTagObject`](crate::ExecutableTagObject)).
+    ExecutableTagObject = 79,
+
     /// Code delimiting the upper boundary of "object" types.
-    ObjectCodeUpperBound = 79,
+    ObjectCodeUpperBound = 80,
 
     /// Code reserved to indicate mis-tagged [`Val`]s.
     Bad = 0x7f,
@@ -241,6 +245,10 @@ impl Tag {
             Tag::MapObject => Some(ScValType::Map),
             Tag::AddressObject => Some(ScValType::Address),
             Tag::MuxedAddressObject => Some(ScValType::Address),
+            #[cfg(feature = "cap_0085_executable_ref")]
+            Tag::ExecutableTagObject => Some(ScValType::ExecutableTag),
+            #[cfg(not(feature = "cap_0085_executable_ref"))]
+            Tag::ExecutableTagObject => None,
             Tag::ObjectCodeUpperBound => None,
             Tag::Bad => None,
         }
@@ -341,6 +349,7 @@ declare_tag_based_object_wrapper!(VecObject);
 declare_tag_based_object_wrapper!(MapObject);
 declare_tag_based_object_wrapper!(AddressObject);
 declare_tag_based_object_wrapper!(MuxedAddressObject);
+declare_tag_based_object_wrapper!(ExecutableTagObject);
 
 // This is a 0-arg struct rather than an enum to ensure it completely compiles
 // away, the same way `()` would, while remaining a separate type to allow
@@ -614,6 +623,8 @@ impl Val {
             | ScValType::Vec
             | ScValType::Map
             | ScValType::Address => true,
+            #[cfg(feature = "cap_0085_executable_ref")]
+            ScValType::ExecutableTag => true,
             ScValType::ContractInstance
             | ScValType::LedgerKeyContractInstance
             | ScValType::LedgerKeyNonce => false,
@@ -690,7 +701,8 @@ impl Val {
             | Tag::VecObject
             | Tag::MapObject
             | Tag::AddressObject
-            | Tag::MuxedAddressObject => self.has_minor(0),
+            | Tag::MuxedAddressObject
+            | Tag::ExecutableTagObject => self.has_minor(0),
         }
     }
 
@@ -872,6 +884,7 @@ impl Debug for Val {
             Tag::MapObject => fmt_obj("Map", self, f),
             Tag::AddressObject => fmt_obj("Address", self, f),
             Tag::MuxedAddressObject => fmt_obj("MuxedAddress", self, f),
+            Tag::ExecutableTagObject => fmt_obj("ExecutableTag", self, f),
 
             Tag::Bad
             | Tag::SmallCodeUpperBound

soroban-env-common/src/vmcaller_env.rs

@@ -3,10 +3,10 @@
 use crate::xdr::{ScErrorCode, ScErrorType};
 
 use super::{
-    AddressObject, Bool, BytesObject, ContractTtlExtension, DurationObject, Error, I128Object,
-    I256Object, I256Val, I64Object, MapObject, MuxedAddressObject, StorageType, StringObject,
-    SymbolObject, TimepointObject, U128Object, U256Object, U256Val, U32Val, U64Object, U64Val, Val,
-    VecObject, Void,
+    AddressObject, Bool, BytesObject, ContractTtlExtension, DurationObject, Error,
+    ExecutableTagObject, I128Object, I256Object, I256Val, I64Object, MapObject, MuxedAddressObject,
+    StorageType, StringObject, SymbolObject, TimepointObject, U128Object, U256Object, U256Val,
+    U32Val, U64Object, U64Val, Val, VecObject, Void,
 };
 use crate::call_macro_with_all_host_functions;
 use crate::{CheckedEnvArg, EnvBase, Symbol};

soroban-env-guest/Cargo.toml

@@ -19,4 +19,5 @@ all-features = true
 
 [features]
 testutils = ["soroban-env-common/testutils"]
-next = ["soroban-env-common/next"]
+next = ["soroban-env-common/next", "cap_0085_executable_ref"]
+cap_0085_executable_ref = ["soroban-env-common/cap_0085_executable_ref"]