From c7ba7a103056099925b8a9768a6fc5645e593aba Mon Sep 17 00:00:00 2001 From: Miguel Tavares <88039515+mvares@users.noreply.github.com> Date: Mon, 8 Jul 2024 06:13:31 -0300 Subject: [PATCH] docs: unify wallet transfer docs (#2573) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: unify wallet transfer docs * improving writing * remove transferring assets doc * change wait call * remove the duplicated section --------- Co-authored-by: Miguel Oliveira <88039515+msensys@users.noreply.github.com> Co-authored-by: Peter Smith Co-authored-by: Daniel Bate Co-authored-by: Sérgio Torres <30977845+Torres-ssf@users.noreply.github.com> --- .changeset/warm-lobsters-film.md | 4 ++ apps/docs/.vitepress/config.ts | 4 -- .../src/guide/cookbook/transferring-assets.md | 47 --------------- .../src/guide/wallets/wallet-transferring.md | 58 ++++++++++++------- 4 files changed, 42 insertions(+), 71 deletions(-) create mode 100644 .changeset/warm-lobsters-film.md delete mode 100644 apps/docs/src/guide/cookbook/transferring-assets.md diff --git a/.changeset/warm-lobsters-film.md b/.changeset/warm-lobsters-film.md new file mode 100644 index 00000000000..0b1ee72cfb5 --- /dev/null +++ b/.changeset/warm-lobsters-film.md @@ -0,0 +1,4 @@ +--- +--- + +docs: unify wallet transfer docs \ No newline at end of file diff --git a/apps/docs/.vitepress/config.ts b/apps/docs/.vitepress/config.ts index 5308cb9f8bc..ee23c150c52 100644 --- a/apps/docs/.vitepress/config.ts +++ b/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', diff --git a/apps/docs/src/guide/cookbook/transferring-assets.md b/apps/docs/src/guide/cookbook/transferring-assets.md deleted file mode 100644 index fb7a09027d8..00000000000 --- a/apps/docs/src/guide/cookbook/transferring-assets.md +++ /dev/null @@ -1,47 +0,0 @@ -# Transferring Assets - -This documentation provides a guide on how to transfer assets between wallets and to contracts using the SDK. - -## Transferring Assets Between Accounts - -The `account.transfer` method is used to initiate a transaction request that transfers an asset from one wallet to another. This method requires three parameters: - -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). - -Upon execution, this function returns a promise that resolves to a transaction response. To wait for the transaction to be processed, call `response.wait()`. - -### Example - -Here is an illustration on how to use the `account.transfer` function: - -<<< @/../../docs-snippets/src/guide/cookbook/transferring-assets.test.ts#transferring-assets-1{ts:line-numbers} - -In the previous example, we used the `transfer` method, which essentially creates a `ScriptTransactionRequest`, populates its data with the provided transfer information, and submits the transaction request to the node. - -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. - -This method also creates a `ScriptTransactionRequest` and populates it with the provided data, but instead of submitting it to the node, it returns the request. - -<<< @/../../docs-snippets/src/guide/cookbook/transferring-assets.test.ts#transferring-assets-2{ts:line-numbers} - -It's important to be aware that once you have this transaction request, any modifications made to it will result in a new and distinct transaction. Consequently, this will lead to a different transaction ID. Therefore, make sure to not changing the transaction request if you expects the ID to remain the same. - -<<< @/../../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. This method closely mirrors the `account.transfer` method in terms of parameter structure. - -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. - -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...')`. - -### Example - -Here's an example demonstrating how to use `transferToContract`: - -<<< @/../../docs-snippets/src/guide/cookbook/transferring-assets.test.ts#transferring-assets-4{ts:line-numbers} - -Remember to always invoke the `waitForResult()` function on the transaction response. This ensures that the transaction has been successfully mined before proceeding. diff --git a/apps/docs/src/guide/wallets/wallet-transferring.md b/apps/docs/src/guide/wallets/wallet-transferring.md index 6a0f5783530..402343e5be0 100644 --- a/apps/docs/src/guide/wallets/wallet-transferring.md +++ b/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. \ No newline at end of file