Add CAP-68 - new host functions for protocol 23. (#1627)

This is a 'catch-all' CAP for closing some gaps in the host interface. These are meant to be very simple, so I don't see much value in creating multiple CAPs, even though the functions are not always related to each other.
stellar · Jan 21, 2025 · fb5d9ef · fb5d9ef
1 parent 3d4fde9
commit fb5d9ef
Show file tree

Hide file tree

Showing 2 changed files with 180 additions and 1 deletion.
diff --git a/core/README.md b/core/README.md
@@ -100,7 +100,8 @@
 | [CAP-0064](cap-0064.md) | Memo Authorization for Soroban | Dmytro Kozhevin | Draft |
 | [CAP-0065](cap-0065.md) | Reusable Module Cache | Graydon Hoare | Draft |
 | [CAP-0066](cap-0066.md) | Soroban In-memory Read Resource | Garand Tyson | Draft |
-| [CAP-0067](cap-0065.md) | Unified Asset Events | Siddharth Suresh | Draft |
+| [CAP-0067](cap-0067.md) | Unified Asset Events | Siddharth Suresh | Draft |
+| [CAP-0068](cap-0068.md) | New host functions for protocol 23 | Dmytro Kozhevin | Draft |
 
 ### Rejected Proposals
 | Number | Title | Author | Status |

diff --git a/core/cap-0068.md b/core/cap-0068.md
@@ -0,0 +1,178 @@
+## Preamble
+
+```
+CAP: 0068
+Title: New host functions for protocol 23
+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 few simple new Soroban host functions to be added in protocol 23.
+
+## Working Group
+
+As described in the preamble section.
+
+## Motivation
+
+This CAP describes a few different host functions that cover the usability gaps in the existing Soroban host functionality. The motivation is specific to the individual functions and is described below.
+
+### Getter for `Address`s executable
+
+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.
+
+
+### Conversion between `Bytes` and `String`
+
+`String` host type is basically an alias to the `Bytes` type as it doesn't enforce any specific encoding to be used.  However, the only way to convert between the two is to allocate a buffer of arbitrary length in the linear memory of the contract, which is rather inefficient as it requires the contract to link the allocator library which might be otherwise not necessary. Conversion between the compatible types is a generally useful feature to provide (e.g. for connecting different contract APIs), but the additional motivation in this is case is also the fact that the set of the host functions defined for `Bytes` is much broader than the one for `String`.
+
+
+### 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
+The following new host functions are provided:
+
+- A function that returns an executable for the provided `Address`, if any
+- A function that converts a `BytesObject` into `StringObject` with the same contents
+- A function that converts a `StringObject` into `BytesObject` with the same contents
+
+## Specification
+
+### New host functions
+
+The diff is based on commit `822727b37b7ef2eea1fc0bafc558820dc450c67e` of `rs-soroban-env`.
+
+```json
+ 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
+@@ -1957,8 +1957,33 @@
+                     ],
+                     "return": "U32Val",
+                     "docs": "Return the index of a Symbol in an array of linear-memory byte-slices, or trap if not found."
++                },
++                {
++                    "export": "n",
++                    "name": "string_to_bytes",
++                    "args": [
++                        {
++                            "name": "str",
++                            "type": "StringObject"
++                        }
++                    ],
++                    "return": "BytesObject",
++                    "docs": "Converts the provided string to bytes with exactly the same contents.",
++                    "min_supported_protocol": 23
++                },
++                {
++                    "export": "o",
++                    "name": "bytes_to_string",
++                    "args": [
++                        {
++                            "name": "bytes",
++                            "type": "BytesObject"
++                        }
++                    ],
++                    "return": "StringObject",
++                    "docs": "Converts the provided bytes array to string with exactly the same contents. No encoding checks are performed and thus the output string's encoding should be interpreted by the consumer of the string.",
++                    "min_supported_protocol": 23
+                 }
+-
+             ]
+         },
+         {
+@@ -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` function
+
+This function returns the value of type `Option<AddressExecutable>` where `AddressExecutable` is defined as follows:
+
+```rust
+#[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`
+
+#### `string_to_bytes`/`bytes_to_string` functions
+
+These functions perform the `StringObject`<->`BytesObject` conversions. Both allocate a new object of the respective output type from the underlying bytes buffer without performing any additional validation.
+
+While there is room for optimization here via using the shared bytes buffer, this CAP doesn't go for it as the benefit is too marginal compared to the necessary effort.
+
+## Protocol Upgrade Transition
+
+The proposed host functions 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 functions 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