Guide for type conversions (#839)

* add guide for type conversions

* resolve merge conflict

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
+
+<Tabs groupId="language" defaultValue="rust">
+    <TabItem value="rust" label="Rust">
+
+    ```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
+    }
+    ```
+    </TabItem>
+
+  <TabItem value="js" label="JS">
+    ```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();
+    ```
+
+  </TabItem>
+
+    <TabItem value="python" label="Python">
+
+    ```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)
+    ```
+    </TabItem>
+
+</Tabs>
+
+## 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.
+
+<Tabs groupId="language" defaultValue="rust">
+    <TabItem value="rust" label="Rust">
+
+    ```rust
+    use soroban_sdk::{Address, String, Env};
+
+    pub fn address_to_string(address: Address) -> String {
+      address.to_string()
+    }
+    ```
+    </TabItem>
+
+  <TabItem value="js" label="JS">
+
+    ```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();
+    ```
+
+  </TabItem>
+
+</Tabs>
+
+# 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.
+
+<Tabs groupId="language" defaultValue="rust">
+    <TabItem value="rust" label="Rust">
+
+    ```rust
+    use soroban_sdk::{Address, Val};
+
+    pub fn address_to_sc_val(address: Address) -> Val {
+      address.to_val()
+    }
+    ```
+    </TabItem>
+
+  <TabItem value="js" label="JS">
+
+    ```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();
+    ```
+
+  </TabItem>
+
+    <TabItem value="python" label="Python">
+
+    ```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()
+    ```
+    </TabItem>
+
+</Tabs>

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.
+
+<Tabs groupId="language" defaultValue="rust">
+    <TabItem value="rust" label="Rust">
+
+    ```rust
+    use soroban_sdk::{Address, Bytes, Env};
+
+    pub fn bytes_to_address(bytes: Bytes) -> Address {
+      Address::from_string_bytes(&bytes)
+    }
+    ```
+    </TabItem>
+
+  <TabItem value="js" label="JS">
+
+    ```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();
+    ```
+
+  </TabItem>
+
+  <TabItem value="python" label="Python">
+
+    ```python
+    from stellar_sdk.address import Address
+
+    # Example bytes value
+    raw_bytes = bytes.fromhex('99db3e3c18e3ae1640bf56823389f811b53ac9c01b2b91eac5c52cba60c5c9fe')
+    bytes_to_address = Address.from_raw_account(raw_bytes)
+    ```
+    </TabItem>
+
+</Tabs>
+
+## 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.
+
+<Tabs groupId="language" defaultValue="rust">
+  <TabItem value="rust" label="Rust">
+
+    ```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())
+    }
+    ```
+
+  </TabItem>
+
+  <TabItem value="js" label="JS">
+
+    ```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');
+    ```
+
+  </TabItem>
+
+    <TabItem value="python" label="Python">
+
+    ```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')
+    ```
+    </TabItem>
+
+</Tabs>
+
+## 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.
+
+<Tabs groupId="language" defaultValue="rust">
+    <TabItem value="rust" label="Rust">
+  
+    ```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())
+    }
+
+    ```
+    </TabItem>
+
+    <TabItem value="js" label="JS">
+
+    ```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);
+    ```
+
+  </TabItem>
+
+  <TabItem value="python" label="Python">
+
+    ```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)
+    ```
+
+  </TabItem>
+</Tabs>

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
+
+<Tabs groupId="language">
+  <TabItem value="js" label="JS">
+
+    ```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.
+
+  </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)
+
+    ```
+    `stellar_sdk.scval.from_bytes()` converts an ScVal value to bytes.
+    `sc_val` is the ScVal value to be converted to bytes.
+    </TabItem>
+
+</Tabs>
+
+## ScVal to address
+
+<Tabs groupId="language">
+  <TabItem value="js" label="JS">
+
+    ```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.
+
+  </TabItem>
+
+  <TabItem value="python" label="Python">
+
+    ```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.
+
+    </TabItem>
+
+</Tabs>
+
+## ScVal to String
+
+<Tabs groupId="language">
+  <TabItem value="js" label="JS">
+
+    ```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.
+
+  </TabItem>
+
+    <TabItem value="python" label="Python">
+
+    ```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.
+    </TabItem>
+
+</Tabs>