Split CAP-68 into two parts corresponding to different host fn sets. (#…

…1634)

core/README.md

@@ -101,7 +101,8 @@
 | [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-0067.md) | Unified Asset Events | Siddharth Suresh | Draft |
-| [CAP-0068](cap-0068.md) | New host functions for protocol 23 | Dmytro Kozhevin | Draft |
+| [CAP-0068](cap-0068.md) | Host function for getting  executable for `Address` | Dmytro Kozhevin | Draft |
+| [CAP-0069](cap-0069.md) | String/Bytes conversion host functions | Dmytro Kozhevin | Draft |
 
 ### Rejected Proposals
 | Number | Title | Author | Status |

core/cap-0068.md

@@ -2,7 +2,7 @@
 
 ```
 CAP: 0068
-Title: New host functions for protocol 23
+Title: Host function for getting  executable for `Address`
 Working Group:
     Owner: Dmytro Kozhevin <@dmkozh>
     Authors: Dmytro Kozhevin <@dmkozh>
@@ -14,45 +14,34 @@ Protocol version: 23
 ```
 
 ## Simple Summary
-This is a CAP describing a few simple new Soroban host functions to be added in protocol 23.
+
+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
 
-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
+A new host functions that returns an executable for the provided `Address` is added to the Soroban host.
 
 ## Specification
 
-### New host functions
+### New host function
 
 The diff is based on commit `822727b37b7ef2eea1fc0bafc558820dc450c67e` of `rs-soroban-env`.
 
@@ -64,41 +53,6 @@ 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",
@@ -119,14 +73,11 @@ index d421dca2..41bc7e47 100644
                  }
              ]
          },
--- 
 ```
 
 ### Semantics
 
-#### `get_address_executable` function
-
-This function returns the value of type `Option<AddressExecutable>` where `AddressExecutable` is defined as follows:
+`get_address_executable` host function will be added. This function returns the value of type `Option<AddressExecutable>` where `AddressExecutable` is defined as follows:
 
 ```rust
 #[contracttype]
@@ -151,23 +102,17 @@ The semantics of the return value are as follows:
         - 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.
+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 functions will have the appropriate metering. No new cost types need to be introduced, as the operations can lean on the existing metering primitives.
+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
 

core/cap-0069.md

@@ -0,0 +1,115 @@
+## Preamble
+
+```
+CAP: 0069
+Title: String/Bytes conversion host functions
+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/1633
+Protocol version: 23
+```
+
+## Simple Summary
+This is a CAP describing new Soroban host functions for conversion between `String` and `Bytes` types in Soroban.
+
+## Working Group
+
+As described in the preamble section.
+
+## Motivation
+
+`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 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`.
+
+```diff mddiffcheck.ignore=true
+ 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
+                 }
+-
+             ]
+         },
+         {
+```
+
+### Semantics
+
+`string_to_bytes`/`bytes_to_string` functions will be added to Soroban host. 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
+
+None.
+
+## Test Cases
+
+## Implementation