docs: unify wallet transfer docs (#2573)

* docs: unify wallet transfer docs

* improving writing

* remove transferring assets doc

* change wait call

* remove the duplicated section

---------

Co-authored-by: Miguel Oliveira <[email protected]>
Co-authored-by: Peter Smith <[email protected]>
Co-authored-by: Daniel Bate <[email protected]>
Co-authored-by: Sérgio Torres <[email protected]>

.changeset/warm-lobsters-film.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs: unify wallet transfer docs

apps/docs/.vitepress/config.ts

@@ -367,10 +367,6 @@ export default defineConfig({
             link: '/guide/cookbook/',
             collapsed: true,
             items: [
-              {
-                text: 'Transferring Assets',
-                link: '/guide/cookbook/transferring-assets',
-              },
               {
                 text: 'Deposit And Withdraw',
                 link: '/guide/cookbook/deposit-and-withdraw',

apps/docs/src/guide/wallets/wallet-transferring.md

@@ -1,43 +1,61 @@
 # Wallet Transferring
 
-This guide demonstrates how to transfer assets between accounts and contracts, and how to validate your balance prior to a transfer.
+This guide provides instructions for transferring assets between wallets and contracts using the SDK. It includes methods to validate balances and initiate and configure transfer requests.
 
-## Transferring Between Wallets
+## Transferring Assets Between Accounts
 
-Transferring assets between wallets is really simple within the SDK.
+The `transfer` method initiates a transaction request that transfers an asset from one wallet to another. This method requires three parameters:
 
-<<< @/../../docs-snippets/src/guide/wallets/wallet-transferring.test.ts#wallet-transferring-1{ts:line-numbers}
+1. The receiver's wallet address
+2. The amount of the asset to be transferred
+3. The ID of the asset to be transferred (optional - defaults to the base asset ID)
 
-After waiting the transaction to be processed, the assets are successfully moved to the recipient's wallet.
+Upon execution, this function returns a promise that resolves to a transaction response. To wait for the transaction to be processed, call `response.waitForResult()`.
 
-It is also possible to specify the recipient's address as a string:
+### Example
 
-<<< @/../../docs-snippets/src/guide/wallets/wallet-transferring.test.ts#wallet-transferring-2{ts:line-numbers}
+Here is an example of how to use the `transfer` function:
 
-When transferring the base chain coin like ETH, you can omit the `assetId`:
+<<< @/../../docs-snippets/src/guide/cookbook/transferring-assets.test.ts#transferring-assets-1{ts:line-numbers}
 
-<<< @/../../docs-snippets/src/guide/wallets/wallet-transferring.test.ts#wallet-transferring-3{ts:line-numbers}
+In the previous example, we used the `transfer` method which creates a `ScriptTransactionRequest`, populates its data with the provided transfer information and submits the transaction.
 
-## Transferring To Multiple Wallets
+However, there may be times when you need the Transaction ID before actually submitting it to the node. To achieve this, you can simply call the `createTransfer` method instead.
 
-To transfer assets to multiple wallets, use the `Account.batchTransfer` method:
+This method also creates a `ScriptTransactionRequest` and populates it with the provided data but returns the request object prior to submission.
 
-<<< @/../../docs-snippets/src/guide/wallets/wallet-transferring.test.ts#wallet-transferring-6{ts:line-numbers}
+<<< @/../../docs-snippets/src/guide/cookbook/transferring-assets.test.ts#transferring-assets-2{ts:line-numbers}
+
+> **Note**: Any changes made to a transaction request will alter the transaction ID. Therefore, you should only get the transaction ID after all modifications have been made.
+
+<<< @/../../docs-snippets/src/guide/cookbook/transferring-assets.test.ts#transferring-assets-3{ts:line-numbers}
+
+## Transferring Assets To Contracts
+
+When transferring assets to a deployed contract, we use the `transferToContract` method, which shares a similar parameter structure with the `transfer` method.
+
+However, instead of supplying the target wallet's address, as done in `destination.address` for the transfer method, we need to provide an instance of [Address](../types/address.md) created from the deployed contract id.
 
-## Transferring To Contracts
+If you have the [Contract](../contracts/) instance of the deployed contract, you can simply use its `id` property. However, if the contract was deployed with `forc deploy` or not by you, you will likely only have its ID in a hex string format. In such cases, you can create an [Address](../types/address.md) instance from the contract ID using `Address.fromAddressOrString('0x123...')`.
 
-Transferring assets from your wallet to a deployed contract is straightforward. All you need is the contract's address.
+Here's an example demonstrating how to use `transferToContract`:
 
-You can transfer assets to a deployed contract instance by using its `id`:
+<<< @/../../docs-snippets/src/guide/cookbook/transferring-assets.test.ts#transferring-assets-4{ts:line-numbers}
 
-<<< @/../../docs-snippets/src/guide/wallets/wallet-transferring.test.ts#wallet-transferring-4{ts:line-numbers}
+Always remember to call the `waitForResult()` function on the transaction response. That ensures the transaction has been mined successfully before proceeding.
+
+
+## Transferring Assets To Multiple Wallets
+
+To transfer assets to multiple wallets, use the `Account.batchTransfer` method:
+
+<<< @/../../docs-snippets/src/guide/wallets/wallet-transferring.test.ts#wallet-transferring-6{ts:line-numbers}
 
-Alternatively, you can simply use the contract's string address in the [`Bech32`](../types/bech32.md) format:
+This section demonstrates additional examples of transferring assets between wallets and to contracts.
 
-<<< @/../../docs-snippets/src/guide/wallets/wallet-transferring.test.ts#wallet-transferring-5{ts:line-numbers}
 
-# Balances
+## Checking Balances
 
 Before transferring assets, ensure your wallet has sufficient funds. Attempting a transfer without enough funds will result in an error: `not enough coins to fit the target`.
 
-You can see how to check your balance at the [`checking-balances`](./checking-balances.md) page.
+You can see how to check your balance at the [`checking-balances`](./checking-balances.md) page.