Skip to content

Latest commit

 

History

History
123 lines (90 loc) · 6.03 KB

cap-0068.md

File metadata and controls

123 lines (90 loc) · 6.03 KB

Preamble

CAP: 0068
Title: Host function for getting  executable for `Address`
Working Group:
    Owner: Dmytro Kozhevin <@dmkozh>
    Authors: Dmytro Kozhevin <@dmkozh>
    Consulted:
Status: Draft
Created: 2025-01-17
Discussion: https://github.com/stellar/stellar-protocol/discussions/1626
Protocol version: 23

Simple Summary

This is a CAP describing a new Soroban host function for getting the executable corresponding to an Address.

Working Group

As described in the preamble section.

Motivation

There is currently no way to get the executable for an arbitrary address, so it's not possible to distinguish between Wasm and built-in contracts (currently, the only such contract is Stellar Asset contract) and not possible to get the specific Wasm hash corresponding to the contract. This information serves multiple different use cases, such as:

  • Custom accounts will be able to provide authorization policies based on the executables, for example, only allow a few vetted token implementations to be used.
  • Contracts will be able to generically distinguish between SAC instances and custom tokens on-chain. Currently possible for a custom token to impersonate metadata of any SAC, including the one for the 'native' token (XLM) and there is no on-chain way to distinguish between these. This is especially relevant for the bridge protocols that provide a capability to wrap Stellar tokens on different chains and need to create metadata for the wrapped tokens.
  • In general contracts will be able to 'pin' the exact implementations of their dependencies. While this is not necessary (or even desired) for majority of the protocols, there are use cases where pinning increases security. For example, this allows custom accounts to give restricted authorization privileges to the separate 'session' contracts without worrying about the change in the implementation of these contracts.

Goals Alignment

This CAP is aligned with the following Stellar Network Goals:

  • The Stellar Network should make it easy for developers of Stellar projects to create highly usable products

Abstract

A new host functions that returns an executable for the provided Address is added to the Soroban host.

Specification

New host function

The diff is based on commit 822727b37b7ef2eea1fc0bafc558820dc450c67e of rs-soroban-env.

 soroban-env-common/env.json | 40 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/soroban-env-common/env.json b/soroban-env-common/env.json
index d421dca2..41bc7e47 100644
--- a/soroban-env-common/env.json
+++ b/soroban-env-common/env.json
@@ -2403,6 +2428,19 @@
                     ],
                     "return": "Void",
                     "docs": "Authorizes sub-contract calls for the next contract call on behalf of the current contract. Every entry in the argument vector corresponds to `InvokerContractAuthEntry` contract type that authorizes a tree of `require_auth` calls on behalf of the current contract. The entries must not contain any authorizations for the direct contract call, i.e. if current contract needs to call contract function F1 that calls function F2 both of which require auth, only F2 should be present in `auth_entries`."
+                },
+                {
+                    "export": "4",
+                    "name": "get_address_executable",
+                    "args": [
+                        {
+                            "name": "address",
+                            "type": "AddressObject"
+                        }
+                    ],
+                    "return": "Val",
+                    "docs": "Returns the executable corresponding to the provided address. When the address does not exist on-chain, returns `Void` value. When it does exist, returns a value of `AddressExecutable` contract type. It is an enum with either `Account` value for the 'classic' accounts, or `Contract` value and respective `ContractExecutable` for the contracts.",
+                    "min_supported_protocol": 23
                 }
             ]
         },

Semantics

get_address_executable host function will be added. This function returns the value of type Option<AddressExecutable> where AddressExecutable is defined as follows:

#[contracttype]
enum AddressExecutable {
    Contract(ContractExecutable),
    Account,
}

enum ContractExecutable {
    Wasm(BytesN<32>),
    StellarAsset,
}

The semantics of the return value are as follows:

  • If there is no ledger entry for the provided address in the storage None (i.e. Val::VOID) is returned
    • 'No ledger entry' means no respective AccountEntry for the account (ScAddress::Account) addresses and no respective ContractData (with ScVal::LedgerKeyContractInstance key) entry for contract addresses (ScAddress::Contract)
  • If there is a ledger entry, then it is converted to the AddressExecutable:
    • Contracts are represented as ContractExecutable::Contract value
      • Wasm contracts are represented by ContractExecutable::Wasm with the corresponding SHA-256 hash of the underlying Wasm code
      • Stellar asset contract instances are represented by ContractExecutable::StellarAsset
    • Accounts are represented as AddressExecutable::Account

Protocol Upgrade Transition

The proposed host function will use the standard mechanism for protocol-gating the host functions and will become available in protocol 23. Before protocol 23 it will be impossible to upload Wasm that uses the new functions.

Backwards Incompatibilities

This CAP does not introduce any backward incompatibilities.

Resource Utilization

The new host function will have the appropriate metering. No new cost types need to be introduced, as the operations can lean on the existing metering primitives.

Security Concerns

get_address_executable gives contracts access to data that has previously been unavailable. However, there is no obvious way to abuse this data, as it does not reveal the internal state of the contract.

Test Cases

Implementation