fix(docs): improve clarity and structure of USDT0 to FXRP swap guide

Author: fassko

docs/fassets/developer-guides/usdt0-fxrp-swap.mdx

@@ -2,7 +2,7 @@
 title: Swap USDT0 to FXRP
 tags: [intermediate, fassets]
 slug: usdt0-fxrp-swap
-description: Swap USDT0 to FXRP tokens using Uniswap V3 router
+description: Swap USDT0 to FXRP using Uniswap V3 router
 keywords: [fassets, flare-network]
 ---
 
@@ -13,20 +13,22 @@ import Remix from "@site/src/components/remix";
 
 ## Overview
 
-In this guide, you will learn how to swap USDT0 to FXRP tokens using the Uniswap V3 router (SparkDEX).
+In this guide, you will learn how to swap USDT0 to FXRP using the Uniswap V3 router (SparkDEX).
 FXRP is the ERC-20 representation of XRP used by [FAssets](/fassets/overview).
 
 ## Prerequisites
 
 Before starting, make sure you have:
 
 - Basic understanding of the [FAssets system](/fassets/overview).
-- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts) package.
+- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts) package installed.
 - Familiarity with [Uniswap V3 swaps](https://docs.uniswap.org/contracts/v3/guides/swaps/single-swaps).
-- Addresses on Flare Mainnet:
-  - V3 SwapRouter (SparkDEX): [0x8a1E35F5c98C4E85B36B7B253222eE17773b2781](https://flarescan.com/address/0x8a1E35F5c98C4E85B36B7B253222eE17773b2781/contract/14/code).
-  - USDT0: [0xe7cd86e13AC4309349F30B3435a9d337750fC82D](https://flarescan.com/address/0xe7cd86e13AC4309349F30B3435a9d337750fC82D).
-  - FXRP: [resolved dynamically from the Asset Manager](/fassets/developer-guides/fassets-fxrp-address).
+
+## Required Addresses on Flare Mainnet
+
+- V3 SwapRouter (SparkDEX): [0x8a1E35F5c98C4E85B36B7B253222eE17773b2781](https://flarescan.com/address/0x8a1E35F5c98C4E85B36B7B253222eE17773b2781/contract/14/code).
+- USDT0: [0xe7cd86e13AC4309349F30B3435a9d337750fC82D](https://flarescan.com/address/0xe7cd86e13AC4309349F30B3435a9d337750fC82D).
+- FXRP: [resolved dynamically from the Asset Manager](/fassets/developer-guides/fassets-fxrp-address).
 
 ## Solidity Uniswap V3 Wrapper Contract
 
@@ -42,45 +44,42 @@ This Solidity contract wraps the Uniswap V3 router, providing safe token transfe
 
 ### Code Explanation
 
-1. Defines the Uniswap V3 router function for swaps, which allows interaction with the Uniswap V3 protocol.
-
-2. `exactInputSingle` function used for direct swaps between two tokens in a single pool.
+1. Define the Uniswap V3 router function for swaps, which allows interaction with the Uniswap V3 protocol.
+   It comes from the [Uniswap V3 periphery](https://github.com/Uniswap/v3-periphery).
 
-3. Uniswap V3 factory interface that returns the factory address responsible for creating pools.
+2. Use the Uniswap V3 factory interface to locate a specific pool for a token pair and the fee tier.
 
-4. Uniswap V3 factory interface, used to locate a specific pool for a given token pair and fee tier.
+3. Define the Uniswap V3 pool interface that provides liquidity and token details for a given pool.
 
-5. The Uniswap V3 pool interface provides liquidity and token details for a given pool.
+4. Create the `UniswapV3Wrapper` contract, which acts as a wrapper around Uniswap V3 to simplify swaps and add safety checks.
 
-6. `UniswapV3Wrapper` contract, which acts as a wrapper around Uniswap V3 to simplify swaps and add safety checks.
+5. Use the existing Uniswap V3 SwapRouter on Flare (SparkDEX) as the main entry point for executing swaps.
 
-7. Existing Uniswap V3 SwapRouter on Flare (SparkDEX), used as the main entry point for executing swaps.
+6. Store the Uniswap V3 factory in the contract for looking up pools.
 
-8. The Uniswap V3 factory is stored in the contract for looking up pools.
+7. Define events that log important actions such as swaps executed, pools checked, and tokens approved.
 
-9. Events, which log important actions such as swaps executed, pools checked, and tokens approved.
+8. Create a constructor that initializes the swap router and factory.
 
-10. Constructor that initializes the swap router and factory, ensuring both references are immutable.
+9. Check if the pool exists and has liquidity, preventing the swaps execution in empty or non-existent pools.
 
-11. Check if the pool exists and has liquidity, preventing execution of swaps in empty or non-existent pools.
+10. Create a swap exact input single function that executes a single-hop swap through the Uniswap V3 router protocol.
 
-12. Swap exact input single function, which executes a single-hop swap through the Uniswap V3 router protocol.
+    10.1. Check if pool exists, ensuring a valid pool address is returned.
 
-    12.1. Check if pool exists, ensuring a valid pool address is returned.
+    10.2. Check if the pool has liquidity, requiring the available liquidity is greater than zero.
 
-    12.2. Check if the pool has liquidity, requiring that the available liquidity is greater than zero.
+    10.3. Transfer tokens from the user to this contract, using SafeERC20 for secure transfers.
 
-    12.3. Transfer tokens from user to this contract, using SafeERC20 for secure transfers.
+    10.4. Approve the router to spend tokens using the `SafeERC20` library, allowing the router to perform the swap.
 
-    12.4. Approve router to spend tokens using the `SafeERC20` library, allowing the router to perform the swap.
+    10.5. Prepare swap parameters, filling the `ExactInputSingleParams` struct with all necessary details.
 
-    12.5. Prepare swap parameters, filling the `ExactInputSingleParams` struct with all necessary details.
+    10.6. Execute the swap, calling the `swapRouter.exactInputSingle` function to perform the transaction.
 
-    12.6. Execute swap, calling `swapRouter.exactInputSingle` function to perform the transaction.
+    10.7. Emit the swap executed event, logging details about the user, tokens, and amounts.
 
-    12.7. Emit swap executed event, logging details about the user, tokens, and amounts.
-
-## Execute the Swap
+## Execute the Swap with Hardhat
 
 To execute a swap, you need to deploy the wrapper contract and call `swapExactInputSingle` with the swap parameters.
 
@@ -93,41 +92,29 @@ To execute a swap, you need to deploy the wrapper contract and call `swapExactIn
 
 ### Code Breakdown
 
-1. Contract artifacts are imported, including `IAssetManager`, `UniswapV3Wrapper`, and `ERC20`, which provide access to the deployed contracts.
+1. Import contract artifacts, including `IAssetManager`, `UniswapV3Wrapper`, and `ERC20`, which provide access to the deployed contracts.
 
-2. Flare Uniswap V3 addresses (SparkDEX) are defined, specifying the SwapRouter address used for executing swaps.
+2. Define Flare Uniswap V3 addresses (SparkDEX), specifying the SwapRouter address used for executing swaps.
 
-3. USDT0 token address on Flare Mainnet, which represents the stablecoin used as the input asset for the swap.
+3. Set the USDT0 token address on Flare Mainnet, which represents the stablecoin used as the input asset for the swap.
 
-4. Pool fee tier is set to 500 (0.05%), which defines the fee level of the pool to use on the Uniswap V3 router (SparkDEX).
+4. Set the pool fee tier to 500 (0.05%), which defines the fee level of the pool to use on the Uniswap V3 router (SparkDEX).
 
-5. Swap parameters are defined.
+5. Define swap parameters.
 
 6. Define the function `deployAndVerifyContract()` that deploys the UniswapV3Wrapper contract and verifies it on the blockchain explorer.
 
-7. The `main()` function is the entry point to execute the complete swap logic.
-
-8. Deploy and verify the `UniswapV3Wrapper` smart contract, retrieving its deployed address for later use.
-
-9. Get the deployer account using `web3.eth.getAccounts()`.
-
-10. Retrieve the FXRP token address dynamically from the Asset Manager contract.
-
-11. Define USDT0 and FXRP contract instances.
-
-12. Check the deployer account's initial balances of USDT0 and FXRP.
-
-13. Verify that there is enough USDT0 to perform the swap.
+7. Create the `setupAndInitializeTokens()` function that prepares accounts and ERC20 contracts.
 
-14. Check the Uniswap V3 pool using the wrapper contract to ensure that the USDT0/FXRP pool exists and has liquidity.
+8. Define the `verifyPoolAndLiquidity()` function which ensures the USDT0/FXRP pool exists and is usable.
 
-15. Approve the USDT0 token to the wrapper contract, allowing it to spend the tokens on behalf of the deployer.
+9. Create the `approveUsdt0ForSwap()` function that approves the wrapper contract to spend USDT0 on behalf of the deployer.
 
-16. Execute the swap using the UniswapV3Wrapper contract's `swapExactInputSingle` method.
+10. Create the `executeSparkDexSwap()` function that executes the swap on SparkDEX using the Uniswap V3 wrapper.
 
-17. Extract the swap result by checking the new FXRP balance and calculating the difference from the initial balance.
+11. Create the `checkFinalBalances()` function that verifies the swap results.
 
-18. Check final balances after the swap to verify execution.
+12. Create the `main()` function that orchestrates the entire flow of the swap.
 
 ### Run the Script
 
@@ -145,11 +132,12 @@ This script is included in the [Flare Hardhat Starter Kit](/network/guides/hardh
 
 In this guide, you learned how to swap USDT0 to FXRP using the Uniswap V3 router (SparkDEX).
 
-:::tip[What's next]
+:::tip
 
 To continue your FAssets development journey, you can:
 
-- Learn how to [mint FAssets using the executor](/fassets/developer-guides/fassets-mint-executor).
+- Learn how to [mint FXRP](/fassets/developer-guides/fassets-mint).
 - Understand how to [redeem FXRP](/fassets/developer-guides/fassets-redeem).
+- Explore [FAssets system settings](/fassets/operational-parameters).
 
 :::

examples/developer-hub-javascript/uniswapV3Wrapper.ts

@@ -40,7 +40,7 @@ async function deployAndVerifyContract() {
       address: uniswapV3WrapperAddress,
       constructorArguments: args,
     });
-  } catch (e: unknown) {
+  } catch (e: any) {
     console.log(e);
   }
 
@@ -49,21 +49,15 @@ async function deployAndVerifyContract() {
   return uniswapV3Wrapper;
 }
 
-// 7. The main function to execute the swap
-async function main() {
-  // 8. Deploy and verify the UniswapV3 wrapper smart contract and get its address
-  const uniswapV3Wrapper: UniswapV3WrapperInstance =
-    await deployAndVerifyContract();
-  const uniswapV3WrapperAddress = await uniswapV3Wrapper.address;
-
-  // 9. Get the deployer account
+// 7. Function to setup and initialize tokens
+async function setupAndInitializeTokens() {
   const accounts = await web3.eth.getAccounts();
   const deployer = accounts[0];
 
   console.log("Deployer:", deployer);
   console.log("Total accounts available:", accounts.length);
 
-  // 10. Get the FXRP address on Flare (from the Asset Manager)
+  // FXRP address on Flare (from asset manager)
   const assetManager = await getAssetManagerFXRP();
   const FXRP = await assetManager.fAsset();
 
@@ -74,11 +68,10 @@ async function main() {
   console.log("Amount Out Min:", AMOUNT_OUT_MIN.toString());
   console.log("");
 
-  // 11. Define the USDT0 and FXRP token addresses
   const usdt0: ERC20Instance = await ERC20.at(USDT0);
   const fxrp: ERC20Instance = await ERC20.at(FXRP);
 
-  // 12. Check initial balances
+  // Check initial balances
   const initialUsdt0Balance = BigInt(
     (await usdt0.balanceOf(deployer)).toString(),
   );
@@ -89,7 +82,7 @@ async function main() {
   console.log("Initial USDT0 balance:", initialUsdt0Balance.toString());
   console.log("Initial FXRP balance:", initialFxrpBalance.toString());
 
-  // 13. Check if there is enough USDT0 to perform the swap
+  // Check if there are enough USDT0
   const amountInBN = AMOUNT_IN;
   if (initialUsdt0Balance < amountInBN) {
     console.log(
@@ -101,11 +94,20 @@ async function main() {
     console.log(
       "Please ensure you have sufficient USDT0 tokens to perform the swap.",
     );
-    return;
+    throw new Error("Insufficient USDT0 balance");
   }
 
-  // 14 Check Uniswap V3 pool using wrapper if it exists and has liquidity
-  console.log("\n=== Step 1: Pool Verification ===");
+  return { deployer, usdt0, fxrp, initialUsdt0Balance, initialFxrpBalance };
+}
+
+// 8. Function to verify the pool and liquidity
+async function verifyPoolAndLiquidity(
+  uniswapV3Wrapper: UniswapV3WrapperInstance,
+) {
+  console.log("\n=== Pool Verification ===");
+  const assetManager = await getAssetManagerFXRP();
+  const FXRP = await assetManager.fAsset();
+
   const poolInfo = await uniswapV3Wrapper.checkPool(USDT0, FXRP, FEE);
   console.log("Pool info:", poolInfo);
   const poolAddress = poolInfo.poolAddress;
@@ -119,26 +121,38 @@ async function main() {
   if (poolAddress === "0x0000000000000000000000000000000000000000") {
     console.log("❌ Pool does not exist for this token pair and fee tier");
     console.log("Please check if the USDT0/FXRP pool exists on SparkDEX");
-    return;
+    throw new Error("Pool does not exist");
   }
 
   if (!hasLiquidity) {
     console.log("❌ Pool exists but has no liquidity");
-    return;
+    throw new Error("Pool has no liquidity");
   }
 
   console.log("✅ Pool verification successful!");
+  return { poolAddress, hasLiquidity, liquidity };
+}
 
-  // 15. Approve USDT0 to wrapper contract to spend the tokens
-  console.log("\n=== Step 2: Token Approval ===");
+// 9. Function to approve USDT0 for the swap
+async function approveUsdt0ForSwap(
+  usdt0: ERC20Instance,
+  uniswapV3WrapperAddress: string,
+) {
+  console.log("\n=== Token Approval ===");
   const approveTx = await usdt0.approve(
     uniswapV3WrapperAddress,
     AMOUNT_IN.toString(),
   );
   console.log("✅ USDT0 approved to wrapper contract", approveTx);
+  return approveTx;
+}
+
+// 10. Function to execute the SparkDEX swap
+async function executeSparkDexSwap(uniswapV3Wrapper: UniswapV3WrapperInstance) {
+  console.log("\n=== Execute SparkDEX Swap ===");
+  const assetManager = await getAssetManagerFXRP();
+  const FXRP = await assetManager.fAsset();
 
-  // 16. Execute swap using the Uniswap V3 wrapper contract
-  console.log("\n=== Step 3: Execute SparkDEX Swap ===");
   const deadline = Math.floor(Date.now() / 1000) + 20 * 60; // 20 minutes
   console.log("Deadline:", deadline);
 
@@ -150,21 +164,27 @@ async function main() {
     AMOUNT_IN.toString(),
     AMOUNT_OUT_MIN.toString(),
     deadline,
-    0, // sqrtPriceLimitX96 = 0 (no limit)
+    0, // sqrtPriceLimitX96 = 0 (no limit for the price)
+    // https://docs.uniswap.org/contracts/v3/guides/swaps/single-swaps#swap-input-parameters
   );
 
   console.log("Transaction submitted:", swapTx);
 
-  await swapTx.receipt;
+  const swapReceipt = await swapTx.receipt;
   console.log("✅ SparkDEX swap executed successfully!");
 
-  // 17. Extract amount out from events or calculate from balance change
-  const finalFxrpBalance = BigInt((await fxrp.balanceOf(deployer)).toString());
-  const amountOut = finalFxrpBalance - initialFxrpBalance;
-  console.log("Amount out:", amountOut.toString());
+  return { swapTx, swapReceipt };
+}
 
-  // 18. Check final balances to verify the swap
-  console.log("\n=== Step 4: Final Balances ===");
+// 11. Function to check the final balances
+async function checkFinalBalances(
+  usdt0: ERC20Instance,
+  fxrp: ERC20Instance,
+  deployer: string,
+  initialUsdt0Balance: bigint,
+  initialFxrpBalance: bigint,
+) {
+  console.log("\n=== Final Balances ===");
   const finalUsdt0Balance = BigInt(
     (await usdt0.balanceOf(deployer)).toString(),
   );
@@ -182,6 +202,31 @@ async function main() {
     "FXRP received:",
     (finalFxrpBalanceAfter - initialFxrpBalance).toString(),
   );
+
+  return { finalUsdt0Balance, finalFxrpBalanceAfter };
+}
+
+// 12. The main function to execute the complete swap logic and verify the results
+async function main() {
+  const uniswapV3Wrapper: UniswapV3WrapperInstance =
+    await deployAndVerifyContract();
+
+  const { deployer, usdt0, fxrp, initialUsdt0Balance, initialFxrpBalance } =
+    await setupAndInitializeTokens();
+
+  await verifyPoolAndLiquidity(uniswapV3Wrapper);
+
+  await approveUsdt0ForSwap(usdt0, uniswapV3Wrapper.address);
+
+  await executeSparkDexSwap(uniswapV3Wrapper);
+
+  await checkFinalBalances(
+    usdt0,
+    fxrp,
+    deployer,
+    initialUsdt0Balance,
+    initialFxrpBalance,
+  );
 }
 
 main().catch((error) => {