Merge pull request #18 from CoinFabrik/feat/bitcoin-swap-update

Bitcoin Native Swap

docs/README.md

@@ -1,12 +1,17 @@
 ---
 cover: .gitbook/assets/alexlab_doc_cover.jpg
 coverY: 0
+
+
 ---
+
+<!-- 
 {% hint style="danger" %}
 🔥🌶️ Don't miss out! We've just launched the new [Bitcoin Native Token Swaps app](https://app.alexlab.co/bitcoin/swap)! 🌶️🔥
 
 [Read more here...](product-features/bitcoin-swaps/README.md)
 {% endhint %}
+ -->
 
 ALEX is building the finance layer on Bitcoin. The ALEX DEX is the largest on Bitcoin layers (Stacks Chain) fully integrated with XLink, our cross-chain bridge aggregating liquidity across L2s and multi-chain, with LISA as our liquid staking platform.&#x20;
 

docs/SUMMARY.md

@@ -2,12 +2,19 @@
 
 * [What is ALEX](README.md)
 
+<!-- 
 ## 🌶️ What is new?
 * [🔥 Bitcoin Native Swaps](product-features/bitcoin-swaps/README.md)
+ -->
+
 
 
 ## Features
 
+* [🌶️ Bitcoin Native Swap](product-features/bitcoin-swaps/README.md)
+  * [💡 Key concepts](product-features/bitcoin-swaps/key-concepts.md)
+  * [🧑‍🏫 How to swap](product-features/bitcoin-swaps/how-to.md)
+  * [❓ FAQs](product-features/bitcoin-swaps/faqs.md)
 * [🔄 Token Swaps](product-features/token-swaps/README.md)
   * [💡 Key concepts](product-features/token-swaps/key-concepts.md)
   * [🧑‍🏫 How to swap](product-features/token-swaps/how-to.md)
@@ -16,12 +23,12 @@
   * [💡 Key concepts](product-features/liquidity-pools/key-concepts.md)
   * [🧑‍🏫 How to add/remove liquidity](product-features/liquidity-pools/how-to.md)
   * [❓ FAQs](product-features/liquidity-pools/faqs.md)
-  * [📝 Self-Service Listing](product-features/self-service-listing.md)
+  * [📝 Self-service listing](product-features/self-service-listing.md)
 * [🌾 Farming](product-features/farming/README.md)
   * [💡 Key concepts](product-features/farming/key-concepts.md)
   * [🧑‍🏫 How to farm & harvest](product-features/farming/how-to.md)
   * [❓ FAQs](product-features/farming/faqs.md)
-  * [🧑‍🌾 Self-Service Farming](product-features/self-service-farming.md)
+  * [🧑‍🌾 Self-service farming](product-features/self-service-farming.md)
 * [⚓ Stake](product-features/staking/README.md)
   * [💡 Key concepts](product-features/staking/key-concepts.md)
   * [🧑‍🏫 How to stake](product-features/staking/how-to.md)

docs/product-features/bitcoin-swaps/README.md

@@ -13,15 +13,17 @@ layout:
     visible: false
 ---
 
-# 🔥 Bitcoin Native Swaps
 
-The new Bitcoin-native token swaps offers the most practical way to exchange tokens. This method is easier, faster, and less exposed to price variations compared to bridging, swapping and bridging back. Best of all, you can complete the entire process securely in a single step—right from the comfort of your favorite blockchain.
+# Bitcoin Native Swap
 
-## 👉 Get started now
 
-Go to [ALEX Lab App](https://app.alexlab.co) and select **Bitcoin** in the upper left corner of the page or go directly to [app.alexlab.co/bitcoin/swap](https://app.alexlab.co/bitcoin/swap/).
+The Bitcoin Native Swap offers the most practical way to exchange tokens. This method is easier, faster, and less exposed to 
+price variations compared to bridging, swapping and bridging back. Best of all, you can complete the entire process securely 
+in a single step—right from the comfort of your favorite blockchain.
+
+
+👉 Get started now: Go to our swap dApp and select Bitcoin in the upper left corner of the page or go [here](https://app.alexlab.co/bitcoin/swap/).
 
-<!--
 
 ## Explore
 
@@ -29,7 +31,6 @@ Go to [ALEX Lab App](https://app.alexlab.co) and select **Bitcoin** in the upper
 {% content-ref url="how-to.md" %} [how-to.md](how-to.md) {% endcontent-ref %}
 {% content-ref url="faqs.md" %} [faqs.md](faqs.md) {% endcontent-ref %}
 
--->
 
 ## Support
 

docs/product-features/bitcoin-swaps/faqs.md

@@ -0,0 +1,46 @@
+---
+description: Common questions you may have when dealing with the Bitcoin Native Swap.
+---
+
+# ❓ FAQs
+
+<details>
+
+<summary>Why should I use the ALEX Bitcoin Native Swap instead of performing the operations myself?</summary>
+
+The main benefit of the **Bitcoin Native Swap** on ALEX is that it ensures you won't miss the chance to execute a transaction at your desired exchange rate. Since the swap is performed automatically, you don't have to worry about price fluctuations that may occur if you perform the operation manually. 
+From a user perspective, the Bitcoin Native Swap also simplifies an otherwise lengthy process. You can execute the swap in just one operation instead of interacting with multiple wallets, networks, or contracts. Should any error occur in any of the intermediate steps, the whole process will revert, allowing you control over the entire swap.
+
+</details>
+
+<details>
+
+<summary>Will my fees be lower or higher than in a manual operation?</summary>
+
+Fees depend on many variables, such as transaction size and pool liquidity. The **Bitcoin Native Swap** performs the same operations as you would in a manual operation, so fees should be roughly equal. They may be slightly higher than in a manual operation if, for example, the fees drop in the extra minutes it takes you to complete the steps yourself. However, the difference is negligible. If anything, fees may be slightly lower since Bitcoin Native Swap finds the most optimal route for your transaction.
+
+</details>
+
+<details>
+
+<summary>Why are my tokens being converted to other tokens before being swapped for my target token?</summary>
+
+The ALEX Bitcoin Native Swap may use intermediate tokens to complete the exchange because it is designed to find the most optimal route for the swap. Sometimes, there may not be a liquidity pool trading both the base and the target token, so the **Bitcoin Native Swap** must use other liquidity pools to complete the exchange. The route, as well as the fee, will always be displayed before your transaction is confirmed.
+
+</details>
+
+<details>
+
+<summary>How are swaps and liquidity pools related?</summary>
+
+When you perform a swap on ALEX, you are interacting with liquidity pools. Each pool contains two tokens, which makes it possible to exchange one for the other. Besides, the exchange rate of the swap is determined by the price of the tokens in the pool via an Automated Market Maker (AMM). 
+
+</details>
+
+<details>
+
+<summary>What is the difference between a swap fee and a liquidity provider fee?</summary>
+
+The liquidity provider fee is the amount paid by the user to the Liquidity Providers of the pool that is being used for the swap. The swap fee, in this case, refers to the fee that is being distributed to the ALEX Lab Platform for facillitating the exchange.
+
+</details>

docs/product-features/bitcoin-swaps/how-to.md

@@ -0,0 +1,110 @@
+---
+description: This guide will showcase how to swap two tokens on ALEX Lab App.
+---
+
+# 🧑‍🏫 How to Swap on Bitcoin
+
+When performing a token swap, you transfer an amount of the token you want to exchange (base token) to the ALEX smart contract. In return, you receive a pre-agreed amount of the desired token (target token) from the ALEX smart contract, all within a single swap transaction. The resulting balance changes will be reflected in your wallet.
+
+That said, let's get hands-on!
+
+## :currency\_exchange: :moneybag: Trade One Token for Another
+
+### Step 1: Head to the Bitcoin Swap Panel
+
+Go to [https://app.alexlab.co/](https://app.alexlab.co/) to see the Swap panel. You can also navigate to it by clicking the `Swap` tab on the top menu bar. By default, the `Swap` section will be set to the Stacks Native Swap. For the **Bitcoin Native Swap**, select `Bitcoin` on the slider in the top left corner.
+
+<div>
+
+<figure><img src="../../.gitbook/assets/token-swaps/1-swap-tab.png" alt="" width="375"><figcaption></figcaption>Swap tab</figure>
+
+<figure><img src="../../.gitbook/assets/bitcoin-swap/bitcoin-swap-slider.png" alt="" width="375"><figcaption>Bitcoin Swap slider</figcaption></figure>
+
+</div>
+
+<div>
+
+<figure><img src="../../.gitbook/assets/bitcoin-swap/bitcoin-swap-start.png" alt=""><figcaption>Bitcoin Swap panel</figcaption></figure> 
+
+</div>
+
+### Step 2: Select Tokens and Amount
+
+Select the tokens you want to exchange and enter the amount.
+
+* The token at the top is the **base** token, the token you currently hold and want to exchange.
+* The token below is the **quoted** or **target** token, the token you will receive in the trade.
+* The dropdown arrow next to the token symbol will open the **token search** and **selection panel**.
+* Below the amounts, you will find the current **exchange rate**, as well as the USD equivalent.
+* The central down-pointing arrow shows the **direction of the transaction**. In the example below, BTC will be exchanged for ALEX. By clicking the arrow, you can quickly **invert** the order of the transaction: the base token becomes the quoted token and vice versa.
+
+<figure><img src="../../.gitbook/assets/bitcoin-swap/bitcoin-swap-panel.png" alt=""><figcaption><p>Example of the Bitcoin Swap panel</p></figcaption></figure>
+
+{% hint style="warning" %}
+Clicking the `Max` button will automatically set the amount to your total available balance.
+{% endhint %}
+
+<figure><img src="../../.gitbook/assets/bitcoin-swap/bitcoin-swap-token-list.png" alt=""><figcaption><p>Token search and selection panel.</p></figcaption></figure>
+
+### Step 3: Check Transaction Details
+
+#### Transaction Details
+
+Check the transaction details by clicking the dropdown `Details` arrow below the amounts. This will expand a Details panel with relevant trading information.
+
+<figure><img src="../../.gitbook/assets/bitcoin-swap/bitcoin-swap-enter-amount.png" alt=""><figcaption><p>Bitcoin Swap panel with Transaction Details panel expanded.</p></figcaption></figure>
+
+* **Route:** The exchange route to convert from the base token into the target token. In the example we see STX -> ALEX, indicating it is a one-step or direct swap. Bear in mind that some transactions may require intermediate swaps.
+* **Swap Slippage:** The maximum percentage of price movement you'll accept between the time you submit the transaction and its execution. The default slippage tolerance setting is 4%, but you can select a custom percentage by clicking on the edit button. If price movement exceeds the slippage tolerance, the transaction will be reverted.
+* **Liquidity Provider Fee:** The portion of the fee that is distributed between the Liquidity Providers (LPs) to incentivize them to continue providing liquidity.
+* **Price Impact:** How much your swap affects the exchange rate.
+* **Minimum Received:** The minimum amount of target token you will receive considering the maximum slippage variation. For example, if the Swap Slippage is set to the default value of 4% and you expect to receive 100 target tokens, the Minimum Received will be 96 target tokens.
+* **Swap Fee:** The cost associated with performing a swap, excluding the Liquidity Provider Fee. It is deducted from the base token amount and it is distributed to the ALEX Lab Platform.
+
+You can find more information on the aforementioned fields on the [Key Concepts Section](./key-concepts.md). 
+
+Below the Details panel, you will see the **Network Fee**, which is the amount of tokens paid to the Bitcoin network to incentivize miners to continue validating transactions. You can set your preferred fee with the :pencil: "edit" button.
+
+<figure><img src="../../.gitbook/assets/bitcoin-swap/bitcoin-swap-edit-fee.png" alt=""><figcaption><p>Edit Fee panel</p></figcaption></figure>
+
+#### Transaction Settings
+
+If you want to adjust the **Swap Slippage**, select the "Edit" button to the right of the Swap Slippage field to open the **Transaction Settings** pop up. This will show a `Recommended` Slippage Tolerance, set at 4%, and an option to **Customize** the tolerance. Set your desired tolerance and click `Confirm`. This will determine your allowed range for price movement. Your transaction will revert if the price changes unfavourably by more than this percentage.
+
+<div>
+<figure><img src="../../.gitbook/assets/bitcoin-swap/bitcoin-swap-edit-slippage.png" alt="" width="375"><figcaption>Edit Swap Slippage button</figcaption></figure></div>
+
+<figure><img src="../../.gitbook/assets/bitcoin-swap/bitcoin-swap-transaction-settings.png" alt="" width="375"><figcaption><p>Transaction Settings panel example, with slippage tolerance set to 2%.</p></figcaption></figure>
+</div>
+
+### Step 4: Confirm Transaction
+
+Once you're ready to move ahead, select the `Swap` button which will bring up the Confirmation panel. This panel provides a final overview of your transaction details, allowing you to double-check price, route, fees and slippage. If everything looks good, click `Confirm` 😎.
+
+### Step 5: Confirm Transaction in your Wallet
+
+After clicking `Confirm`, you will need to confirm the transaction in your wallet. Here, your Bitcoin wallet is interacting with the ALEX smart contract and is asking you for approval. Scroll through the wallet transaction window, review it and confirm the transaction. By doing this, you are allowing the wallet to sign and broadcast the transaction.
+
+<div><figure><img src="../../.gitbook/assets/bitcoin-swap/bitcoin-swap-wallet-confirm-1.png" alt="" width="375"><figcaption><p>Transfer amounts involved and expandable details.</p></figcaption></figure> <figure><img src="../../.gitbook/assets/bitcoin-swap/bitcoin-swap-wallet-confirm-2.png" alt="" width="375"><figcaption><p>Inputs and outputs and confirmation button.</p></figcaption></figure></div>
+
+### Step 6: Wait for Confirmation <a href="#step-7" id="step-7"></a>
+
+Wait for the transaction to be confirmed on the network.
+
+{% hint style="info" %}
+Recommended to track transaction status:
+
+* Turn on [Telegram notifications](https://t.me/stacks_tx_notification_bot), you will get notified when the transaction is confirmed.
+* Search for the transaction on the [ALEX Explorer](https://app.alexlab.co/explorer).
+* Check your address activity on the wallet.
+{% endhint %}
+
+<div><figure><img src="../../.gitbook/assets/token-swaps/6-tg-tx-pending.png" alt="" width="345"><figcaption><p>Telegram message with transaction pending status.</p></figcaption></figure> <figure><img src="../../.gitbook/assets/token-swaps/6-tg-tx-success.png" alt="" width="350"><figcaption><p>Telegram message with transaction success status.</p></figcaption></figure></div>
+
+### Step 7: Check the Updated Balance
+
+Once the transaction is completed, you will see the balance updated in your wallet.
+
+Thank you for successfully swapping on ALEX! :white\_check\_mark:
+
+

docs/product-features/bitcoin-swaps/key-concepts.md

@@ -0,0 +1,51 @@
+---
+description: Learn the key terms involved in swap operations.
+---
+
+# 💡 Key concepts
+
+### Token Swap
+
+A Token Swap is the exchange or trade of a certain amount of one crypto asset for another. In ALEX Lab Platform, swaps are performed on the ALEX's decentralized exchange (DEX) and are facilitated by liquidity pools. 
+
+### Base Token
+
+The token you currently hold and want to exchange. This is the token you will transfer to the ALEX smart contract during the swap transaction.
+
+### Target Token
+
+Also known as the "quoted token", this is the token you will receive in the swap transaction in exchange for the base token.
+
+### Swap Transaction
+
+All interactions on the ALEX DEX are carried out through smart contracts that operate on the Stacks blockchain. As you may know, it is not possible to deploy complex smart contracts on the Bitcoin blockchain, so ALEX uses Stacks to add a financial layer to Bitcoin. 
+
+**Bitcoin Native Swaps** operate by bridging the **base token** on Bitcoin to Stacks, where the swap is performed. Afterwards, the token will be bridged from Stacks to the **target token** on Bitcoin. From a user standpoint, this operation is seamlessly handled by the ALEX DEX, since you will send and receive tokens from the same Bitcoin address. Once the transaction is confirmed, it means the swap was executed successfully. If the transaction is reverted, no funds will be lost.
+
+The Bitcoing Native Swap eliminates the need for intermediate operations, saving time and protecting the user from fluctuations in prices. For more information on the benefits of the Bitcoin Native Swap, you can consult the [FAQs](./faqs.md).
+
+### Exchange Rate
+
+The exchange rate determines how many target tokens you would receive for one base token. On the ALEX DEX, this rate is algorithmically determined by the [ALEX Automated Market Maker (AMM)](../../detailed-information/alexs-automated-market-maker-amm.md) protocol and is updated after each swap.
+
+### Swap Fee
+
+This is the cost associated with performing a swap. It is deducted from the base token amount and is tipically set at 0.5%, though it can vary depending on the token pair (liquidity pool) involved. **Swap Fees** are distributed among Liquidity Providers and the ALEX Lab Platform.
+
+The swap fees on the Bitcoin Native Swap are expressed in sat/vB, or satoshis per virtual bytes. Satoshis are the smallest units of Bitcoin and virtual Bytes are a measure of transaction size on the Bitcoin Network.
+
+### Swap Route
+
+If a direct swap between your desired token pair isn't possible, ALEX DEX may use intermediate tokens to complete the exchange. For example, swapping Token-A to Token-C might require an intermediate swap through Token-B. This process is known as a multi-hop or multi-step swap. In this case, the swap route would be Token-A -> Token-B -> Token-C, where Token-B is the intermediate token. Routes on ALEX DEX can involve up to three intermediate tokens.
+
+### Slippage
+
+Since blockchain transactions are not instantaneous, the price at the moment of executing a swap may differ from the price when the transaction was submitted. This occurs because ongoing trades cause fluctuations in the exchange rate between a token pair. This difference between the prices at the moment of submission and execution is known as slippage, and users may set it at whatever percentage they find most convenient.
+
+### Slippage Tolerance
+
+ALEX Lab Platform allows you to set a maximum percentage for slippage, which is the maximum price movement you are willing to accept between submission and execution of the swap transaction. The default slippage tolerance is 4%, but you can adjust this setting. If the price movement exceeds the slippage tolerance, the transaction will be reverted.
+
+### Price Impact
+
+The price impact refers to how much a swap affects the exchange rate. You might encounter it expressed as a percentage. For small swaps, price impact is typically negligible. However, for larger swaps, the price impact increases as the trade size approaches the pool's liquidity.

docs/product-features/token-swaps/how-to.md

@@ -97,4 +97,4 @@ Recommended to track transaction status:
 
 Once the transaction is completed, you will see the balance updated in your wallet.
 
-Thank you for successfully swapping on ALEX! :arrows\_counterclockwise: :moneybag: :white\_check\_mark:
+Thank you for successfully swapping on ALEX! :white\_check\_mark:

docs/product-features/token-swaps/key-concepts.md

@@ -1,5 +1,5 @@
 ---
-description: Learn the key terms involved in ALEX swap operations.
+description: Learn the key terms involved in swap operations.
 ---
 
 # 💡 Key concepts
@@ -34,7 +34,7 @@ If a direct swap between your desired token pair isn't possible, ALEX DEX may us
 
 ### Slippage
 
-Since the exchange rate fluctuates due to ongoing trades and blockchain transactions are not instantaneous, the price at the moment of the swap transaction execution may differ from the price at the moment of submitting the transaction. This difference is called slippage and occurs when traders have to accept a different price than what they initially requested.
+Since blockchain transactions are not instantaneous, the price at the moment of executing a swap may differ from the price when the transaction was submitted. This occurs because ongoing trades cause fluctuations in the exchange rate between a token pair. This difference between the prices at the moment of submission and execution is known as slippage, and users may set it at whatever percentage they find most convenient.
 
 ### Slippage Tolerance