Update and review conversion guides (#1904)

* light touches and a python example for address conversions

Fixes #1858

* remove one unnecessary set of codeblock tags

* update the bytes conversion guide

Fixes #1859

* update the string conversions guide

Fixes #1867

* remove unused imports

* update scval conversions guide

Fixes #1866

* simplify scval conversions from base64 strings

Author: ElliotFriend

docs/build/guides/conversions/address-conversions.mdx

@@ -8,11 +8,11 @@ import { CodeExample } from "@site/src/components/CodeExample";
 
 The `Address` is an opaque type that represents either a 'default' externally owned account on the Stellar network, or a contract (that may also provide logic for custom externally owned accounts, see [authorization docs](../../../learn/fundamentals/contract-development/authorization.mdx#account-abstraction) for details). For the smart contracts it normally doesn't matter which kind of `Address` is used. However, in some contexts it's useful to convert `Address` to/from different data types, such as string or XDR. The conversions have distinctly different purpose depending on whether they happen in the smart contract itself, or in the client code.
 
-# String conversions
+## String conversions
 
 The default string format for `Address` is a so called 'string key' (or 'strkey'), defined fully in [SEP-23](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0023.md). For the default externally owned accounts strkey always starts with `G` and for all the contracts it starts with `C`.
 
-## Conversions in Client SDKs
+### String Conversions in Client SDKs
 
 Outside of the smart contracts, it is convenient to represent `Address` as string most of the time. It can be stored in string serialization formats such as JSON and XML. 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. Thus
 
@@ -30,46 +30,49 @@ const address = new StellarSdk.Address(stellarAddress);
 const addressToString = address.toString();
 ```
 
+```python
+from stellar_sdk import Address
+
+# Example Stellar address
+stellar_address = "GCM5WPR4DDR24FSAX5LIEM4J7AI3KOWJYANSXEPKYXCSZOTAYXE75AFN"
+# Create an Address object from string
+address = Address(stellar_address)
+# Convert the address back to string
+address_to_string = address.address
+```
+
 </CodeExample>
 
-## Conversions in Smart Contracts
+### String Conversions in Smart Contracts
 
 It's generally preferred for contracts to operate directly on the `Address` type. String conversions may be useful for specialized use cases, such as passing the Stellar `Address`es to/from other chains.
 
-<CodeExample>
-
 ```rust
 use soroban_sdk::{Address, String, Env};
 
 pub fn address_to_string(address: Address) -> String {
     address.to_string()
 }
 
-pub fn address_from_string(strkey: &String) -> Address {
-    Address::from_string(strkey)
+pub fn address_from_string(strkey: String) -> Address {
+    Address::from_string(&strkey)
 }
 ```
 
-</CodeExample>
-
 `Address` can also be built from a string literal, which may be useful for testing.
 
-<CodeExample>
-
 ```rust
 let test_address = Address::from_str(
     &env,
     "GCM5WPR4DDR24FSAX5LIEM4J7AI3KOWJYANSXEPKYXCSZOTAYXE75AFN",
 );
 ```
 
-</CodeExample>
-
-# XDR conversions
+## XDR conversions
 
 XDR is schema-based binary serialization format used by the Stellar network. It is used for all the Stellar blockchain interactions, such as building the transactions, storing data in the ledger, communicating the transaction results etc. Stellar SDKs provide the typed wrappers for all the Stellar XDR data types. Address is represented as `ScAddress` type, which can then be wrapped into `ScVal` which is a type that represents any contract type supported by Stellar contracts.
 
-## Conversions in Client SDKs
+### XDR Conversions in Client SDKs
 
 On the client side XDR conversions are useful to build the transactions and process the transaction results.
 
@@ -90,7 +93,7 @@ const scAddress = address.toScAddress();
 ```
 
 ```python
-from stellar_sdk.address import Address
+from stellar_sdk import Address
 
 # Example Stellar address
 stellar_address = 'GBJCHUKZMTFSLOMNC7P4TS4VJJBTCYL3XKSOLXAUJSD56C4LHND5TWUC'
@@ -102,27 +105,23 @@ sc_address_xdr = address.to_xdr_sc_address()
 
 </CodeExample>
 
-## Conversions in Smart Contracts
+### XDR Conversions in Smart Contracts
 
 Smart contracts don't need to explicitly interact with the XDR types, as all the smart contract data types are automatically converted to XDR by the smart contract runtime. Every contract type, including `Address`, can be serialized to XDR bytes. This conversion is useful, for example, for performing hashing in smart contracts. It is also possible to convert the serialized XDR bytes back to contract types, which can be useful in some narrow use cases, such as custom authentication schemes.
 
-Note, that XDR conversions are and advanced feature and are not necessary for most of the Stellar smart contracts.
-
-<CodeExample>
+Note, that XDR conversions are an advanced feature and are not necessary for most Stellar smart contracts.
 
 ```rust
 use soroban_sdk::{
     xdr::{FromXdr, ToXdr},
     Address, Bytes, Env,
 };
 
-pub fn address_to_xdr_bytes(env: &Env, address: Address) -> Bytes {
-    address.to_xdr(env)
+pub fn address_to_xdr_bytes(env: Env, address: Address) -> Bytes {
+    address.to_xdr(&env)
 }
 
-pub fn address_from_xdr_bytes(env: &Env, bytes: &Bytes) -> Address {
-    Address::from_xdr(env, bytes).unwrap()
+pub fn address_from_xdr_bytes(env: Env, bytes: Bytes) -> Address {
+    Address::from_xdr(&env, &bytes).unwrap()
 }
 ```
-
-</CodeExample>

docs/build/guides/conversions/bytes-conversions.mdx

@@ -15,7 +15,7 @@ When retrieving data stored on the blockchain, addresses might be stored in byte
 <CodeExample>
 
 ```rust
-use soroban_sdk::{Address, Bytes, Env};
+use soroban_sdk::{Address, Bytes};
 
 pub fn bytes_to_address(bytes: Bytes) -> Address {
     Address::from_string_bytes(&bytes)
@@ -42,7 +42,7 @@ addressFromBytes.toString();
 from stellar_sdk.address import Address
 
 # Example bytes value
-raw_bytes = bytes.fromhex('99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe')
+raw_bytes = bytes.fromhex("99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe")
 bytes_to_address = Address.from_raw_account(raw_bytes)
 ```
 
@@ -55,16 +55,14 @@ When dealing with binary data, you may need to convert certain portions of the d
 <CodeExample>
 
 ```rust
-use soroban_sdk::{String, Bytes, Env, FromVal};
+use soroban_sdk::{String, Bytes};
 
-pub fn bytes_to_string(env: &Env, bytes: Bytes) -> String {
-  String::from_val(env, &bytes.to_val())
+pub fn bytes_to_string(bytes: Bytes) -> String {
+    String::from(bytes)
 }
 ```
 
 ```js
-const StellarSdk = require("@stellar/stellar-sdk");
-
 // Example bytes value
 const rawBytes = Buffer.from(
   "99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe",
@@ -75,12 +73,10 @@ const bytesToString = rawBytes.toString("hex");
 ```
 
 ```python
-from stellar_sdk.address import Address
-
-# Example bytes
-raw_bytes = b'99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe'
+# Example bytes value
+raw_bytes = bytes.fromhex("99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe")
 # Convert bytes to string
-bytes_to_string = raw_bytes.decode('utf-8')
+bytes_to_string = raw_bytes.hex()
 ```
 
 </CodeExample>
@@ -92,30 +88,26 @@ In a Soroban smart contract that interacts with an external oracle service to pr
 <CodeExample>
 
 ```rust
-use soroban_sdk::{Bytes, Env, FromVal, Val};
+use soroban_sdk::{Bytes, Val};
 
-pub fn bytes_to_val(env: &Env, bytes: Bytes) -> Val {
-    Val::from_val(env, &bytes.to_val())
+pub fn bytes_to_val(bytes: Bytes) -> Val {
+    Val::from(bytes)
 }
 ```
 
 ```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);
+const bytesToScVal = StellarSdk.nativeToScVal(rawBytes);
 ```
 
 ```python
-import stellar_sdk
-
 # Example bytes value
-raw_bytes = b'example_bytes_data'
+raw_bytes = bytes.fromhex("99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe")
 # Convert bytes to ScVal
 sc_val = stellar_sdk.scval.to_bytes(raw_bytes)
 ```

docs/build/guides/conversions/scval-conversions.mdx

@@ -4,98 +4,66 @@ hide_table_of_contents: true
 description: Convert a ScVal to other type
 ---
 
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
+import { CodeExample } from "@site/src/components/CodeExample";
 
 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
+## ScVal to bytes
 
-<Tabs groupId="language">
-<TabItem value="js" label="JS">
+<CodeExample>
 
 ```js
-const StellarSdk = require("@stellar/stellar-sdk");
-
-/* Convert ScVal to bytes */
-const bytesFromScVal = StellarSdk.scVal.bytes();
+// An ScVal bytes value
+const myScVal = StellarSdk.xdr.ScVal.fromXDR("AAAADQAAAARQ/8AB", "base64");
+// Convert the ScVal to a Buffer
+const bytesFromScVal = StellarSdk.scValToNative(myScVal);
 ```
 
-- `.bytes()` converts an ScVal value to bytes.
-- `scVal` is the ScVal value to be converted to bytes.
-
-</TabItem>
-<TabItem value="python" label="Python">
-
 ```python
-import stellar_sdk
-
-# Convert ScVal to bytes
-sc_val_to_bytes = stellar_sdk.scval.from_bytes(sc_val)
+# Convert the ScVal to bytes
+bytes_from_sc_val = stellar_sdk.scval.from_bytes("AAAADQAAAARQ/8AB")
 ```
 
-- `stellar_sdk.scval.from_bytes()` converts an ScVal value to bytes.
-- `sc_val` is the ScVal value to be converted to bytes.
-
-</TabItem>
-</Tabs>
+</CodeExample>
 
 ## ScVal to address
 
-<Tabs groupId="language">
-<TabItem value="js" label="JS">
+<CodeExample>
 
 ```js
-const StellarSdk = require("@stellar/stellar-sdk");
-
-const addressFromScVal = StellarSdk.Address.fromScVal(scVal);
-addressFromScVal.toString();
+// An ScVal Address value
+const myScVal = StellarSdk.xdr.ScVal.fromXDR(
+  "AAAAEgAAAAAAAAAAmds+PBjjrhZAv1aCM4n4EbU6ycAbK5HqxcUsumDFyf4=",
+  "base64",
+);
+// Convert the ScVal to an Address
+const addressFromScVal = StellarSdk.Address.fromScVal(myScVal);
 ```
 
-- `StellarSdk.Address.fromScVal()` converts an ScVal value to an address.
-- `scVal` is the ScVal value to be converted to an address.
-
-</TabItem>
-<TabItem value="python" label="Python">
-
 ```python
-import stellar_sdk
-
-sc_to_address = Address.from_xdr_sc_address(sc_val)
+# Convert the ScVal to address
+address_from_sc_val = stellar_sdk.scval.from_address("AAAAEgAAAAAAAAAAmds+PBjjrhZAv1aCM4n4EbU6ycAbK5HqxcUsumDFyf4=")
 ```
 
-- `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.
-
-</TabItem>
-</Tabs>
+</CodeExample>
 
 ## ScVal to String
 
-<Tabs groupId="language">
-<TabItem value="js" label="JS">
+<CodeExample>
 
 ```js
-const StellarSdk = require("@stellar/stellar-sdk");
-
-const stringFromScVal = scVal.toString("utf-8");
+// An ScVal string value
+const myScVal = StellarSdk.xdr.ScVal.fromXDR(
+  "AAAADgAAAA9IZWxsbywgU3RlbGxhciEA",
+  "base64",
+);
+// Convert the ScVal to a string
+const stringFromScVal = StellarSdk.scValToNative(myScVal);
 ```
 
-`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.
-
-</TabItem>
-<TabItem value="python" label="Python">
-
 ```python
-
-import stellar_sdk
-
-# scval to string
-sc_val_to_string = stellar_sdk.scval.from_string(sc_val)
+# Convert the ScVal to a string
+string_from_sc_val = stellar_sdk.scval.from_string("AAAADgAAAA9IZWxsbywgU3RlbGxhciEA").decode()
 ```
 
-- `stellar_sdk.scval.from_string()` converts an ScVal value to a string.
-- `sc_val` represents the ScVal value to be converted to a string.
-
-</TabItem>
-</Tabs>
+</CodeExample>