Add externally managed contract executable type

[mootz12]

Problem

The factory pattern is commonly used in smart contract protocols to deploy many contract instances that share the same WASM (a "fleet" of contracts). When that shared WASM needs to be upgraded, the admin must submit a separate upgrade transaction for every instance. This is fine for small fleets, but for large ones it is expensive and creates a window during the rollout where some instances run the old WASM and some run the new.

Because some upgrades carry security fixes, or are not backwards-compatible with the previous version, there is incentive for the upgrade to apply atomically across the entire fleet.

Ecosystems that manage reusable code via proxies, such as Ethereum, achieve this with the beacon proxy pattern.

Stellar has no equivalent today. Each contract instance defines its own WASM hash, and we intentionally do not expose the proxy primitives (fallback() or delegatecall) that beacon implementations rely on. This discussion proposes fixing this by extending the contract executable definition to support references to an updatable WASM hash.

Proposal

We would like to extend the contract instance executable definition to include an external reference variant:

ContractExecutable::ExternalRef { contract: Address, name: Symbol }

A contract can manage WASM entries via a new ScVal ledger key type ScVal::LedgerKeyWasmRef(Symbol) and a new host function that validates wasm_hash exists as a code entry:

set_contract_wasm_ref(name: Symbol, wasm_hash: BytesObject) -> Void

A contract can switch its executable to an external reference or update it's external reference via a new host function:

update_current_contract_executable_external_ref(contract: AddressObject, name: Symbol) -> Void

A factory contract can deploy contracts with an externally referenced WASM with the new host functions:

create_contract_with_external_ref(deployer: AddressObject, contract: AddressObject, name: Symbol, salt: BytesObject) -> AddressObject
create_contract_with_external_ref_and_constructor(deployer: AddressObject, contract: AddressObject, name: Symbol, salt: BytesObject, constructor_args: VecObject) -> AddressObject

Diagrams

Legend:

• Manager - a contract that manages contract wasm hashes
• Follower - a contract whose executable is an ExternalRef to the Manager
• Factory - a contract that deploys follower contracts
• Ledger - where everything is stored

Resolving an ExternalRef Contract during a contract invocation

sequenceDiagram
    actor U as Caller
    participant H as Host
    participant L as Ledger
    U->>H: invoke Follower.transfer(...)
    H->>L: read Follower instance
    L-->>H: executable = ExternalRef{ Manager, "token" }
    H->>L: read reserved entry (Manager, WasmRef("token"))
    L-->>H: wasm_hash
    H->>L: read ContractCode(wasm_hash)
    L-->>H: wasm code
    Note over H: instantiate VM, run transfer(...)
    H-->>U: result of transfer(...)

Loading

Manager upgrading a WASM it controls

sequenceDiagram
    actor Op as Admin
    participant M as Manager
    participant H as Host
    participant L as Ledger
    Op->>M: upgrade("token", new_hash)
    M->>M: governance checks (require_auth(admin), timelock, ...)
    M->>H: set_contract_wasm_ref("token", new_hash)
    H->>H: assert ContractCode(new_hash) exists
    H->>L: write (Manager, WasmRef("token")) = new_hash
    H->>H: emit wasm_ref_updated(Manager, "token", old_hash, new_hash)
    H-->>M: ok
    Note over L: every Follower with ExternalRef{ Manager, "token" }<br/>resolves to new_hash on its next call

Loading

Factory deploying a new follower contract

sequenceDiagram
    actor U as Deployer
    participant Fa as Factory
    participant H as Host
    participant L as Ledger
    U->>Fa: deploy(salt)
    Fa->>H: create_contract_with_external_ref(deployer, Manager, "token", salt)
    H->>H: derive Follower address from (deployer, salt)
    H->>L: read (Manager, WasmRef("token"))
    L-->>H: wasm_hash
    H->>H: assert ContractCode(wasm_hash) exists
    H->>L: write Follower instance, executable = ExternalRef{ Manager, "token" }
    H-->>Fa: Follower address
    Fa-->>U: Follower address
    Note over H,L: the _and_constructor variant also loads the code<br/>and runs the Follower's constructor against it

Loading

Alternatives

• Arbitrary storage slot. Rather than a reserved, typed key, the executable could point at any storage entry ExternalRef { contract: Address, key: Val }. This is the simplest protocol change, but potentially the easiest to go wrong as no additional host functions are added that can validate things like "this entry holds a deployed WASM hash".

Questions

• When a follower runs extend_current_contract_instance_and_code_ttl, what gets extended?
  • Follower instance -> yes
  • Manager WASM ref entry -> ?
  • WASM code -> ?

[dmkozh]

Thanks for posting this. I think another alternative that might be suggested is a direct ability for a contract to 'inherit' the executable of another contract directly. However, I think the proposed approach has several benefits compared to the direct inheritance approach:

• Proxying support must be intentional (there is no way to just naively inherit an arbitrary contract)
• The proxied contract logic is clearly separated from the manager contract logic (in case of inheritance both must be present in the same contract)
• One manager can manage an arbitrary number of Wasms

Some small design notes:

• create_contract_with_external_ref function doesn't seem necessary, we only need a version with constructor. Protocol already defines that contracts without explicit constructor have implicit constructor that accepts 0 arguments and does nothing, so at the host level it's sufficient to just pass an empty arguments vec object for such contracts

• extend_current_contract_instance_and_code_ttl question raises an interesting point: I think the behavior is quite clear here and we should bump instance, ref entry, and code itself (the intention here is 'bump everything necessary for my contract to execute'). But what we also need to consider is the ability to extend TTL of the reference itself. Adding a dedicated host function for that looks a bit annoying. Maybe we should actually consider the alternative you suggested - protocol can still verify that the reference you're pointing at contains a hash of an on-chain Wasm entry at the moment of the source update. This way we can cut the number of the new host functions greatly and thus make the proposal simpler.

[mootz12]

Thanks for the feedback @dmkozh!

direct ability for a contract to 'inherit' the executable of another contract directly

Yeah, considered this but agree with your reasoning. Primarily, it's very awkward to manage the instance executable data based on if you are the follower or the source.

create_contract_with_external_ref function doesn't seem necessary

Good catch, I missed that detail about explicit constructors. Will remove in the CAP.

extend_current_contract_instance_and_code_ttl question

Agree, bumping all 3 is the most obvious result. On first glance we should be able to bump the reference within the above host function.

But what we also need to consider is the ability to extend TTL of the reference itself

From the manager you mean? Yeah, we would need an additional host function here as is. Annoying - good catch.

Maybe we should actually consider the alternative you suggested (Arbitrary storage slot)

My main concern the host has assurances that WASM hashes map to contract code that exists. Allowing arbitrary data to be used would break that, even if we verify on source update, as the manager could just delete it or something. It looks like the code has enough error handling to manage this, but it felt like a more intrusive change than adding fairly simple host functions.

If you feel otherwise, this is simpler so happy to go this route. It's worth noting that the key is just a generic ScVal now. This isn't really an issue but forcing Symbol does allow them to be automatically readable by explorers.

---

Unrelated, but realized while responding but I think it makes sense to loosen the name: Symbol requirement to name: String if we stick with the reserved ScVal ledger key. Symbol doesn't allow : or . so common scope/version strings like token:latest or token:v1.2.3 would not be supported.