String/Bytes conversion host functions

Preamble

CAP: 0069
Title: String/Bytes conversion host functions
Working Group:
    Owner: Dmytro Kozhevin <@dmkozh>
    Authors: Dmytro Kozhevin <@dmkozh>
    Consulted:
Status: Final
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.

 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