From 869fb9f90ebc92fd7d499b7859fc89b5431e494e Mon Sep 17 00:00:00 2001 From: Levai! Date: Thu, 15 Aug 2024 19:04:41 +0100 Subject: [PATCH] Guide for type conversions (#839) * add guide for type conversions * resolve merge conflict --- .../conversions/address-conversions.mdx | 136 +++++++++++++++++ .../guides/conversions/bytes-conversions.mdx | 144 ++++++++++++++++++ .../guides/conversions/scval-conversions.mdx | 107 +++++++++++++ .../guides/conversions/string-conversions.mdx | 125 +++++++++++++++ 4 files changed, 512 insertions(+) create mode 100644 docs/build/guides/conversions/address-conversions.mdx create mode 100644 docs/build/guides/conversions/bytes-conversions.mdx create mode 100644 docs/build/guides/conversions/scval-conversions.mdx create mode 100644 docs/build/guides/conversions/string-conversions.mdx diff --git a/docs/build/guides/conversions/address-conversions.mdx b/docs/build/guides/conversions/address-conversions.mdx new file mode 100644 index 000000000..c6d3e0966 --- /dev/null +++ b/docs/build/guides/conversions/address-conversions.mdx @@ -0,0 +1,136 @@ +--- +title: Convert an address to other types +hide_table_of_contents: true +draft: true +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +The `Address` is an opaque type that could represent an "account" on the Stellar network (i.e., a keypair), or a "contract." From Soroban's point of view, it doesn't really matter which it is. The "account" variety of these addresses are typically displayed as a `G...` public address, and the "contract" variety is typically displayed as a `C...` address. An address may also be displayed in other formats such as a 32 byte array, a string, or an ScVal type. The Soroban SDKs provide methods that easily convert an address to any of these types. + +## Address to bytesN + +Bytes are a more compact and efficient way to store data in terms of storage optimization and data transmission. In situations where you need to store or transmit an address in a fixed-size, such as for cryptographic operations or data serialization, you need to convert the address to a bytesN format + + + + + ```rust + use soroban_sdk::{Address, BytesN, Env, FromVal}; + + pub fn address_to_bytes32(env: &Env, address: Address) -> BytesN<32> { + let address_to_bytes: BytesN<32> = BytesN::from_val(env, &address.to_val()); + address_to_bytes + } + ``` + + + + ```js + const StellarSdk = require('@stellar/stellar-sdk'); + + // Example Stellar address + const stellarAddress = 'GCM5WPR4DDR24FSAX5LIEM4J7AI3KOWJYANSXEPKYXCSZOTAYXE75AFN'; + // Create an Address object + const address = new StellarSdk.Address(stellarAddress); + // Convert the Address to raw public key bytes (Buffer) + const buffer = address.toBuffer(); + ``` + + + + + + ```python + from stellar_sdk.address import Address + from stellar_sdk.strkey import StrKey + + # Example Stellar address + stellar_address = 'GCM5WPR4DDR24FSAX5LIEM4J7AI3KOWJYANSXEPKYXCSZOTAYXE75AFN' + # Convert the address to bytes + StrKey.decode_ed25519_public_key(stellar_address) + ``` + + + + +## Address to String + +When transferring data between different systems or over a network, using text-based formats like JSON and XML string formats are often required. Storing addresses as strings in databases can simplify database schema design and queries. Strings are easier to manipulate and are more compatible with user interfaces and APIs. + + + + + ```rust + use soroban_sdk::{Address, String, Env}; + + pub fn address_to_string(address: Address) -> String { + address.to_string() + } + ``` + + + + + ```js + const StellarSdk = require('@stellar/stellar-sdk'); + + // Example Stellar address + const stellarAddress = 'GCM5WPR4DDR24FSAX5LIEM4J7AI3KOWJYANSXEPKYXCSZOTAYXE75AFN'; + // Create an Address object + const address = new StellarSdk.Address(stellarAddress); + // Convert the address to string + const addressToString = address.toString(); + ``` + + + + + +# Address to ScVal + +Addresses are often passed as function parameters in Soroban smart contracts. These addresses must be in ScVal format because the Soroban virtual machine processes data in this format. Similarly, if a smart contract function returns an address, it will be returned as an ScVal. Converting to and from ScVal ensures that you can properly handle these return values. + + + + + ```rust + use soroban_sdk::{Address, Val}; + + pub fn address_to_sc_val(address: Address) -> Val { + address.to_val() + } + ``` + + + + + ```js + // Example Stellar address + const stellarAddress = 'GCM5WPR4DDR24FSAX5LIEM4J7AI3KOWJYANSXEPKYXCSZOTAYXE75AFN'; + // Create an Address object + const address = new StellarSdk.Address(stellarAddress); + // Convert the Address to xdr.ScVal + const scVal = address.toScVal(); + // Convert the Address to xdr.ScAddress + const scAddress = address.toScAddress(); + ``` + + + + + + ```python + from stellar_sdk.address import Address + + # Example Stellar address + stellar_address = 'GBJCHUKZMTFSLOMNC7P4TS4VJJBTCYL3XKSOLXAUJSD56C4LHND5TWUC' + # Create an Address object + address = Address(stellar_address) + # Convert the Address object to an ScAddress + sc_address_xdr = address.to_xdr_sc_address() + ``` + + + diff --git a/docs/build/guides/conversions/bytes-conversions.mdx b/docs/build/guides/conversions/bytes-conversions.mdx new file mode 100644 index 000000000..96400af8b --- /dev/null +++ b/docs/build/guides/conversions/bytes-conversions.mdx @@ -0,0 +1,144 @@ +--- +title: Convert from bytes to other types +hide_table_of_contents: true +draft: true +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +Bytes is a contiguous growable array type containing u8s. They may represent various types of data including strings, addresses, or other information. Converting any data type to bytes ensures that the data be consistently handled by the Soroban runtime and interacting systems. + +## Bytes to Address + +When retrieving data stored on the blockchain, addresses might be stored in byte representation for compactness and efficiency. Off-chain systems, such as APIs, databases, or user interfaces, usually expect addresses in a human-readable format. In such cases, you need to convert the bytes to an address format to ensure compatibility. + + + + + ```rust + use soroban_sdk::{Address, Bytes, Env}; + + pub fn bytes_to_address(bytes: Bytes) -> Address { + Address::from_string_bytes(&bytes) + } + ``` + + + + + ```js + const StellarSdk = require('@stellar/stellar-sdk'); + + // Example bytes value + const rawBytes = Buffer.from('99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe', 'hex'); + // Convert bytes to an account Address + const addressFromBytes = StellarSdk.Address.account(rawBytes); + addressFromBytes.toString(); + // Convert from bytes to a string address + const addressFromBytes = StellarSdk.Address.contract(rawBytes); + addressFromBytes.toString(); + ``` + + + + + + ```python + from stellar_sdk.address import Address + + # Example bytes value + raw_bytes = bytes.fromhex('99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe') + bytes_to_address = Address.from_raw_account(raw_bytes) + ``` + + + + +## Bytes to String + +When dealing with binary data, you may need to convert certain portions of the data to a human-readable format like strings for logging, debugging, processing or display. + + + + + ```rust + use soroban_sdk::{String, Bytes, Env, FromVal}; + + pub fn bytes_to_string(env: &Env, bytes: Bytes) -> String { + String::from_val(env, &bytes.to_val()) + } + ``` + + + + + + ```js + const StellarSdk = require('@stellar/stellar-sdk'); + + // Example bytes value + const rawBytes = Buffer.from('99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe', 'hex'); + // Convert bytes to string + const bytesToString = rawBytes.toString('hex'); + ``` + + + + + + ```python + from stellar_sdk.address import Address + + # Example bytes + raw_bytes = b'99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe' + # Convert bytes to string + bytes_to_string = raw_bytes.decode('utf-8') + ``` + + + + +## Bytes to ScVal + +In a Soroban smart contract that interacts with an external oracle service to provide price data in raw byte format, you would need to convert the bytes to ScVal to process and manipulate the data within your contract. + + + + + ```rust + use soroban_sdk::{Bytes, Env, FromVal, Val}; + + pub fn bytes_to_val(env: &Env, bytes: Bytes) -> Val { + Val::from_val(env, &bytes.to_val()) + } + + ``` + + + + + ```js + const StellarSdk = require('@stellar/stellar-sdk'); + + // Example bytes value + const rawBytes = Buffer.from('99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe', 'hex'); + // Convert bytes to xdr.ScVal + const bytesToScVal = StellarSdk.xdr.ScVal.scvBytes(rawBytes); + ``` + + + + + + ```python + import stellar_sdk + + # Example bytes value + raw_bytes = b'example_bytes_data' + # Convert bytes to ScVal + sc_val = stellar_sdk.scval.to_bytes(raw_bytes) + ``` + + + diff --git a/docs/build/guides/conversions/scval-conversions.mdx b/docs/build/guides/conversions/scval-conversions.mdx new file mode 100644 index 000000000..dc0fcb205 --- /dev/null +++ b/docs/build/guides/conversions/scval-conversions.mdx @@ -0,0 +1,107 @@ +--- +title: Convert a ScVal to other type +hide_table_of_contents: true +draft: true +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +Soroban Contract Value (`ScVal`) is a custom type defined within the Soroban runtime environment that represents other data types such as strings, bytes, and more complex structures used within smart contracts in a format that that the soroban runtime can process, store and retrieve efficiently. + +## ScVal to bytesN + + + + + ```js + const StellarSdk = require('@stellar/stellar-sdk'); + + // Convert ScVal to bytes + const bytesFromScVal = scVal.bytes(); + + ``` + `.bytes()` converts an ScVal value to bytes. + `scVal` is the ScVal value to be converted to bytes. + + + + + + ```python + import stellar_sdk + + # Convert ScVal to bytes + sc_val_to_bytes = stellar_sdk.scval.from_bytes(sc_val) + + ``` + `stellar_sdk.scval.from_bytes()` converts an ScVal value to bytes. + `sc_val` is the ScVal value to be converted to bytes. + + + + +## ScVal to address + + + + + ```js + const StellarSdk = require('@stellar/stellar-sdk'); + + const addressFromScVal = StellarSdk.Address.fromScVal(scVal); + addressFromScVal.toString(); + + ``` + `StellarSdk.Address.fromScVal()` converts an ScVal value to an address. + `scVal` is the ScVal value to be converted to an address. + + + + + + ```python + import stellar_sdk + + sc_to_address = Address.from_xdr_sc_address(sc_val) + + ``` + `stellar_sdk.scval.from_xdr_sc_addres9()` converts an ScVal value to an address. + `sc_val` represents the ScVal value to be converted to an address. + + + + + +## ScVal to String + + + + + ```js + const StellarSdk = require('@stellar/stellar-sdk'); + + const stringFromScVal = scVal.toString('utf-8'); + + ``` + `scVal.toString()` converts an ScVal value to a string. + `scVal` is the ScVal value to be converted to a string. + `utf-8` is the encoding format for the string. + + + + + + ```python + + import stellar_sdk + + # scval to string + sc_val_to_string = stellar_sdk.scval.from_string(sc_val) + + ``` + `stellar_sdk.scval.from_string()` converts an ScVal value to a string. + `sc_val` represents the ScVal value to be converted to a string. + + + diff --git a/docs/build/guides/conversions/string-conversions.mdx b/docs/build/guides/conversions/string-conversions.mdx new file mode 100644 index 000000000..2448bfd9c --- /dev/null +++ b/docs/build/guides/conversions/string-conversions.mdx @@ -0,0 +1,125 @@ +--- +title: Convert a string to other types +hide_table_of_contents: true +draft: true +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +Strings are a sequence of characters used to represent readable text. They are used to store and manipulate text-based information such as function names, arguments, key-value data and interfacing with external systems. Strings may often need to be converted to other data types for efficient processing and storage. + +## String to bytesN + +Some systems use binary formats where data needs to be represented as a fixed-length byte array for storage or processing. For example, fixed-length hashes or identifiers. Converting strings to a fixed byte size ensures that the data fits the required size constraints. + + + + + ```rust + use soroban_sdk::{String, BytesN, Env, FromVal}; + + pub fn string_to_bytesN(env: &Env, string: String) -> BytesN<32> { + BytesN::from_val(env, &string.to_val()) + } + ``` + + + + + ```js + import StellarSdk = require('@stellar/stellar-sdk'); + + // Example string + const stringValue = 'Hello, Stellar!'; + // Convert the string to bytes format + const byteValue = Buffer.from(stringValue, 'utf-8'); + ``` + + + + + ```python + import stellar_sdk + + string_value.encode() + ``` + `string_value` is the string value to be converted to bytes. + `.encode()` is a method that converts the string to bytes. + + + + + +## String to address + +An address received in a user input may be of string type and you would need to convert it to an address type to perform validations, transactions, or other operations within your smart contract. + + + + + ```rust + use soroban_sdk::{Address, Env, String}; + + pub fn string_to_address(string: String) -> Address { + Address::from_string(&string) + } + ``` + + + + + ```js + const StellarSdk = require('@stellar/stellar-sdk'); + + const stringToAddress = StellarSdk.Address.fromString(stellarAddress); + ``` + `stellarAddress` is the string value to be converted to an address. + `StellarSdk.Address.fromString()` is a method that converts a string to an address. + + + + + +## String to ScVal + +When calling functions or methods that expect ScVal types, you need to convert your string data to ScVal to make the call successful. For example, if your smart contract needs to store or manipulate a user input string within its state or use it as part of its logic, you would convert the string to an ScVal type to integrate it with the contract's operations. + + + + + ```rust + use soroban_sdk::{String, Env, Val}; + + pub fn string_to_val(env: &Env, string: String) -> Val { + string.to_val() + } + ``` + + + + + ```js + import StellarSdk from '@stellar/stellar-sdk'; + + // Example string value + const stringValue = 'Hello, Stellar!'; + // Convert the string to ScVal + const stringToScVal = StellarSdk.xdr.ScVal.scvString(stringValue); + ``` + + + + + + ```python + import stellar_sdk + + string_to_sc_val = stellar_sdk.scval.to_string(string_value) + ``` + `string_value` is the string value to be converted to an ScVal + `stellar_sdk.scval.to_string()` converts the string value to an ScVal + + + +