# What is ALEX? ALEX is building the finance layer on Bitcoin. The ALEX DEX is the largest on Bitcoin layers (Stacks Chain) fully integrated with Brotocol, our cross-chain bridge aggregating liquidity across L2s and multi-chain, with LISA as our liquid staking platform. We’re creating a seamless user experience, enabling one-click trading and asset transfer across blockchains that abstract away wallet and network complexity. All roads lead to Bitcoin, and all roads on Bitcoin meet on ALEX. There is close to $1T of capital asleep in Bitcoin wallets, this is an ocean of money that ALEX seeks to awaken. ALEX unlocks the potential of Bitcoin by taking the ultimate store of value and building on top of it the first truly permissionless, trustless and decentralized financial service for the people. ALEX offers a suite of DeFi opportunities that includes: * Discover and participate in the IDO rounds of emerging projects through the Launchpad * AMM DEX with deep liquidity * Earn exciting returns through providing liquidity, $ALEX staking, and yield farming * Cross-chain bridging through Brotocol from Bitcoin L1, to L2s and EVM chains. * Liquid token staking through LISA. * Advanced order-book DEX allows limited orders and market orders. Just as Bitcoin is the “gold standard” of crypto, ALEX will become gold standard of DeFi.

# Connect Your Wallet Follow these steps to connect your wallet to ALEX Lab. [**🚀 Connect to ALEX Now!**](https://app.alexlab.co) ### Step 1: Open the Wallet Manager

ALEX Homepage, displaying the Swap panel

First, click on the **Wallet Manager** located in the top right corner of the ALEX Lab homepage. This is where you’ll manage all your wallet connections.

### Step 2: Choose the Blockchain and Wallet By default, the ALEX Lab homepage opens the **Stacks Swap**, so the **Wallet Manager** will display wallets for the **Stacks Chain**. For the **Bitcoin Chain**, click on the slider in the top left corner to open the [Bitcoin Swap](https://app.alexlab.co/bitcoin/swap).

Slider for selecting Bitcoin or Stacks swap

In the Wallet Manager, select the blockchain you are using (e.g., **Stacks Chain**, **Bitcoin Chain** or **EVM Chain**), then choose the wallet that you want to connect. Supported wallets include Leather, Xverse, OKX and others.

For this example we will choose **Stacks Chain** and **Leather** wallet, but the steps are roughly equal for all supported wallets. ### Step 3: Enter Your Password After selecting your wallet, you will be prompted to enter your wallet’s password.

### Step 4: Select Your Account Once the password is entered, choose the specific account you want to connect. This account will be used for executing transactions on the bridge.

### Step 5: Confirm Your Connection Once the wallet is successfully connected, you will notice the icon in the top right corner of the screen, confirming that your wallet has been successfully linked.

{% hint style="info" %} Keep in mind that, for bridging, you will need to connect wallets for both the source and destination blockchains (e.g., Stacks, Bitcoin, and EVM). Once connected, you will see the respective blockchain icons in the top right corner of the app. {% endhint %} # Join the Community ALEX has a dedicated social media presence across multiple platforms. This allows users to follow the latest updates and discuss and promote their own projects on the ALEX ecosystem. Engaging with the ALEX community can also earn you rewards via [ALEX Surge](https://app.alexlab.co/surge). ## Social Media ### Twitter [𝕏 Follow ALEX on X (Formerly Twitter)!](https://x.com/ALEXLabBTC?mx=2) X/Twitter is one of the main mediums through which updates are communicated to the ALEX community. You can follow the launch of the latest features and events through the official ALEX twitter or our [verified team profiles](#verified-team-profiles). ### Discord [👾 Join ALEX on Discord!](https://discord.gg/alexlab) The ALEX Discord server allows users to interact with each other, ask questions and promote their own projects. When getting started, you can head over to the **Homebase** to explore the available channels. If you have any questions, you can refer to the **Helpdesk** and send your inquiries directly to the ALEX team. ### YouTube [▶️ Subscribe to ALEX on Youtube!](https://www.youtube.com/c/Alexgobtc) On the ALEX youtube page, the community will find useful tutorials and videos on milestones for the ALEX project. ### LinkedIn [🌐 Network on LinkedIn!](https://www.linkedin.com/company/alexgobtc/) Follow ALEX on LinkedIn to stay connected with the professional side of the community. This platform features updates on business developments and partnerships from ALEX. ### GitHub [🐱 Follow ALEX on GitHub!](https://github.com/alexgo-io) ALEX's GitHub is where developers can review and contribute to the open-source code that powers the ALEX ecosystem. Stay up-to-date with the latest innovations and technical progress. ### Medium [📝 Follow our blog on Medium!](https://medium.com/@alexgoBtc) The ALEX Medium blog provides articles that range from tutorials and updates on upcoming projects, all the way to business insights. ## Verified Team Profiles If you wish to follow members of the ALEX team to get updates on the ALEX ecosystem as soon as they're available, you can refer to the following verified profiles. There are members of the ALEX team on both X/Twitter and Discord. These are the only official profiles of ALEX team members on X (formerly Twitter) and Discord. Beware of accounts falsely claiming to belong to the ALEX team. Make sure to keep your personal information and wallet keys private. ### X/Twitter Chiente Hsu: Rachel: ### Discord #### Verified Tag on Discord for Team Authenticity ![Discord Role Verification](/files/9LQHAYfkSAJgiApMhum0) If you are looking for help with something beyond our Gitbook resources or trying to report issues on the platform, you may reach out to our team with the ALEX Team role. {% hint style="danger" %} Due to the high influx of Discord scammers impersonating team members to deceit other community members, be sure to stay safe and always double-check the user's roles. {% endhint %} # Buy ALEX Tokens Follow these steps to buy ALEX tokens! Starting from the [AlexLab](https://alexlab.co/) website, if you click on the `Buy ALEX` button, it will display all the available markets where the ALEX token can be purchased.

The procedure will be different depending on the marketplace you choose to buy ALEX tokens. ## Using ALEX Lab Platform If you decide to use the [ALEX Lab](https://app.alexlab.co/swap) platform (the last option on the list), you can follow these steps: 1. First, connect your wallet. You can follow this step-by-step guide: [How to connect your wallet](https://docs.alexlab.co/getting-started/how-to-connect-your-wallet) 2. Next, depending on which blockchain you are using, follow the appropriate path to obtain ALEX tokens: * **Bitcoin users**: Use the Bitcoin Native Swap to get ALEX BRC-20 or Runes. * 📘 [Step-by-step guide](https://docs.alexlab.co/what-can-you-do/bitcoin-swaps/how-to) * 🔁 [Bitcoin Swap page](https://app.alexlab.co/bitcoin/swap/) * **Stacks users**: Use the Stacks Swap to acquire ALEX tokens directly on the Stacks L2. * 📘 [Step-by-step guide](https://docs.alexlab.co/what-can-you-do/stacks-swaps/how-to) * 🔁 [Stacks Swap page](https://app.alexlab.co/swap) * To see which tokens you can trade in exchange for ALEX coins using the Stacks Swap, check this [token list](https://app.alexlab.co/token-list) * **Users on other blockchains (e.g. Ethereum, BNB)**: First, bridge your assets to either Stacks or Bitcoin, and then follow the appropriate method above. * 🌉 [Bridge page](https://app.alexlab.co/bridge/cross-bridge) ## Move ALEX Across Different Chains Once you have ALEX tokens on one blockchain, you can use the ALEX Lab Bridge (powered by [Brotocol 👥](https://brotocol.xyz/about)) to bridge ALEX across different blockchain ecosystems.

You can check Brotocol's [step-by-step guide](https://docs.brotocol.xyz/what-can-you-do/brobridge/how-to-bridge) for more information. # Bitcoin Swaps 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 {% content-ref url="/pages/CG6wwfOHCgwie47FxSbH" %} [Key Concepts](/what-can-you-do/bitcoin-swaps/key-concepts) {% endcontent-ref %} {% content-ref url="/pages/CzwxNWE7PAgRvhivqFmu" %} [How to Swap](/what-can-you-do/bitcoin-swaps/how-to) {% endcontent-ref %} {% content-ref url="/pages/5N1Ur3m3YOVBve9bje56" %} [FAQs](/what-can-you-do/bitcoin-swaps/faqs) {% endcontent-ref %} ## Support For assistance, please reach out to our Community Managers on [Discord](https://discord.com/invite/alexlab) and [Telegram Channel](https://t.me/AlexCommunity). # Key Concepts Learn the key terms involved in swap operations. ### 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](/what-can-you-do/bitcoin-swaps/faqs). ### 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)](https://github.com/alexgo-io/alexlab-doc/blob/main/users/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. # How to Swap This guide will showcase how to swap two tokens on ALEX Lab App. 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 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.

### 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.

{% hint style="warning" %} Clicking the `Max` button will automatically set the amount to your total available balance. {% endhint %}

### 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.

Bitcoin Swap panel with Transaction Details panel expanded.

* **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](/what-can-you-do/bitcoin-swaps/key-concepts). 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.

#### 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.

Transaction Settings panel example, with slippage tolerance set to 2%.

### Step 4: Confirm the Swap 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 the 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.

Transfer amounts involved and expandable details.

Inputs and outputs and confirmation button.

### Step 6: Wait for Transaction Confirmation 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 %}

Telegram message with transaction pending status.

Telegram message with transaction success status.

### 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: # FAQs Common questions you may have when dealing with the Bitcoin Native Swap.

Why should I use the ALEX Bitcoin Native Swap instead of performing the operations myself?

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.

Will my fees be lower or higher than in a manual operation?

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.

Why are my tokens being converted to other tokens before being swapped for my target token?

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.

How are swaps and liquidity pools related?

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).

What is the difference between a swap fee and a liquidity provider fee?

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.

# Stacks Swaps Use the ALEX decentralized exchange (DEX) for trustless swaps. Token swaps on ALEX are a simple way to exchange one token for another using liquidity pools on the Stacks Bitcoin L2. Within the ALEX Lab App, you maintain complete control of your assets, as all transactions require your confirmation and are securely routed through your wallet. Discover just how easy it is to [trade on ALEX](https://app.alexlab.co/swap)! ## Explore {% content-ref url="/pages/8m4D6GXnVJCZ1ZkMsTtN" %} [Key Concepts](/what-can-you-do/stacks-swaps/key-concepts) {% endcontent-ref %} {% content-ref url="/pages/PgSbReViycjZ3fibjRM7" %} [How to Swap](/what-can-you-do/stacks-swaps/how-to) {% endcontent-ref %} {% content-ref url="/pages/yBgXq2jLSMMeh9sxH4mz" %} [FAQs](/what-can-you-do/stacks-swaps/faqs) {% endcontent-ref %} ## Support For assistance, please reach out to our Community Managers on [Discord](https://discord.com/invite/alexlab) and [Telegram Channel](https://t.me/AlexCommunity). # Key Concepts Learn the key terms involved in swap operations. ### 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. ### Swap Transaction The ALEX DEX operates through smart contracts built on the Stacks blockchain, so all interactions, including swaps, are carried out through blockchain transactions. When you confirm a swap transaction on the ALEX Lab Platform, you are submitting it to the Stacks network to interact with the ALEX DEX smart contract. Once the transaction is confirmed, it means the swap was executed successfully. If the transaction is reverted, no funds will be lost. ### 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. ### 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)](https://github.com/alexgo-io/alexlab-doc/blob/main/users/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 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. # How to Swap This guide will showcase how to swap two tokens on ALEX Lab App. 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 Stacks Swap Page Go to to see the Swap panel. You can also navigate to it by clicking the "Swap" tab on the top menu bar.

### Step 2: Select Token Pair Select the tokens you want to exchange and 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 below example, STX 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.

Example of the Swap panel displaying exchange of 5 STX into ALEX governance tokens.

{% hint style="warning" %} Clicking the "Max" button will automatically set the amount to your total available balance. {% endhint %}

### 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. * **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. * **Liquidity Provider Fee:** The swap fee, which is shared between the Liquidity Providers (LPs) and the ALEX Lab Platform. * **Price Impact:** How much your swap affects the exchange rate. * **Slippage Tolerance:** 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. If price movement exceeds the slippage tolerance, the transaction will be reverted. * **Minimum Received:** The minimum amount of target token you will receive considering the maximum slippage variation.

Swap panel with Transaction Details panel expanded.

#### Transaction Settings If you want to adjust slippage tolerance, select the "Settings" icon to open the Transaction Settings panel. 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.

### Step 5: Confirm the Transaction in Your Wallet After clicking `Confirm`, you will need to confirm the transaction in your wallet. Here, your Stacks wallet is interacting with 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. {% hint style="info" %} To be completely sure, you can check: * The transaction is requested by **"Alex app" (app.alexlab.co)** * The transfer amounts, covered by [Stacks post conditions](https://docs.stacks.co/stacks-101/post-conditions). If these conditions are not met, the transaction will abort. Note: * The amount you transfer to the smart contract is exactly determined (STX in the example). * The amount the smart contract transfers to you (ALEX in the example) is subject to an "equal to or greater than" condition. This accounts the potential slippage variation, and here you can see the exact lower bound. {% endhint %}

Transfer amounts involved and post conditions.

Function arguments and confirmation button.

Transaction pending displayed on Leather wallet.

Transaction completed, token transfers are visible.

Where does the swap fee go?

From the total fee charged during a swap operation, a portion is rebated to users who provide liquidity to the pool (liquidity providers), while the remaining part goes to the ALEX Lab Foundation. By default, this split is 50/50, but it may vary depending on the specific liquidity pool settings. You can view these percentages in the Pool Info panel by navigating to the Swap -> Pool tab from the navbar and selecting your pool of interest from the list.

In which cases is routing necessary?

Token swaps on ALEX are performed on a decentralized exchange (DEX) and powered by liquidity pools. This implies that if you want to trade STX for ALEX tokens, you are interacting with the STX-ALEX liquidity pool. Since this pool exists, a direct swap is possible. Now, suppose you want to trade MEME1 for MEME2, but there isn't a specific MEME1-MEME2 liquidity pool. In this case, the platform will use intermediate pools. For example, if there are STX-MEME1 and ALEX-MEME2 liquidity pools, they will act as intermediaries. In this case, the swap route would be MEME1 -> STX -> ALEX -> MEME2. While MEME1 is still the base token and MEME2 the target token, the swap involves two intermediate tokens (STX and ALEX).

How do token swaps work?

Swaps on ALEX's decentralized exchange (DEX) operate through smart contracts built on the Stacks network. These smart contracts manage liquidity pools, which are collections of crypto assets deposited by users. When you perform a swap, you trade tokens with the liquidity pool, eliminating the need for a direct counterparty. For example, if a user wants to trade Stacks' native currency (STX) for ALEX's governance token (ALEX), they would interact with the STX-ALEX liquidity pool on ALEX's smart contracts. The [Automated Market Maker (AMM)](https://github.com/alexgo-io/alexlab-doc/blob/main/users/detailed-information/alexs-automated-market-maker-amm.md) protocol controls prices, fees, and token amounts. For further information on this topic please refer to the [ALEXGo Trading Pool documentation](https://docs.alexgo.io/automated-market-making/trading-pool).

# Liquidity Pools Participate in ALEX DEX liquidity pools and earn a share of the trading fees! By adding liquidity to a pool, you will earn fees from all trades between a token pair proportional to your share of the pool. Fees are added to the pool, automatically accrued in real-time and can be claimed by withdrawing back your liquidity. ## Explore {% content-ref url="/pages/swQPLXbJZVRm0XE3PAjs" %} [Key Concepts](/what-can-you-do/liquidity-pools/key-concepts) {% endcontent-ref %} {% content-ref url="/pages/knrZ8R7QLMTSYkACrMGS" %} [How to Add Liquidity](/what-can-you-do/liquidity-pools/how-to-add) {% endcontent-ref %} {% content-ref url="/pages/zE93cB7VNOiHPnQRUBaI" %} [How to Remove Liquidity](/what-can-you-do/liquidity-pools/how-to-remove) {% endcontent-ref %} {% content-ref url="/pages/Sg11nlp6kb38OW2duXiO" %} [FAQs](/what-can-you-do/liquidity-pools/faqs) {% endcontent-ref %} ### Looking to Create Your Own Pool? The Self-Service Listing allows you to create your own trading pool within the ALEX decentralized exhange. Visit the dedicated page for more details. {% content-ref url="/pages/qiUnYKOcxl176SSUe4p6" %} [Create Your Own Pool](/what-can-you-do-as-a-project-owner/self-service-listing) {% endcontent-ref %} ## Support For assistance, please reach out to our Community Managers on [Discord](https://discord.com/invite/alexlab) and [Telegram Channel](https://t.me/AlexCommunity). # Key Concepts Learn the basics of liquidity pools and providers, their role in DEXs and AMMs, and their function within the ALEX decentralized exchange. ## What Are Liquidity Pools? Liquidity pools are crowdfunded collections of crypto assets held in a smart contract, designed to provide liquidity for decentralized exchanges (DEXs) and support various decentralized finance (DeFi) protocols. While their applications are diverse, ranging from lending and borrowing platforms to algorithmic protocols for stablecoins, their primary use is on DEXs. In this case, liquidity pools enable users to trade crypto assets without the need for a centralized intermediary, serving as reserves of assets that users can trade against. ## Their Role in Automated Market Makers (AMMs) Automated Market Makers (AMMs) are the predominant type of decentralized exchange (DEX). While other DEX designs exist, AMM-based DEXs have become extremely popular. These exchanges operate using liquidity pools and algorithmic mechanisms to determine prices and facilitate the trading of crypto assets between peers. Smart contracts manage all trades executed within the AMM, including aspects such as fees, prices, and minimum target token amounts. In AMM-based DEXs, there is no need for direct counterparties as in traditional order book trading. Instead, liquidity pools act as the counterparties, providing instant liquidity when needed. ## ALEX Liquidity Pools The ALEX decentralized exchange is AMM-based and consists of a set of smart contracts built on top of the Stacks network. Each liquidity pool is composed of funds from a specific pair of cryptocurrencies, which are locked into a smart contract by voluntary depositors. These pools enable users to perform trustless swaps between the token pairs. For example, if a user wants to trade Stacks' native token (STX) for ALEX's governance token (ALEX), they would interact with the STX-ALEX liquidity pool on ALEX's smart contracts. For more details on how to execute such swaps, refer to the [Token Swaps](/what-can-you-do/stacks-swaps) section. The users who deposit their assets into these pools are known as liquidity providers (LPs). To incentivize participation, the ALEX AMM protocol rewards LPs with a portion of the trading fees collected on each swap. These fees are accrued every time a transaction occurs within the pool. ## Liquidity Providers (LPs) In exchange for providing funds to a pool, liquidity providers receive an amount of LP tokens that represent their share of assets within that pool. LP token holders earn a proportional share of all transaction fees charged to traders who perform swaps within the pool. Liquidity can be removed at any time, and the earnings associated with those LP tokens are also withdrawn at this point. For example, if a user holds 5% of the pool’s total funds, they will earn 5% of the transaction fees allocated to liquidity providers. These earnings are withdrawn when the liquidity is removed. {% hint style="info" %} **Note:** The initials "LP" are used both to abbreviate "liquidity provider" and to refer to the tokens these users receive, which represent their share of the contributed funds in the pool. {% endhint %} ## Impermanent Loss Impermanent loss in decentralized finance (DeFi) occurs when a liquidity provider (LP) supplies assets to a liquidity pool and the price of those assets changes relative to when they were deposited. This loss is termed "impermanent" because it only becomes permanent if the LP withdraws their funds when prices have diverged significantly. Here's how it works: * In most DeFi protocols, LPs provide two assets (e.g., STX and a stablecoin) in equal value to a liquidity pool. * If the price of one asset (e.g., STX) rises or falls relative to the other, arbitrage traders will trade against the pool, ensuring that the asset prices in the pool reflect current market conditions. * These trades lead to a different balance of assets in the pool (ratio). When the LP eventually withdraws their funds, they may receive a different amount of each asset than what they initially provided. * If the value of the assets in the pool has diverged significantly, the LP might have been better off simply holding the assets outside of the pool, resulting in a perceived **loss**. * This loss is termed **impermanent** because it can be mitigated if the token prices return to their original values. Additionally, this loss can be offset by trading fees earned from the pool, meaning the LP might still come out ahead if the accumulated fees exceed the loss. {% hint style="info" %} You can check a complete walkthrough example in the FAQs: [**How does impermanent loss happen?**](/what-can-you-do/liquidity-pools/faqs#how-does-impermanent-loss-happen) {% endhint %} # How to Add Liquidity In this guide, you'll find the required steps to provide liquidity to ALEX DEX pools. When **adding liquidity**, you will deposit an equivalent value of both tokens into the pool. In return, you'll receive LP tokens, which represent your share of that specific liquidity pool. Ready to start? Let's get hands-on! ### Step 1: Go to the Pool Page Go to and click on navbar's Swap -> Pool tab.

### Step 2: Select Pool All available pools will be displayed including information such as: * **Trading Pair:** The token pair that constitute liquidity pools to which you can add liquidity. * **Liquidity:** The total liquidity in the pool, expressed in USD value. * **Volume:** The trading volume between the token pair over the last 7 days. By hovering on the trading volume for a specific row/pool, the 24-hour volume is also displayed. * **Fee Rebate:** Potential LP earnings from swap fees over a year, based on the last week's average. This metric, also known as Pool APR, reflects the potential profitability of participating in a pool over a year, assuming similar trading activity continues. Select the token pair to which you want to add liquidity from the displayed list. Note you can sort by pool metrics.

Selected STX-ALEX liquidity pool as example.

{% hint style="warning" %} When hovering over a pool, you might notice a "+LP" button. This serves as a visual indicator for the selected pool. Clicking it will take you to the same screen as clicking anywhere on the pool's row. {% endhint %} ### Step 3: Add Liquidity to Your Pool After selecting a pool, you will be taken to a control panel for that specific liquidity pool, where you can add liquidity to the token pair and view more detailed metrics\[^1]. When you set the amount for one token, the corresponding amount for the other token is automatically calculated, as liquidity must be provided in equal value for both tokens. **Need tokens?** Visit the [Token Swaps](/what-can-you-do/stacks-swaps) docs section and to learn how to exchange tokens on ALEX Lab platform.

Control panel example for STX-ALEX liquidity pool. Amount is set to 4 STX and ALEX token amount is automatically determined.

{% hint style="warning" %} Clicking the "Max" button will automatically set the amount to your total available balance. {% endhint %} ### Step 4: Adjust Transaction Settings If you want to adjust slippage, select the "Settings" icon to open the Transaction Settings panel and set your desired tolerance. The default slippage tolerance for non-stable swap token pairs is set to 4%, meaning your transaction will revert if the exchange rate changes unfavourably by more than this percentage. The displayed number of LP tokens you will receive is approximate due to this potential variation.

Transaction Settings panel example, with slippage tolerance set to 3%.

### Step 5: Confirm Added Liquidity One you decide the amount, click the "Add" button. Confirmation panel will appear. Here you can double check balances, slippage and LP tokens. If everything it's okay, click "Confirm" :sunglasses:

### Step 6: Confirm the Transaction in Your Wallet After clicking "Confirm", you will need to confirm the transaction in your wallet. Here, your Stacks wallet is interacting with 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. {% hint style="info" %} To be completely sure, you can check: * Transaction is requested by **"Alex app" (app.alexlab.co)** * The amounts you will transfer to the smart contract, covered by [Stacks post conditions](https://docs.stacks.co/stacks-101/post-conditions). Note that one transfer amount is exactly determined (STX in the example) while the other is subject to a "less than or equal to" condition. This accounts the potential slippage variation, and here you can see the exact upper bound. If these conditions are not met, the transaction will abort. {% endhint %}

Amounts to transfer and post conditions.

### Step 7: Wait for Transaction Confirmation Wait for the transaction to be confirmed on the network.

### Step 8: Check the Updated Liquidity After successfully adding liquidity, you will be able to see your LP tokens and related details in "My Liquidity" panel. * **My LP** are your LP token holdings specific to the pool you contributed to. Each pool issues its own unique LP tokens. * The **Pooled** amount represents your total token holdings in the liquidity pool. Initially, reflects the amount you added and it increases over time due to accrued fees, showing your updated share of the pool's total liquidity. * The **My Pool Share** shows how much of the overall pool you own, as a percentage. * The **Indicative Value** reflects the value of your holdings in USD, which can change based on the price action of the underlying assets.

{% hint style="info" %} You can find the "My Liquidity" panel above the Liquidity Pool control panel (shown in Step 3). A summarized version is also available under the Swap -> Pool tab or at . {% endhint %} # How to Remove Liquidity In this guide, you'll find the required steps to withdraw liquidity from ALEX DEX pools. When **removing liquidity**, you will transfer your LP tokens back to the ALEX smart contract and withdraw an equivalent value of the token pair plus any fees accrued while holding those LP tokens. Since the relative balance of the tokens in the liquidity pool may have changed since your initial deposit, you could experience what's known as [Impermanent Loss](/what-can-you-do/liquidity-pools/key-concepts#impermanent-loss). Ready to start? Let's get hands-on! ### Step 1: Go to the Pool Page As when adding liquidity, go to and click on navbar's Swap -> Pool tab.

Once you're on the Pool page, you'll find the "My Liquidity" panel at the top of the pool list. This panel provides a summary of all your pool contributions.

The pools where you are providing liquidity are displayed here. There is only one in this example.

### Step 2: Select Pool Select the pool you would like to remove liquidity from, either through the "My Liquidity" panel or directly from the pool list.

### Step 3: Open the Remove Liquidity Tab Once in the panel of the pool, select the "Remove Liquidity" tab.

### Step 4: Enter Amount to Withdraw For this step, it's important to have in mind that the LP tokens you hold represent your share of the pool's funds. By entering the LP token amount, you're specifying the portion of the pooled funds you want to withdraw. Clicking the `Max` button sets your entire LP token balance, indicating you want to remove all liquidity from the pool. When you enter the amount of LP tokens, you are specifiyng amount you will transfer to ALEX smart contract in order to receive your funds and any accrued fees in return. These fees are the ones accrued while holding those LP tokens. Once you have decided the LP token amount, click the "Remove" button.

Example of removing all liquidity; the amount matches the LP token balance.

### Step 5: Confirm Liquidity Removal A confirmation panel will appear where you can double check the amount. If everything looks correct, click "Confirm" :sunglasses:

### Step 7: Wait for Transaction Confirmation Wait for the transaction to be confirmed on the network.

### Step 8: Check the Updated Liquidity Once the transaction is completed, you will see the changes reflected in the "My Liquidity" panel, and the updated token balances should appear in your wallet.

# FAQs Common questions you might have as a liquidity provider or pool creator. ## Liquidity Pools and Providers

What is the difference between swap fee and fee rebate?

The **swap fee** is the total fee charged to users for executing a token swap. It's the fee that directly impacts the trader and is displayed as "Fees" in the Pool Info panel. On the other hand, the **fee rebate** is the portion of the swap fee that is distributed to liquidity providers as a reward for supplying liquidity to the pool. The remaining portion of the swap fee goes to the ALEX Lab Foundation. You can also find the fee rebate percentage in the Pool Info panel. Pool Info panel, with highligthed "Fees" box

Pool Info panel, with highligthed "Fees" box

What is the swap fee percentage that goes to liquidity providers?

The swap fee percentage that goes to liquidity providers is known as the **fee rebate**. It is typically set at 50% of the swap fee, though it can vary depending on the pool. You can check this percentage in the Pool Info panel.

What are the LP Tokens?

Also know as "Pool Tokens", these tokens are issued to liquidity providers to represent their share of the liquidity pool. The total supply of LP tokens represents the 100% of the pool's funds. When users add liquidity to a pool, they receive LP tokens as proof of ownership. These tokens entitle them to a proportional share of the pooled assets and a portion of the fees generated by trades (swaps) within the pool. When liquidity is removed, the user transfers LP tokens back to the protocol. This determines how much of the pool's assets are returned to the user, along with their share of the transaction fees accrued during the time their liquidity was provided.

How does the fee rebate benefit liquidity providers?

The fee rebate is automatically accrued and reinvested into the pool, increasing the overall value of the pool. Since liquidity providers (LPs) hold a share of the pool, their holdings grow in value over time. However, these rewards can only be claimed when LP tokens (representing their share of liquidity) are withdrawn from the pool.

How are fees transferred to the liquidity provider's wallet?

The fees are not directly transferred to the liquidity provider's (LP) wallet. Instead, the swap fees allocated to LPs are accrued and reinvested into the liquidity pool. By holding LP tokens, liquidity providers accumulate their share of the fees over time. These accrued fees become available when they withdraw funds from the pool (i.e. when they remove liquidity). At that point, LP tokens are transferred back to the protocol, and in return, the provider receives their corresponding share of the pool's funds, including the accumulated fees.

Where can I see the fees I've gained so far as a liquidity provider?

While there isn't a direct way to view your fees separately, you can check the "My Liquidity" panel for this purpose, which shows your LP tokens and liquidity provision details. To access it, navigate to the Swap -> Pool tab and select your pool of interest from the list. You'll also see a summarized version above the pool list. In this panel, the **Pooled** amount reflects your total token holdings in the liquidity pool, which includes both your initial deposit and any fees you've accrued. Over time, this amount increases as more fees are added. The **Indicative Value** shows the USD equivalent of your holdings, which may fluctuate due to price changes of the pool's assets, but still provides a useful reference for tracking your gains.

How is liquidity provision related to farming?

Liquidity providers can stake or lock up their LP tokens for a fixed period of time (a selected number of ALEX cycles) to earn additional rewards. These rewards are separate from the earnings generated through liquidity provision, that come from swap operations fees (trading fees). This process is known as Yield Farming, or simply 'Farming'. For more details, explore the [ALEX Farming](/what-can-you-do/farming) feature.

Can I remove liquidity at any time?

Yes, you can remove liquidity at any time. However, if you've staked your LP tokens for farming, you won't be able to withdraw them until the staking period has ended. For removing liquidity from pools **you have created**, please refer to the [Self-Service Listing Documentation](/what-can-you-do-as-a-project-owner/self-service-listing).

How does impermanent loss happen?

Let's walk through an example of how impermanent loss might look for a liquidity provider (LP). Carol deposits 100 [STX](https://www.coingecko.com/en/coins/stacks) and 150 [sUSDT](https://www.coingecko.com/en/coins/bridged-tether-alex-bridge) into a liquidity pool. As with ALEX DEX's AMM, the deposited token pair must to be of equivalent value. This means that the price of STX is 1.5 sUSDT at the time of deposit, making Carol's total deposit worth 300 USD. Now, let's assume the total pool size is 1,000 STX and 1,500 sUSDT, funded by Carol and other LPs. So Carol has a 10% share of the pool. Next, suppose the price of STX rises to 6 sUSDT. As this happens, arbitrage traders will add sUSDT to the pool and remove STX, adjusting the balances to reflect the new market price. Since AMMs don't use order books, the asset's price in the pool is determined by the ratio between their balances. With the price change–STX is now 6 sUSDT– the pool now holds 500 STX and 3,000 sUSDT, thanks to the work of arbitrage traders. So, Carol decides to withdraw her funds. As we know from earlier, she's entitled to a 10% share of the pool. As a result, she can withdraw 50 STX and 300 sUSDT, which now totals 600 USD. At first glance, it looks like she's made a good profit on her initial 300 USD deposit, right? However, if Carol had simply held onto her 100 STX and 150 sUSDT, their combined value would now be 750 USD. This shows that Carol would have been better off holding her assets instead of providing liquidity. This is impermanent loss. With that said, this example doesn't account for the trading fees Carol would have earned as a liquidity provider, which could potentially offset or even exceed the loss, making liquidity provision profitable overall.

Can I create my own pool?

Yes! [Self-Service Listing](/what-can-you-do-as-a-project-owner/self-service-listing) allows you to create your own trading pool on ALEX DEX. This feature lets you list your token for permissionless trading against an anchor token, typically one with a stable value, providing a reliable reference point for pricing your token.

## Self-Service Listing

Which are the supported anchor tokens?

Native STX token, ALEX token and aBTC token.

Is there a minimum liquidity amount for the anchor token?

Yes. Initial liquidity of the anchor token must be a minimum of 1,800 STX or the equivalent value in ALEX or aBTC tokens.

How is the listed token initial price determined?

The initial price is determined by the initial liquidity provided by the creator. The ratio between the pair of funds determines the price relationship between both tokens. For instance, if the creator provides 8,000 listing tokens and 2,000 anchor tokens, that means the initial ratio is 4:1. Note that pool ratios are calculated as the minimal expression of the fraction between the token balances. In this case, is 8,000 / 2,000. We can think of this initial ratio in two ways (and they are both equivalent): * 4 listing tokens equals 1 anchor token. * 1 listing token equals 0.25 anchor tokens.

How does the price of the listing token change once the pool is created?

Once the pool is created, the price discovery phase begins. Users can permissionlessly trade the pair of assets, and the [Automated Market Maker (AMM)](https://github.com/alexgo-io/alexlab-doc/blob/main/users/detailed-information/alexs-automated-market-maker-amm.md) algorithm will determine the price dynamics of the newly listed token. For further information on this topic please refer to the [ALEXGo Trading Pool documentation](https://docs.alexgo.io/automated-market-making/trading-pool).

Is there some requirement to make the listed token visible on ALEX Token List?

Yes. ALEX requires a [Coingecko](https://www.coingecko.com/) or [CoinMarketCap](https://coinmarketcap.com/) token listing to verify the provided social media information before uploading it to the official list at [app.alexlab.co/token-list](https://app.alexlab.co/token-list). Once that is done, click on `Customer Support` on the [Self-Service Listing page](https://app.alexlab.co/self-service-listing) or contact us via Telegram at [t.me/ALEXselfservice ](https://t.me/ALEXselfservice)to submit your information (e.g. X accont, Discord, official website).

What is a wrapped version of a token contract?

Wrapped token contracts refer to "pass-through" tokens that don't retain economics; their purpose is to simplify development and enhance security. ALEX is responsible for deploying wrapped contracts. As its primarily technical, it is not relevant from a user perspective other than it involves a whole step in the procedure and takes some time.

Why would I lock or burn LP tokens when creating my Liquidity Pool?

The Initial LP Smart Lock feature ensures that community-contributed funds remain secure for the 6 month lock-up period, preventing early withdrawals that could devalue the LP token. It shows commitment from the project's team, signaling that they don't intend to conduct a rug pull on their investors. Burning tokens reassures investors that the project's team is not holding LP tokens for a future sell-off. It also reduces the total amount of tokens in circulation, maintaining the token's value.

# Farming Stake your LP tokens and maximize your rewards! Yield Farming on ALEX is an excellent way to earn exciting returns. By farming (staking or locking up your LP tokens), you earn rewards in addition to the earnings from being a liquidity provider. Among these rewards are ALEX tokens, APower tokens, and tokens provided by the project. To get started with farming, you first deposit two tokens into a liquidity pool, receiving LP tokens in return. Then, you stake these LP tokens in a farm, allowing you to harvest rewards after each farming cycle while still benefiting from the trading fees generated by the pool. {% hint style="info" %} **What are LP tokens?** LP tokens represent your share of a liquidity pool as a liquidity provider. These tokens entitle you to a portion of the pool's assets and a share of the fees generated by trades (swaps) in the pool. Learn more on the [Key Concepts](/what-can-you-do/farming/key-concepts) page. {% endhint %} ## Explore {% content-ref url="/pages/C2aNzBf3PhJ3BRpEyZT1" %} [Key Concepts](/what-can-you-do/farming/key-concepts) {% endcontent-ref %} {% content-ref url="/pages/DKQG6Xc7zZZQwH4BQdA5" %} [How to Farm](/what-can-you-do/farming/how-to-farm) {% endcontent-ref %} {% content-ref url="/pages/iCYacBS3LeJZ1088AemA" %} [How to Harvest](/what-can-you-do/farming/how-to-harvest) {% endcontent-ref %} {% content-ref url="/pages/5nYV1NfdP2QNut8p7ULl" %} [FAQs](/what-can-you-do/farming/faqs) {% endcontent-ref %} ### Looking to create your own farm? Farming can be added to pools you have created to reward liquidity providers with additional yield. Visit the dedicated page for more details. {% content-ref url="/pages/u9ak1hc35dYFAUPECeuM" %} [Add Farming to Your Pool](/what-can-you-do-as-a-project-owner/self-service-farming) {% endcontent-ref %} ## Support For assistance, please reach out to our Community Managers on [Discord](https://discord.com/invite/alexlab) and [Telegram Channel](https://t.me/AlexCommunity). You can also email us at . # Key Concepts All you need to know for successfully farming on ALEX Lab, from farm basics to dashboard metrics! ## Farm Basics Yield farming works in a very similar way to standard staking, with the key difference being that the tokens you stake are LP tokens. As in traditional staking, you lock up your tokens for a certain period (measured in cycles) and earn rewards over time. After each cycle, you will have rewards available to harvest[^1]. ### What Are LP Tokens? LP tokens are the tokens you receive when you provide funds to a liquidity pool. These tokens represent your share of the pool's assets. As a liquidity provider, you earn a portion of the fees charged to users who perform swaps within the pool. For a deeper understanding of these concepts, check out the [Liquidity Pools](/what-can-you-do/liquidity-pools) section of the docs. {% hint style="warning" %} You may notice that farming often yields higher rewards than regular staking. Well, farming involves liquidity provision and comes with the risk of Impermanent Loss. It's not as scary as it sounds, but it is worth learning about the concept before you get started. Learn more in the [Impermanent Loss subsection](/what-can-you-do/liquidity-pools/key-concepts#impermanent-loss) from the Liquidity Pools page. {% endhint %} ### What Exactly is a Farm? A farm is a staking pool for a specific LP token. Each liquidity pool has their specific native LP tokens. There are different LP tokens corresponding to each liquidity pool on the ALEX Lab Platform. Farms are identified by these two attributes. * **Trading Pair:** The specific LP token that the farm accepts. To obtain these LP tokens, you will have to provide liquidity to the pool associated with the same trading pair. * **Token Rewards:** The token in which the farm rewards the stakers at the end of each cycle. This token is predefined by the farm and cannot be changed. Some farms may offer two kind of reward tokens. Farms only accept LP tokens of one kind. For example, the STX-ALEX farm only accepts STX-ALEX LP tokens, which you receive in exchange for providing liquidity to the STX-ALEX pool. {% hint style="info" %} **Smart Contacts.** During farming, LP tokens are locked in the ALEX smart contract. Although they belong to you and only you have the authority to withdraw them, they are not held by your address during the lock-up period. As a result, you won't be able to view your LP tokens in the My Liquidity panel on the [ALEX Lab Pools page](https://app.alexlab.co/pool) during staking. {% endhint %} ### Cycles and Cooldown Period Farming is measured in cycles. **One cycle** is 525 Stacks blocks (after Stacks Nakamoto release, the farming cycle will be counted based on tenure height), which is approximately **3.5 days** or **525 Bitcoin blocks**. This means that when you stake tokens in a farm, you need to specify the number of cycles you want to lock up your tokens in the farm. Rewards are distributed after a cycle ends. Your staked tokens will start generating yield in the next upcoming cycle, which means there will be no reward during the time gap between when you stake and when the upcoming cycle starts. To maximize your earnings, it's best to stake for longer cycle periods, avoiding gaps in rewards due to the cooldown. That's why 32-cycle staking is recommended. Let's use an example. Assume you stake for one cycle at a time. When that cycle ends, you can claim the rewards associated with that cycle. To continue generating rewards, you will have to withdraw your LP tokens and restake them. However, when you restake them, the current cycle will not be eligible for you to earn rewards. Therefore, you will have to wait until the next cycle to acquire rewards. Over 100 cycles, this method would cause you to miss rewards for about 50 cycles. In contrast, if you stake for 32 cycles, you will only miss rewards for 3 cycles. ### Reward Distribution Farms may offer different types of reward tokens, and each farm has a predetermined amount of rewards. For simplicity, we can assume that the total rewards distributed to stakers during each cycle remains constant. At the end of each cycle, the rewards are available to be harvested by the farmers (stakers) in proportion to their share of LP tokens within that cycle. Rewards are distributed proportionally to each farmer based on their staked amount. This can be represented by the following equation: $$ \begin{equation} \textrm{Farmer Reward} = \frac{\textrm{Farmer Staked Amount}}{\textrm{Total Staked Amount}} ; \cdot ; \textrm{Total Rewards}. \end{equation} $$ Each value in the equation applies to a specific cycle. When there are two reward tokens (e.g., $ALEX and APower), the formula is applied separately for each token, resulting in two **Farming Reward** amounts, one for each reward token. ### Farm APR The Farm APR metric reflects your potential annual earnings from farming, based on the most recent cycle yields. It represents the potential profitability of participating in a farm over a year, assuming the total staked tokens remain similar to the last cycle. The Farm APR is calculated based on the rewards distributed in the current cycle: $$ \begin{equation} \textrm{Farm APR} = \frac{\textrm{Total Rewards}}{\textrm{Total Staked Amount}} ; \cdot ; \textrm{Annual Factor} ; \cdot ; 100. \end{equation} $$ Where * Total Rewards refers to the rewards distributed in the cycle (including $ALEX and potentially other tokens) converted to USD value; * Total Staked Amount is the total value of staked LP tokens in USD; * Annual Factor is 100.15 (\~ 100 cycles per year); * 100 factor is used to express the APR as a percentage. ## My Farming Dashboard Once you have staked LP tokens into a farm, it's important to familiarize yourself with this dashboard. You can access it by clicking on a farm from the [ALEX Lab Farms page](https://app.alexlab.co/farm). Let's walk through all the farming metrics.

My Farming dashboard example for ALEX - LiALEX farm. This user has accumulated rewards from previous cycles that are available to claim. Also, there are no LP tokens that have completed their staking period and are ready for withdrawal (LP to claim).

### Active Farming LP The tokens you have staked in the farm. When your staking period ends for a certain amount, those tokens will move from here to the [LP to claim](#lp-to-claim) section of the dashborad. If you staked multiple times at different cycles, the lock periods apply to each amount separately. ### Average APR This metric represents the average of all your farming cycle APRs (both current and upcoming). ### Rewards to Claim The rewards available for you to harvest. If you don't harvest, these rewards will accumulate over time. However, to maximize your returns, we recommend harvesting your rewards after every cycle ends. This way, you can stake them or buy more LP tokens to generate compound interest. ### LP to Claim The tokens that have completed their staking period. These tokens are no longer in a farming state. To make them generate farming rewards again, you will have to withdraw and restake them. ### Cycles Your active farming cycles. Here, there will be shown all the cycles during which you have LP tokens locked and earning rewards. For each cycle, you will find: * The **Cycle Number**, with a "current" or "upcoming" tag. * The **Farming Amount**, which indicates the amount you have staked in that cycle. * The **Farm APR**, calculated based on equation (2). * Your **Estimated Earnings**, derived from equation (1). For the **current cycle**, all metrics are exact, as the staked tokens are already defined. For the **upcoming cycles**, all metrics are estimates since we cannot predict how many LP tokens will be staked; we can only say how many LP tokens are commited so far for that cycle. This explains why the APR percentage appears higher for more distant cycles, due to the estimated total staked amount. [^1]: Except for the cycle in which you stake, which is within a cooldown period (explained in section in below). # How to Farm Step-by-step guides to learn how to stake LP tokens into a farm, harvest rewards and remove LP tokens from the farm. Yield farming takes a few easy steps to get set up. It works very similar to standard staking, with the key difference being that the tokens you stake are LP tokens. As with traditional staking, you lock up your tokens for a certain period (measured in cycles) and earn rewards over time. After each cycle (except for the first cooldown one), you will have rewards available to harvest. It is very important to understand that farms only accept their specific native LP tokens. For example, the STX-ALEX farm will only accept STX-ALEX LP tokens, which are the tokens you receive in exchange for providing liquidity to the STX-ALEX pool. There are different LP tokens corresponding to each liquidity pool on the ALEX Lab Platform. With this information in mind, choose the guide that best fits your needs. ## Guides * [🐥 Getting Started (From Scratch)](#hatched_chick-getting-started) * [🌻 How to Put LP Tokens in a Farm (Stake)](#sunflower-how-to-put-lp-tokens-in-a-farm-stake) * [🚜 Harvesting Your Farming Rewards](/what-can-you-do/farming/how-to-harvest) * [🛎️ Withdrawing LP Tokens (Unstake)](/what-can-you-do/farming/how-to-harvest#bellhop-withdrawing-lp-tokens-unstake) ## :hatched\_chick: Getting Started ### Finding Your Farm Before proceeding, choose a farm that aligns with your goals. Go to and navigate to the Earn -> Farm tab.

You'll see a list of all the available farms along with key information. You can sort the farms by various metrics and scroll to explore different reward tokens offered.

#### Farm Basics * **Trading Pair:** The specific LP token the farm accepts. * **Reward:** The earnings you obtain when harvesting the farm. #### Farm Metrics * **Liquidity:** The total USD value of the staked tokens in the farm. * **Farm APR:** Potential annual earnings from farming, based on the most recent cycle yields. This metric represents the potential profitability of participating in a farm over a year, assuming the total staked tokens remain similar to the last cycle. * **Fee Rebate:** Potential annual earnings from providing liquidity. Also known as Pool APR, it reflects the potential profitability of participating in a liquidity pool over a year, assuming similar trading activity continues. This value matches the one displayed on the ALEX Lab [Pool list](https://app.alexlab.co/pool). Once you find a farm that fits your goals, note the **Trading Pair** (e.g., STX-aBTC) as you will need it in the next step. ### Providing Liquidity to Get LP Tokens Now that you've chosen a farm to stake in, you'll need LP tokens, which are obtained by adding liquidity to a pool. 1. Click on the Pool tab in the top navigation bar.

2. Find the pool that matches the **Trading Pair** you noted before. This is the liquidity pool linked to the farm you've selected. 3. Click on the pool. This will open the pool control panel, where you can add liquidity. We have a [Guide to Adding Liquidity](/what-can-you-do/liquidity-pools/how-to-add) that you can follow to obtain LP tokens. ## :sunflower: How to Put LP Tokens in a Farm (Stake) If you have LP tokens, you're ready to start staking them in a farm and earning rewards! ### Step 1: Go to the Farm Page Go to the [Farm page](https://app.alexlab.co/farm) and locate your farm of interest. You can access it by navigating to and selecting the Earn -> Farm tab. At the top of the farm list, you'll see the farms suggested by the ALEX Lab Platform based on your LP tokens balance. In the example below, the suggested farm is STX-ALEX. This indicated that the user has provided liquidity in the STX-ALEX pool and has LP tokens available for farming.

Example of farm suggestions. This user is a STX-ALEX pool provider and possesses STX-ALEX LP tokens that can be staked in the STX-ALEX farm.

### Step 2: Select Farm Select the farm you want to stake in from the farm list.

{% hint style="warning" %} When hovering over a farm, you may notice a "+ Stake LP" button. This serves as a visual indicator for the selected farm. Clicking it will take you to the same screen as clicking anywhere on the farm's row. {% endhint %} ### Step 3: Enter LP Tokens to Stake Once you have selected the farm, enter the amount of LP tokens you would like to stake, or click `Max` to use all available LP Tokens. Next, choose the number of reward cycles you want to lock your tokens into the farm. Each cycle is approximately 3.5 days.

Example with an amount of LP tokens to stake for 32 cycles.

{% hint style="info" %} Your staked amount will start generating yield from the next upcoming cycle, as the current cycle is in "cooldown" period. To maximize the APR you earn, it's best to stake for longer cycle periods to avoid missing out on any reward cycles due to this cooldown cycle. That's why 32-cycle staking is recommended if your goal is to maximize earnings. {% endhint %} ### Step 4: Confirm Stake Once you have entered the amount, click the `Stake` button. Confirmation panel will appear. Here you can double check amount and reward cycles. If everything looks okay, click `Confirm`. 😎

### Step 5: Confirm the Transaction in Your Wallet After clicking `Confirm`, you will need to confirm the transaction in your wallet. Remember that farming locks up LP tokens in a smart contract for the selected number of reward cycles. At this point, your Stacks wallet is interacting with 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. {% hint style="info" %} To be completely sure, you can check: * Transaction is requested by **"Alex app" (app.alexlab.co)** * The amounts you will transfer to the smart contract, covered by [Stacks post conditions](https://docs.stacks.co/stacks-101/post-conditions). {% endhint %}

Wallet pop-up with function arguments and confirmation button.

### Step 6: Wait for Transaction Confirmation Wait for the transaction to be confirmed on the network.

### Step 7: Check Active Farms After successfully staking your LP tokens in a farm, you will be able to see your active farms in the "My Farms" panel on the main [Farms page](https://app.alexlab.co/farm).

Example of the "My Farms" panel. Here you will find all your active farms; click on any of them for detailed information.

By clicking on a farm, you will access the `My Farming` dashboard for that specific farm, which includes detailed metrics. On the right side of the dashborad, you will see that the current cycle has no earnings and no farming tokens. The reason you can't join the current reward cycle is that it had already started prior to your participation. However, once you successfully stake your LP into the farm, it gets registered for the next cycle. This assures you a proportional share of the farm rewards based on the number of LP tokens you have staked. This is why it's convenient to stake for long periods: every time you stake, you must wait for the current cycle to end before you start generating rewards in the next cycle. For more info on the `My Farming` dashboard and metrics, we recommend reading the [Key concepts](/what-can-you-do/farming/key-concepts) page.

Example of the "My Farming" dashboard for the STX-ALEX farm. The user has just staked, so it is in the cooldown period.

Now that you have your tokens staked on a farm, you rewards are growing 🌱. Be patient 🧘 and when the time comes, check out the [How to Harvest Guide](/what-can-you-do/farming/how-to-harvest) to claim your rewards. # How to Harvest Farming will earn you rewards over time. At the end of every staking cycle (525 blocks, approximately 3.5 days), rewards will be available to harvest. To claim your rewards, follow these steps: 1. Go to the [Farms page](https://app.alexlab.co/farm) on ALEX Lab App, which you can access through the Earn -> Farm tab. 2. You will find the **My Farms** panel which your active farms. Click on the farm you want to harvest, either from the panel or from the farm list. 3. Expand the **My Farming** dashboard. If a cycle has ended, you will see rewards available to claim. 4. Click on the "Harvest All" button and confirm the transaction on your wallet (just as you did in the previous guides). 5. Wait for the transaction to be confirmed on the network. Remember, you can turn on [Telegram notifications](https://t.me/stacks_tx_notification_bot) or search for the transaction on the [ALEX Explorer](https://app.alexlab.co/explorer). 6. Once the transaction is completed, the reward amounts will be reflected in your wallet balance. You can always check your balance also on the ALEX Lab App, located beside the "Wallet Manager" at the top menu bar. You can collect these rewards and use them for various purposes on the ALEX Lab Platform. For example, you can [stake](https://app.alexlab.co/stake) your $ALEX rewards manually to generate compounding interest. You can also use your APower rewards to increase your access to IDOs on the [ALEX Launchpad](https://app.alexlab.co/launchpad). You can even obtain more LP tokens! ### How Often Should I Harvest My Rewards? To maximize your returns, it is best to harvest your rewards at the end of every cycle. This way, you have them available to generate more rewards! 🤩 For example, you can manually stake your $ALEX rewards to generate compounding interest. If your rewards are another token, you can still [swap](https://app.alexlab.co/swap) and convert them to $ALEX. Another option would be to use your rewards to buy more LP tokens and benefit from being a [liquidity provider](/what-can-you-do/liquidity-pools). Happy Farming! 🥕 🥬 🍅 ## :bellhop: Withdrawing LP Tokens (Unstake) Withdrawing you LP tokens takes just a few steps. The important thing is when to do it. When farming, you are committed to locking up your tokens for a predefined period (reward cycles, each cycle contains 525 Stacks blocks, an estimation of \~3.5 days per cycle). Once these cycles conclude, you will be able to unstake them and regain control over your LP tokens. If you staked multiple times at different moments, the lock periods apply to each amount separately. Let's go through it step-by-step: 1. Go to the [Farms page](https://app.alexlab.co/farm) on ALEX Lab App, which you can access through the Earn -> Farm tab. 2. You will see the **My Farming** dashboard. Expand it to see all your farming details. 3. Find the farm from which you want to withdraw LP tokens and click on it. 4. Your LP tokens will automatically be available for withdrawal when your committed cycles end. You will find them under the **LP to claim** title on the dashboard. 5. Click on the "Harvest All" button and confirm the transaction in your wallet (just as you did in the previous guides). This will return your LP tokens back to your possession and automatically collect any unharvested rewards. 6. Wait for the transaction to be confirmed on the network. Remember, you can turn on [Telegram notifications](https://t.me/stacks_tx_notification_bot) or search for the transaction on the [ALEX Explorer](https://app.alexlab.co/explorer). 7. Once the transaction is completed, you will see the changes reflected in your wallet balance and on the platform panels. In particular, you will see your LP token balance on the [Pool page](https://app.alexlab.co/pool) in the **My Liquidity** panel or by selecting the pool from the list. You can also check your balance on the ALEX Lab App, located beside the Wallet Manager at the top menu bar. If you want to farm your LP tokens again, remember: your staked amount will start generating yield from the next upcoming cycle. To maximize the APR you earn, it's best to stake for longer cycle periods to avoid missing out on any reward cycles due to the cooldown period. Thanks for farming on ALEX Lab! 🧑‍🌾 # FAQs Common questions you may have when dealing with farms.

How is farming related to staking?

Yield farming is a specific type of staking. In farming, you stake **LP tokens**, the tokens received in exchange for providing liquidity to a trading pool. This means that farmers are also [liquidity providers](/what-can-you-do/liquidity-pools) (LPs). So while both farming and staking involve locking up tokens to earn rewards, farming always requires participation in a liquidity pool first.

What is harvesting?

Harvesting refers to the act of **claiming your farming rewards**. Similar to how you claim staking rewards, in farming, you "harvest" the rewards earned from staking your LP tokens in a farm.

Do farming rewards accumulate?

Yes, farming rewards accumulate over time. It is not mandatory to harvest your rewards at the end of each cycle, you can claim them whenever you choose. Also, when you withdraw (unstake) your LP tokens, any unharvested rewards will automatically be withdrawn as well.

What is the cooldown period?

The cooldown period refers to the time between when your LP tokens are staked into the farm and when a new farming cycle begins. Essentially, it is the remaining time (measured in Stacks blocks) of the current staking cycle. This implies that your staked tokens won't start generating rewards immediately, but in the next upcoming cycle. For more details, check the [Cycles and Cooldown Period](/what-can-you-do/farming/key-concepts#cycles-and-cooldown-period) section of the Key concepts page.

Why is it more convenient to stake for longer periods?

Because of the cooldown period. If you plan to stake for multiple cycles, it is more efficient to stake for the entire period upfront rather than withdrawing and restaking repeatedly. For example, if you want to farm for 12 cycles and choose to stake three times for 4-cycle periods, you will miss out on rewards for 3 cycles. This happens because each time you withdraw and restake, you enter a cooldown period. In contrast, if you stake directly for the full 12 cycles, you will only miss rewards for 1 cycle, the very first one.

What can I do with my rewards?

You have several options for your rewards: you can hold them, trade them, or generate compound interest. Compound interest occurs when your rewards generate more rewards. Here are some ways to achieve this within the ALEX Lab Platform: * Stake the rewards on [ALEX Staking](/what-can-you-do/staking). You can even buy LiALEX for auto-compounding rewards, maximizing your long-term yield. * Provide liquidity to a pool to earn a share of the trading fees. To further enhance your yield, stake the LP tokens in a farm.

How can I restake my rewards in the farm?

Reinvesting your rewards in the farm is an effective strategy to achieve compound interest, but it requires a few extra steps. To restake, you will need to transform your rewards into LP tokens first. There are two scenarios to consider. * **Case 1:** The reward token is one of the trading pair tokens. * **Case 2:** The reward token is none of the trading pair tokens. Here are the steps to restake your farming rewards: 1. [Swap](https://app.alexlab.co/swap) the rewards in order to obtain the liquidity pool trading pair tokens. This may involve one swap for Case 1 and two swaps for Case 2. 2. [Provide liquidity](https://app.alexlab.co/pool) to the pool associated with the trading pair to receive LP tokens. 3. Finally, stake the new LP tokens into the farm.

What is APower?

ALEX Staking Power, or APower, is a non-transferrable and non-tradable token. It is a special incentive that you can earn through staking on the ALEX Lab Platform, either by: 1. **Stake $ALEX (1x Multiplier)** 2. **Stake LP tokens through Yield Farming (0.3x Multiplier)** APower is the access token for participating in the "Community Round" of any future IDO on our [Launchpad](https://app.alexlab.co/launchpad). IDO tickets allocated to this round can only be purchased by utilizing APower. There is no maximum amount of APower an address can earn over a period of time. If you are interested in frequently participating in IDOs, staking $ALEX would generate APower fastest. Every IDO is unique, however, and may have a cap on the amount of APower that can be utilized to allocate IDO tickets. This prevents IDOs from being dominated by a small group of "whale" members. Full Medium post [here](https://medium.com/alexgobtc/what-is-alex-staking-power-and-how-do-i-use-it-1b3de3797fa2).

What happens to my LP tokens when I stake them?

When you stake your LP tokens in a yield farm, they are technically transferred from your wallet to the farming smart contract.

Why can't I see my LP tokens in the My Liquidity panel?

Since LP tokens are held by the ALEX smart contract during farming, you must first unstake them from the farm for them to appear in the **My Liquidity** panel. To access this panel, navigate to the **Swap** > **Pool** tab. Once you select the desired pool from the list, it will appear just above the **Pool Info** panel.

Why does farming come with the risk of Impermanent Loss?

The risk of Impermanent Loss is associated with providing liquidity. To farm, you must be a liquidity provider (LP), which inherently carries this risk. When you provide liquidity, you add assets to a liquidity pool. The market prices of those assets can fluctuate. Impermanent Loss occurs when the prices of the assets change unfavorably compared to their value at the time of deposit. This loss is termed "impermanent" because it only becomes permanent if the LP withdraws their funds when prices have diverged significantly. For further information, please refer to the [Impermanent Loss subsection](/what-can-you-do/liquidity-pools/key-concepts#impermanent-loss) on the Liquidity Pools page.

# Stake Stake your ALEX tokens and start earning rewards! ALEX staking involves "locking up" your ALEX tokens on the platform for an amount of time, measured in cycles, in exchange for protocol rewards. You can think of $ALEX staking as depositing money into an interest-earning account: the longer you keep the money in the account, the more interest you earn. Similarly, the longer you stake $ALEX, the more rewards you earn. The protocol rewards are provided in the form of more $ALEX and APower tokens. {% hint style="info" %} **What is APower?** APower is the lottery ticket that allows you to take part in any future IDO rounds on our Launchpad. It is a non-transferrable and non-tradable token that is earned by staking. Learn more on the [FAQs](/what-can-you-do/staking/faqs#what-is-apower) page. {% endhint %} ALEX provides two different forms of staking to suit every user's need. * [**Manual Staking**](/what-can-you-do/staking/key-concepts#manual-staking): Stake $ALEX directly on the [ALEX Lab Platform](https://app.alexlab.co/stake). * [**Liquid Staking**](/what-can-you-do/staking/key-concepts#liquid-staking): Stake $ALEX via LiALEX, powered by [LISA Protocol](https://www.lisalab.io/). ## Explore {% content-ref url="/pages/KcH4AePsIGns0PAb5n1R" %} [Key Concepts](/what-can-you-do/staking/key-concepts) {% endcontent-ref %} {% content-ref url="/pages/7UV8Hb7tbWHp0jkyhFaw" %} [How to Stake](/what-can-you-do/staking/how-to-stake) {% endcontent-ref %} {% content-ref url="/pages/WWzq4TjBNLeF3zXqghIB" %} [How to Harvest](/what-can-you-do/staking/how-to-harvest) {% endcontent-ref %} {% content-ref url="/pages/6VgJEOJUnosie92jVfHk" %} [How to Liquid Stake](/what-can-you-do/staking/how-to-liquid-stake) {% endcontent-ref %} {% content-ref url="/pages/fnudg5EqLSR8dFoP2kBh" %} [FAQs](/what-can-you-do/staking/faqs) {% endcontent-ref %} ## Support For assistance, please reach out to our Community Managers on [Discord](https://discord.com/invite/alexlab) and [Telegram Channel](https://t.me/AlexCommunity). You can also email us at . # Key Concepts ## Staking Basics Staking consists of locking your ALEX tokens temporarily to earn ALEX and APower tokens as rewards. Users can stake their tokens to earn passive income in the form of newly minted tokens and transaction fees. The ALEX staking pool offers two main options, each one rewarding stakers with a different token: manual staking with $ALEX or liquid staking with LiALEX. ### Rewards Staking rewards are the compensation that you can receive in return for locking up your $ALEX tokens for a certain amount of staking cycles. The longer you stake your $ALEX, the greater the rewards. They are obtained from transaction fees and newly minted tokens. The network calculates each participant's reward share based on their staked amount. Rewards are either automatically reinvested in the case of **Liquid Staking** or can be claimed after **every cycle** in the case of **Manual Staking.** This means that, even if you decided to stake your tokens for 8 cycles, you will be able to claim rewards after each cycle concludes. To maximize your returns, you should claim and re-stake your rewards as soon as they are available to generate compounded returns. Unclaimed rewards do not expire, so you can claim them whenever you wish, but they do not generate returns either. ### APR The average APR (Annual Percentage Rate) reflects the yearly interest of your investment minus fees. It does not include compounding interest. The longer the staking cycle, the higher the APR, since you will be skipping less cycles due to cool-down. ### Cycles and Cooldown Period Staking is measured in cycles. Cycles are **525 Stacks blocks** or about **3.5 days long**, and both manual and auto-staking receive rewards when each cycle concludes. When you decide to stake your ALEX tokens, you need to select the amount of cycles you wish to stake for. In the case of **Manual Staking**, your $ALEX won't be accessible during that period. After the chosen cycles expire, you can claim your rewards and withdraw your staked tokens, or re-stake them for however many cycles you choose. Bear in mind that, once your custom-selected number of cycles ends, there will be a **cooldown cycle** with no rewards received, after which you may re-stake and resume earning rewards. For that reason, the longer you stake, the fewer cool-down cycles you will have, resulting in greater returns overall. ## Manual Staking Manual Staking is the conventional way of staking your tokens on the ALEX network. After each cycle, you will have the option to harvest your rewards, which you may re-stake manually to generate compound interest. When you harvest your rewards, those tokens are automatically transferred to your wallet. ## Liquid Staking [Liquid Staking](https://app.lisalab.io/li/alex/staking) with LiALEX allows users to earn rewards just as in manual staking, but with the added benefits of maintaining liquidity and automatic re-staking. Liquid staking is made possible through LISA, a set of tools deployed by ALEX Lab on the Stacks blockchain. Liquid staking earns you passive compound interest on your investment, as you won't need to manually harvest and re-stake your rewards. Since your rewards are automatically reinvested, there is no cooldown period, which allows you to maximize your returns. Staking $ALEX through LISA provides users with LiALEX, a transferable utility token that can be used for other on-chain activities. Liquid staking not only allows you to earn rewards from your investment, but also frees you from the constraints of locking up your assets. For more information, you can consult the [LISA Documentation](https://docs.lisalab.io/). # How to Stake Staking on ALEX requires a few easy steps. In short, it consists of locking up your tokens temporarily to earn rewards. In staking, time is measured in cycles, and at the end of each cycle, you will be able to harvest your rewards. At that point, you may choose to transfer rewards to your wallet or to proceed to Liquid Staking with LiALEX. ### Step 1: Connect Stacks Wallet If you haven't already, the first step is to connect your wallet to ALEX. Go to the [Stake page](https://app.alexlab.co/stake) and under the **My Staking** section, press the `Connect stacks wallet` button. After performing the corresponding validation, **My Staking** will display. You can always change your wallet configuration from the `Wallet Manager` in the top right corner.

### Step 2: My Staking In **My Staking**, **Manual Staking** will indicate how much ALEX you're currently staking, along with its estimated Annual Percentage Rate (APR). Bear in mind that, unlike Annual Percentage Yield (APY), APR doesn't take into account the compounding effect of rewards. On the right-hand side of **My Staking**, you will see the **Cycles** section, which indicates how much time is left for the upcoming cycle, as well as the number of the current one. You can expand this section to display **All Cycles**. The timer indicates how much time is left of the current cycle. Bear in mind that your tokens will be staked on the upcoming cycle for the first time.

#### Staking Metrics * **Manual Staking:** The amount of $ALEX you are currently staking. * **APR:** The Annual Percentage Rate of your investment. It is the interest you would earn by staking for one year. * **Liquid Staking:** The amount of $ALEX you are currently staking through LISA. * **APY:** The Annual Percentage Yield of your investment. It is the interest you would earn by staking for one year, including compounding interest from re-staking your rewards. * **APower to be Distributed:** The amount of APower you will earn as a result of your investment. #### Cycles * **Cycles:** The number of the current cycle, as well as the numbers of the two upcoming cycles. * **Liquid Staking:** The amount of $ALEX you will be staking through LISA for each cycle as a result of your investments so far. * **Manual Staking:** The amount of $ALEX you will be manually staking for each cycle as a result of your investments so far. By pressing `Proceed to LISA to Stake` you will open the dashboard for liquid staking on LISA. For more information, you can consult the [LISA Staking Guide](https://docs.lisalab.io/features-how-tos/staking-stacking). Once you've verified your current balances, APR, APY and cycle timing, you can proceed to the next step. ### Step 3: Add ALEX Staking Select how much $ALEX you wish to stake and for how long. You can use the slider to personalize the amount of cycles, and you will see an estimate of how many days the selected amount of cycles will last. If you wish to stake ALEX tokens for different periods of time, you will need to execute two transactions. For example, if you wish to stake 100 ALEX for 8 cycles and 80 ALEX for 24 cycles, you will need to follow these steps twice.

The `MAX` button will stake your entire balance. In **Staking Details** you can see the numbers of the cycles you'll be staking for under your current settings, along with the corresponding "Start" and "End" blocks on the Stacks network. Afterwards, click `Stake` to begin staking. ### Step 4: Confirm Staking You will be prompted to confirm that the selected settings are correct. Please verify the information on the pop-up window and press `Confirm` to continue.

### Step 5: Confirm Transaction on Your Wallet Your Stacks wallet will ask you to confirm the transaction. After that, wait for your transaction to be confirmed on the network.

A `Transaction Mining...` pop-up should appear on the top right corner of your screen, followed by `Transaction Successful` a few moments later. ### Step 6: Check Transaction Status Wait for the transaction to be confirmed on the network. Your staked tokens could take between 20-40 minutes to appear on the [Stake page](https://app.alexlab.co/stake), but once the transaction is confirmed on the ALEX network, you will be able to see your staked tokens in the **My Staking** section.

Recently staked $ALEX in "My Staking" panel

{% 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 %} # How to Harvest Once your first staking cycle ends, you will be able to start harvesting your rewards. This section explains how to transfer your rewards to your wallet. To proceed to Liquid Staking with LiALEX, refer to the [Auto-Stake section](https://github.com/alexgo-io/alexlab-doc/blob/main/users/product-features/staking/how-to.md#auto-stake-liquid-staking). ### Step 1: Check My Staking As when staking, go to the [Stake page](https://app.alexlab.co/stake), or, alternatively, click on the navbar's `Earn` -> `Stake` tab from the [ALEX Lab homepage](https://app.alexlab.co). Once you're on the Stake page, you'll find the **My Staking** panel, which displays your current stake. ### Step 2: Harvest Your Principal and Your Rewards If a cycle has ended and you can claim rewards, you will see your $ALEX and APower on the `Harvest` button. If you have no rewards to claim yet, `Harvest` will be greyed out. The button will also display the amount of $ALEX and APower that are available for harvesting. Bear in mind that, if your staking period has ended, harvesting will also transfer your **Principal** (your staked $ALEX), to your wallet. It is not possible to collect only a portion of your principal or your rewards. Click on the `Harvest` button to claim your rewards.

### Step 3: Confirm Harvest A confirmation panel will appear where you can double check the amount. If everything looks correct, click `Confirm`.

#### Confirm Harvest * **Principal:** This is the amount of staked $ALEX that is no longer locked-up and can be transferred to your wallet. If you've staked 100 ALEX tokens for 4 cycles, and only the first cycle has ended, you will be able to harvest your rewards for that cycle while staked $ALEX remain locked-up for 3 more cycles. Hence, the principal would be 0 for this case. However, after the 4th cycle, the principal would be 100. * **Reward:** The amount of ALEX tokens and APower you can claim as a reward for staking your $ALEX tokens. If you don't harvest your rewards, they will continue to accumulate. * **Total Claim:** The sum of your principal and rewards, in $ALEX and APower. This is the amount that will be transferred to your wallet. ### Step 4: Confirm Transaction After clicking `Confirm`, you will need to confirm the transaction in your wallet. Here, your Stacks 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.

Transaction preview displayed on Leather wallet

### Step 5: Check Transaction Status Wait for the transaction to be confirmed on the network. Transferring your rewards and staked tokens could take between 20-40 minutes, but once the transaction is confirmed on the ALEX network, you will be able to see your rewards in your wallet. {% 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 %}

# How to Liquid Stake Once your first staking cycle has concluded, you will have the option to continue earning rewards via **Liquid Staking**. Liquid Staking allows you to earn rewards while maintaining liquidity as you receive LiALEX in exchange for your stake. You can start liquid staking directly from the [LISA Lab Homepage](https://app.lisalab.io/li/alex/staking), or from the [ALEX Lab Homepage](https://app.alexlab.co/stake) if you've manually staked before. This section explains how to start liquid staking your rewards from manual staking. For more information, you can refer to the [Key Concepts](/what-can-you-do/staking/key-concepts) section. ## Step 1: Check My Staking Head to the [Stake page](https://app.alexlab.co/stake), or, alternatively, click on the navbar's `Earn` -> `Stake` tab from the [ALEX Labs homepage](https://app.alexlab.co). Once you're on the Stake page, you'll find the **My Staking** panel, which displays your current stake. ## Step 2: Auto Stake Your Principal and Your Rewards If a cycle has ended and you can claim rewards, you will see the amount of claimable $ALEX and APower on the `Harvest` button. If you have no rewards to claim yet, the `Harvest` button will be greyed out. Below the button, you will see the `Auto Stake` slider. Click on it if you wish to proceed to Liquid Staking and receive LiALEX in exchange for staking your rewards. Bear in mind that, if your staking period has ended, `Auto Stake` will also stake your **Principal** (your original $ALEX stake) rather than just your rewards. It is not possible to auto stake only a portion of your principal or your rewards. With the `Auto Stake` slider in green, click on the `Harvest` button to stake your rewards.

## Step 3: Confirm Auto Stake A confirmation panel will appear where you can double check the amount. If everything looks correct, click `Confirm`.

### Confirm Harvest * **Harvest:** The amount of staked $ALEX that will be auto staked and the amount of APower that you have earned by staking. * **Auto Stake (receive):** The amount of LiALEX tokens you will receive in exchange for continuing to stake your $ALEX. This allows you the benefit of maintaining liquidity while continuing to earn staking rewards. * **Stake Price:** The price of LiALEX relative to $ALEX. * **Total Claim:** The amount of LiALEX and APower that will be transferred to your wallet. Your ALEX tokens will continue being staked. ## Step 4: Confirm Transaction After clicking `Confirm`, you will need to confirm the transaction in your wallet. Here, your Stacks 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.

## Step 5: Confirm Transaction on Your Wallet Wait for the transaction to be confirmed on the network. Your LiALEX could take between 20-40 minutes to appear on the [Stake page](https://app.alexlab.co/stake), but once the transaction is confirmed on the ALEX network, you will be able to see your staked tokens in the **My Staking** section.

Note that Liquid Staking does not have a cooldown period, meaning your tokens start earning rewards from the current cycle onward. For more information, please refer to the [Staking FAQs](/what-can-you-do/staking/faqs). {% 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 %}

# FAQs

How is staking different from farming?

Staking involves locking cryptocurrency in a smart contract for a set amount of time in exchange for rewards. During that period, the tokens won't be accessible to the user. It is generally safer and the returns tend to be lower. Farming involves lending or staking crypto holdings in DeFi protocols to supply liquidity. The tokens must be deposited into a liquidity pool, and depositors receive LP tokens, representing their share of the pool. They can earn additional tokens by participating in DeFi activities such as lending, borrowing, or trading. You can also consult the [farming documentation](/what-can-you-do/farming).

What is harvesting?

Harvesting refers to the act of **claiming your staking rewards**. When you claim your rewards, they are automatically transferred to your wallet.

Can I only collect a portion of my rewards?

No. If your staking period has ended, all the rewards and APower you have accrued, as well as the $ALEX you've staked, will be transferred to your wallet. You will be able to re-stake them on the next cycle, after the current one ends. If a cycle has ended but you've staked your $ALEX for longer, you will be able to claim your rewards but not your staked ALEX tokens, which will remain locked-up until the staking period you selected expires. If you wish to avoid cooldown periods and manual staking, you can use the **Auto Staking** function with [LiALEX](/what-can-you-do/staking/key-concepts#liquid-staking).

Do staking rewards accumulate?

Yes, staking rewards accumulate over time. It is not mandatory to harvest your rewards at the end of each cycle, you can claim them whenever you choose. Also, when you withdraw (unstake) your $ALEX or LiALEX, any unharvested rewards will automatically be withdrawn as well.

Can I claim my rewards after every cycle?

Yes, rewards can be claimed after every cycle concludes, even if you've staked your $ALEX for several cycles. Bear in mind that, although you can claim rewards, your staked tokens can only be withdrawn after the selected cycles expire.

What is the cooldown period?

The cooldown period refers to the time between when your ALEX tokens are staked and when a new cycle begins. Essentially, it is the remaining time (measured in Stacks blocks) of the current staking cycle. This implies that your staked tokens won't start generating rewards immediately, but in the next upcoming cycle. For example, if you staked your $ALEX for 32 cycles, you won't receive any rewards for the 33rd cycle. Afterwards, you will be able to earn rewards again if you choose to re-stake your tokens. For more details, check the [Cycles and Cooldown Period](/what-can-you-do/staking/key-concepts#cycles-and-cooldown-period) section of the Key concepts page.

Why is it more convenient to stake for longer periods?

Because of the cooldown period. If you plan to stake for multiple cycles, it is more efficient to stake for the entire period upfront rather than withdrawing and restaking repeatedly. Lets suppose you want to stake for 12 cycles and choose to stake thrice for 4-cycle periods, you will miss out on rewards for 3 cycles. This happens because each time you withdraw and restake, you enter a cooldown period. In contrast, if you stake directly for the full 12 cycles, you will only miss rewards for 1 cycle, the very first one. The more cycles you choose to stake for, the less cool-down cycles you will have in the middle. To avoid cool-down cycles altogether, you may use [Liquid Staking with LiALEX](/what-can-you-do/staking/key-concepts#liquid-staking).

I just staked $ALEX, when will I see my investment?

The transaction may take up to 40 minutes to become visible in the "My Staking" menu. You can consult the [Staking Guide](https://github.com/alexgo-io/alexlab-doc/blob/main/users/product-features/staking/how-to.md#step-5-check-transaction-status) for more information on verifying your staking status.

What is APower?

ALEX Staking Power, or APower, is a special incentive awarded only to $ALEX stakers and yield farmers. APower is a non-transferrable and non-tradable token, that provides special access to future IDOs on the ALEX Launchpad. There are two ways to earn APower through staking on the ALEX platform, either by: 1. **Stake $ALEX (1x Multiplier)** 2. **Stake LP tokens through Yield Farming (0.3x Multiplier)** There is no maximum amount of APower an address can earn over a period of time. If you are interested in frequently participating in IDOs, staking $ALEX would generate APower the fastest.

What is LiALEX?

LiALEX is the transferable utility token that allows you to maintain liquidity while staking your $ALEX. When you stake $ALEX through LISA, you mint LiALEX that allow you to participate in other DeFi activities, such as requesting stablecoin loans or investing them in farming pools. For more information, refer to the [LISA Documentation](https://docs.lisalab.io/)

# Launchpad Our launchpad is where emerging projects on Stacks are connected with our core community of dedicated $ALEX stakers and yield farmers. That is done through validating IDO tickets which requires both $ALEX or $STX as well as APower, a non-trade and non-transferable token that can only be earned through $ALEX staking or yield farming. Projects that IDO on ALEX can be confident that only our most dedicated long-term holders with a proven track record of staking are able to participate. If you are a project wishing to apply to our launchpad, please start by clicking [here](https://blocksurvey.io/survey/t/ae87cacb-d736-456d-a3b4-7e404e184ae8/r/l).

# Join the ALEX Launchpad! If you are looking to launch your projects on the Bitcoin ecosystem, there's no better place to launch than on the ALEX Launchpad—powered by the ALEX community!

Welcome to the ALEX Launchpad — the best launchpad built on Bitcoin! {% hint style="info" %} **Backstory:** The ALEX Launchpad is the first launchpad built on Bitcoin since February 2022, having facilitated more than 10+ successful launches with up to \~355.9 BTC committed by the community to date! Plus, the options to bridge to more than 18+ networks! {% endhint %} ### What is the ALEX Launchpad? The ALEX Launchpad is a community-based IDO integrated with [Brotocol](https://brotocol.xyz/about) to enable multichain support for projects to raise funds and launch their projects on up to 18 different networks, including Bitcoin (BRC20, Runes), Stacks, Ethereum, BNB, Base, Core, Bsqure, BOB, Bitlayer, Merlin, AILayer, Mode, X Layer, Arbitrum, Aurora, Manta, Linea and more to come.

### Why Raise with the ALEX Launchpad? The ALEX Launchpad provides you with the highest probability of success while incurring the least amount of downside risk. Here's why: * \#1: ALEX has the highest DEX activity and social metrics. * \#2: ALEX is expansive and backed by strong momentum. * \#3: We provide top-class support from our team before, during, and after the launch to ensure maximum success. * \#4: Our IDO terms are designed to be fair with very low risks for both you and your community. ### #1: ALEX by the Numbers

As of December 2024, the ALEX Ecosystem is ranked the #1 for the highest, here are the stats: * **TVL :** $219.8M * **Total Trading Volume:** $2.4B+ * **Active Users:** 69K+ * **Supported Networks:** 19+ Network (via Brotocol) * **Funds Raised:** 11.32 BTC , 400K USDT, 16.5K ALEX * **Appx. Funds Committed:** \~355.9 BTC (*Excluding other tokens*) * **Average Oversubscribed Ratio:** 5X+ * **ALEX in STX Ecosystem TVL Ratio: \~**56.4% * **ALEX Social Metrics:** * 110.5K Followers on 𝕏 * 50.2K Members on Discord * 5.8K Members on Telegram * 500+ Members on Chinese TG * 1.6K Members on Korean TG * 1.3K Members on Japan TG * 46.5K Followers on Brotocol's 𝕏

#### What is **Oversubscribed Ratio?** The '**Oversubscribed Ratio'** refers to instances where projects receive funding that surpasses their fundraising target. For instance, if a project aims to raise $100,000 but ends up collecting $250,000, the filled percentage would exceed 100%. In such scenarios, for every $1 pledged beyond the 100% mark, the amount is divided by the Oversubscribed Ratio, which in this example would be 2.5X. Therefore, if you allocated $100 towards the IDO, only $40 would be utilized for participation, with the remaining $60 being refunded to the community investor. * **Appx. Funds Committed:** \~355.9 BTC (*Excluding other tokens*) * **Funds Raised:** 11.32 BTC , 400K USDT, 16.5K ALEX {% hint style="info" %} **\~355.9 BTC is equivalent to over $33.8 million** committed to the ALEX Launchpad to date, excluding other forms of tokens! (*Assuming each BTC costs $95,000*) {% endhint %} A higher rate of oversubscription leads to a more dispersed allocation of tokens, ensuring the distribution is as equitable as possible. Historical data from past launches on the ALEX Launchpad indicate a higher likelihood of projects being oversubscribed rather than undersubscribed, thereby increasing your project's chances for a successful fundraising outcome. ### #2: ALEX DEX Momentum

The ALEX DEX is currently experiencing peak momentum, positioning it as the optimal platform for token listings. When evaluating DEX momentum, we consider it a key indicator for assessing the potential visibility of your token. Higher momentum translates to greater exposure for your token, enhancing its market presence and trading opportunities. At average, our DEX receives up to: * \~$7-10M daily trading volume * \~$30-40M weekly trading volume * \~$80-110M monthly trading volume *These volumes does not include Bridge volume from Brotocol.* ### #3: Support from the ALEX Lab Foundation

Raising a round can be challenging but we are help to support you through and through, here are some of the supports we will be providing during the Launchpad: * Amplification of your project across our Socials * 𝕏 Space sessions with our communities * Cross borders beyond English communities; we will push your contents to our partners who manages Chinese, Japanese and Korean communities * (Optional) Tokenomic advisory * Tap into our vast network of connections that can help ### Requirements for the Launchpad Some of the requirements we look for from projects looking to raise with the ALEX Launchpad: * Strong organic social followings on 𝕏 * Working product or usable MVP(s) * User activities metrics of your products / ecosystems * Revenue model of your project * Strong team background * (Optional) Interest from notable CEXs * (Optional) Revenue data of your projects * All IDO terms has be to agreed on.

### ALEX Launchpad IDO Terms By launching on the ALEX you agree to the below terms: 1. **Fundraising Requirement:** Raise at least $100,000 through the ALEX Launchpad. 2. **Buyback Mechanism:** Agree to a one-week buyback mechanism where, if the token price falls below the Buyback price, you will buy back all tokens sold during the IDO. Example: If the IDO price is $1, the Buyback price is $0.9, and the price drops to $0.8 a week after launch, the buyback is triggered at $0.9. 3. **Liquidity Commitment:** Commit to 6-months LP staking contributing at least 10% of the funds raised and an equivalent value of 10% of your total token supply to the liquidity pool (LP) to enable trading immediately after the Launchpad concludes. 1. Example: For a $100,000 raise, this means contributing $10,000 in BTC/STX/sUSDT and another $10,000 worth of your token. 2. Note: Additional liquidity can be added by anyone after the launch. 4. **Launchpad Fees:** 1. We charge a 0% service fee for listing 2. < 1.0% token supply for marketing budgets Please review the above terms and reach out to the ALEX team with any questions or concerns by sending us a DM via our emails available in the[ Official Links](/resources/official-links).

### The Launchpad Process Now that you have made your mind and decided that the ALEX Launchpad is for your project, here's what to expect to happen: #### #1: Introduction to the ALEX Team After you've reviewed all the Launchpad information above and decided to proceed with ALEX, we'll set up a communication channel (e.g., Telegram) for an initial interaction. Here, we'll discuss your needs, get to know you and your project better, and a team member will schedule an introductory meeting or call to delve into your project's details and the launch process. #### #2: Project Information Submission for Due Diligence We will ask your team to complete a Blocksurvey form for due diligence purposes. This form will request information such as: * Project brief & summary * Team background * Product information & Use cases * Revenue Model * Official Links & Documentation * Current Development Phase * Roadmaps * Estimated IDO valuation #### #3: Initial Call (Brief Process & Terms) Once we receive the completed Blocksurvey form, we'll arrange a call to: * Get to know you and your team better (preferably with video enabled) * Discuss your current milestones, CEX listing strategies, onboarded partners, product functionality, and IDO terms. * Breakdown how the Launchpad user experience works—for your users and our users. After this call, you'll have a clear understanding of the process, terms of the IDO, how the Launchpad works, and an opportunity to ask any initial questions or seek clarifications. #### #4: Agreement to the IDO Terms During or after the call, we'll confirm if you fully agree to the following IDO terms: * Raise a minimum of $100K. * Implement a buyback mechanism if the price falls below the IDO price within a week of launch. * Commit 10% of raised funds and 10% of total token supply for initial liquidity. * **Accept the fees terms:** 0 % service fee and <1.0% marketing budget of the token supply . By agreeing to these terms, you commit to fulfilling these obligations during and post-IDO. #### #5: Launchpad Fundraising Documentation Submission If you've agreed to the IDO terms and our Launchpad Committee has vetted your project: You'll be asked to fill out the IDO Notion Application form, detailing launch specifics, tokenomics, financial projections, marketing strategies, and other operational details.

#### #6: Community Vote Once the IDO Notion Application is completed, a community vote will be conducted using all provided project information and the fundraising goal. If the vote results in a majority YES, your project will be listed on the ALEX Launchpad. Users vote with their ALEX or LiALEX tokens, which are non-transferable and earned by participating in Stake and Farm within the ALEX Ecosystem. #### #7: Launchpad Setup Post community approval: We'll coordinate with you to set the launch date and configure settings for Community, Whitelist, and Public Round portions.

#### #8: Launchpad Marketing (Pre, During, and Post) With the launchpad set up and the countdown initiated, we'll engage in co-marketing efforts as follows: * **Pre-launch:** We will focus on announcements, teasers, and community engagement to build anticipation. * **During Launch:** Live updates, AMAs (Ask Me Anything sessions), and real-time interactions will keep the community engaged. * **Post-Launch:** We'll provide reports on the success of the IDO, send thank-you messages, and continue with ongoing community updates. We will collaborate with you to enhance social amplification not only through our channels but also via our network connections, including Key Opinion Leaders (KOLs), ALEX holders, and investors. If you lack a clear path to Centralized Exchange (CEX) listings, we can assist in establishing these connections. Our marketing collaboration goes beyond merely listing your project on our website. We will also co-run marketing campaigns designed to maximize visibility and impressions for your IDO round. During the co-marketing phase, we will host an AMA in the form of 𝕏 Spaces, allowing our 110K followers to participate live or watch the recorded session to gain a better understanding of your project. #### #9: Launchpad Goes Live! Once all preparations are complete, the IDO officially commences at the scheduled time. Investors can then participate in the token sale, marking the beginning of your project's fundraising phase on the ALEX Launchpad. During the launchpad, you can decide to have up to three phases: * **Community Launch:** Open to anyone with APower on a first-come, first-served (FCFS) basis. * **Public Launch:** Open to anyone, does not require Apower to participate, and is conducted through a fair random number drawing process. * **Whitelist Launch:** This phase is optional and allows the project team to whitelist specific addresses (community members, KOLs, partners, etc.) for marketing purposes. This can be set up either at the start of the IDO or later on. These phases are optional, depending on how you would ideally want your IDO round to be. {% hint style="info" %} During the Launchpad call in [#id-3-initial-call-brief-process-and-terms](#id-3-initial-call-brief-process-and-terms "mention"), we will dive deep into the Launchpad mechanism: **IDO Lottery, Launchpad phases and fair random number drawing process.** {% endhint %} Each step ensures that your project is vetted, prepared, and promoted effectively within the ALEX ecosystem, leading up to a successful token launch. After the launchpad has completed, the unallocated funds will be returned to the investors, while the allocated funds will be converted into the IDO tokens based on the IDO launch price.

**Send us a message via our** **ALEX Official Telegram channel, and we will get back to you!**

# Surge Participate in ALEX Surge and earn rewards by providing liquidity! ALEX Surge is a round-based liquidity incentives program designed to reward participants, including liquidity providers (LPs) and voters who help distribute rewards. By participating in Surge, LPs can stake their liquidity pool tokens (LP tokens) to earn additional $ALEX rewards, while voters can use their $ALEX or $LiALEX tokens to determine which liquidity pools receive a larger share of these rewards. {% hint style="warning" %} **Important:** LP tokens fluctuate in value based on pool activity and market conditions. Liquidity providers should consider factors like **impermanent loss** before staking in Surge. {% endhint %} Every Surge round consists of multiple stages, including **registration, voting & staking, and reward emissions**. To join the current Surge campaign and start earning rewards, visit the [ALEX Surge App](https://app.alexlab.co/surge). {% hint style="warning" %} 🚨 **Cut-off Dates in ALEX Surge** Cut-off dates define the deadlines for each phase in a Surge round: * **Registration Cut-off**: no new pools can join after this date. * **Voting Cut-off**: votes are locked, finalizing reward distribution. * **Staking Cut-off**: last opportunity to stake LP tokens. The current phase is always visible on the Surge interface. {% endhint %} ## Explore {% content-ref url="/pages/INNVoiVtjzp68hloJ2Wy" %} [Key concepts](/what-can-you-do/surge/key-concepts) {% endcontent-ref %} {% content-ref url="/pages/kmqRztAU2e9sNFQkJBij" %} [How to participate](/what-can-you-do/surge/how-to) {% endcontent-ref %} {% content-ref url="/pages/0NNkg3s16R7vW9JNIAfw" %} [FAQs](/what-can-you-do/surge/faqs) {% endcontent-ref %} ## Support For assistance, please reach out to our Community Managers on [Discord](https://discord.com/invite/alexlab) and [Telegram Channel](https://t.me/AlexCommunity). # Key concepts Understand the essential concepts behind ALEX Surge, including LP tokens, voting mechanisms, and reward structures. ## Surge Rounds & Phases ⏳ ALEX Surge operates in recurring rounds, with each round following a structured cycle that determines when pools can register, when users can vote, and when rewards are distributed. Each phase has a specific purpose, ensuring fair participation and smooth reward allocation. ## LP Tokens 💧 LP (Liquidity Provider) tokens represent your ownership share in a liquidity pool. When you deposit assets into a pool on ALEX Lab, you receive LP tokens in return, which track your contribution relative to the total pool size. In ALEX Surge, LP tokens play a crucial role in staking and rewards distribution. Liquidity providers can stake their LP tokens during a Surge round to earn a portion of the $ALEX rewards allocated to their chosen pool. The more LP tokens staked, the higher the potential rewards. Since LP tokens fluctuate in value based on pool activity and market conditions, liquidity providers should consider factors like impermanent loss before staking. ## Staking in Surge 🔹 Staking in ALEX Surge allows liquidity providers to commit their LP tokens to a specific pool in exchange for $ALEX rewards. By staking, participants help strengthen liquidity pools while earning rewards based on the total amount staked in each round. **LP tokens can only be staked during the staking phase of each Surge round and remain locked until the end of the reward emission phase.** At that point, stakers can harvest their rewards and unstake their LP tokens. Rewards are distributed proportionally, meaning pools with more staked LP tokens and higher votes receive a larger share of $ALEX. Staking is optional but offers an additional incentive for liquidity providers looking to maximize their returns in ALEX Surge. ## Voting Power ⚖️ Voting power in ALEX Surge determines how much influence a participant has when distributing $ALEX rewards across liquidity pools. It is calculated based on a user’s $ALEX and $LiALEX holdings at the start of each Surge round. Each user can allocate their voting power to one or multiple pools. The more votes a pool receives, the higher the share of rewards it earns. Once a vote is cast, the used voting power cannot be changed for that round. Additionally, the ALEX Lab Foundation contributes 5,000,000 voting power in every round, influencing the reward distribution based on Social Leaderboard rankings. ## Voting Mechanisms in ALEX Surge 🗳️ Voting in ALEX Surge determines how $ALEX rewards are allocated among liquidity pools. Participants cast votes using their voting power, which is calculated at the start of each round based on their $ALEX and $LiALEX holdings. Once submitted, votes cannot be changed for that Surge cycle. Pools with higher vote totals receive a larger share of the $ALEX emissions, influencing the distribution of rewards across the ecosystem. ### Voter Rewards 🎁 Voter rewards are additional incentives provided by liquidity pools to attract votes. Projects or pool creators can donate extra rewards, which are distributed among users who vote for their pool during a Surge round. Once voter rewards are allocated, they cannot be withdrawn or modified. Users who support pools offering these incentives receive their share of the donated rewards after the emission phase ends. ## The Social Leaderboard 📈 The Social Leaderboard is a ranking system in ALEX Surge that rewards community engagement. Pools that actively promote their participation on Twitter/X can improve their ranking and increase their chances of receiving votes from the ALEX Lab Foundation. Leaderboard rankings are based on social media engagement, including likes, reposts, and replies. **To be considered in each Surge round, projects must submit their social activity through Discord or Blocksurvey before the voting phase ends.** ## Reward Distribution 💰 In ALEX Surge, rewards are distributed based on the number of votes a liquidity pool receives and the amount of LP tokens staked. The total $ALEX rewards allocated to a Surge round are divided among pools according to their voting share. Liquidity providers who stake LP tokens in pools that receive votes earn rewards proportional to their stake. Additionally, some pools may offer voter rewards as extra incentives for participants who vote for them. ## Cut-off Dates 🚨 For details on cut-off dates and deadlines, refer to the [Cut-off Dates section in the Surge README](/what-can-you-do/surge). ## Risks and Considerations ⚠️ Participating in ALEX Surge involves risks similar to providing liquidity in any AMM-based DEX. Impermanent loss can occur if token prices fluctuate, affecting the value of staked LP tokens. Additionally, once voter rewards are donated, they cannot be withdrawn. Understanding these risks helps participants make informed decisions before voting or staking. # How to participate A step-by-step guide on how to participate in ALEX Surge and earn rewards. ALEX Surge is a **round-based liquidity incentives program** that rewards participants, including **liquidity providers (LPs) and voters**, for contributing to deeper and more robust liquidity pools on ALEX. The Surge dashboard will display the different rounds of the program, such as Surge #16, Surge #17, etc. Each Surge round follows these phases: * **Registration**: projects can register their liquidity pools before the cut-off date. * **Voting**: users vote to decide how $ALEX rewards will be distributed. * **Staking**: liquidity providers stake LP tokens to earn additional rewards. * **Surge Rewards Emission**: $ALEX rewards are distributed based on the votes and staking amounts. The cut-off date is the deadline for registering liquidity pools in the current round. After this date, no new pools can enter, and the voting phase begins. You can check the timeline at the top of the Surge page to track the current phase of the program. *** ## 📝 Register a Pool If you are a project owner or community member, you can register a liquidity pool to participate in the **ALEX Surge campaign**. ### Step 1: Open the Surge App Go to the [ALEX Surge App](https://app.alexlab.co/surge) and click `Register for Surge`.

### Step 2: Complete the Registration * Fill in the required details and submit your pool before the cut-off date. * Once the cut-off date passes, new registrations will no longer be accepted.

### Step 3: (Optional) Donate Voter Rewards You can add extra rewards to incentivize users to vote for your pool. {% hint style="warning" %} **Once donated, voter rewards cannot be revoked or withdrawn.** {% endhint %}

Once you've decided on an amount of voter rewards, press the `Donate Rewards` button. A confirmation pop-up will appear. If you understand that your donated rewards cannot be revoked, click `Confirm`.

### Step 4: Promote Your Pool To improve your ranking in the Social Leaderboard, engage with the ALEX community: * Use **@alexlabbtc** and **#ALEXSurge** in your **Twitter/X** posts. * Submit tweets via **Discord** or **Blocksurvey**. Once registered, your pool will appear on the **Social Leaderboard**, where it will be ranked based on **Twitter/X engagement metrics**. *** ## 🗳️ Voting for Emissions During the voting phase, users can vote for their preferred liquidity pools to influence the distribution of $ALEX rewards. ### Step 1: Open the Surge Voting Section After the registration cut-off, go to the [Surge App](https://app.alexlab.co/surge) and click `Vote for Emissions`.

### Step 2: Allocate Your Voting Power Your voting power is based on your $ALEX and $LiALEX holdings. * Choose how to distribute your votes among the available pools. * Pools with more votes receive a higher share of the $ALEX rewards. ### Step 3: Submit Your Vote Click **Cast Votes** to finalize your selection. **⚠️ You can only vote once per round per wallet**.

ℹ️ Understanding the Voting Panel * **Surge #XX Vote Ends In**: This shows how much time is left before the voting phase closes. Once the countdown reaches zero, no more votes can be cast for that round. * **Current Votes**: This represents the total number of votes cast in this round so far. Every time a user votes, this number increases. * **Emissions Per Surge**: this is the total amount of $ALEX rewards available for distribution in the current Surge round. The more votes a pool receives, the larger the share of these rewards it will get. * **Voting Power Used**: this shows how much of your available voting power you have used. Each user gets voting power based on their holdings and staked tokens, and once they vote, their used amount appears here. Pools that receive more votes will get a **higher share of the $ALEX rewards**. *** ## 🔹 Staking LP Tokens After voting, liquidity providers can stake LP tokens to earn additional rewards. ### Step 1: Open the Surge Staking Section Go to the **Stake LP To Earn** section before the staking phase ends. ### Step 2: Select a Pool and Stake LP Tokens Click `+ Stake LP` on the pool you want to stake in.

### Step 3: Stake in Multiple Pools (Optional) You can stake LP tokens in **multiple pools**, but each stake is separate. ### Step 4: Reward Distribution * Rewards are distributed proportionally based on your staked LP tokens relative to the total staked amount in that pool. * The more LP tokens you stake, the greater your share of the $ALEX rewards. {% hint style="info" %} 🚨 **Important Notes:** * The **ALEX Lab Foundation** also votes but **does not receive voter rewards**. * The voting **percentage** at the end of the staking phase determines how the **$ALEX rewards** are distributed. * You cannot withdraw staked LP tokens until the end of the Surge round. {% endhint %} *** ## 💰 Claim Your Rewards Once the voting and staking phase ends, the **reward emission phase** begins. ### Step 1: Wait for Rewards Distribution * Once the staking period ends, the reward emission phase lasts approximately 27–28 days. * During this period, rewards are accumulated and become available for claiming. * Your rewards depend on the total votes received by your pool and the amount of LP tokens you staked.

Overview of pending rewards before claiming

### Step 2: Claim Your Rewards 1. Go to the [Surge App](https://app.alexlab.co/surge) and navigate to the Claim Rewards section. 2. Click **Harvest all** to claim your LP tokens and earned $ALEX rewards.

{% hint style="info" %} 🚨 Important Notes: * You can only claim rewards after the emission phase is complete. * If you staked LP tokens, they will be automatically unstaked when you claim your rewards. * A new Surge round starts after the rewards have been distributed. {% endhint %} *** ## 🔥 Social Leaderboard and Additional Incentives ALEX Surge includes a **Social Leaderboard Campaign**, where pools can improve their ranking by engaging with the community on **Twitter/X**. ### 📌 How to Improve Your Pool's Ranking: * **Post about your project** using **@alexlabbtc** and **#ALEXSurge**. * **Submit tweets via Discord or Blocksurvey** to be counted towards the leaderboard. * **Engagement matters**: * **Likes** → **0.5X multiplier** * **Reposts/Quote Reposts** → **1.25X multiplier** * **Replies** → **1.5X multiplier** Pools with higher engagement **receive more votes from the ALEX Lab Foundation**, increasing their rewards. *** 🚀 **Now you’re ready to participate in ALEX Surge and start earning rewards!** # FAQs Common questions you may have when participating in ALEX Surge.

What is ALEX Surge?

**ALEX Surge** is a round-based liquidity incentives program designed to reward users who contribute to liquidity on the ALEX's decentralized exchange (DEX). Participants can vote with $ALEX or $LiALEX tokens to determine how $ALEX rewards are distributed among pools. Additionally, liquidity providers can stake their LP tokens to earn extra rewards. Each Surge round distributes approximately 5,000,000 $ALEX based on the voting results, making it a unique opportunity for liquidity providers to earn additional rewards beyond standard pool fees.

How do I participate in ALEX Surge?

You can participate in ALEX Surge in several ways: 1. **As a Pool Registrant**: If you are a project owner or community member, you can register a liquidity pool to compete for $ALEX rewards. Once registered, users can vote for your pool, and liquidity providers can stake LP tokens in it. You may also donate voter rewards to attract more votes. 2. **As a Liquidity Provider (LP)**: Provide liquidity to a pool and stake your LP tokens in Surge to earn $ALEX rewards. The more LP tokens you stake, the larger your share of the rewards. 3. **As a Voter**: Use your $ALEX or $LiALEX tokens to vote for your preferred pools. Pools with more votes receive a larger share of the $ALEX rewards. Additionally, some pools offer **Voter Rewards**, which are extra incentives donated by the pool registrants to attract votes. By voting for these pools, you can earn a proportional share of the Voter Rewards allocated to that pool. 4. **By Promoting Your Pool on Social Media**: If you have a registered pool, you can increase its visibility by engaging with the ALEX community on **Twitter/X**. Pools with higher engagement may receive more votes from the ALEX Lab Foundation.

What are LP tokens?

**LP tokens** are the tokens you receive when you provide liquidity to a trading pool on the ALEX's decentralized exchange (DEX). These tokens represent your share of the pool's assets. In ALEX Surge, staking LP tokens allows liquidity providers to earn a share of the $ALEX rewards allocated to the pool, based on voting results and the total amount staked. For more information, refer to the [Liquidity Providers](https://github.com/alexgo-io/alexlab-doc/blob/main/users/product-features/liquidity-pools/key-concepts/README.md#liquidity-providers-lps) section.

How are rewards distributed in ALEX Surge?

Each Surge round distributes a fixed amount of $ALEX rewards among the participating pools based on the voting results: 1. **Voting Rewards**: The total $ALEX emissions for the round are allocated to pools proportionally to the votes received. Pools with more votes get a larger share of the rewards. 2. **Staking Rewards**: Within each pool, the allocated $ALEX rewards are distributed among liquidity providers based on their staked LP tokens. 3. **Voter Rewards**: Some pools donate additional rewards to attract voters. These rewards are distributed proportionally to those who voted for that pool.

What are Voter Rewards?

**Voter Rewards** are additional incentives that projects voluntarily donate to attract votes for their liquidity pools. If a voter supports a pool that has donated voter rewards, they will receive a proportional share of those rewards. {% hint style="warning" %} **Note:** Once donated, voter rewards **cannot be revoked or withdrawn**. {% endhint %}

Can I vote for multiple pools?

Yes, you can distribute your voting power across multiple pools when voting. However, you can only submit your vote once per round per wallet, meaning you cannot modify or add votes later. Make sure to allocate your votes strategically before confirming.

What happens if I don't harvest my rewards?

Your rewards will accumulate over time, and you are not required to harvest them immediately after the emission phase ends. If you staked LP tokens, any unclaimed rewards will be automatically harvested when you unstake your LP tokens.

What is the Social Leaderboard?

The Social Leaderboard ranks pools based on their engagement on Twitter/X. Pools with higher engagement have a better chance of receiving votes from the ALEX Lab Foundation, which holds significant voting power.

How does the ALEX Lab Foundation vote in Surge?

The **ALEX Lab Foundation** votes with **5,000,000 voting power** to help distribute rewards to pools. The foundation's votes are influenced by the **Social Leaderboard rankings**, favoring pools with higher community engagement. {% hint style="info" %} **Important:** The foundation’s votes **do not receive any voter rewards**. {% endhint %}

How long does the reward emission phase last?

The **reward emission phase** typically lasts **27–28 days**. During this period, rewards are distributed to the pools based on the voting results. After the emission phase ends, participants can **harvest their rewards** and **withdraw their staked LP tokens**.

Can I register my pool multiple times?

Yes, pools can be **registered multiple times** before the cut-off date. Each registration allows you to **add more voter rewards** to attract additional votes. {% hint style="warning" %} **Note:** Once you donate voter rewards, they **cannot be revoked**. {% endhint %}

What happens if I withdraw my LP tokens before the reward emission phase ends?

You **cannot withdraw** your staked LP tokens until the reward emission phase is complete. Once the phase ends, you can **unstake** your LP tokens and **claim any earned rewards**.

⚠️ Is there any risk involved in staking LP tokens in Surge?

Yes, staking LP tokens in Surge involves the same risks as providing liquidity in any **AMM-based DEX**, including the risk of **Impermanent Loss**. This occurs when the value of the assets in the liquidity pool fluctuates significantly, potentially reducing the total value of your LP tokens. For more details, check the [Impermanent Loss subsection](/what-can-you-do/liquidity-pools/key-concepts#impermanent-loss).

Can I participate in multiple Surge rounds?

Yes, after each Surge round concludes, the process **repeats monthly**. You can participate in as many rounds as you like by registering pools, voting, and staking LP tokens in each new round.

# Create Your Own Pool Create your own pool and make your token tradeable on ALEX decentralized exchange in simple steps! {% hint style="warning" %} **Supported Tokens:** ALEX Self-Service Listing currently supports Stacks Chain Tokens (SIP-010 Standard Token). {% endhint %} ## 🚀 Getting Started ### How Does It Work? Self-Service Listing allows you to **create your own liquidity pool** on the ALEX DEX, enabling the **permissionless trade** of the **listed token** with an **anchor token** within the exchange. The anchor token is typically one with a stable value, providing a reliable reference point for defining the price of the newly listed token. Pool creation usually takes between 24 to 48 hours. Once the pool is created and live, the price discovery phase begins: users can start trading the listed token against the anchor token and viceversa. Users interested in providing liquidity can contribute to the pool like any other ALEX pool. The pool owner is the initial liquidity provider and is responsible for selecting the settings for the initial LP tokens (see [Step 2: Choose LP Lock & Burn Settings](#step-2-choose-lp-lock-and-burn-settings)). The trading pool operates using the [ALEX Automated Market Maker (AMM)](https://github.com/alexgo-io/alexlab-doc/blob/main/users/detailed-information/alexs-automated-market-maker-amm.md) algorithm, which dynamically determines the exchange rate (price) based on the trades. **Available Anchor Tokens:** Native STX token, ALEX token and aBTC token. {% hint style="info" %} Interested in having your own unique pairs out of the available anchor tokens? Please [reach out to us](https://t.me/ALEXselfservice). It is important to note that unique pairs are subject to approval by the ALEX Lab Foundation team. {% endhint %} ### Minimum requirements 👉 **Token Deployment.** Ensure your token is deployed on the Stacks blockchain, as you will need to provide the token contract. 👉 **Select an Anchor Token.** Choose an anchor token from the available options: Stacks native token STX, ALEX token, or aBTC token. Ensure you have at least 1,800 STX or an equivalent value in ALEX or aBTC token to create the pool—this is the minimum anchor token liquidity. 👉 **Determine Initial Price.** Decide the initial price for your listing token in terms of anchor token units. This should answer the question: how many anchor tokens do users need to buy one listed token? 👉 **Calculate Initial Liquidity.** Once the initial price is determined, you can set the initial liquidity amounts for both tokens in the pool. You may calculate this manually or use the ALEX Lab UI for assistance. If you're planning to [add farming to the pool](/what-can-you-do-as-a-project-owner/self-service-farming), make sure to reserve enough tokens for farm rewards.

Manual calculation example (price, ratio, and initial amounts)

Let's suppose you choose STX as the anchor token and want to provide 4,000 STX as the initial anchor token liquidity. To determine the price, you will need to decide how many STX equals 1 of your listing token. In other words, decide how many STX users will need to buy 1 listed token. Let's say you set the price of your token at 0.5 STX. To calculate the initial liquidity for the listed token, you need to divide the anchor token amount by the price. This is `4,000 STX / 0.5 STX = 8,000`, resulting in the initial amount for the listed token. The liquidity pool for the pair **Listed Token** :rocket: **- Anchor Token** :anchor: will have an initial ratio of 2:1. This ratio is calculated as the minimal expression of the fraction `8,000 / 4,000` (initial listed token amount slash initial anchor token amount).

🔎 For more details, check the [FAQs](/what-can-you-do/liquidity-pools/faqs#self-service-listing) section. With that said, let's get hands-on! ## 🛠️ Procedure ### Step 0: Go to the Self-Service Listing page Head to the [Self-Service Listing page](https://app.alexlab.co/self-service-listing) at the ALEX Lab App. Alternatively, you can access it via the [app.alexlab.co](https://app.alexlab.co) homepage by navigating to the `Swap` -> `Pool` tab. Once on the Pool main page, hit the `+ Create` button and select the `Creating a new pool` option.

### Step 1: Submit Token Information and Deposit the Anchor Token In this step, you will set up the pool trading pair and configuration parameters. As part of this same transaction, you will transfer the anchor token's initial liquidity :moneybag: :anchor:.

Step 1.1: Input the SIP-10 Token Contract Address

Provide the listed token contract address. Ensure it complies with the [SIP-010 Fungible Token Standard](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) trait. In the example, the contract address is `SP108J6F4C7JD93BGJ91TEB5D3CFB5XW39QHDJ3MV.rabby-token`.

Step 1.2: Confirm Token Information Provided by the Contract

Verify that the token information retrieved from the contract is correct. In the example: * **Token name** -> `RABBY Token` * **Token symbol** -> `RABBY` * **Description** -> Unlock the potential of programmable adventures within Bitcoin's rabbit holes. * **Token deployment address** -> `SP108J6F4C7JD93BGJ91TEB5D3CFB5XW39QHDJ3MV` * **Token logo**

Step 1.3: Set the Initial Liquidity and Price

Enter the initial balances for both tokens. You can experiment with different amounts to observe how the exchange rate changes, though we recommend calculating these values beforehand. In the screenshot example, this is: * **Anchor Token ⚓** (a.k.a `token-x`) -> `4,000 STX ($7,200)` * **Listing Token 🚀** (a.k.a `token-y`) -> `200,000 RABBY` * **Exchange Rate ⚖️** -> `1 RABBY = 0.02 STX ($0.03)` Once the pool opens, the AMM algorithm will automatically rebalance the exchange rate as users trade the tokens.

Step 1.4: Advanced Pool Settings (Optional)

This step is optional, as the default settings are usually sufficient. However, we recommend consulting the [ALEXGo Technical documentation](https://docs.alexgo.io/automated-market-making/trading-pool) before making customizations. If you have questions to ask before customization, reach out via [Discord](https://discord.com/invite/alexlab) or [Telegram](https://t.me/AlexCommunity).

Step 1.5: Submit Transaction

Keep in mind that as part of this same transaction, you will transfer the anchor token's initial liquidity. By confirming the transaction, you are accepting the transfer of specific amount of anchor tokens from your wallet to the ALEX smart contract. Click `Submit` and scroll through the wallet transaction window, ensuring the parameters and transfer amount are correct. If everything looks good, confirm the transaction on your wallet. This will allow your wallet to sign and broadcast the transaction. 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.

### Step 2: Choose LP Lock and Burn Settings After submitting the Self-Service Listing Pool, a pop-up will appear, allowing the creator to choose whether to lock or burn the initial LP tokens, or to leave the liquidity pool unlocked. By default, the Self-Service Listing Pool is set to be locked for 6 months, as it is the recommended option. Users are prompted to select one of three settings: * **Do not lock LP 🔓**: There will be no lock-up period and the initial liquidity provider (the pool creator) will receive the corresponding LP tokens once the pool is live and operational. Since the pool is unlocked, the owner will be able to withdraw liquidity at any time. * **LP is locked for 6 months 🔒** : This is the default option. It locks liquidity within decentralized smart contracts for a 6 month period, requiring a manual LP claim upon maturity. When the period concludes, the pool owner can withdraw liquidity as any other provider. This prevents unexpected withdrawals and protects liquidity providers from rug pulls. * **Burn LP 🔥** : Permanently burns a portion of tokens, ensuring that they can never be recovered or withdrawn. Since the initial liquidity vanishes, this option protects future liquidity providers from rug pulls and enhances trust and transparency.

In case of locking or burning tokens, there will be a highlighted banner that displays the setting selected by the pool creator. This way, liquidity providers will know if the initial LP tokens have been locked or burnt, or if neither option has been applied. ### Step 3: Contract Creation Once the transaction you executed in Step 1 is completed, you will see the checkbox labeled `Deposit Anchor Token ✅` marked as done. The ALEX team will review the submitted information and create a specific contract (a wrapped version) for your token to interact with the AMM DEX. This process may take between 24 and 48 hours. ### Step 4: Deposit Listing Token Once the `Contract ready ✅` checkbox is marked as done, you're ready to deposit the listing token balance. This step involves interacting with a smart contract, so be sure to review the transaction details, paying particular attention to the amount to transfer. By accepting this transaction, you agree to transfer the initial liquidity of the listing token from your wallet to the ALEX smart contract. ### Step 5: Pool Creation Success Once the `Deposit Listing Token ✅` transaction is completed and the `Open pool ✅` checkbox is marked as done, your pool will be automatically ready for use. The new pool will appear as an ALEX Pool under the `Self Listed` tab on [app.alexlab.co/pool](https://app.alexlab.co/pool). 🤝 After completing this step, you (and everyone) can start trading the token pair on ALEX DEX 🤝

{% hint style="warning" %} If you have added a custom `start-block` configuration, the pool will be unavailabe until that block is reached. {% endhint %} ### Step 6: Provide Additional Token Information (Optional) To make your token visible on the ALEX Token List at [app.alexlab.co/token-list](https://app.alexlab.co/token-list), provide additional token information. Click on `Customer Support` on the [Self-Service Listing page](https://app.alexlab.co/self-service-listing) or contact us via Telegram at [t.me/ALEXselfservice](https://t.me/ALEXselfservice) to submit the information (e.g. X accont, Discord, official website).

ALEX requires a [Coingecko](https://www.coingecko.com/) or [CoinMarketCap](https://coinmarketcap.com/) token listing to verify the provided social media information before uploading it to the official list at [app.alexlab.co/token-list](https://app.alexlab.co/token-list). Thanks for creating your pool on the ALEX DEX 🎉 📈 # Add Farming to Your Pool Add the farming feature to your pool and reward LPs with an additional yield! {% hint style="warning" %} You can only add farming to liquidity pools that you have created via the ALEX Self-Service Listing. If you don't have your own pool yet and want to create one, check the [Self-Service Listing](https://github.com/alexgo-io/alexlab-doc/blob/main/users/product-features/broken-reference/README.md) page to find out how. {% endhint %} ## 🚀 Getting started ### How Does It Work? * The pool owner creates the farm by specifying the number of cycles and depositing the total reward amount. These two inputs determine the rewards distributed per cycle, which are equal for each cycle. * The pool's liquidity providers stake their LP tokens in the newly created farm, earning rewards at the end of each cycle, just like any other farm within the ALEX Lab Platform. For further details on how farms operate within ALEX, refer to the [Farming Key concepts](/what-can-you-do/farming/key-concepts) section of the docs. ### Considerations Before you start, familiarize yourself with the basic rules of Self-Service Farming. 1. Only the pool creator can use Self-Service Farming to add farming to their pool. 2. When creating a liquidity pool, an anchor token (Token X) and a listing token (Token Y) are defined. Self-Service Farming only allows the listing token to be used as the farming reward. 3. The total amount of rewards for the entire farm lifecycle must be deposited at the time of farm creation. 4. A "gathering" period occurs between the creation of the farm and the start of the first emission cycle. Farmers who stake their LP tokens during this period will be eligible to receive the farming rewards associated with the first emission cycle. ## 📝 Procedure ### Step 1: Go to the Farm Page Go to the [Farm page](https://app.alexlab.co/farm) and click on the "Create" button.

In this guide we are assuming that you already have a pool, so select the `Creating a new farm` option and click `Continue`.

### Step 2: Select a Pool Select a pool from the ones you've created.

### Step 3: Enter Rewards to Be Distributed Enter the total amount of rewards that will be distributed in your farm. This amount is deposited at farm creation. Also, remember that in Self-Service Farming, the reward token has to be the same as the listing token.

### Step 4: Enter Cycle Length and Amount Select the **Reward Cycle Length**, which is the number of cycles in which your farm will be active and distributing rewards. This number, along with the total farming rewards, determines the **Est. Farming Rewards Per Cycle**. At this point, you will also be able to see the number of the cycles in which your farm will be officially open, displayed as **Farm Opening Cycle**. The farm will be created instantly once the farm creation transaction is confirmed. However, the **Emission Start Cycle** will be the next upcoming cycle. The time gap between the farm creation and the start of the first emission cycle is the so-called "gathering" period, during which users can begin staking their LP tokens in the farm. {% hint style="danger" %} **Caution:** To maximize the gathering period, it is advisable to create your farm at the start of a new farming cycle. {% endhint %}

#### Example From the screenshot above, the **Total Farming Rewards** is `15,000 DOGGY`, and **Reward Cycle Length** is `10`, meaning that `15,000 DOGGY / 10 = 1,500 DOGGY` will be the **Farming Rewards Per Cycle**. If the user submits, the farm will be created at Cycle #80, leaving 33 blocks for the gathering period (approximately 5 hours and 29 minutes). In these cases, it is recommended to wait for the next cycle, as indicated in the alert box. This prevents LP tokens from being committed to the farm too late for the next reward distribution cycle. If the user decides to proceed, the **Farm Opening Cycle** will run from Cycle #81 to Cycle #90, lasting approximately 35 days. ### Step 5: Confirm Rewards Submission Once you're ready to move ahead, select the `Submit Rewards` button which will bring up the Confirmation panel. This panel provides a final overview of the farm creation, allowing you to double-check the total rewards and the farm opening period. If everything looks good, click `Confirm` 😎.

### Step 6: Confirm the Transaction in Your Wallet After clicking `Confirm`, you will need to confirm the transaction in your wallet. Here, your Stacks wallet is interacting with ALEX smart contract and is asking you for approval. Remember, in this farm creation transaction, you are transferring the total amount of rewards to the ALEX smart contract. 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. {% hint style="info" %} To be completely sure, you can check: * The transaction is requested by **"Alex app" (app.alexlab.co)** * The transfer amount, covered by [Stacks post conditions](https://docs.stacks.co/stacks-101/post-conditions). Note that the amount you transfer to the smart contract is exactly determined (DOGGY in the example). If this condition is not met, the transaction will abort. {% endhint %} ### Step 7: Wait for Transaction Confirmation Wait for the transaction to be confirmed on the network. {% hint style="info" %} Recommended to track transaction status: * Turn on Telegram notifications, 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 %} ### Step 8: Check Successful Farm Creation Once the transaction is completed, your farm will have been successfully created. Your farm will appear on the [Farms](https://app.alexlab.co/farm) page and from that moment is open to the first farmers who want to join during the gathering period. Thanks for launching your farm through ALEX Lab! 🌽 🌾 🚜 ## Support For assistance, please reach out to our Community Managers on [Discord](https://discord.com/invite/alexlab) and [Telegram Channel](https://t.me/AlexCommunity). # Tokenomics ALEXnomics charts a course toward the decentralization and autonomy of the ALEX protocol. Given a common thread of an ALEX token to bind them, how does an amorphous community weave itself towards a tapestry? Tokenomics is not a series of binary “do or don’t” gates, but of incentives and self-governance as steering mechanisms to guide a community toward maximizing its utility. In this paper we lay out the framework for progressive governance and liquidity decentralization, with the vision of establishing an enduring public institution. ALEX balances incentivizing our early liquidity providers with the long term interest of the platform, through “cap” and “gate” mechanisms from traditional finance. We also introduce quantitative risk analysis to Tokenomics, using Value-at-Risk modeling and statistical simulations in our risk management framework. We’re able to simulate Black Swan events worse than any historically recorded to ensure ALEX is robust in any market environment, as well as our defensive measures should a shortfall event occur. ## **What is ALEX?** ALEX is an open-source DeFi protocol on Bitcoin via Stacks’ smart contracts. The vision of ALEX is to contribute towards the financial infrastructure needed to realize Web3. We help realize this by providing the following basic elements of a mature financial system: Markets: * Launchpad provides an interface for new project launches. * Decentralized exchange with both AMM (Automated Market Maker) and off chain order-book to facilitate liquidity for projects built on Stacks Financial Instruments: * We introduce fixed-rate and fixed-term lending and borrowing markets — effectively creating the first zero-coupon bonds in the DeFi space Leverage * We offer the use of leverage for the pursuit of higher returns, both through margin trading as well as yield farming Notably we eliminate the risk of forced liquidation through the [use of dynamic collateral rebalancing pools](https://medium.com/alexgobtc/whitepaper-2-automated-market-making-of-the-collateral-rebalancing-pool-937f1068fe0). By establishing these financial primitives, the building blocks of a financial ecosystem, more advanced financial instruments can be subsequently recreated in DeFi space. ## **ALEX Token** Tokens are an effective mechanism to distribute the fundamental value of a project. ALEX token, noted as **$ALEX is a medium for the exchange of time value and risk/return preferences**. $ALEX is the participation token of the platform and protocol that provides protocol & platform governance benefits to a governance participant who holds $ALEX. $ALEX is also the medium by which participants of platform activities — namely provision of liquidity on our DEX and staking — are incentivized. $ALEX can be acquired through our DEX, LP participation and staking, with three main functionalities: ### **Incentives** The primary utility of $ALEX is to serve as the medium by which participants of platform activities — namely provision of liquidity on our DEX and staking — are incentivized. $ALEX emissions will sustainably drive adoption and continued participation, engaging a community of users and strategic partners. ### **Staking** $ALEX can be locked for a voluntary period of time, to earn $ALEX as rewards. 50% of the initial token supply is allocated for staking where $ALEX or Liquidity Tokens can be locked for a voluntary period of time earning $ALEX as rewards. ### **Voting** $ALEX is the mechanism for entering and exiting the ALEX community, as well as for voting and platform governance. $ALEX holders have voting rights on, but not limited to: * Future platform development * Transaction fee rebate to liquidity providers * Staking policy * Reserve fund distribution policy * ALEX token supply policy (including buyback and increase) ## **Progressive Governance Decentralization** ALEX approaches governance decentralization progressively, through a process where the founding team increasingly relinquishes control over time. It allows the team to focus on and catalyze network development at its initial stage. Networks can distribute tokens, for example. Tokens decentralize the control, operation, and management of the network itself. At the same time, progressive decentralization creates a path toward regulatory compliance. The framework of our legal entity setup is governed by the ALEX Lab Foundation, currently consisting of the ALEX team. The goal of the Foundation is to progressive transition into a full DAO with every $ALEX holder an eligible Foundation member. ### **Token Distribution** The Issuer Co issues a total initial supply of 1,000,000,000 (one billion) ALEX governance tokens, $ALEX. The total initial supply is allocated as the following * 20% to the Foundation, to be allocated to the Community Reserve Pool to support the ecosystem, early adopters and future development of ALEX * 50% is reserved for the community staking $ALEX or Liquidity Tokens to earn $ALEX * 30% to employees, advisors and early investors and founding team

### **Community Token Emission Schedule** Different staking pools may have different token emission schedules, reflecting differentiated risks associated with the underlying pools/assets. The launch of a staking pool will require 20 unique wallets to signal activation as part of a function in the smart contract, after which a countdown begins and anyone is eligible to stake within a given Stacks block thereafter. Across all staking pools, the total emission of $ALEX will be capped to:

## **Governance** ALEX not only builds decentralized finance but is also committed to decentralizing the entire project progressively. The goal of the ALEX Lab Foundation is to become a full-fledged DAO, one which gives the ALEX community complete control over both on-chain and off-chain governance decisions. However, this is a complex process, one which will have to be approached incrementally and deliberately by necessity. ### **ALEX Genesis DAO** The first step toward progressive decentralization of governance is the creation of ALEX Genesis DAO. Approximately 60 days after Mainnet launch, the Foundation will announce a Genesis Team as well as a formalized ALEX Growth Proposal (AGP) framework through which any $ALEX holder can submit a proposal for community consideration. The Genesis Team will consist of ALEX Team members that act as an intermediary between the community and the Foundation. AGPs may be as simple as a slight adjustment to transaction fees to as complex as adding new functionalities or adding cross-chain assets. The Genesis Team will review community-approved AGPs, and provide an implementation proposal on the feasibility and time required to execute the AGP. The implementation proposals will be open to a vote by $ALEX holders.

The Genesis DAO will be in place for the first 6–18 months after mainnet, empirically determining the best governance practices together with the community. Although every effort will be made to respect the finality of the governance vote, as a failsafe the Foundation will have veto power and the ability to suspend the governance system. Once the governance system is operating in a reliable, distributed manner, the transition to the formal ALEX DAO will begin. The Genesis Team will suggest that the fail-safe be removed and the community will vote on transferring all governance to the ALEX DAO. ## **Progressive Liquidity Decentralization** DeFi protocols have to balance bootstrapping initial liquidity while maintaining long-term usage. Incentivizing provision of short-term liquidity has been compared to “renting” liquidity. Short-term incentives attract mercenary capital that captures a significant portion of the initial rewards and then summarily exits shortly thereafter to pursue the next highest yielding project. Smaller protocol users are demoralized as exploitative behavior is rewarded. Borrowing from traditional money managers’ liquidity management through a series of gates, ALEX creates mechanisms of liquidity commitment. This will filter for LPs who are committed to the long-term growth of ALEX, as we achieve Progressive Liquidity Decentralization (PLD). Progressive liquidity decentralization is managing the transition from the concentrated liquidity that characterizes the launch of a platform, towards a state of decentralized liquidity where no individual or small group of individuals control the majority of the platform liquidity. ALEX will introduce a “cap” on the amount a single liquidity provider can contribute as well as “gates” that will manage an orderly exit of capital, with a view to ensuring that no single LP can be more than a certain percentage of total liquidity and a long-term liquidity commitment is rewarded. This serves to align the interest of our Liquidity Providers with the interests of the ALEX community and protocol, which best ensures the long term growth, prosperity and price appreciation of the ALEX Token. ## **Risk Management of ALEX Reserve Pool** How will a Black Swan event impact the ALEX platform? How should one “quantify” the risk? And what are the measures taken to ensure ALEX’s solvency? ALEX essentially consists of two parts: a Decentralized Exchange (DEX) and a platform for loanable funds (PLF). The former facilitates the swapping activities, whereas the latter is lending/borrowing. PLF typically requires over-collateralization, meaning the value of the loan is typically lower than the collateralization value to ensure that the loans stay afloat. When the market is distressed, the collateral value is likely to be lower than the loan value, which triggers a default. Most DeFi lend/borrow protocols introduce “liquidators”, who would unwind the collateral pool by imposing a hefty fee, causing a significant loss to the borrowers. To ensure a smooth borrowing/lending experience, ALEX employs Collateral Rebalancing (white paper link [here](https://medium.com/alexgobtc/whitepaper-2-automated-market-making-of-the-collateral-rebalancing-pool-937f1068fe0)) by constantly rebalancing the collateral pool between risky and riskless assets to avoid forced liquidation. Despite all cautious measures, a Black Swan event could result in a drastic fall in collateral value, causing risky assets unable to be converted fully to riskless assets in time. While borrowers walk away with a default, ALEX platform takes the hit. How can ALEX ensure its platform sustainability? To answer this question, we start with a framework to quantify the market risk. Then we design various lines of defense to protect ALEX’s solvency. ### **Value At Risk (VaR)** VaR is a statistical framework in risk management that quantifies risk exposure. Commonly applied in traditional finance, it is defined as the ***maximum dollar amount expected to be lost over a given time horizon***. VaR, for example, allows a financial institution to say “We are 99% confident our losses will not exceed $5M in one trading day.” ALEX’s risk modeling is conservative: 1. We focus on the extreme loss occurring events with extremely low probability. 2. To magnify the market dislocation, we simulate magnified “jumps” in crypto price movement, meaning the price could suddenly gap down to unprecedented levels. For instance, in the past five years, the largest negative hourly jump size is 18%. The probability of a jump size between -10% and -18% is as low as 0.017%. To study the impact of possible Black Swan events, we randomly add negative jumps sizes of 20%, amplifying the probability of jumps to 100 times the historical average. These simulations provide insight into the magnitude of the loss that the platform would incur. For example, with an initial LTV of 75% and the jump frequency 100 times higher than the historical average, the **probability is less than 1% to have 12.5% of the collateral value to default.** Furthermore, under reasonable assumptions on the size of the collateral rebalancing pool and ALEX annual fee revenue, we can compare the loss with the revenue generated by ALEX through transaction fees. In the case study listed in the appendix (with collateral pool size is assumed to be 31.25% and the monthly fee revenue 1.25% of the total TVL), **we conclude that the loss incurred to the platform is equivalent to roughly 3 months fee.** **The severity of the black swan events modeled here provides confidence that the elimination of liquidation risk on ALEX is sustainable in the long term.** ### **Shortfall Event** If, for any unforeseen reason, a Shortfall Event occurs, the first line of defense is the ALEX Reserve Pool. The Reserve Pool’s main income is transaction fees. As we rebate LPs a percentage of the transaction cost, the rest will be assigned to the Reserve Pool automatically. Subject to governance, Reserve Pool size is relative to platform risk and may trigger $ALEX buyback or new issuance. So long as the Reserve Pool is solvent, it will cover the losses of minor shortfall events with no suspension of protocol operations. Should the Reserve Pool become insolvent, subject to a vote of approval from the community, more ALEX Token may be issued. This is the second line of defense. All proceeds of the sale would go to the Reserve Pool, until shortfall loss is covered. ## **Conclusion** ALEX is a protocol built by veteran quants who have built the quantitative trading and risk management systems for Wall St. banks. We have taken that knowledge and expertise into DeFi and tokenomics. For our risk management, rather than rely on a “token reserve” of arbitrary size, we apply statistical modeling to draw inference on how ALEX will be resilient to Black Swan events. Decentralization is our greatest strength, as it allows us to create an open and adaptive protocol that can evolve in entirely new ways. The progressive decentralization of governance we pursue begins with our Genesis Dao. The progressive decentralization of liquidity we pursue through mechanisms of commitment unique to DeFi. By introducing “caps” on the amount a single LP can contribute as well as “gates” that will manage an orderly exit of capital, we balance incentivizing our early LPs with the long-term interests of the ALEX protocol and community. ALEX seeks partnership and community from our ecosystem to establish enduring financial infrastructure. This has been only a quick introduction to ALEX Token to present an overview of our token utility and broader tokenomics. Look out for more blog posts in the very near future, and please check our documentation and social media channels for more information.\[1] ## **Appendix** ### **Scenario analysis: Likelihood of and Impact of a Shortfall Event** In the event of extreme adverse market conditions (Black Swan event), the Collateral Rebalancing Pool (CRP) is likely to be most impacted because borrowers default on their loans. To quantify the impact of our capital sufficiency, we rely on simulation techniques. Let’s assume the CRP holds BTC-UDSC as a risky-riskless asset pair, with a contract loan term of three months. In the simulation, we assume the BTC-USD price follows a Brownian motion with a jump diffusion: 1. The Brownian motion has an annualized average return of -200%. This is equivalent to a 50% BTC price drop within three months, which is among the worst scenarios ever observed in BTC history. Annualize volatility is calibrated to 100% (average annual volatility of the last 5 years is \~ 80%) 2. To be conservative, we add a jump diffusion process, defined as the following: where is the BTC price at t and t-1 hour respectively. In the past five years, the largest negative hourly Jump size is 18%. The probability of a Jump between -10% and -18% is as low as 0.017%. To study the impact of possible Black Swan events, we randomly add negative jump sizes of 20% to the brownian motion, amplifying the probability of a jump to 1, 10, 20, 50 and 100 times of historical average. Another key parameter to calibrate is Loan-to-Value (LTV), the ratio of the loan amount to the value of the collaterals. The larger the LTV, the more chance the loss could occur to the platform. We assume LTV is between 70% and 80%, a relatively high level to all other Defi projects. Figures 1 and 2 assume that loss occurs at 5% probability within the duration of a three-month loan. \*\*\*\*The loss is expressed as a percentage of initial CRP value with respect to LTV and price jump amplifiers. Unsurprisingly, the higher chance of loss corresponds to a larger initial LTV. For example, when BTC-USD price jump is 100 times more frequent than the historical average, and a LTV of 75% LTV, 10% of the collateral would default. Figures 3 and 4 studies the loss occurring at 1% probability during three months. Using the same assumption on jumps before, and a LTV of 75% LTV, 10% of the collateral would default.

### **How to Interpret the platform loss** We hope to provide an intuitive framework to analyze the platform loss in case of market stress. Certain assumptions are imposed, allowing us to quantify the loss relative to the platform revenue. Assuming TVL is $20mn, which is comparable to similar Defi projects in their initial launch stage. Annual fee revenue is assumed to be 30% of the TVL, of which 50% is allocated to the LP, and 50% would be left at ALEX Reserve Pool.

We assume an equal split of TVL, i.e. $10Mn, between DEX and borrowing/lending pool. The value of Token and yieldToken shouldn’t be distant, as long as the interest rate is kept within a reasonable range. Therefore, the value of the yield Token in ALEX is assumed to be 5mm. As minting yieldToken requires collateral, an LTV of 80% means that the collateral amount in the pool is equivalent to 6.25mm, a ratio of 31.25% to the total TVL of ALEX. According to our simulation, in the extreme case of 100X jump amplifiers and 75% initial LTV, the platform could lose 12.5% of the collateral pool with a probability of less than 1%, if market catastrophe leads to liquidity vacuum and risky assets unable to convert to riskless assets on time. Translating to the ratio of TVL, this loss is equivalent to around 3.9% of the total TVL of ALEX. Under our fee assumption, ALEX generates monthly fee equivalents to 2.5% of the total TVL, among which 1.25% will be allocated to the Reserve Pool. **Therefore, our loss is slightly higher than the 3-month cumulative fee of the platform.** \[1] After Mainnet launch, $ALEX can be acquired through our DEX or earned as incentives by anyone who is a liquidity provider or our DEX or stakes $ALEX with the platform. More information about the Mainnet launch and how to acquire your first $ALEX will be published soon. We encourage our community to participate in ALEX Testnet, as every participant contributes to the improvement of ALEX and is a true asset to the ALEX community. # Official Links All official links are available here for your reference to prevent you from falling into phishing websites impersonating ALEX. ### Platform Links **Landing Page:** **App Landing Page:** **Spot Swap:** [swap](https://app.alexlab.co/swap) **Add/Remove Liquidity:** **Orderbook:** **Token List:** **Platform Explorer:** ### Social Media **X/Twitter:** **Discord:** **YouTube:** **LinkedIn:** **GitHub:** **Medium:** ### Verified Team X/Twitter Profiles Chiente Hsu: Rachel: ### Verified Tag on Discord for Team Authenticity ![Discord Role Verification](/files/9LQHAYfkSAJgiApMhum0) If you are looking for help with something beyond our Gitbook resources or trying to report issues on the platform, you may reach out to our team with the ALEX Team role. Due to the high influx of Discord scammers impersonating team members to deceit other community members, be sure to stay safe and always double-check the user's roles. # Overview **ALEX** is building the financial infrastructure on Bitcoin by combining Bitcoin L1 with Stacks L2 to unlock smart contract capabilities, DeFi primitives, and permissionless financial tools for Bitcoin users. Our architecture allows decentralized trading, cross-chain swaps, yield generation, and more — all secured by Bitcoin and powered by Stacks. With Ordinals, BRC-20s, and Layer 2 innovation accelerating, ALEX is shaping the future of Bitcoin DeFi. ## About This documentation is designed for developers building on or integrating with the ALEX ecosystem. Here you'll find: 🧩 Technical overviews of [AMM](/developers/products/alexs-automated-market-maker-amm), [Orderbook](/developers/products/what-is-orderbook) and [Launchpad](/developers/products/what-is-the-launchpad) 📡 [REST API reference](https://github.com/alexgo-io/alexlab-doc/blob/main/developers/developers/api-references.md) to access the latest market data on ALEX 🏛️ [Smart contracts documentation](https://github.com/alexgo-io/alexlab-doc/blob/main/developers/developers/protocol-contracts/README.md) 🛡️ [Security audit reports](https://github.com/alexgo-io/alexlab-doc/blob/main/developers/developers/security-audit.md) ## Need Help? If you have questions or need assistance, join our developer community on [GitHub](https://github.com/alexgo-io) or reach out to our team through [Discord](https://discord.gg/alexlab). # AMM ## **ALEX’s Automated Market Maker (AMM) — Short Version** ALEX’s core product is essentially a zero-coupon bond in conventional finance. A key benefit of this product is reduced uncertainty about a loan’s interest rate, resulting in better financial planning. Specifically, prior to entering a loan contract, borrowers and lenders secure the loan’s interest rate and tenor on ALEX. ## **1. Automated Market Making (AMM) Protocol** When designing AMM, ALEX believes in the following: (i) AMMs are mathematically neat and reflect economic supply and demand. For example, price should increase when supply is low or when demand is high; (ii) AMMs are a type of mean which remains constant during trading activities. This approach is adopted by popular platforms, such as *Uniswap*, which employ algorithmic means; and (iii) AMM can be interpreted through the lens of modern finance theory. Doing so enables ALEX to grow and draw comparisons with conventional finance. After extensive research, our beliefs led us to the AMM first proposed by *YieldSpace*. While we appreciate the mathematical beauty of their derivation, we adapt it in several ways with ALEX. For example, we replace a simple interest rate with a compounding interest rate. This change is in line with standard uses in financial pricing and modeling since the adoption of the Black-Scholes model. We also introduce a new capital efficiency scheme, as explained below. In mathematical terms, our AMM can be expressed as: *x ¹⁻ ᵗ + y ¹⁻ ᵗ = L* where *x, y, t,* and *L* are, respectively, the balance of “Token”, the balance of “ayToken”, time to maturity, and a constant term when *t* is fixed. Interest rate *r* is defined as *r =* log\*(y/x)\*, i.e. natural logarithm of the ratio of balance between “ayToken” and “Token”, while the price of “ayToken” with respect to “Token” is *(y/x)ᵗ.* Our design depicts an AMM in the form of a generalized mean. It makes economic sense because the shape of the curve is decreasing and convex. It incorporates time to maturity *t*, which is explicitly built-in to derive ayToken’s spot price. ## **2. Liquidity Providers (LP) and Capital Efficiency** LPs deposit both ayToken and Token in a pool to facilitate trading activities. LPs are typically ready to market-make on all possible scenarios of interest rate movements ranging from *−∞* to *+∞.* However\*,\* part of the interest rates curve or movements will never be considered by market participants. One example of this occurs when the interest rate is negative. Although negative rates can be introduced in the fiat world by central bankers as a monetary policy tool, yield farmers in the crypto world are still longing everything to be positive. In ALEX, a positive rate refers to the spot price of ayToken not exceeding 1 and ayToken reserve being larger than Token. Inspired by *Uniswap v3*, ALEX employs virtual tokens — part of the assets that will never be touched, hence they are not required to be held by LPs. ![https://miro.medium.com/max/1400/1\*h06s2YnEFXi6L97lAlP2\_Q.png](https://miro.medium.com/max/1400/1*h06s2YnEFXi6L97lAlP2_Q.png) Figure 1: *t =* 0.5 and *L =* 20. Blue line (IFC) satisfies *x ¹⁻ ᵗ + y ¹⁻ ᵗ = L,* whereas red line (CEC) satisfies *x ¹⁻ ᵗ + (y+yᵥ) ¹⁻ ᵗ = L*. Virtual reserve *yᵥ* = 100. Figure 1 illustrates an example of adopting virtual tokens in the event of a positive interest rate. The blue line is the standard AMM. The blue dot marks an equal balance of Token and ayToken of *yᵥ*, meaning there is no (or a 0%) interest rate. *yᵥ* is the boundary amount, as any amount lower than it will never be touched by an LP to avoid a negative rate, which is represented by the blue dashed line. Thus, *yᵥ* is the virtual token reserve. Effectively, LP is market-making on the red line, which shifts the blue line lower by *yᵥ*. When ayToken is depleted as shown by the red dashed line, trading activities are suspended. A numerical example provided in Table 1 shows capital efficiency with respect to various interest rates, assuming *t =* 0.5 and *L =* 20 for illustration’s sake. When the current interest rate *r =* 10%, LPs are required to deposit 95 Token and 105 ayToken according to standard AMM. However, if the interest rate is floored at 0%, LPs only need to contribute 5 ayToken, as the rest 100 ayToken would be virtual. This is a decent saving of more than 90%. ![https://miro.medium.com/max/1400/1\*1donSHtKYaEUb3Y7d9ZwbA.png](https://miro.medium.com/max/1400/1*1donSHtKYaEUb3Y7d9ZwbA.png) ## **3. Yield Curve and Yield Farming** By expressing interest rate as *pₜ =1/eʳᵗ*, i.e. r = (-1/*t)* log *pₜ*, we can obtain a series of interest rates from trading pool prices with respect to various maturities based on which we are able to build a yield curve. The yield curve is the benchmark tool for modeling risk-free rates in conventional finance. The shape of the curve dictates the expectation of future interest rate paths, which helps market participants understand market behaviors and trends. Currently, we might be able to build a Bitcoin yield curve from Bitcoin futures listed on Chicago Mercantile Exchange (CME). However, not only is the exchange heavily regulated, its trading volume is skewed to the very short-dated front-end contracts lasting several months only. ALEX aims to offer futures contracts up to 1y when the platform goes live. Should markets mature, ALEX may extend to longer tenors. Yield farmers can benefit from understanding the yield curve by purchasing ayToken whose tenor corresponds to high interest rates and selling ayToken whose tenor associates with low interest rates. This is a typical “carry” strategy. Last but certainly not least, based on the development of a yield curve and the solid design work of our AMM, ALEX is able to provide more products. Specifically, ALEX will be able to offer derivatives, including options and structured products, building on and extending a large number of influential works of literature and applications in conventional finance. # Trading Pool v1 ## Introduction In this section you will find an overview of the ALEX "Trading Pool" and its automated market making (AMM) protocol. At ALEX, we build DeFi primitives targeting developers looking to build ecosystem on Bitcoin. As such, we focus on trading of crypto assets with Bitcoin as the settlement layer. At the core of this focus is the AMM protocol, which allows users to exchange one crypto asset for another in a trustless manner. Trading Pool implements Generalized Mean Equation and, with a suitable parameterisation, supports both risky pairs (i.e. $$x y=L$$), stable pairs (i.e. $$x +y=L$$) and any linear combination in-between (i.e. Curve). Trading Pool is parameterised with a single parameter $$t$$. $$t$$ can be between 0 and 1, with $$t=1$$ being equivalent of constant product formula (i.e. Uniswap V2) and $$t=0$$ being equivalent of constant sum formula (i.e. mStable). $$0\ 0` before division in price calculations * Prevents runtime errors in edge cases **2. Balance Underflow Prevention** * Replaced conditional logic with explicit assertions * Example: `(asserts! (> balance-y dy) ERR-NO-LIQUIDITY)` before `(- balance-y dy)` * Applied to: `swap-x-for-y`, `swap-y-for-x`, `reduce-position` **3. Fee Validation** * Explicit validation to prevent zero swaps * Validates: `dx > 0`, `dx > fee`, `fee-rebate <= fee` **4. Input Validation** * Added `validate-pool-params` helper function * Validates: `token-x ≠ token-y`, `factor <= ONE_8` * Applied to: `create-pool`, `add-to-position` **5. Threshold Handling** * Improved handling to prevent division by zero when `t >= ONE_8` * Safe division because `t-comp` only used when `t < threshold` ### Accuracy Improvements **1. pow-down/pow-up Error Model** v1 used `mul-up` which compounded error: ```clarity (max-error (+ u1 (mul-up raw MAX_POW_RELATIVE_ERROR))) ``` v2 uses direct division with proper rounding: ```clarity (relative-error-part (if (is-eq raw u0) u0 (/ (+ (* raw MAX_POW_RELATIVE_ERROR) (- ONE_8 u1)) ONE_8))) (max-error (if (< relative-error-part MIN_POW_ABSOLUTE_ERROR) MIN_POW_ABSOLUTE_ERROR relative-error-part)) ``` Changes: * Removed `mul-up` to avoid compounding error * Direct division with round-up for error calculation * Added `MIN_POW_ABSOLUTE_ERROR` constant * Uses `<=` instead of `<` for comparison **2. get-switch-threshold Usage** * Result cached at function start instead of multiple calls * Reduces redundant computation ### Code Quality Improvements **1. Constants Organization** * All constants defined at top (lines 27-58) * Replaced magic numbers with named constants (e.g., `MAX_UINT`) **2. Address References** * Changed from relative (`.executor-dao`) to absolute addresses (`'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.executor-dao'`) **3. Clarity 3 Compatibility** * Uses `stacks-block-height` instead of `block-height` **4. Error Handling** * Standardized patterns across all functions *** ## What Are the Biggest Changes? ### 1. **New Mathematical Formula (Power-Based → Solidly)** **Before (v1)**: Used power calculations with `pow-fixed` function * Small swaps (0.0001 units) often returned zero * High gas costs: 800k for swaps * Precision loss when subtracting nearly equal fixed-point numbers * Example: Pool with 0.1 units each, t=0.05, swap 0.0001 → returned 0 **Now (v2)**: Uses Solidly formula with native `sqrti` * All swap sizes work correctly * 60-77% gas reduction (180k-320k for swaps) * Closed-form solutions: no iteration needed * Formula: $$x^n \cdot y + x \cdot y^n = k$$ where $$n \in {1, 2}$$ ### 2. **Enhanced Security with restrict-assets?** **Before (v1)**: Relied on token behavior **Now (v2)**: Clarity v4 `restrict-assets?` enforcement * Automatic rollback if token transfers exceed specified amount * Protection against reentrancy attacks * Enforced swap amounts ### 3. **Better Price Accuracy** **Before (v1)**: Power calculations lost precision in small swaps **Now (v2)**: Closed-form solutions with native `sqrti` * Accurate for all pool sizes * Scale-invariant behavior * No precision loss from subtracting similar numbers *** ## Problems Addressed ### Problem 1: Small Swap Precision Loss **Root cause**: For small swaps, `x^α - (x+dx)^α` loses precision when subtracting nearly equal fixed-point numbers. **Example**: ``` Pool: 0.1 units each, t=0.05 (α=0.95) Swap: 0.0001 units v1: Returns 0 v2: Returns 0.00009995 (correct) ``` **Solution**: Solidly formula uses quadratic formula `y' = (-x' + √(x'² + 4k/x')) / 2` with native `sqrti`, avoiding subtraction of similar numbers. ### Problem 2: High Gas Costs **Root cause**: Complex power calculations require many computational steps and iterations. **Solution**: Solidly formula has closed-form solutions: * n=1 (volatile): Direct division, 77% gas reduction (800k → 180k) * n=2 (stable): Quadratic formula with `sqrti`, 60% gas reduction (800k → 320k) ### Problem 3: Security Gaps **Root cause**: v1 relied on token behavior without blockchain-level enforcement. **Solution**: * Clarity v4 `restrict-assets?` enforces transfer limits at blockchain level * Explicit validation: division-by-zero protection, balance underflow prevention, fee validation * Input validation via `validate-pool-params` helper ### Problem 4: Scale Dependence **Root cause**: v1 formula behavior varied with absolute pool size due to fixed-point precision. **Solution**: Solidly formula is scale-invariant—pool with \[1, 1] behaves identically to \[1000, 1000] in terms of price impact and slippage. *** ## Implementation Status ### Development Complete (December 2025) ✅ **Core Implementation**: Complete * Solidly formula implemented and tested * `restrict-assets?` security integration complete * Gas optimizations applied * All existing v1 features working * 44/44 tests passing ✅ **Development Environment**: Complete * Clarinet SDK upgraded to v3.11.0 with full Clarity v4 support * Comprehensive test suite passing * Security scenarios validated (normal, token drain, STX drain) * Mathematical properties verified (price bounds, function symmetry) * Error code behavior confirmed 📋 **Next Steps**: External Security Audit * Contract ready for professional security audit * Testnet deployment for user testing * Mainnet deployment via DAO proposal after audit approval ### Deployment Approach The upgrade will replace the existing `amm-pool-v2-01` contract with `amm-pool-v2-02`. This is a **logic-only upgrade** that: * ✅ Requires no pool migration * ✅ Requires no liquidity provider action * ✅ Maintains all existing pool parameters and balances * ✅ Seamless from the user perspective All existing pools will automatically benefit from the improved formula and enhanced security without any user intervention. *** ## What This Means for You ### If You're a Trader: * ✅ Small swaps will work reliably * ✅ Lower transaction fees (40-77% reduction) * ✅ More accurate pricing * ✅ Same familiar interface and pool structure * ✅ Enhanced protection against malicious tokens ### If You're a Liquidity Provider: * ✅ More efficient pools (less gas waste) * ✅ Better price stability * ✅ Same rewards structure * ✅ Improved pool token (LP Token) consistency * ✅ No migration required—your positions automatically benefit * ✅ Additional security for your liquidity ### If You're a Developer: * ✅ Same API as v1 (easy integration) * ✅ Four new utility functions for advanced use cases: * `get-y-in-given-x-out`: Calculate Y needed when withdrawing X * `get-x-in-given-y-out`: Calculate X needed when withdrawing Y * `get-x-given-price`: Calculate X to reach target price * `get-y-given-price`: Calculate Y to reach target price * ✅ Better documentation and clearer code * ✅ `restrict-assets?` examples for building secure integrations *** ## Performance Metrics ### Gas Cost Comparison (Simnet Testing) | Operation | v1 | v2 (n=2) | v2 (n=1) | Reduction | | --------------- | -------- | -------- | -------- | ---------- | | create-pool | 150k | 130k | 110k | 13-27% | | add-to-position | 200k | 160k | 140k | 20-30% | | **swap** | **800k** | **320k** | **180k** | **60-77%** | | reduce-position | 180k | 150k | 130k | 17-28% | ### Precision Improvement (1,000 test swaps) | Swap Size | v1 Failures | v2 Failures | | ------------ | ----------- | ----------- | | 1e-8 to 1e-6 | 95% | 0% | | 1e-6 to 1e-4 | 30% | 0% | | 1e-4 to 1e-2 | 5% | 0% | | > 1e-2 | <1% | 0% | ### Contract Size | Metric | v1 | v2 | | --------- | --- | --- | | Lines | 761 | 728 | | Functions | 48 | 52 | | Tests | 18 | 22 | *** ## Alternative Methodologies Evaluated Before selecting Solidly, we evaluated several alternative AMM formulas: ### 1. Wombat Exchange **Invariant**: `(x - A/x) + (y - A/y) = D` * Pros: Good precision for stable pairs, proven in production * Cons: Not scale-invariant (A must equal `α × L²` for consistent behavior), requires custom square root ### 2. Solidly (Selected) **Invariant**: `x^n·y + x·y^n = k` * Pros: Scale-invariant, closed-form for n=1,2 using native `sqrti`, deployed on Solidly, Velodrome, Aerodrome * Cons: Limited to n≤2 for closed-form solutions ### 3. Saddle Finance **Invariant**: `A(x + y) + xy = k` * Pros: Simpler than Curve, decent for stable pairs * Cons: Not scale-invariant (similar to Wombat), limited production usage ### 4. Hybrid Constant Function **Invariant**: `w(x + y) + (1-w)(xy)/(x+y) = k` * Pros: Interesting theoretical properties * Cons: Limited production testing, partially scale-invariant ### Selection Rationale | Criterion | Wombat | Solidly | Saddle | Hybrid | | ---------------------- | ---------------- | ----------- | ------- | -------- | | Scale Invariant | No | Yes | No | Partial | | Small Swap Precision | Good | Excellent | Good | Moderate | | Native Clarity Support | No (custom sqrt) | Yes (sqrti) | No | Yes | | Production Use | Yes | Yes | Limited | No | **Decision**: Solidly selected for scale invariance and native `sqrti` support. ### Why Not n≥3? n=3+ requires Newton's method iteration: * Non-deterministic gas costs * Precision issues in fixed-point * <1% of pools would use it Decision: Prioritize closed-form solutions (n=1,2). *** ## Implementation Details ### Invariant Calculation ```clarity (define-read-only (get-invariant (balance-x uint) (balance-y uint) (t uint)) (let ((n (t-to-n t))) (if (is-eq n u1) (* u2 (mul-down balance-x balance-y)) ;; k = 2xy ;; n=2: k = x²y + xy² (let ( (x-squared (mul-down balance-x balance-x)) (y-squared (mul-down balance-y balance-y)) ) (+ (mul-down x-squared balance-y) (mul-down balance-x y-squared)))))) ``` ### Swap Calculation (n=2) ```clarity ;; Solve: (y')² + x'·y' - k/x' = 0 (let ( (discriminant (+ x-new-squared (div-down (* u4 k) x-new))) (sqrt-discriminant (sqrti (* discriminant ONE_8))) (y-new (/ (- sqrt-discriminant x-new) u2)) ) (- balance-y y-new)) ``` ### Mapping Strategy ```clarity (define-read-only (t-to-n (t uint)) (if (< t (get-switch-threshold)) ;; Default: 0.8 u2 ;; Stable pairs u1 ;; Volatile pairs )) ``` | ALEX t | Solidly n | Formula | Use Case | | ------- | --------- | ------------- | ----------- | | 0.8-1.0 | n=1 | 2xy = k | Volatile | | 0.2-0.8 | n=2 | x²y + xy² = k | Semi-stable | | <0.2 | n=2 | x²y + xy² = k | Stable | ### New API Functions v2 adds 4 read-only functions: 1. `get-y-in-given-x-out` - Calculate Y needed when withdrawing X 2. `get-x-in-given-y-out` - Calculate X needed when withdrawing Y 3. `get-x-given-price` - Calculate X to reach target price 4. `get-y-given-price` - Calculate Y to reach target price *** ## Frequently Asked Questions **Q: Will my existing LP positions be affected?**\ A: No action required. Logic-only upgrade. Existing positions benefit from the improved formula without migration. **Q: Will the pool parameter** $$t$$ **still exist?**\ A: The $$t$$ parameter remains for backward compatibility. It's internally mapped to $$n$$ (1 or 2) in v2: * $$t \geq 0.8$$ → $$n=1$$ (volatile, constant product-like) * $$t < 0.8$$ → $$n=2$$ (stable, enhanced curve) **Q: Why not support more** $$n$$ **values (n=3, n=4, etc.)?**\ A: Higher $$n$$ values require iterative Newton's method calculations, which would: * Increase gas costs unpredictably * Introduce precision issues * Benefit less than 1% of pools * Add complexity for minimal gain The $$n=1$$ and $$n=2$$ cases cover all practical use cases with closed-form solutions. **Q: Is this battle-tested?**\ A: The Solidly formula is used by: * Velodrome Finance: \~$50M daily volume * Aerodrome: \~$100M daily volume * Solidly (original): Production deployment * Combined: $150M+ daily volume Implementation tested on Stacks testnet with 44/44 tests passing. Security audit scheduled before mainnet deployment. **Q: When can we expect deployment?**\ A: Development is complete with 44/44 tests passing. Timeline: 1. ✅ **Development & Testing**: Complete (Clarinet SDK v3.11.0 with Clarity v4 support) 2. 📋 **External Security Audit**: Contract ready for professional audit 3. 📋 **Testnet Deployment**: User testing after audit completion 4. 📋 **Mainnet Deployment**: Via DAO proposal after audit approval Updates will be provided as milestones are reached. **Q: Will there be any downtime during the upgrade?**\ A: No. Seamless upgrade with no service interruption. Pools continue operating normally. **Q: Can I still use the same helper functions?**\ A: All v1 helper functions remain: * `swap-helper` (automatic routing) * `swap-helper-a`, `swap-helper-b`, `swap-helper-c` (multi-hop) * `get-oracle-instant`, `get-oracle-resilient` (price oracles) * `get-position-given-mint`, `get-position-given-burn` * `get-token-given-position` Plus four new functions for advanced use cases. *** ## Timeline Summary | Phase | Status | Notes | | ------------------ | ---------- | ---------------------------------------------------------- | | Core Development | ✅ Complete | Solidly formula + restrict-assets? implemented | | SDK Tooling | ✅ Complete | Clarinet SDK v3.11.0 with Clarity v4 support | | Testing | ✅ Complete | 44/44 tests passing (functionality, security, mathematics) | | Security Audit | 📋 Ready | Contract ready for external audit | | Testnet Deployment | 📋 Planned | User testing after audit | | Mainnet Deployment | 📋 Planned | Via DAO proposal after audit approval | *** ## Summary Trading Pool v2 improvements: 1. **Mathematical Formula**: Solidly formula fixes precision issues and reduces gas costs by 60-77% 2. **Security Enhancements**: * Clarity v4 `restrict-assets?` for malicious token protection * Division-by-zero protection, balance underflow prevention, fee validation * Input validation via `validate-pool-params` helper 3. **Accuracy Improvements**: * Improved pow-down/pow-up error model * Better threshold handling * No precision loss in small swaps 4. **Code Quality**: * Constants organization, standardized error handling * Clarity 3 compatibility (`stacks-block-height`) * Absolute address references 5. **Proven Technology**: Solidly formula used by DEXs with $150M+ daily volume 6. **Backward Compatible**: Same API, same $$t$$ parameter (mapped to $$n$$), same error codes ### Migration Logic-only upgrade. No pool migration required. No user action required. ### Breaking Changes * Address references changed from relative to absolute * Requires Clarity 3 compatible environment ### Non-Breaking Changes * Public API: All function signatures unchanged * Error codes: All error codes unchanged * Return types: All return types unchanged * Mathematical formulas: Core formulas unchanged (only error handling improved) *** ## Technical Details: The Math Behind v2 ### Formula Evolution **v1 (Power-Based)**: $$x^{1-t} + y^{1-t} = L$$ Where $$t$$ is a parameter between 0 and 1: * $$t=1$$: Constant product (Uniswap-like) * $$t=0$$: Constant sum (mStable-like) * $$0\ 2. Velodrome Finance: 3. Aerodrome: 4. Wombat Whitepaper: 5. Curve StableSwap: 6. Clarity sqrti: 7. Clarity restrict-assets?: *** **Questions or feedback?** Join the discussion in the [ALEX Discord](https://discord.gg/alexlab) or [GitHub](https://github.com/alexgo-io/alex-dao-2). # DAMM ALEX AMM v3, also known as the Discrete Automated Market Maker (DAMM), is coming soon! ## Abstract The ALEX AMM v3 contract is an enhanced version of the Automated Market Making (AMM), optimized for concentrated liquidity. It utilizes the invariant function $(Vx + x) \* (Vy + y) = K$, which, with appropriately chosen virtual liquidity values $Vx$ and $Vy$, allows the AMM to focus liquidity within a specific price range $\[P\_{start}, P\_{end}]$. ## Math The invariant function is: $$ (Vx + x) \* (Vy + y) = K $$ Where $Vx$ and $Vy$ ensure the pair is traded in the price range $\[P\_{start}, P\_{end}]$. $$ Vx = f\_x(P\_{start}, P\_{end}, x, y) $$ $$ Vy = f\_y(P\_{start}, P\_{end}, x, y) $$ In order to simply the math, we segregate the price range $(0, \infty)$ by introducing an integer parameter $tick$ and bin size $bs$, where for each $tick$ we have a price range $P\_{start} = (1 + 0.01 \* bs)^{tick}$ and $P\_{end} = (1 + 0.01 \* bs)^{tick + 1}$. We define $t = \sqrt{1 + 0.01 \* bs}$ and $p = P\_{start}$, then we have: $$ P\_{end} = t^2 \* P\_{start} = pt^2 $$ The price of the pair is $P\_{start}$ when balance x is swapped out (i.e. $\Delta x = -x$), and is $P\_{end}$ when balance y is swapped out (i.e. $\Delta y = -y$). Hence: $$ p = \frac{Vx}{Vy + y + \Delta y} = \frac{Vx^2}{Vx \* (Vy + y + \Delta y)} = \frac{Vx^2}{K} $$ $$ pt^2 = \frac{Vx + x + \Delta x}{Vy} = \frac{Vy \* (Vx + x + \Delta x)}{Vy ^ 2} = \frac{K}{Vy^2} $$ Hence: $$ p^2t^2 = \frac{Vx^2}{Vy^2} $$ $$ Vx = ptVy $$ So: $$ pt^2 = \frac{K}{Vy^2} = \frac{(Vx + x)(Vy + y)}{Vy^2} = \frac{(ptVy + x)(Vy + y)}{Vy^2} $$ $$ p(t^2 - t)Vy^2 - (x + pty)Vy - xy = 0 $$ $$ Vy = \frac{x + pty + \sqrt{(x + pty)^2 + 4p(t^2 - t)xy}}{2p(t^2 - t)} $$ $$ Vx = \frac{x + pty + \sqrt{(x + pty)^2 + 4p(t^2 - t)xy}}{2(t - 1)} $$ ## Swap x for y util price hit $P\_{max}$ This is similar to Immediate or Cancel (IOC) order in orderbook, given $\Delta x$, swap as much as possible until the price hit $P\_{max}$, where $P\_{max}$ is within the price range $\[P\_{start}, P\_{end}]$. $$ P\_{max} = \frac{Vx + x + \Delta x\_{max}}{Vy + y - \Delta y} $$ $$ K \* P\_{max} = (Vx + x + \Delta x\_{max})^2 $$ $$ \Delta x\_{max} = \sqrt{K \* P\_{max}} - (Vx + x) $$ $$ \Delta x\_{swappable} = min(max(0, \Delta x\_{max}), \Delta x) $$ $$ \Delta y = (Vy + y) - \frac{K}{Vx + x + \Delta x\_{swappable}} $$ ## Swap y for x util price hit $P\_{min}$ Likewise, given $\Delta y$, swap as much as possible until the price hit $P\_{min}$, where $P\_{min}$ is within the price range $\[P\_{start}, P\_{end}]$. $$ P\_{min} = \frac{Vx + x - \Delta x}{Vy + y + \Delta y\_{max}} $$ $$ \frac{K}{P\_{min}} = (Vy + y + \Delta y\_{max})^2 $$ $$ \Delta y\_{max} = \sqrt{\frac{K}{P\_{min}}} - (Vy + y) $$ $$ \Delta y\_{swappable} = min(max(0, \Delta y\_{max}), \Delta y) $$ $$ \Delta x = (Vx + x) - \frac{K}{Vy + y + \Delta y\_{swappable}} $$ ## Add liquidity After adding $\Delta x$ and $\Delta y$ to the pool, the pool size (i.e. liquidity token balance) and token pair price will both be affected. $$ Price = \frac{V\_x' + x + \Delta x}{V\_y' + y + \Delta y} $$ The price should be checked to prevent unexpected deviation from other markets. And the pool size increase proportionally to the virtual balances. $$ L\_p' = L\_p \* \frac{V\_x'}{V\_x} = L\_p \* \frac{V\_y'}{V\_y} $$ This is based on the fact that swapping does not change $V\_x$, $V\_y$, and the pool size. So when token y is depleted, i.e. $y = 0$, the balance of token x represents the total value of the pool: $$ V\_x = \frac{x + pty + \sqrt{(x + pty)^2 + 4p(t^2 - t)xy}}{2(t - 1)} = \frac{x}{t-1} $$ $$ x = (t-1)\*V\_x $$ $$ L\_p' = L\_p \* \frac{x'}{x} = L\_p \* \frac{(t-1)\*V\_x'}{(t-1)\*V\_x}= L\_p \* \frac{V\_x'}{V\_x} $$ The same when token x is depleted, i.e. $x = 0$, the balance of token y represents the total value of the pool: $$ Vy = \frac{x + pty + \sqrt{(x + pty)^2 + 4p(t^2 - t)xy}}{2p(t^2 - t)} = \frac{y}{t-1} $$ $$ y = (t-1)\*V\_y $$ $$ L\_p' = L\_p \* \frac{y'}{y} = L\_p \* \frac{(t-1)\*V\_y'}{(t-1)\*V\_y}= L\_p \* \frac{V\_y'}{V\_y} $$ ## Reduce liquidity If we change the existing pool balance proportionally, we get the new invariant function: $$ (\sigma Vx + \sigma x) \* (\sigma Vy + \sigma y) = \sigma ^2 K $$ $$ Price = \frac{\sigma Vx + \sigma x}{\sigma Vy + \sigma y} = \frac{Vx + x}{Vy + y} $$ Hence changing the existing pool balance proportionally does not affect the price of the pair. So when adjusting the liquidity, for a given $\Delta x$ we have: $$ \frac{y - \Delta y}{x - \Delta x} = \frac{y}{x} $$ $$ \Delta y = \frac{y}{x} \* \Delta x $$ ## Appendix ### Implement pow-fixed in Clarity The pow-fixed function needed for AMM v3 is defined as: $$ pow(x, n) = x ^ n $$ Where x is a fixed point number with precision $10^8$, and n is an integer. To simplify the calculation in Clarity, we assume only a limited set of bin sizes are supported (e.g. 5%, 10%, and 20%), and the price range falls between 0.00000001 and 100000000. And then we can pre-calculate the result for $(1 + bs) ^ {(2 ^ n)}$. ```clarity (define-constant PRICES_5 (list u26574222192236 u51550191262 u2270466719 u476494146 u218287458 u147745544 u121550625 u110250000 u105000000)) (define-constant PRICES_10 (list u19873012250342 u44579156845 u2111377674 u459497298 u214358881 u146410000 u121000000 u110000000)) (define-constant PRICES_20 (list u11684220576272 u34182189187 u1848842588 u429981695 u207360000 u144000000 u120000000)) ``` So that for a given tick, we have: $$ tick = \sum\_{i=n}^{0} (abs(tick & (2^i)) \* (2^i)) $$ $$ Price = \prod\_{i=n}^{0} (1 + 0.01 \* bs)^{abs(tick & (2^i)) \* (2^i)} $$ This mathematical optimization reduce the calculation complexity exponentially. ## Calculate Virtual Balances in Clarity Since there's no float point numbers in clarity, we use fixed decimal to calculate values, specifically using uint128 to represent a decimal with 8 fixed decimal places. So the calculations should be handled very cautiously in order to prevent precision loss (with error rate less than roughly 1e-8) and arithmetic overflow. This is how it looks like after we translate the formula of the virtual balances into code using float point numbers: ```javascript const ts = 1 + 0.01 * bin; const t = Math.sqrt(ts); const price = ts ** tick; // x + pty const x_pty = balanceX + price * t * balanceY; const denominator_vx = 2 * (t - 1); const denominator_vy = 2 * (price * (ts - t)); const numerator = x_pty + Math.sqrt(x_pty ** 2 + 2 * denominator_vy * balanceX * balanceY); const vx = numerator / denominator_vx; const vy = numerator / denominator_vy; ``` Then we translate it into code using fixed decimal with 8 decimal places: ```javascript const ONE_8 = 10n ** 8n; const ONE_16 = 10n ** 16n; // bin: 1n, 5n, 10n or 20n const ts = ONE_8 + (10n ** 6n) * bin; const t = Math.sqrt(ts * ONE_8); const price = pow_fixed(ts, tick); // x + pty const x_pty = balanceX + price * t * balanceY / ONE_16; const denominator_vx = 2n * (t - ONE_8); const denominator_vy = 2n * (price * (ts - t) / ONE_8); const numerator = x_pty + Math.sqrt(x_pty ** 2n + 2n * denominator_vy * balanceX * balanceY / ONE_8); const vx = numerator * ONE_8 / denominator_vx; const vy = numerator * ONE_8 / denominator_vy; ``` Now we consider the value ranges of the input: * balanceX, balanceY cap at 1000T=$10^{15}$: `[0n, 10n ** (8n + 15n)]` * Allowed price range: `[10n ** 4n, 10n ** (8n + 7n)]` * U128\_MAX: `2n ** 128n - 1n` = `340282366920938463463374607431768211455n`, approximately `3.4e38` When the values are small, there might be precision loss, for example: * When price and balanceY are small, e.g. price=1e4, balanceX=0, balanceY=1e3, `x_pty = 1e4 * 1e8 * 1e3 / 1e16 = 0` which should be `1e-9` in float point number, in this case `numerator = 2 * x_pty = 0` which should be `2e-9` in float point number, resulting `vx = 0` which should be `1e-9 / (1.01 ** 0.5 - 1) = 20.0498756211e-8` when `bin = 1` * When price is small, e.g. price=1e4, `denominator_vy = 2 * 1e4 * (1.01 - 1.01 ** 0.5) = 100`, which should be `100.2487577582` And when values are huge, there might be overflow, for example when `balanceX > 2e19` then `x_pty > 2e19`, `x_pty ** 2n > U128_MAX` To remediate that, we can scale balanceX and balanceY, to make max(balanceX, balanceY) be around `1e16`. This is based on the fact that virtual balances and balances scale proportionally, which is proved before. And do not divide by 1e8 so fast when getting `denominator_vy`. So we get the first revised version: ```javascript const ONE_8 = 10n ** 8n; const ONE_16 = 10n ** 16n; // bin: 1n, 5n, 10n or 20n const ts = ONE_8 + (10n ** 6n) * bin; const t = Math.sqrt(ts * ONE_8); const price = pow_fixed(ts, tick); // scale balances const amplify_factor = max(1n, ONE_16 / (max(balanceX, balanceY) + 1n)); const shrink_factor = max(max(balanceX, balanceY) / ONE_16, 1n); const bx_scaled = balanceX * amplify_factor / shrink_factor; const by_scaled = balanceY * amplify_factor / shrink_factor; // x + pty const x_pty = bx_scaled + (t * by_scaled / ONE_8) * price / ONE_8; const denominator_vx = 2n * (t - ONE_8); const denominator_vy_e8 = 2n * price * (ts - t); const numerator = x_pty + Math.sqrt(x_pty ** 2n + 2n * denominator_vy_e8 * bx_scaled * by_scaled / ONE_16); const vx_scaled = numerator * ONE_8 / denominator_vx; const vy_scaled = numerator * ONE_16 / denominator_vy_e8; const vx = vx_scaled * shrink_factor / amplify_factor; const vy = vy_scaled * shrink_factor / amplify_factor; ``` There are 2 issues with the first revision: 1. The max value of `x_pty` can be roughly `1e16 + 1e8 * 1e16 * 1e15 / 1e16`, which is `1e23`, this will cause `x_pty ** 2` to overflow when calculating the numerator 2. `denominator_vy_e8 * bx_scaled * by_scaled / ONE_16` should be handled cautiously to prevent precision loss For the first issue we use the same scaling method: ```javascript const x_pty = bx_scaled + (t * by_scaled / ONE_8) * price / ONE_8; const x_pty_shrink_factor = max(x_pty / ONE_16, 1n); const x_pty_scaled = x_pty / x_pty_shrink_factor; const denominator_vx = 2n * (t - ONE_8); const denominator_vy_e8 = 2n * price * (ts - t); // numerator is also scaled accordingly (numerator_scaled = numerator / x_pty_shrink_factor) to avoid overflow in the following calculations, and is approximately between 1e16 and 1e17 const numerator_scaled = x_pty_scaled + Math.sqrt( x_pty_scaled ** 2n + 2n * denominator_vy_e8 * bx_scaled * by_scaled / ONE_16 / (x_pty_shrink_factor ** 2) ); const vx_scaled = numerator_scaled * ONE_8 / denominator_vx; const vy_scaled = numerator_scaled * ONE_16 / denominator_vy_e8; const vx = vx_scaled * shrink_factor * x_pty_shrink_factor / amplify_factor; const vy = vy_scaled * shrink_factor * x_pty_shrink_factor / amplify_factor; ``` Since both `denominator_vy_e8` and `x_pty_shrink_factor` scale proportionally to price, and `x_pty_shrink_factor` is greater than 1 when `price` is greater than approximately `1e8`, hence `denominator_vy_e8 / x_pty_shrink_factor` is greater than `1e12`. And also `x_pty_shrink_factor` cap at approximately `1e7` when `by_scaled` and `price` are with the maximum value. Base on those, we can rewrite `2n * denominator_vy_e8 * bx_scaled * by_scaled / ONE_16 / (x_pty_shrink_factor ** 2)` into `2n * (denominator_vy_e8 / x_pty_shrink_factor) * (bx_scaled * by_scaled / ONE_16 / x_pty_shrink_factor)` to prevent precision loss. Now we get final revision: ```javascript const ONE_8 = 10n ** 8n; const ONE_16 = 10n ** 16n; // bin: 1n, 5n, 10n or 20n const ts = ONE_8 + (10n ** 6n) * bin; const t = Math.sqrt(ts * ONE_8); const price = pow_fixed(ts, tick); // scale balances const amplify_factor = max(1n, ONE_16 / (max(balanceX, balanceY) + 1n)); const shrink_factor = max(max(balanceX, balanceY) / ONE_16, 1n); const bx_scaled = balanceX * amplify_factor / shrink_factor; const by_scaled = balanceY * amplify_factor / shrink_factor; // x + pty const x_pty = bx_scaled + (t * by_scaled / ONE_8) * price / ONE_8; const x_pty_shrink_factor = max(x_pty / ONE_16, 1n); const x_pty_scaled = x_pty / x_pty_shrink_factor; const denominator_vx = 2n * (t - ONE_8); const denominator_vy_e8 = 2n * price * (ts - t); // numerator is also scaled accordingly (numerator_scaled = numerator / x_pty_shrink_factor) to avoid overflow in the following calculations, and is approximately between 1e16 and 1e17 const numerator_scaled = x_pty_scaled + Math.sqrt( x_pty_scaled ** 2n + 2n * (denominator_vy_e8 / x_pty_shrink_factor) * (bx_scaled * by_scaled / ONE_16 / x_pty_shrink_factor) ); const vx_scaled = numerator_scaled * ONE_8 / denominator_vx; const vy_scaled = numerator_scaled * ONE_16 / denominator_vy_e8; const vx = vx_scaled * shrink_factor * x_pty_shrink_factor / amplify_factor; const vy = vy_scaled * shrink_factor * x_pty_shrink_factor / amplify_factor; ``` # Orderbook

Orderbook is ALEX's scaling solution layer that brings **instant trade confirmation** to the security of Bitcoin. Orderbook uses a hybrid on-chain/off-chain design, whereby a commitment to buy or sell certain asset is communicated in a cryptographically signed message, which is then matched by an off-chain matching engine before settling on-chain. Orderbook is designed such that many types of market exchanges, not only a traditional CLOB but also an NFT marketplace or social trading, can be built on top. ## Why do we need the Orderbook? Orderbook is ALEX's scaling solution layer that brings **instant trade confirmation** to the security of Bitcoin. Orderbook therefore addresses a key user experience issue our community has on Stocks - that the trade confirmation requires waiting of 10-15 minutes (along with Bitcoin block confirmation). ## What are the benefits of using the Orderbook? There are a number of benefits for Bitcoin/Stacks users to use Orderbook to trade assets. ### Instant trade confirmation with Bitcoin finality As we said earlier, Orderbook is our scaling solution layer that combines instant trade confirmation with Bitcoin finality. Orderbook therefore addresses a key user experience issue our community has on Stocks - that the trade confirmation requires waiting of 10-15 minutes (along with Bitcoin block confirmation). ### Gas-free orders Orderbook uses a hybrid on-chain/off-chain design, whereby a commitment to buy or sell certain asset is communicated in a cryptographically signed message, which is then matched by an off-chain matching engine before settling on-chain. This design means users of Orderbook can create/close orders gas-free and confirm their orders instantly without having to wait for the underlying block confirmation. ### Security of your assets You have the full ownership and control of your assets on Orderbook. Zero credit risk. ### By developers, for developers Ease and fun of development is at the core of Orderbook design. Orderbook is designed such that many types of market exchanges, not only a traditional CLOB but also an NFT marketplace or social trading, can be built on top. # Understanding the Orderbook Orderbook uses a hybrid on-chain/off-chain design, whereby a commitment to buy or sell certain asset is communicated in a cryptographically signed message, which is then matched by an off-chain matching engine before settling on-chain.

# Launchpad

Every project needs a platform to launch their project tokens and our Launchpad is a lottery-based token launch platform that uses a hybrid off-chain / on-chain model. All user funds related transactions are on chain. These include the submission of the Launch ticket together with the required payment tokens, the distribution or claim of the project tokens won, and the distribution or refund of the payment tokens in the case of not winning the lottery. What is computationally expensive, i.e. the lottery drawing itself, is done off chain, but submitted to our on-chain contract for verification. The lottery drawing is also transparent and verifiable as it is based on the random seed available from the latest block height, i.e. anyone can independently verify the winners' table. ## Off-chain lottery system Lottery system is based on a random number generator called “linear congruential generator”, which is [one of the oldest and best-known pseudorandom number generator algorithms](https://en.wikipedia.org/wiki/Linear_congruential_generator). It starts by firstly drawing a verifiable random function seed (“seed”) from the Stacks block following the registration end. The seed is then 1. multiplied by a constant (*134775813*), 2. added to another constant (*1*), and, finally, 3. the modulus of its outcome by another constant (*4294967296*) is calculated to serve as the next random number. This random number is then scaled by `maximum step size`, the ratio of the total number of registered tickets over the total number of tickets to be won (i.e. oversubscription ratio), multiplied by 1.5 times `walk resolution`. This `maximum step size` helps ensure the fair-ness of the lottery system. If a random number drawn falls between a particular `walk resolution` within a block that corresponds to a ticket held by a user, the ticket is determined to have won the lottery. To generate the next random number, we move to the end of the `walk resolution` of the current random number, and draw another random number using the above linear congruential generator with the current random number as its seed. The process is repeated until we reach the end of the chain, with the tickets upon whose corresponding `walk resolution` random numbers fell having won the lottery. These “winners” are first determined off-chain, without the need for any on-chain events, thereby greatly increasing the overall efficiency of the lottery system. ## On-chain verification In order to ensure these “winners” are not tempered with or generated in error, upon submission of the list to process claim (whereby the “winners” receive the project tokens) and refund, the contract verifies independently that the list is correct using the same process outlined above, before triggering on-chain events (i.e. processing claims and refunds). This hybrid on-chain/off-chain lottery system therefore allows ALEX to create a Launchpad that combines the efficiency/speed of off-chain processing, while maintaining verifiability/immutability of on-chain processing. # Stacks ALEX DAO - Comprehensive Technical Design Overview This document provides a detailed overview of the smart contracts that enable ALEX DeFi operations. We categorize these contracts based on their functionalities, explain their interactions, and describe some common technical aspects. ### AMM Trading Pool This section provides an overview of the ALEX on-chain Trading Pool and its Automated Market Making (AMM) protocol. ![](https://kroki.io/plantuml/svg/eNptjssKgzAQRfd-xeC2pK-1CP0AoQuX3YxxGgIxkZkoSOm_NyrFhW7vuefOMOmI3jiC_FFVUDO21ht4huBy-GS84aIpsetUn4ga7-p6O2uHXFya8uVDT4zRBi85oMDcOVCZjJXI005PtiRCXk-L_y9m34OVEQcXdxNvoqQJ8UgCJxDSA1ObxoQkrl8tYjb_BqrcbqxBSlb-A0UYXfM=) #### Pool: amm-pool-v2-01.clar This is the primary contract in ALEX's AMM Trading Pool system. It encompasses several core operations, including pool creation, liquidity operations, LP token management, and token swapping. This contract is complemented by the two auxiliary contracts listed below. [Complete technical documentation](/developers/alex-contracts/protocol-contracts/amm-pool-v2-01.clar) #### Registry: amm-registry-v2-01.clar This contract functions as a persistence module for all pool-related information needed by the ALEX Automated Market Maker (AMM) Trading Pool system. It also manages a list of blocklisted operators. [Complete technical documentation](/developers/alex-contracts/protocol-contracts/amm-registry-v2-01.clar) ### Vault The Vault component of the ALEX platform is distinct from the Trading Pool components by design. This separation offers numerous advantages, such as reduced transaction costs for users and a faster learning curve for developers who are creating custom pools on ALEX. #### Vault: amm-vault-v2-01.clar The Vault contract supports the primary contract `amm-pool-v2-01.clar` in position and swap operations by keeping records of the reserves accumulated from fees and securing pool assets. This contract also offers a flash-loan feature for registered tokens, available to approved users. [Complete technical documentation](/developers/alex-contracts/protocol-contracts/amm-vault-v2-01.clar) ### Farming Campaign: farming-campaign-v2-02.clar This contract manages the ALEX Surge liquidity incentive program, overseeing pool registration, voting, staking, and reward distribution. It determines how $ALEX rewards are allocated based on user votes and supports additional voter incentives. [Complete technical documentation](/developers/alex-contracts/protocol-contracts/farming-campaign-v2-02.clar) ### Common features #### Governance The smart contracts discussed in this section include features to control administrative privileges, access, and operational status. It is needed to duplicate some functions for them to be available on each contract. **Admin access control** Contracts in the ALEX platform may include a feature that checks administrative access through the function `is-dao-or-extension`. This function ensures that the caller (`tx-sender`) is either the DAO executor or an authorized extension. **Operational status** The `amm-pool-v2-01` and `amm-vault-v2-01` contracts have functionalities to set and query the operational status of the contract. Specifically, these contracts include a `paused` flag. When this flag is set to true, all operations within the contract are halted. **Blocklisted operators** The `amm-registry-v2-01` contract features the ability to update (on admin operator request) and query a list of blacklisted addresses that are prohibited from operating within the trading pool. The `amm-pool-v2-01` contract delegates the task of this verification to the Registry, which performs a check against the `tx-sender`. #### Traits In Clarity language, a trait defines a public interface to which smart contracts can conform. All Trading Pool contracts in this documentation import traits to ensure interface conformity for various types (such as tokens and flash-loan users) and to conduct their transactions safely. These traits are customized versions of standard traits which are provided by the ALEX platform to serve specific purposes. Below is a list of all the traits utilized by the Trading Pool contracts. **sip-010-trait** This is a customized version of the Stacks' Standard Trait Definition for Fungible Tokens and is used by contracts in the ALEX platform. The changes in this version include support for 8-digit fixed notation and additional helper functions for `transfer`, `get-balance`, and `get-total-supply`. Mint and burn functions are also included along with their respective helpers. [ALEX sip-010 customized implementation](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/traits/trait-sip-010.clar) | [Full sip-010 standard](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) **semi-fungible-trait** This is a customized version of the Stacks' Standard Trait Definition for Semi-Fungible Tokens and is used only by the Vault contract. The customizations are similar to those in the customized `sip-010-trait`, with additional fixed notation helpers for the `transfer-memo`, `get-overall-balance`, and `get-overall-supply` functions. Additionally, the `get-token-uri` function is customized to redefine the `response` parameter type to the tuple: `(optional (string-utf8 256)) uint` instead of sip-013's `string-ascii`. [ALEX sip-013 customized implementation](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/traits/trait-semi-fungible.clar) | [Full sip-013 standard](https://github.com/stacksgov/sips/blob/main/sips/sip-013/sip-013-semi-fungible-token-standard.md) **flash-loan-user-trait** This is a custom trait from ALEX designed to support flash-loan operations and is used only by the Vault contract. The trait defines an `execute` function, which is asserted in the Vault's `flash-loan` function signature, allowing the flash-loan user to execute their logic with the loaned amount. [ALEX flash-loan customized implementation](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/traits/trait-flash-loan-user.clar) #### Mathematics helpers The Pool and Vault contracts are equipped with helper functions that facilitate various mathematical operations (e.g., amounts, percentages) with the necessary precision. These helpers improve the expressiveness of the contracts' logic. Some of these helper functions utilize mathematical constants defined within each contract. All helper functions are declared as private and, like the governance functions, may be replicated across both contracts using the same equations. | Topic | Functions | | ---------------------------------- | --------------------------------------------------------------------- | | Precision multipliers and divisors | `mul-down`, `mul-up`, `div-down`, `div-up` | | Rolling summation | `rolling_sum_div`, `rolling_div_sum` | | Accumulate | `accumulate_division`, `accumulate_product` | | Power and exponential | `pow-fixed`, `pow-priv`, `pow-down`, `pow-up`, `exp-fixed`, `exp-pos` | | Logarithmic | `log-fixed`, `ln-fixed`, `ln-priv` | # amm-pool-v2-01.clar #### Location: [`alex-dao-2/contracts/extensions/amm-pool-v2-01.clar`](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/extensions/amm-pool-v2-01.clar) This document provides comprehensive technical documentation for the primary contract in ALEX's AMM Trading Pool system. The contract encompasses several core operations, including pool creation, liquidity operations (adding or removing assets), LP token management (minting and burning tokens that represent a user's share of the pool and potential earnings), and token swapping (facilitating the exchange of tokens within an existing and funded pool while charging a corresponding fee). This contract is complemented by two auxiliary contracts: a REGISTRY contract that handles the persistence of pool information, and a VAULT contract that secures the assets and manages the reserves accumulated from the fees. For detailed information about these auxiliary contracts, please refer to their respective technical documentation: [amm-registry-v2-01.clar](/developers/alex-contracts/protocol-contracts/amm-registry-v2-01.clar) and [amm-vault-v2-01.clar](/developers/alex-contracts/protocol-contracts/amm-vault-v2-01.clar). ## Storage ### Variables: (data-var) * `paused` (bool) This data variable acts as a flag to determine and control the operational status of the contract within the system. When set to 'paused,' it will block all position and swap transactions. ### Constants * `x_a_list_no_deci` * `x_a_list` #### Mathematical constants These symbolic constants are employed to define and restrict decimal precision and boundary limits in calculations within the system. * `ONE_8` * `UNSIGNED_ONE_8` * `MAX_NATURAL_EXPONENT` * `MIN_NATURAL_EXPONENT` * `MILD_EXPONENT_BOUND` * `MAX_POW_RELATIVE_ERROR` ## Contract calls (interactions) * `executor-dao` Calls are made to verify whether a certain contract-caller is designated as an extension. * `amm-registry-v2-01` This contract is called to manage and configure the data and settings of AMM pools. In this document, it is referred to as the 'registry'. * `amm-vault-v2-01` This contract is called to execute token transfers during the reduction of positions and swapping operations. Additionally, calls are made to add fees charged to the reserves. * `token-amm-pool-v2-01` In operations to add or reduce positions, interactions with this contract involve minting and burning of LP (Liquidity Provider) Tokens and retrieving their balance amounts. In this document, it is referred to as the 'LP Token'. * Tokens (`token-x-trait`, `token-y-trait`, `token-z-trait`, etc.) During the process of adding positions and executing swaps, a trait is used to invoke the relevant tokens to perform the necessary transfers involved in the transaction. This trait is a customized version of the Stacks' standard definition for Fungible Tokens (`sip-010`), with support for 8-digit fixed notation. ## Features ### POOL features 1. `create-pool` This function establishes a liquidity pool for a specified token pair (token-x/token-y). It starts by verifying that the `tx-sender` is not blacklisted through the [`is-blocklisted-or-default` function](#governance-features). Following this validation, the function delegates the pool creation task to the registry. The pools are uniquely identified by their `token-x`, `token-y`, and `factor` values. Upon successful creation, the function automatically invokes `add-to-position` function to initialize token positions for the specified pair within the new pool.\ **Input**: ```lisp (token-x-trait ) (token-y-trait ) (factor uint) (pool-owner principal) (dx uint) (dy uint) ``` 2. `add-to-position` The `add-to-position` function adds asset positions to an existing liquidity pool by transferring the respective tokens from the `tx-sender` to the system vault contract. It updates the pool details in the registry contract and mints LP tokens to the sender, representing their share of the pool and potential earnings. This minting operation is tracked using a unique pool identifier (POOL\_ID).\ **Input**: ```lisp (token-x-trait ) (token-y-trait ) (factor uint) (dx uint) (max-dy (optional uint)) ``` 3. `reduce-position` This function performs the inverse operation of `add-to-position` by allowing users to withdraw asset positions from an existing token pair pool. Upon meeting all requirements (such as the operational status of the pool contract, a valid percentage, and sufficient liquidity pool supply), the function transfers the calculated amount from the vault to the sender and burns the corresponding LP tokens. Note that this function cannot be invoked by blacklisted senders.\ **Input**: ```lisp (token-x-trait ) (token-y-trait ) (factor uint) (percent uint) ``` 4. **Swap tokens functions**: The swap tokens functions enable token exchanges between two given tokens within the liquidity pool. For a swap to successfully execute, the pool contract must contain sufficient liquidity for the specified token pair. The basic steps are: a. transferring a specified amount of token-x from the sender to the system vault b. transferring a calculated amount of token-y from the system vault to the sender while considering swap fees and expected minimum amounts c. registering the fee in token-x within the vault d. updating the pool registry's liquidity status\ \ These steps are mirrored for swaps involving the reverse token pair (token-y/token-x).\ \ If no direct pool exists for the desired pair, the contract provides helper functions to facilitate multi-hop swaps using intermediate token pools. This process, also known as multi-step swap, allows the exchange via a route like token-x/intermediate-token and intermediate-token/token-y. Note that this feature requires prior knowledge of the intermediary pools to connect the desired pair in the swap.\ \ The current protocol version supports up to 4-pools-route operations which are implemented in the following functions: * `swap-helper` Swaps a given token-x for a required token-y. 1 pool route: token-x/token-y.\ **Input**: ```lisp (token-x-trait ) (token-y-trait ) (factor uint) (dx uint) (min-dy (optional uint)) ``` * `swap-helper-a` Swaps a given token-x for a required token-z. 2 pools route: token-x/token-y - token-y/token-z.\ **Input**: ```lisp (token-x-trait ) (token-y-trait ) (token-z-trait ) (factor-x uint) (factor-y uint) (dx uint) (min-dz (optional uint)) ``` * `swap-helper-b` Swaps a given token-x for a required token-w. 3 pools route: token-x/token-y - token-y/token-z - token-z/token-w.\ **Input**: ```lisp (token-x-trait ) (token-y-trait ) (token-z-trait ) (token-w-trait ) (factor-x uint) (factor-y uint) (factor-z uint) (dx uint) (min-dw (optional uint)) ``` * `swap-helper-c` Swaps a given token-x for a required token-v. 4 pools route: token-x/token-y - token-y/token-z - token-z/token-w - token-w/token-v.\ **Input**: ```lisp (token-x-trait ) (token-y-trait ) (token-z-trait ) (token-w-trait ) (token-v-trait ) (factor-x uint) (factor-y uint) (factor-z uint) (factor-w uint) (dx uint) (min-dv (optional uint)) ``` **Note**: all these helpers use the swap supporting functions `swap-x-for-y` and `swap-y-for-x`. ### Supporting features The following functions are tools to assist the off-chain activities. 1. Fee helpers (`fee-helper`, `fee-helper-a`, `fee-helper-b`, `fee-helper-c`) These functions retrieve current fees for an existing pool based on the specified tokens and factors. 2. Rate helpers (`get-helper`, `get-helper-a`, `get-helper-b`, `get-helper-c`) These functions retrieve exchange rates for a given amount in an existing pool based on the specified tokens and factors. **Note**: The above functions, along with their variations, support intermediary routes similar to those in the swapping functions (e.g., token-x/token-y, token-x/token-y-token-y/token-z, etc.). ### Governance features 1. `is-dao-or-extension` This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract.\ **Input**: None. 2. `is-blocklisted-or-default` A read-only feature that verifies if a given address is blacklisted in the registry contract.\ **Input**: ```lisp (sender principal) ``` 3. `is-paused` A read-only function that checks the operational status of the contract.\ **Input**: None. 4. `pause` A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status.\ **Input**: ```lisp (new-paused bool) ``` ### Getter and Setter functions All getter and setter functions in the contract handle pool information, delegating their retrieval or update operations to the corresponding functions in the registry contract [amm-registry-v2-01.clar](/developers/alex-contracts/protocol-contracts/amm-registry-v2-01.clar). #### Setters The following is the complete list of setter functions for pool configurations. All set configuration functions are restricted to the respective pool owner or ALEX admin operators (see function `is-dao-or-extension`). * `set-fee-rate-x` and `set-fee-rate-y`: set the swap fee (% of swap amount) of `token-x` and `token-y`, respectively. Both `fee-rate-x` and `fee-rate-y` are zero by default. * `set-start-block` and `set-end-block`: set the block heights before and after, respectively, which the pool is not available. Both `start-block` and `end-block` is set to `u340282366920938463463374607431768211455` by default. * `set-threshold-x` and `set-threshold-y`: set the amount of `token-x` and `token-y`, respectively, below which a minimum % slippage is applied. Both `threshold-x` and `threshold-y` are zero by default. * `set-max-in-ratio` and `set-max-out-ratio`: set the maximum ratio values used to calculate the highest amount that can be deposited (IN) or exchanged (OUT) within the pool. * `set-oracle-enabled`: add or remove the pool from the on-chain price oracle. Oracle is disabled by default. * `set-oracle-average`: set the exponential moving average factor for the `oracle-resilient`. Please note this call will reset the existing `oracle-resilient` value. The `oracle-average` is zero by default. We recommend `0.99e8`. #### Getters **Main getters** * `get-invariant` (consumes the preceding registry's `get-switch-threshold`) * `get-max-ratio-limit` * `get-pool-details` * `get-pool-details-by-id` * `get-pool-exists` * `get-switch-threshold` **Pool configuration getter functions (query the registry via the aforementioned `get-pool-details` function)** * `check-pool-status` * `get-balances` * `get-start-block` * `get-end-block` * `get-fee-rate-x` * `get-fee-rate-y` * `get-fee-rebate` * `get-max-in-ratio` * `get-max-out-ratio` * `get-oracle-average` * `get-oracle-enabled` * `get-oracle-resilient` * `get-oracle-instant` * `get-pool-owner` * `get-price` * `get-threshold-x` * `get-threshold-y` **Pool token information getter functions (query the registry via the aforementioned `get-pool-details` function)** * `get-x-given-price` * `get-y-given-price` * `get-y-given-x` * `get-x-given-y` * `get-y-in-given-x-out` * `get-x-in-given-y-out` * `get-position-given-mint` * `get-position-given-burn` * `get-token-given-position` #### Internal helper functions **Token helpers** These helper functions facilitate the retrieval of specific token data using another known data as input: * `get-x-given-price-internal` * `get-y-given-price-internal` * `get-y-given-x-internal` * `get-x-given-y-internal` * `get-y-in-given-x-out-internal` * `get-x-in-given-y-out-internal` * `get-position-given-burn-internal` * `get-position-given-mint-internal` * `get-price-internal` * `get-token-given-position-internal` **Mathematical helpers** These helper functions aid in various calculations within the context of the contract, such as amounts, percentages, etc. Some of these functions rely on predefined constants, as specified in [mathematical constants](#mathematical-constants): `accumulate_division`, `accumulate_product`, `div-down`, `div-up`, `exp-fixed`, `exp-pos`, `ln-fixed`, `ln-priv`, `log-fixed`, `mul-down`, `mul-up`, `pow-down`, `pow-fixed`, `pow-priv`, `pow-up`, `rolling_div_sum`, `rolling_sum_div`. ## Errors defined in the contract * `ERR-BLOCKLISTED` * `ERR-EXCEEDS-MAX-SLIPPAGE` * `ERR-INVALID-EXPONENT` * `ERR-INVALID-LIQUIDITY` * `ERR-INVALID-POOL` * `ERR-MAX-IN-RATIO` * `ERR-MAX-OUT-RATIO` * `ERR-NO-LIQUIDITY` * `ERR-NOT-AUTHORIZED` * `ERR-ORACLE-AVERAGE-BIGGER-THAN-ONE` * `ERR-ORACLE-NOT-ENABLED` * `ERR-OUT-OF-BOUNDS` * `ERR-PAUSED` * `ERR-PERCENT-GREATER-THAN-ONE` * `ERR-POOL-ALREADY-EXISTS` * `ERR-PRODUCT-OUT-OF-BOUNDS` * `ERR-SWITCH-THRESHOLD-BIGGER-THAN-ONE` * `ERR-X-OUT-OF-BOUNDS` * `ERR-Y-OUT-OF-BOUNDS` # amm-registry-v2-01.clar #### Location: [`alex-dao-2/contracts/aux/amm-registry-v2-01.clar`](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/aux/amm-registry-v2-01.clar) This document provides comprehensive technical details for the registry contract within ALEX's Automated Market Maker (AMM) Trading Pool system. The contract primarily functions as a persistence module for all pool-related information needed by the main contract [amm-pool-v2-01.clar](/developers/alex-contracts/protocol-contracts/amm-pool-v2-01.clar). To achieve this, the contract allows for the creation and updating of pools. Pool creation involves persisting an entry in a datamap, using `token-x`, `token-y`, and `factor` as the key and containing all relevant pool information. Additionally, the contract includes configuration getters and setters that support position and swap operations. It is also responsible for managing a list of blocklisted operators. ## Storage ### Variables: (datamap) * `pools-data-map` (datamap key: { token-x: principal, token-y: principal, factor: uint } value: { pool-id: uint, total-supply: uint, balance-x: uint, balance-y: uint, pool-owner: principal, fee-rate-x: uint, fee-rate-y: uint, fee-rebate: uint, oracle-enabled: bool, oracle-average: uint, oracle-resilient: uint, start-block: uint, end-block: uint, threshold-x: uint, threshold-y: uint, max-in-ratio: uint, max-out-ratio: uint } ) A datamap structure that persists complete pool information. The map key consists of the unique pool identifier `{token-x, token-y, factor}`, and the map value contains detailed pool attributes. * `pools-id-map` (datamap key: uint value: { token-x: principal, token-y: principal, factor: uint }) A datamap structure that facilitates the retrieval of pool details using the pool ID as the key. The stored values include `token-x` and `token-y` principals, and `factor`. * `blocklist` (datamap key: principal value: bool) A datamap structure that stores a persisted list of blocklisted addresses for operating within the Alex Trading Pool. ### Variables: (data-var) * `pool-nonce` (uint) A persisted variable used to generate a new pool ID incrementally. The stored value represents the last pool ID that was created. * `switch-threshold` (uint) An internal variable used to set a fixed threshold for calculations. It is initialized with `u80000000` and can be retrieved and modified using `get-switch-threshold` and `set-switch-threshold` functions. The value of `switch-threshold` must be less than or equal to the constant `ONE_8`. This value is crucial for the mathematical formulas used within the `amm-pool-v2-01.clar` contract. * `max-ratio-limit` (uint) This variable sets the upper limit for the ratio in a token pool. These ratios are evaluated during each pool swap operation to determine the maximum amount that can be deposited or exchanged in the pool. It is initialized with the value of the constant `ONE_8`. #### Mathematical constants This symbolic constant is employed to define and restrict decimal precision to 8 decimal places. * `ONE_8` It is declared as `u100000000`. ## Contract calls (interactions) * `executor-dao` This call is used to verify whether a certain contract caller is designated as an extension. ## Features 1. `create-pool` This function establishes a liquidity pool for a specified token pair (token-x/token-y). It begins by verifying that the `tx-sender` is an ALEX admin operator (see the function `is-dao-or-extension`), as it is intended to be used by the main `amm-pool-v2-01.clar` contract in the current model. The primary validation performed by this function ensures that the pool does not already exist; if it does, an error is thrown. This validation considers the factor and both token combinations (token-x/token/y or token-y/token-x) as unique identifiers. When a pool is created, an entry is added to the `pools-data-map` structure, using this unique identifier as the key to keep track of all pool information, including balances, fees, thresholds, and more. Additionally, the function generates an ID for the newly created pool (see `pool-nonce`). All remaining values in the datamap are initialized to zero (`u0`), except for `oracle-enabled`, which is set to `false`. Additionally, `start-block` and `end-block` are initialized with the maximum uint value to ensure the pool remains in a non-operational status until properly initialized. For a complete list of fields, refer to the `pools-data-map`.\ **Input**: ```lisp (token-x-trait ) (token-y-trait ) (factor uint) (pool-owner principal) ``` 2. `update-pool` This function updates a liquidity pool identified by the unique combination of `token-x`, `token-y`, and `factor`. It is a governed function that restricts the `tx-sender` to be an ALEX admin operator (see the function `is-dao-or-extension`). Similar to the aforementioned `create-pool` function, `update-pool` is designed to be used by the main `amm-pool-v2-01.clar` contract. However, in this case, it is used indirectly in position and swap operations.\ **Input**: ```lisp (token-x principal) (token-y principal) (factor uint) (pool-data { pool-id: uint, total-supply: uint, balance-x: uint, balance-y: uint, pool-owner: principal, fee-rate-x: uint, fee-rate-y: uint, fee-rebate: uint, oracle-enabled: bool, oracle-average: uint, oracle-resilient: uint, start-block: uint, end-block: uint, threshold-x: uint, threshold-y: uint, max-in-ratio: uint, max-out-ratio: uint } ) ``` ### Governance features 1. `is-dao-or-extension` This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract.\ **Input**: None. 2. `is-blocklisted-or-default` A read-only feature that verifies if a given address is blacklisted using the `blocklist` map.\ **Input**: ```lisp (sender principal) ``` 3. `set-blocklist-many` A public function, governed by the `is-dao-or-extension` mechanism, that allows setting or updating the blocklisted status for a list of addresses (up to 1000 addresses).\ **Input**: ```lisp (list 1000 { sender: principal, blocked: bool }) ``` ### Getter and Setter functions #### Pool administration setters * `set-fee-rebate` * `set-pool-owner` * `set-max-ratio-limit` * `set-switch-threshold` #### Pool operation setters and getters The following groups of functions support pool usage and configuration features consumed by the main `amm-pool-v2-01.clar` contract. #### Setters * `set-start-block` * `set-end-block` * `set-fee-rate-x` * `set-fee-rate-y` * `set-max-in-ratio` * `set-max-out-ratio` * `set-oracle-average` * `set-oracle-enabled` * `set-threshold-x` * `set-threshold-y` #### Getters * `get-pool-details-by-id` * `get-pool-details` * `get-pool-exists` * `get-max-ratio-limit` * `get-switch-threshold` #### Internal helper functions * `set-blocklist` This is a private function designed to complement the aforementioned governance function `set-blocklist-many`.\ **Input**: ```lisp (sender principal) (blocked bool) ``` ## Errors defined in the contract * `ERR-EXCEEDS-MAX-SLIPPAGE` * `ERR-INVALID-LIQUIDITY` * `ERR-INVALID-POOL` * `ERR-MAX-IN-RATIO` * `ERR-MAX-OUT-RATIO` * `ERR-NO-LIQUIDITY` * `ERR-NOT-AUTHORIZED` * `ERR-ORACLE-AVERAGE-BIGGER-THAN-ONE` * `ERR-ORACLE-NOT-ENABLED` * `ERR-PAUSED` * `ERR-PERCENT-GREATER-THAN-ONE` * `ERR-POOL-ALREADY-EXISTS` * `ERR-SWITCH-THRESHOLD-BIGGER-THAN-ONE` # amm-vault-v2-01.clar #### Location: [`alex-dao-2/contracts/aux/amm-vault-v2-01.clar`](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/aux/amm-vault-v2-01.clar) This document provides comprehensive technical details for the vault contract within ALEX's Automated Market Maker (AMM) Trading Pool system. The vault contract supports the primary contract [amm-pool-v2-01.clar](/developers/alex-contracts/protocol-contracts/amm-pool-v2-01.clar) in position and swap operations by keeping record of the reserves accumulated from fees and securing pool assets. It ensures asset security through transfer transactions where the vault contract is the recipient of token transfers, thereby holding and safeguarding the assets within the pool. In addition to supporting Trading Pool operations, the vault contract also offers a flash-loan feature for registered tokens, available to approved users. ## Storage ### Variables: (data-var) * `paused` (bool) This data variable acts as a flag to determine and control the operational status of the contract within the system. #### Token variables * `approved-tokens` (datamap key: principal value: bool) A datamap structure that lists all the approved tokens for transfer and loan operations. * `reserve` (datamap key: principal value: uint) A datamap structure that keeps record of all the reserves in the vault for a specific token. #### Flash-loan variables * `approved-flash-loan-users` (datamap key: principal value: bool) A datamap structure that lists all the approved users for loan operations. * `flash-loan-enabled` (bool) A flag variable indicating the status of the contract's flash-loan feature. Currently, this is only an informative flag. * `flash-loan-fee-rate` (uint) This variable defines the fee rate charged for loan operations. #### Mathematical constants This symbolic constant is employed to define and restrict decimal precision to 8 decimal places. * `ONE_8` It is declared as `u100000000`. ## Contract calls (interactions) * `executor-dao` This call is used to verify whether a certain contract caller is designated as an extension. * `token-trait` Calls are made to token contracts that comply with the defined in each token-trait parameter to facilitate token transfers and retrieve balances during transfer and loan operations. * `flash-loan-user-trait` Calls are made to token contracts that comply with the defined in the flash-loan-user-trait variable to execute loans for the approved flash-loan users and tokens. ## Features 1. `add-to-reserve` This function increases the existing reserves of a specific token by the given amount. It is governed by the `is-dao-or-extension` check to ensure that the `tx-sender` is an ALEX admin operator. Intended to be invoked by the main `amm-pool-v2-01.clar` contract during swap operations, this function is called following a transfer of the incoming token (token-x) to the vault contract. The `add-to-reserve` function is then executed with the token principal and the specified amount, representing the swap fees charged by the system for the transaction.\ **Input**: ```lisp (token-trait principal) (amount uint) ``` 2. `remove-from-reserve` This function serves as the reverse operation of `add-to-reserve`, decreasing the specified amount for the given token. An additional check ensures that the amount is less than or equal to the token's current reserve in the vault. Although it is not currently called by any existing module, the function also verifies that the `tx-sender` is an ALEX admin operator via the `is-dao-or-extension` control.\ **Input**: ```lisp (token-trait principal) (amount uint) ``` 3. `transfer-ft` Like `add-to-reserve`, this function is intended to be called by the `amm-pool-v2-01.clar` contract during swap operations and is governed by the `is-dao-or-extension` check. Controls are in place to ensure that the contract is operational (not paused) and that the given token is approved in the contract's list. If all these conditions are met, the function will execute a transfer of the specified amount from the vault to the designated recipient.\ **Input**: ```lisp (token-trait ) (amount uint) (recipient principal) ``` 4. `transfer-ft-two` This function serves as a helper for calling the `transfer-ft` function twice with two different tokens and amounts for the same recipient within a single transaction. In the current model, this feature is utilized by the `amm-pool-v2-01.clar` contract during position reduction operations to return assets to the user.\ **Input**: ```lisp (token-x-trait ) (dx uint) (token-y-trait ) (dy uint) (recipient principal) ``` 5. `transfer-sft` This function is similar to `transfer-ft`, but it is designed for semi-fungible tokens, which operate with a token ID. It includes the same controls as `transfer-ft` regarding the vault's operational status and approved tokens. Although this function is not called by the `amm-pool-v2-01.clar` contract in the current system design, it requires invocation by an ALEX admin operator, as governed by the `is-dao-or-extension` check.\ **Input**: ```lisp (token-trait ) (token-id uint) (amount uint) (recipient principal) ``` 6. `flash-loan` This function is designed to lend the recipient (the `tx-sender`) a specified amount of tokens to execute an embedded function declared in the `flash-loan-trait`. The recipient then transfers back the same amount plus the corresponding fee (refer to `flash-loan-fee-rate`). As with previous features, controls are in place to check the vault's operational status, approve tokens and flash-loan users, and ensure there is sufficient balance to make the transfer.\ **Input**: ```lisp (flash-loan-user-trait ) (token-trait ) (amount uint) (memo (optional (buff 16))) ``` ### Governance features 1. `is-dao-or-extension` This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract.\ **Input**: None. 2. `is-paused` A read-only function that checks the operational status of the contract.\ **Input**: None. 3. `pause` A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status.\ **Input**: ```lisp (new-paused bool) ``` ### Getter and Setter functions #### Vault administration getter * `get-reserve` #### Flash-loan operation setters and getters **Setters** * `set-approved-flash-loan-user` * `set-approved-token` * `set-flash-loan-enabled` * `set-flash-loan-fee-rate` **Getters** * `get-flash-loan-enabled` * `get-flash-loan-fee-rate` #### Internal helper functions * `check-is-approved-flash-loan-user` This is a private function designed to verify whether a flash-loan user is approved in the contract's persisted datamap, `approved-flash-loan-users`.\ **Input**: ```lisp (flash-loan-user-trait principal) ``` * `check-is-approved-token` This is a private function designed to verify whether a token is approved in the contract's persisted datamap, `approved-tokens`.\ **Input**: ```lisp (flash-loan-token principal) ``` **Mathematical helpers** These helper functions aid in various calculations within the context of the contract. * `mul-down` * `mul-up` ## Errors defined in the contract * `ERR-AMOUNT-EXCEED-RESERVE` * `ERR-INVALID-BALANCE` * `ERR-INVALID-TOKEN` * `ERR-NOT-AUTHORIZED` * `ERR-PAUSED` # farming-campaign-v2-02.clar * [Deployed contract](https://explorer.hiro.so/txid/SP1E0XBN9T4B10E9QMR7XMFJPMA19D77WY3KP2QKC.farming-campaign-v2-02?chain=mainnet) The `farming-campaign-v2-02` contract manages the ALEX Surge liquidity incentive program, where liquidity pools compete to receive $ALEX rewards. Participants influence the reward distribution by voting for pools, while liquidity providers can stake LP tokens to earn additional rewards. Surge is structured in rounds. The process follows these steps: 1. **Pool Registration** – Projects must register liquidity pools before the deadline to participate in the Surge round. 2. **Voting** – Users vote using ALEX and LiALEX tokens to decide how rewards will be distributed among the registered pools. 3. **Staking** – Liquidity providers stake LP tokens, which represent their share of a trading pool’s assets, to earn additional rewards. 4. **Reward Distribution** – At the end of the round, $ALEX rewards are distributed among the pools based on the votes received. Within each pool, the rewards are allocated proportionally to liquidity providers based on the amount of LP tokens they staked. Additionally, projects can donate voter rewards as extra incentives to attract votes for their pools. ## Features ### Public Features #### `stake` This function allows users to stake LP tokens in a registered liquidity pool within an active Surge campaign. Staking LP tokens makes users eligible to receive a share of the $ALEX rewards allocated to the pool based on the total votes it received. The function verifies that the registration period has ended and the staking period is still active. It then interacts with the `token-amm-pool-v2-01` contract to transfer the specified amount of LP tokens from the sender’s wallet to the contract. After the transfer, it updates the total amount of LP tokens staked in the pool. Once the staking is confirmed, the contract updates the `campaign-stakers` map with the staker’s details and emits a notification event. **Parameters** | Name | Type | | ------------- | ------ | | `pool-id` | `uint` | | `campaign-id` | `uint` | | `amount` | `uint` | #### `unstake` This function allows users to withdraw their staked LP tokens from a liquidity pool in a Surge campaign while claiming any earned $ALEX. Before proceeding, it verifies that the staking period has ended and that the user has not already collected their allocation. The contract determines the user's share based on the $ALEX rewards allocated to the pool, which were determined by the votes it received. The distribution within the pool is then proportional to the amount of LP tokens each user staked. Once determined, it mints and transfers the corresponding amount to the user via the `token-alex` contract. Additionally, it calls `token-amm-pool-v2-01` to return the LP tokens back to the user and updates `campaign-stakers` to mark the process as complete. A notification event logs the transaction. **Parameters** | Name | Type | | ------------- | ------ | | `pool-id` | `uint` | | `campaign-id` | `uint` | #### `register-for-campaign` This function allows a liquidity pool to register to participate in a Surge campaign. Before registering, it ensures that the pool is whitelisted and that the registration deadline has not been reached. Additionally, it checks that the pool has not already been registered. Once validated, the function creates an entry in `campaign-registrations`, initializing reward amounts and total staked values to `0`. It also updates `campaign-registered-pools` to add the new registered pool. A notification event logs the registration. **Parameters** | Name | Type | | ------------- | ------ | | `pool-id` | `uint` | | `campaign-id` | `uint` | #### `add-reward-for-campaign` This function allows a registrant to add voter rewards to a liquidity pool already registered in a Surge round. These rewards incentivize users to vote for the pool. The function first verifies that the pool is registered in the campaign. It ensures that the voting phase is still open and validates that the reward token matches either of the pool’s trading tokens by interacting with the `amm-pool-v2-01`. If these conditions are met, the function transfers the specified reward amount from the registrant to the contract using the provided token contract. It then updates the stored reward balances for the pool in `campaign-registrations` and records the registrant’s contribution in `campaign-registrants`. **Parameters** | Name | Type | | -------------------- | ------------ | | `pool-id` | `uint` | | `campaign-id` | `uint` | | `reward-token-trait` | `` | | `reward-amount` | `uint` | #### `vote-campaign` This function allows participants to vote for liquidity pools in a Surge round, determining how $ALEX rewards are distributed. Users allocate their voting power across one or multiple pools. The function verifies that the voting phase is active and retrieves the voter’s available voting power using the `voting-power` function, which calculates the user's voting power based on their $ALEX and $LiALEX holdings. It ensures that the total votes cast does not exceed the voter's limit. Once validated, the function updates the vote counts for each selected pool in `campaign-voter-votes` map, records the total votes cast in `campaign-total-vote` map and applies the vote distribution logic through `update-pool-votes` function. **Parameters** | Name | Type | | ------------- | ------------------------------------------ | | `campaign-id` | `uint` | | `votes` | `list 1000 { pool-id: uint, votes: uint }` | | `lp-pools` | `list 200 uint` | #### `claim-vote-reward` This function allows voters to claim rewards from a Surge round if they voted for a liquidity pool that distributed voter rewards. These rewards are additional incentives offered by pool registrants to encourage voting participation. The function first checks that the voting phase has ended and ensures the voter has not previously claimed rewards for the specified pool. It then calculates the voter’s share based on the total votes cast for the pool, using data stored in `campaign-pool-votes-by-voter` and `campaign-pool-votes-for-project-reward` maps, which track individual and total votes for voter rewards distribution. The function verifies that the requested reward tokens match the liquidity pool’s assets by interacting with the `amm-pool-v2-01` contract. If all conditions are met, the function transfers the voter’s share of the rewards and updates `campaign-vote-rewards-claimed` to prevent duplicate claims. **Parameters** | Name | Type | | ---------------------- | ------------ | | `pool-id` | `uint` | | `campaign-id` | `uint` | | `reward-token-x-trait` | `` | | `reward-token-y-trait` | `` | #### `claim-vote-reward-many` This function enables batch claiming of voter rewards for multiple liquidity pools and campaigns in a single transaction. It iterates over the provided lists of pool IDs, campaign IDs and reward token contracts, calling the `claim-vote-reward` function for each entry. Since it relies on [`claim-vote-reward`](#claim-vote-reward) function, the same eligibility checks apply. **Parameters** | Name | Type | | ----------------------- | --------------------- | | `pool-ids` | `list 100 uint` | | `campaign-ids` | `list 100 uint` | | `reward-token-x-traits` | `list 100 ` | | `reward-token-y-traits` | `list 100 ` | ### Privileged Features #### `revoke-registration` This privileged function allows revoking a pool's registration in a Surge campaign before the registration cut-off date. The action can be performed by the DAO or an authorized extension, or by the pool's registrant if `revoke-enabled` is set to `true`. If revoked, the registrant recovers the voter rewards they contributed. The function ensures that the specified reward tokens match the pool’s trading pair by interacting with `amm-pool-v2-01`. If the conditions are met, it updates the `campaign-registrations` and `campaign-registrants` maps to remove the pool and return the reward tokens to the registrant. ### Governance Features #### `is-dao-or-extension` This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract. #### `set-campaign-nonce` A public function, governed through the `is-dao-or-extension`, that updates the campaign nonce, which serves as a unique identifier for newly created Surge rounds. This ensures that each campaign has a sequential and distinct ID. **Parameters** | Name | Type | | ----------- | ------ | | `new-nonce` | `uint` | #### `set-revoke-enabled` A public function, governed through the `is-dao-or-extension`, that enables or disables the ability to revoke a registered liquidity pool from a campaign before the registration cut-off date. When set to `true`, the registrant of a pool can cancel its participation and recover the reward tokens added during registration. By default, this is set to `false`, meaning that once a pool is registered, it cannot be removed from the campaign. **Parameters** | Name | Type | | --------- | ------ | | `enabled` | `bool` | #### `whitelist-pools` A public function, governed through the `is-dao-or-extension`, that updates the list of liquidity pools eligible to participate in Surge campaigns. Only pools that are whitelisted can be registered in a campaign. **Parameters** | Name | Type | | ------- | ------------------ | | `pools` | `(list 1000 uint)` | #### `create-campaign` A public function, governed through the `is-dao-or-extension`, that initializes a new Surge campaign. This function sets key parameters such as registration, voting, and staking deadlines, as well as the total reward amount allocated for distribution. Each campaign is assigned a unique ID, incremented from the `campaign-nonce` variable. **Parameters** | Name | Type | | --------------------- | ------ | | `registration-cutoff` | `uint` | | `voting-cutoff` | `uint` | | `stake-cutoff` | `uint` | | `stake-end` | `uint` | | `reward-amount` | `uint` | | `snapshot-block` | `uint` | #### `transfer-token` A public function, governed through the `is-dao-or-extension`, that allows the contract to transfer a specified amount of a fungible token to a recipient. **Parameters** | Name | Type | | ------------- | ------------ | | `token-trait` | `` | | `amount` | `uint` | | `recipient` | `principal` | #### `update-campaign` A public function, governed through the `is-dao-or-extension`, that updates the parameters of an existing campaign. This function modifies attributes such as registration deadlines, voting periods, staking timelines, and reward allocations. **Parameters** | Name | Type | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `campaign-id` | `uint` | | `details` | `{ registration-cutoff: uint, voting-cutoff: uint, stake-cutoff: uint, stake-end: uint, reward-amount: uint, snapshot-block: uint }` | #### `update-campaign-registrations` A public function, governed through the `is-dao-or-extension`, that updates the registration details of a liquidity pool within a campaign. This function allows modifying the reward amounts allocated in token X and token Y, as well as the total staked amount in the pool. If the pool is not already registered in the campaign, it will be added to the list of registered pools. **Parameters** | Name | Type | | ----------------- | ------ | | `campaign-id` | `uint` | | `pool-id` | `uint` | | `reward-amount-x` | `uint` | | `reward-amount-y` | `uint` | | `total-staked` | `uint` | #### `update-campaign-stakers` A public function, governed through the `is-dao-or-extension`, that updates the staking details of a participant in a specific liquidity pool within a campaign. This function modifies the amount of LP tokens staked by a user and whether they have claimed their rewards. **Parameters** | Name | Type | | ------------- | ----------- | | `campaign-id` | `uint` | | `pool-id` | `uint` | | `staker` | `principal` | | `amount` | `uint` | | `claimed` | `bool` | #### `update-campaign-registrants` A public function, governed through the `is-dao-or-extension`, that updates the amount of token X and token Y recorded for a registrant when adding a liquidity pool to a campaign. These values represent voter rewards allocated to the pool, which can be modified or revoked before the registration cut-off date. **Parameters** | Name | Type | | ---------------- | ----------- | | `campaign-id` | `uint` | | `pool-id` | `uint` | | `registrant` | `principal` | | `token-x-amount` | `uint` | | `token-y-amount` | `uint` | #### `set-project-reward-ignore-list` A public function, governed through the `is-dao-or-extension`, that updates the list of addresses excluded from receiving voter rewards. **Parameters** | Name | Type | | ----------- | ----------------------- | | `addresses` | `(list 1000 principal)` | ### Getters #### `get-campaign-nonce` #### `get-campaign-or-fail` **Parameters** | Name | Type | | ------------- | ------ | | `campaign-id` | `uint` | #### `get-campaigns-or-fail-many` **Parameters** | Name | Type | | -------------- | ----------------- | | `campaign-ids` | `(list 200 uint)` | #### `get-campaign-registration-by-id-or-fail` **Parameters** | Name | Type | | ------------- | ------ | | `campaign-id` | `uint` | | `pool-id` | `uint` | #### `get-campaign-registration-by-id-or-fail-many` **Parameters** | Name | Type | | -------------- | ----------------- | | `campaign-ids` | `(list 200 uint)` | | `pool-ids` | `(list 200 uint)` | #### `get-campaign-staker-or-default` **Parameters** | Name | Type | | ------------- | ----------- | | `campaign-id` | `uint` | | `pool-id` | `uint` | | `staker` | `principal` | #### `get-campaign-staker-or-default-many` **Parameters** | Name | Type | | -------------- | ---------------------- | | `campaign-ids` | `(list 200 uint)` | | `pool-ids` | `(list 200 uint)` | | `stakers` | `(list 200 principal)` | #### `get-pool-whitelisted` **Parameters** | Name | Type | | --------- | ------ | | `pool-id` | `uint` | #### `get-whitelisted-pools` #### `voting-power` #### `get-campaign-registered-pools` **Parameters** | Name | Type | | ------------- | ------ | | `campaign-id` | `uint` | #### `get-campaign-summary` **Parameters** | Name | Type | | ------------- | ------ | | `campaign-id` | `uint` | #### `get-campaign-staker-history-many` **Parameters** | Name | Type | | -------------- | ----------------- | | `address` | `principal` | | `campaign-ids` | `(list 200 uint)` | #### `get-registration-or-default` **Parameters** | Name | Type | | ------------- | ----------- | | `campaign-id` | `uint` | | `pool-id` | `uint` | | `registrant` | `principal` | #### `get-registration-or-default-many` **Parameters** | Name | Type | | ------------- | ------------------ | | `campaign-id` | `uint` | | `pool-ids` | `(list 1000 uint)` | | `registrant` | `principal` | #### `get-revoke-enabled` **Parameters** | Name | Type | | ------------- | ------ | | `campaign-id` | `uint` | ### Relevant internal functions #### `update-pool-votes` This private function updates the voting records for a liquidity pool. It is invoked by the `vote-campaign` function when a user submits votes. The function retrieves the current vote counts for the specified pool and updates the following vote-tracking maps: `campaign-pool-votes-for-project-reward`, `campaign-pool-votes-for-alex-reward` and `campaign-pool-votes-by-voter`. **Parameters** | Name | Type | | --------- | ----------------------------------------- | | `vote` | `{ pool-id: uint, votes: uint }` | | `context` | `{ campaign-id: uint, voter: principal }` | #### `calculate-lp-voting-power` This private function is used to calculate the LP voting power of a user for a specific liquidity pool. It is called by the `voting-power` function to determine the contribution of LP tokens to a user's total voting power. The function retrieves the pool's details from `amm-registry-v2-01` and `amm-pool-v2-01`. It then queries `alex-farming` contract to check if the user has staked LP tokens. Using this data, it calculates the user's LP voting power by determining how much ALEX-equivalent liquidity they provided, factoring in both directly held and staked LP tokens. **Parameters** | Name | Type | | --------- | ------------------------------------- | | `pool-id` | `uint` | | `acc` | `{ address: principal, total: uint }` | ## Storage ### `campaign-nonce` | Data | Type | | -------- | ------ | | Variable | `uint` | A counter that keeps track of the total number of campaigns created. Each new campaign increments this value by `1`, ensuring a unique identifier for every Surge round. ### `revoke-enabled` | Data | Type | | -------- | ------ | | Variable | `bool` | A flag that determines whether a registered liquidity pool can be revoked from a campaign before the registration cut-off date. When set to `true`, the registrant of a pool can cancel its participation and recover the reward tokens added during registration. By default, this value is set to `false`, meaning that once a pool is registered, it cannot be removed from the campaign. ### `whitelisted-pools` | Data | Type | | -------- | ------------------ | | Variable | `list (1000 uint)` | A list of approved liquidity pools that are eligible to participate in ALEX Surge campaigns. Only pools included in this list can register for a campaign. By default, this list is empty, meaning that no pools are eligible until explicitly added. The DAO or an authorized contract can update this list through governance functions. ### `project-reward-ignore-list` | Data | Type | | -------- | ----------------------- | | Variable | `list (1000 principal)` | A list of addresses that are excluded from receiving voter rewards in ALEX Surge. If a voter's address is included in this list, they will not be eligible to claim any voter rewards, even if they participated in voting. By default, this list is empty, meaning no addresses are excluded initially. The DAO or an authorized contract can update this list through governance functions. ### `campaigns` | Data | Type | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Map | `uint → { registration-cutoff: uint, voting-cutoff: uint, stake-cutoff: uint, stake-end: uint, reward-amount: uint, snapshot-block: uint }` | This map stores campaign data, where each entry is identified by a campaign ID (`uint`). It tracks the key timeline phases and reward details for each ALEX Surge campaign. * `registration-cutoff`: the deadline for registering pools in the campaign. * `voting-cutoff`: the deadline for casting votes. * `stake-cutoff`: indicates the moment from which LP tokens can no longer be staked. * `stake-end`: the point at which the staking period ends and the reward emission phase begins. * `reward-amount`: the total $ALEX allocated for distribution in the campaign. * `snapshot-block`: the block height at which participant balances are recorded for voting power calculations. ### `campaign-registrations` | Data | Type | | ---- | ------------------------------------------------------------------------------------------------------------- | | Map | `{ campaign-id: uint, pool-id: uint } → { reward-amount-x: uint, reward-amount-y: uint, total-staked: uint }` | This map stores the registration data of each liquidity pool within a specific Surge round. Fields: * `campaign-id`: the unique identifier of the Surge round. * `pool-id`: the unique identifier of the registered liquidity pool. * `reward-amount-x`: the amount of rewards in token X allocated to the pool. * `reward-amount-y`: the amount of rewards in token Y allocated to the pool. * `total-staked`: the total amount of LP tokens staked in the pool. This map is updated when a pool registers for a campaign and when LPs stake tokens in it. ### `campaign-stakers` | Data | Type | | ---- | ------------------------------------------------------------------------------------------- | | Map | `{ campaign-id: uint, pool-id: uint, staker: principal } → { amount: uint, claimed: bool }` | This map stores staking data for individual participants in a specific liquidity pool within a Surge round. Fields: * `campaign-id`: The unique identifier of the Surge round. * `pool-id`: The unique identifier of the liquidity pool where the staking occurs. * `staker`: the principal identifier of the user who staked LP tokens. * `amount`: The total amount of LP tokens staked by the user in the pool. * `claimed`: A boolean value indicating whether the user has claimed their rewards. This map is updated when users stake LP tokens and when they claim their rewards at the end of the campaign. ### `campaign-total-vote` | Data | Type | | ---- | --------------------------------------- | | Map | `campaign-id: uint → total-votes: uint` | This map tracks the total number of votes cast in a specific Surge round. It is updated whenever users vote for liquidity pools during the voting phase. ### `campaign-registered-pools` | Data | Type | | ---- | ------------------------------------------------ | | Map | `campaign-id: uint → pool-ids: (list 1000 uint)` | This map stores the list of liquidity pools that have been successfully registered in a specific Surge round. ### `campaign-registrants` | Data | Type | | ---- | -------------------------------------------------------------------------------------------------------------- | | Map | `{ campaign-id: uint, pool-id: uint, registrant: principal } → { token-x-amount: uint, token-y-amount: uint }` | This map records the amount of token X and token Y added by a registrant when adding a liquidity pool to a Surge round. These tokens are used as rewards for voters but can be revoked before the registration cut-off date. ### `campaign-voter-votes` | Data | Type | | ---- | ------------------------------------------------ | | Map | `{ campaign-id: uint, voter: principal } → uint` | This map tracks the total voting power spent by a voter across all liquidity pools in a given Surge round. ### `campaign-pool-votes-by-voter` | Data | Type | | ---- | --------------------------------------------------------------- | | Map | `{ campaign-id: uint, pool-id: uint, voter: principal } → uint` | This map records the number of votes a specific voter has allocated to a particular liquidity pool within a Surge round. It is primarily used to calculate project rewards. ### `campaign-pool-votes-for-project-reward` | Data | Type | | ---- | --------------------------------------------- | | Map | `{ campaign-id: uint, pool-id: uint } → uint` | This map stores the total number of votes received by a liquidity pool in a Surge round, specifically for the calculation of project rewards. ### `campaign-pool-votes-for-alex-reward` | Data | Type | | ---- | --------------------------------------------- | | Map | `{ campaign-id: uint, pool-id: uint } → uint` | This map tracks the total number of votes received by a liquidity pool in a Surge round, specifically for the $ALEX reward distribution. ### `campaign-vote-rewards-claimed` | Data | Type | | ---- | --------------------------------------------------------------- | | Map | `{ campaign-id: uint, pool-id: uint, voter: principal } → bool` | This map tracks whether a voter has claimed their voter rewards for a specific pool in a Surge round. ## Contract calls * `executor-dao`: calls are made to verify whether a certain contract-caller is designated as an extension. * `token-alex`: this contract is called to mint and transfer $ALEX rewards to liquidity providers when they unstake. * `token-wlialex`: this contract is called to retrieve the $LiALEX balance of a voter at the snapshot block to calculate their voting power. * `auto-alex-v3-wrapped`: this contract is necessary for user's voting power calculations. * `alex-staking-v2`: this contract is called to retrieve a user's manually staked $ALEX balance, which is included in the calculation of their total voting power. * `token-amm-pool-v2-01`: this contract is called to transfer staked LP tokens during the staking process and to return them when users unstake. It is also used to validate reward token compatibility when adding voter rewards. * `amm-pool-v2-01`: this contract is called to transfer staked LP tokens during the staking process and to return them when users unstake. It is also used to retrieve LP token balances and total supply when calculating a user's voting power. * `reward-token-trait`: this trait represents the fungible tokens used for distributing staking and voter rewards. It follows the `SIP-010` standard. * `reward-token-x-trait`: this trait refers to one of the two possible reward tokens in a liquidity pool. * `reward-token-y-trait`: this trait refers to one of the two possible reward tokens in a liquidity pool. * Tokens (`token-trait`): this trait is used to interact with fungible tokens when transferring staking deposits, rewards, and voter incentives. It is a customized version of Stacks' standard definition for Fungible Tokens (`sip-010`), with support for 8-digit fixed notation. * `amm-registry-v2-01`: this contract is called to retrieve data about a liquidity pool. It is used in the calculation of LP voting power. * `alex-farming`: this contract is called to retrieve staking information for users who have deposited LP tokens into the Alex Farming system. It is used to calculate LP voting power. ## Errors | Error Name | Value | | ------------------------------------ | ------------- | | `err-not-authorized` | `(err u1000)` | | `err-get-block-info` | `(err u1001)` | | `err-invalid-campaign-registration` | `(err u1002)` | | `err-invalid-campaign-id` | `(err u1003)` | | `err-registration-cutoff-passed` | `(err u1004)` | | `err-stake-cutoff-passed` | `(err u1005)` | | `err-campaign-not-ended` | `(err u1006)` | | `err-token-mismatch` | `(err u1007)` | | `err-invalid-input` | `(err u1008)` | | `err-invalid-reward-token` | `(err u1010)` | | `err-already-claimed` | `(err u1011)` | | `err-stake-end-passed` | `(err u1005)` | | `err-not-registered` | `(err u1013)` | | `err-revoke-disabled` | `(err u1014)` | | `err-registration-cutoff-not-passed` | `(err u1015)` | | `err-voting-cutoff-passed` | `(err u1016)` | | `err-pool-not-registered` | `(err u1017)` | | `err-pool-already-registered` | `(err u1018)` | # amm-pool-v3.clar * Location: `./contracts/amm-pool-v3.clar` The `amm-pool-v3` contract implements the core logic of DAMM (Discrete Automated Market Maker), a concentrated liquidity protocol designed to maximize capital efficiency by organizing liquidity into discrete price ranges called **bins** or **ticks**. Unlike traditional AMMs that spread liquidity across the entire price curve, DAMM allows liquidity providers (LPs) to allocate funds into specific price intervals. Each price bin behaves as an independent constant product pool, with a custom virtual balance system to keep swaps bounded within the configured range. This contract supports the full lifecycle of DAMM pools: * **Pool Creation** – DAO-controlled creation of new pools between two fungible tokens, specifying bin size and fee configuration. * **Liquidity Provision** – LPs add liquidity to specific ticks within a pool, receiving fungible LP tokens for each tick. * **Liquidity Management** – LPs can reduce their positions by percentage, claiming back their share of assets and accrued fees from a specific tick. * **Swapping** – Supports swaps of token X for token Y (and vice versa) within a tick. * **Administrative Control** – The ALEX DAO can pause or sunset pools and adjust fee parameters at any time. * **Fee Claiming** – Accumulated fees can be withdrawn by the DAO to a target address. ## Features ### Public #### `add-to-position` This function allows a user to add liquidity to a specific price bin (tick) within a DAMM pool. Unlike traditional AMMs where liquidity is distributed evenly across all prices, here the user targets a defined price range. The `min-price` and `max-price` parameters act as a safety check, even if the user selects a bin, they might not want to enter at just any price inside that range. These bounds let users specify a narrower range of acceptable prices for their deposit. If the actual price (after adding liquidity) falls outside of this min-max window, the transaction will revert to protect the user from entering at an unfavorable rate. The function accepts a max amount of both tokens (`dx`, `dy`) and bounds on the acceptable price range (`min-price`, `max-price`). It internally calculates the actual amounts of each token that can be added given the pool's current balances and fee configuration. If the price after the addition falls outside the user-defined bounds, the transaction reverts. If this is the first liquidity added to the tick, it sets the virtual balances and initializes the price bin. Otherwise, it uses the existing balances to calculate a fair proportional LP minting. This function interacts with the `amm-liquidity-token-v3` contract to mint LP tokens for the position, and with the respective SIP-010 token contracts to transfer the user's tokens into the pool. All funds are held directly by the `amm-pool-v3 contract`, there is no external vault. **Parameters** | Name | Type | | --------------- | ------------ | | `token-x-trait` | `` | | `token-y-trait` | `` | | `pool-id` | `uint` | | `tick` | `int` | | `dx` | `uint` | | `dy` | `uint` | | `min-price` | `uint` | | `max-price` | `uint` | #### `reduce-position` This function allows a user to reduce their liquidity position in a specific tick of a DAMM pool by a given percentage. Internally, it calculates the user's LP token balance for the selected bin, burns the requested portion, and sends back the proportional share of token X and token Y to the user. The function interacts with the `amm-liquidity-token-v3` contract to burn LP tokens, and with the respective SIP-010 token contracts to transfer assets back to the user. All liquidity is held directly by the `amm-pool-v3` contract, there is no external vault mechanism involved. The `percent` parameter represents the portion of the position to withdraw, using fixed-point math with 8 decimal precision. For example: * `100_000_000` means 100% (full withdrawal) * `50_000_000` means 50% * `10_000_000` means 10% **Parameters** | Name | Type | | --------------- | ------------ | | `token-x-trait` | `` | | `token-y-trait` | `` | | `pool-id` | `uint` | | `tick` | `int` | | `percent` | `uint` | #### `swap-x-for-y-ioc` This function allows users to swap a specific amount of token X (`dx`) for token Y in a selected bin (`tick`) of a DAMM pool, using an **Immediate-Or-Cancel (IOC)** strategy. The swap aims to provide the best possible rate for token Y. The effective upper price limit for the swap is the more restrictive of either the user-defined `max-price` or the natural upper price boundary (`price-end`) of the specified tick. If the requested `dx` would push the price beyond this effective cap, only a partial amount (or none) of `dx` will be swapped. The function validates the pool's status and token traits, calculates how much of token X can be swapped without breaching the price cap, applies fees and potential rebates, and executes the transfers. If conditions are not met (e.g. price exceeds `max-price` or insufficient liquidity), it returns zero values for all outputs. **Parameters** | Name | Type | | --------------- | ------------ | | `token-x-trait` | `` | | `token-y-trait` | `` | | `pool-id` | `uint` | | `tick` | `int` | | `dx` | `uint` | | `max-price` | `uint` | #### `swap-y-for-x-ioc` This function is the reverse of `swap-x-for-y-ioc`, the execution logic is similar. The effective lower price limit for the swap is the less restrictive of either the user-defined `min-price` or the natural lower price boundary (`price-start`) of the specified tick. If the requested `dy` would push the price below this effective cap, only a partial amount (or none) will be swapped. If conditions are not met, it returns zero values for all outputs. **Parameters** | Name | Type | | --------------- | ------------ | | `token-x-trait` | `` | | `token-y-trait` | `` | | `pool-id` | `uint` | | `tick` | `int` | | `dy` | `uint` | | `min-price` | `uint` | ### Governance Features The following functions are guarded by the `is-dao-or-extension` function. This implies that only the ALEX DAO or an enabled extension can use these features. #### `is-dao-or-extension` Standard protocol function to check whether the `contract-caller` is an enabled extension within the DAO or the `tx-sender` is the DAO itself. The extension check is delegated to the `executor-dao` contract. #### `create-pool` Creates a new DAMM pool between two SIP-010 fungible tokens. This function configures a pool with a specific `bin-size`, fee rates for each token, and a fee rebate percentage. It performs several validations before pool creation: * Ensures that both tokens are different and verifies the `bin-size` is one of the allowed values (`u1`, `u5`, `u10`, `u20`). * Checks that a pool with the same token pair (`token-x`, `token-y`) and `bin-size` does not already exist. It also verifies that a pool with the reversed token pair (`token-y`, `token-x`) and the same `bin-size` is not already registered. * Validates that `fee-rate-x` and `fee-rate-y` are strictly less than 1e8 (`ONE_8`) and that `fee-rebate` does not exceed 100%. The pool is stored using a new `pool-id` generated by incrementing `pool-id-nonce`, and it is inserted into both the `pools` map and the `pool-id-by-token` index for lookup by token pair. The pool starts in an active state (not paused or sunset), and the owner is set to the supplied `pool-owner`. Finally, it emits an event with the pool ID, the pool parameters, and the transaction sender. **Parameters** | Name | Type | | --------------- | ------------ | | `token-x-trait` | `` | | `token-y-trait` | `` | | `bin-size` | `uint` | | `pool-owner` | `principal` | | `fee-rate-x` | `uint` | | `fee-rate-y` | `uint` | | `fee-rebate` | `uint` | #### `update-pool-fee` Updates the fee configuration for an existing pool. It sets new values for the swap fee on each token and the rebate returned to liquidity providers. The function also validates that the new fee values for token X and token Y are both less than `ONE_8` (i.e. below 100%). Finally, it emits an event with the pool ID, the updated fees, the fee rebate, and the transaction sender. **Parameters** | Name | Type | | ------------ | ------ | | `pool-id` | `uint` | | `fee-rate-x` | `uint` | | `fee-rate-y` | `uint` | | `fee-rebate` | `uint` | #### `set-pool-status` Updates the operational status of a pool. It can mark a pool as `paused` (temporarily disabling activity) or `sunset` (permanently deactivating the pool), affecting its availability for swaps and actions like adding or removing liquidity. Finally, it emits an event with the pool ID, the deactivation and pause status, and the transaction sender. **Parameters** | Name | Type | | --------- | ------ | | `pool-id` | `uint` | | `sunset` | `bool` | | `paused` | `bool` | #### `claim-fees` Allows the DAO to withdraw accumulated swap fees from a specific pool and tick. The function resets the stored fees to zero and transfers the collected amounts of both tokens to the specified address using the corresponding token contracts. **Parameters** | Name | Type | | ---------------- | ------------ | | `token-x-trait` | `` | | `token-y-trait` | `` | | `pool-id` | `uint` | | `tick` | `int` | | `fee-to-address` | `principal` | ### Getters #### `get-pool-count` #### `get-pool-id` **Parameters** | Name | Type | | ----- | ------------------------------------------------------------ | | `key` | `{ token-x: principal, token-y: principal, bin-size: uint }` | #### `get-pool` **Parameters** | Name | Type | | --------- | ------ | | `pool-id` | `uint` | #### `get-pool-balances` **Parameters** | Name | Type | | --------- | ------ | | `pool-id` | `uint` | | `tick` | `int` | #### `get-liquidity-token-id` **Parameters** | Name | Type | | --------- | ------ | | `pool-id` | `uint` | | `tick` | `int` | #### `parse-liquidity-token-id` **Parameters** | Name | Type | | ---------- | ------ | | `token-id` | `uint` | #### `tick-to-price` **Parameters** | Name | Type | | ---------- | ------ | | `bin-size` | `uint` | | `tick` | `int` | #### `get-price-bounds` **Parameters** | Name | Type | | ---------- | ------ | | `bin-size` | `uint` | | `tick` | `int` | #### `get-virtual-balances` **Parameters** | Name | Type | | ----------- | ------ | | `bin-size` | `uint` | | `tick` | `int` | | `balance-x` | `uint` | | `balance-y` | `uint` | ## Storage ### `pool-id-nonce` | Data | Type | | -------- | ------ | | Variable | `uint` | A global counter used to assign unique identifiers to new pools. It is incremented each time a pool is created through the `create-pool` function. ### `pools` | Data | Type | | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Map | `uint => { token-x: principal, token-y: principal, bin-size: uint, pool-owner: principal, fee-rate-x: uint, fee-rate-y: uint, fee-rebate: uint, sunset: bool, paused: bool }` | Stores configuration data for each pool, indexed by `pool-id`. It includes the token pair, bin size, fee parameters, and status flags (`paused` and `sunset`). This map is used to validate pool existence and retrieve parameters during pool creation, swaps, and liquidity operations. ### `pool-id-by-token` | Data | Type | | ---- | -------------------------------------------------------------------- | | Map | `{ token-x: principal, token-y: principal, bin-size: uint } => uint` | Maps a token pair and bin size to its corresponding `pool-id`. This provides a way to retrieve an existing pool’s ID based on its asset configuration. ### `pool-supply` | Data | Type | | ---- | -------------------------------------------------------------------------------------------------------------------- | | Map | `{ pool-id: uint, tick: int } => { total-supply: uint, balance-x: uint, balance-y: uint, fee-x: uint, fee-y: uint }` | Stores the state of each bin in a pool, indexed by `pool-id` and `tick`. It tracks the total LP token supply, token balances, and accumulated fees for that specific price range within the pool. ## Contract calls * `executor-dao`: called by governance functions (e.g., `create-pool`, `update-pool-fee`) via `is-dao-or-extension` to verify if the `contract-caller` is an authorized extension or if `tx-sender` is the DAO itself. * `amm-liquidity-token-v3`: used to mint and burn LP tokens that represent user positions in specific ticks. * `token-x-trait` / `token-y-trait`: represent the fungible tokens involved in each pool. These trait contracts are used to perform transfers during swaps and liquidity updates. ## Errors | Error Name | Value | | ---------------------------------------- | ------------- | | `ERR-NOT-AUTHORIZED` | `(err u1000)` | | `ERR-POOL-PAUSED` | `(err u1001)` | | `ERR-POOL-SUNSET` | `(err u1002)` | | `ERR-POOL-NOT-FOUND` | `(err u1003)` | | `ERR-INVALID-PAIR` | `(err u1004)` | | `ERR-POOL-ALREADY-EXISTS` | `(err u2000)` | | `ERR-INVALID-PRICE` | `(err u2001)` | | `ERR-INVALID-TOKEN-TRAIT` | `(err u2002)` | | `ERR-INVALID-BIN-SIZE` | `(err u2003)` | | `ERR-PERCENT-GREATER-THAN-ONE` | `(err u2004)` | | `ERR-ZERO-PERCENT` | `(err u2005)` | | `ERR-INVALID-AMOUNT` | `(err u2006)` | | `ERR-POSITION-NOT-FOUND` | `(err u2007)` | | `ERR-PERCENT-GREATER-THAN-OR-EQUALS-ONE` | `(err u2008)` | | `ERR-INSUFFICIENT-LIQUIDITY` | `(err u2009)` | | `ERR-STORAGE-FAILURE` | `(err u3001)` | | `ERR-INVALID-LP-STATE` | `(err u3002)` | | `ERR-MAX-POOLS-ALLOWED` | `(err u3003)` | | `ERR-TICK-OUT-OF-RANGE` | `(err u3004)` | # self-listing-helper-v3a.clar * Location: `./contracts/extensions/self-listing-helper-v3a.clar` * [Deployed contract](https://explorer.hiro.so/txid/SP1E0XBN9T4B10E9QMR7XMFJPMA19D77WY3KP2QKC.self-listing-helper-v3a?chain=mainnet) The `self-listing-helper-v3a` contract enables the creation of trading pools on the ALEX DEX through two distinct mechanisms: a governance-controlled flow and a permissionless flow. In both cases, pools are formed by pairing a governance-approved anchor token (`token-x`) with a listed token (`token-y`), which is the asset being introduced for trading. This dual approach gives projects the flexibility to choose between a guided listing process or a fully autonomous, on-chain setup — all while using the same core infrastructure. ## Permissioned Pools can be created by following a guided process through the [ALEX Lab UI](https://app.alexlab.co/self-service-listing). The user supplies a `token-y` that must be pre-approved by governance before the pool can be initialized. ## Permissionless Users can list a new `token-y` without prior approval by deploying a wrapper contract that matches a governance-approved template. The contract includes a verification system, based on the [`clarity-stacks`](https://github.com/MarvinJanssen/clarity-stacks) library, that reconstructs and validates the original deployment transaction using Merkle proofs and block data. Once verification succeeds, the token is dynamically approved and the pool is created. ## Additional Capabilities The contract also supports: * Liquidity locking or burning for pool integrity * On-chain parameter configuration (fees, oracles, thresholds) * Governance-controlled token approvals * Rebates management for AMM incentives ## Features ### Public #### `create` Permissioned pool creation. The listed token (`token-y`) must be pre-approved to initiate the process. The function first runs validation checks via [`pre-check`](#pre-check), which ensures the anchor token (`token-x`) is approved and that the caller provides sufficient liquidity. It also checks that no existing pool with the given token pair and `factor` already exists. Next, it verifies that the listing token has a reserve in the `amm-vault-v2-01` contract, which serves as a proxy for its approval status. If all validations pass, the function calls [`post-check`](#post-check), which: * Creates the new pool on `amm-pool-v2-01` * Configures its parameters (fees, thresholds, oracle) * Applies LP token lock or burn rules via `liquidity-locker` if requested The function emits a print log with the full pool configuration for transparency. **Parameters** | Name | Type | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request-details` | `{ token-x-trait: , token-y-trait: , factor: uint, bal-x: uint, bal-y: uint, fee-rate-x: uint, fee-rate-y: uint, max-in-ratio: uint, max-out-ratio: uint, threshold-x: uint, threshold-y: uint, oracle-enabled: bool, oracle-average: uint, start-block: uint, lock: (buff 1) }` | #### `create2` Permissionless pool creation. The pool is created in a single transaction using a wrapper contract that matches an approved template and includes on-chain verification data. The function begins by validating the request with [`pre-check`](#pre-check). It then calls `verify-deploy`, which: * Reconstructs the transaction ID based on the deployment parameters * Validates that the contract was mined using a Merkle proof and block data * Ensures the code matches the wrapper template stored in this contract If verification succeeds, the wrapper is stored in `wrap-token-map`, and `token-y` is dynamically approved via `amm-vault-v2-01.set-approved-token`. Finally, [`post-check`](#post-check) is executed to create the pool and configure its parameters. The function emits a print log with both the request and verification details. **Parameters** | Name | Type | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request-details` | `{ token-x-trait: , token-y-trait: , factor: uint, bal-x: uint, bal-y: uint, fee-rate-x: uint, fee-rate-y: uint, max-in-ratio: uint, max-out-ratio: uint, threshold-x: uint, threshold-y: uint, oracle-enabled: bool, oracle-average: uint, start-block: uint, lock: (buff 1) }` | | `verify-params` | `{ nonce: (buff 8), fee-rate: (buff 8), signature: (buff 65), contract: principal, token-y: principal, proof: { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }, tx-block-height: uint, block-header-without-signer-signatures: (buff 712) }` | #### `lock-liquidity` This function locks a specified amount of LP tokens for a given pool. It is typically used immediately after a pool is created, when the creator chooses to lock the initial liquidity to signal trust to other users. Internally, it calls the `lock-liquidity` function of the `liquidity-locker` contract. That contract: * Transfers the LP tokens from the caller to its own custody * Records the locked amount and sets an unlock block height (default: \~6 months) **Parameters** | Name | Type | | --------- | ------ | | `amount` | `uint` | | `pool-id` | `uint` | #### `burn-liquidity` This function allows the caller to burn a specified amount of LP tokens from a given pool. It is one of the options available when configuring the pool after creation, typically used to make the initial liquidity permanently inaccessible. Internally, it calls the `burn-liquidity` function of the `liquidity-locker` contract. That contract: * Calls the `burn-fixed` function on the pool contract to destroy the LP tokens * Updates the internal `burnt-liquidity` record for that pool **Parameters** | Name | Type | | --------- | ------ | | `amount` | `uint` | | `pool-id` | `uint` | #### `claim-liquidity` This function allows users to reclaim their previously locked LP tokens after the lock period has expired. Internally, it calls the `claim-liquidity` function from the `liquidity-locker` contract. That contract: * Checks that the caller has a non-zero locked amount * Verifies that the current block is past the `end-burn-block` set during locking * Transfers the LP tokens back to the user * Deletes the corresponding lock record **Parameters** | Name | Type | | --------- | ------ | | `pool-id` | `uint` | ### Governance Features #### `is-dao-or-extension` This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract. #### `approve-token-x` A public function, governed through `is-dao-or-extension`, that sets the approval status and minimum required balance for a token to be used as the anchor token (`token-x`) in pool creation. This function updates the `approved-token-x` map, enabling the protocol to define which tokens can serve as anchors and to enforce a minimum contribution threshold (`min-x`) for those tokens. **Parameters** | Name | Type | | ---------- | ----------- | | `token` | `principal` | | `approved` | `bool` | | `min-x` | `uint` | #### `set-fee-rebate` A public function, governed through `is-dao-or-extension`, that sets the default fee rebate value used during pool creation. This value is stored locally in the contract and passed as an argument to the `set-fee-rebate` function of the `amm-registry-v2-01` contract when a new pool is initialized. **Parameters** | Name | Type | | ---------------- | ------ | | `new-fee-rebate` | `uint` | #### `set-wrapped-token-template` A public function, governed through `is-dao-or-extension`, that sets the reference template used to validate wrapper token contracts during permissionless pool creation. The `wrapped-token-template` is a list of code segments (as ASCII strings) that represent the expected body of a compliant wrapper contract. When a user submits a deployment proof via `create2`, this template is used to reconstruct the expected code and verify that the deployed contract matches it exactly. **Parameters** | Name | Type | | -------------- | ------------------------------- | | `new-template` | `(list 20 (string-ascii 5000))` | ### Getters #### `get-approved-token-x-or-default` **Parameters** | Name | Type | | --------- | ----------- | | `token-x` | `principal` | #### `get-fee-rebate` #### `get-lock-period` #### `get-locked-liquidity-or-default` **Parameters** | Name | Type | | --------- | ----------- | | `owner` | `principal` | | `pool-id` | `uint` | #### `get-locked-liquidity-for-pool-or-default` **Parameters** | Name | Type | | --------- | ------ | | `pool-id` | `uint` | #### `get-burnt-liquidity-or-default` **Parameters** | Name | Type | | --------- | ------ | | `pool-id` | `uint` | #### `get-wrapped-token-contract-code` **Parameters** | Name | Type | | ------- | ----------- | | `token` | `principal` | ### Relevant internal functions #### `pre-check` This private function performs validations prior to pool creation in both permissioned and permissionless flows. It verifies that: * The `token-x` is approved and has sufficient balance (`bal-x`). * A pool with the given pair and factor does not already exist (in either order). * The provided `lock` parameter is valid (`NONE`, `LOCK`, or `BURN`). It retrieves the approval and minimum balance requirements from the internal `approved-token-x` map and interacts with the `amm-pool-v2-01` contract to check pool existence. **Parameters** | Name | Type | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request-details` | `{ token-x-trait: , token-y-trait: , factor: uint, bal-x: uint, bal-y: uint, fee-rate-x: uint, fee-rate-y: uint, max-in-ratio: uint, max-out-ratio: uint, threshold-x: uint, threshold-y: uint, oracle-enabled: bool, oracle-average: uint, start-block: uint, lock: (buff 1) }` | #### `post-check` This private function finalizes pool creation by initializing the AMM pool and applying additional configuration parameters. It performs the following actions: * Calls the `create-pool` function from the `.amm-pool-v2-01` contract to initialize the pool with the provided liquidity amounts. * If the `lock` is set to `LOCK`, it calls `lock-liquidity` from the `liquidity-locker` contract to lock the initial LP tokens. * If the `lock` is set to `BURN`, it calls `burn-liquidity` from the `liquidity-locker` contract instead. * It applies pool parameters like fee rates, max ratios, thresholds, oracle settings, and the `start-block` by calling their respective setter functions in the `amm-pool-v2-01` contract. * Finally, it applies the global fee rebate for the pool by calling `set-fee-rebate` from the `amm-registry-v2-01` contract. This function is used after both `create` and `create2` to complete the pool setup. **Parameters** | Name | Type | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request-details` | `{ token-x-trait: , token-y-trait: , factor: uint, bal-x: uint, bal-y: uint, fee-rate-x: uint, fee-rate-y: uint, max-in-ratio: uint, max-out-ratio: uint, threshold-x: uint, threshold-y: uint, oracle-enabled: bool, oracle-average: uint, start-block: uint, lock: (buff 1) }` | ## Storage ### `wrapped-token-template` | Data | Type | | -------- | ----------------------------- | | Variable | `list 20 (string-ascii 5000)` | A list of strings that define the expected code template for a valid wrapper token contract. Each entry represents a fragment of the full contract body, and the full code is reconstructed by concatenating these parts with the listed token's contract address. This template is used during permissionless pool creation (`create2`) to verify that a wrapper contract deployed by a user matches the expected safe implementation. ### `approved-token-x` | Data | Type | | ---- | ---------------------------------------------- | | Map | `principal => { approved: bool, min-x: uint }` | A map that stores the approval status and minimum liquidity threshold for tokens used as `token-x` (anchor token) in pool creation. This validation is applied in both permissioned and permissionless listing flows. ### `fee-rebate` | Data | Type | | -------- | ------ | | Variable | `uint` | A global rebate value that is assigned to newly created pools. This value is passed to the `amm-registry-v2-01` contract during pool setup, where it determines the protocol fee discount applied to the pool. ### `wrap-token-map` | Data | Type | | ---- | ------------------------ | | Map | `principal => principal` | A map that links a listed token (`token-y`) to its corresponding verified wrapper contract.\ It is only populated during the permissionless listing flow, once the deployment proof is validated.\ This allows the AMM system to recognize and route trades through the correct wrapper contract. ## Contract calls * `executor-dao`: calls are made to verify whether a certain contract-caller is designated as an extension. * `liquidity-locker`: this contract is used to manage post-creation liquidity settings. It allows the contract to lock, burn, or later claim LP tokens based on the pool creator’s configuration. * `clarity-stacks`: this contract is used to verify that a wrapper contract was properly deployed on the Stacks blockchain. It checks that the contract was mined and included in a valid block. This system is built on top of Marvin Janssen’s [`clarity-stacks`](https://github.com/MarvinJanssen/clarity-stacks) proof framework. * `clarity-stacks-helper`: this contract is called to convert a Clarity string into its consensus-encoded buffer format. * `amm-vault-v2-01`: this contract is called to verify that `token-y` has reserves before pool creation and to approve it in the permissionless listing flow after successful wrapper verification. * `amm-pool-v2-01`: this contract is used to validate pool existence, create new trading pools, and configure pool parameters such as fees, slippage thresholds, oracles, and start block. * `amm-registry-v2-01`: this contract is called during pool creation to assign the fee rebate configuration for the newly created pool. ## Errors | Error Name | Value | | ------------------------------- | ------------- | | `err-not-authorised` | `(err u1000)` | | `err-token-not-approved` | `(err u1002)` | | `err-insufficient-balance` | `(err u1003)` | | `err-pool-exists` | `(err u1004)` | | `err-invalid-lock-parameter` | `(err u1005)` | | `err-invalid-length-nonce` | `(err u2000)` | | `err-invalid-length-fee` | `(err u2001)` | | `err-invalid-length-signature` | `(err u2002)` | | `err-invalid-principal-version` | `(err u2003)` | | `err-principal-not-contract` | `(err u2004)` | # ALEX DAO ## What is a DAO? A DAO, or Decentralized Autonomous Organization, is a type of organization represented by rules encoded as a computer program that is transparent, and controlled by organization members. DAOs operate on blockchain technology, to automate and enforce rules and decisions without the need for a central authority. ## What is ALEX DAO? ALEX DAO manages proposals to the ALEX platform which enables changes to be implemented in a rule-based way. Changes to the platform can take various forms, including modifications to parameters, minting or burning of tokens, and adding, upgrading, or deprecating system contracts. ## ALEX DAO Architecture

### Main DAO Components Overview This architecture has the following main components: #### ALEX-DAO Contract This is the core contract responsible for the DAO's operations and privileges. It is in charge of: * Bootstrapping the DAO * Defining new DAO features through extensions (modules) * Executing proposals * Authorizing components and extensions #### Operators Contract This contract manages the governance of the DAO and is implemented within ALEX's platform as an extension. It is responsible for: * Managing and controlling the users with permission to propose and vote changes to the platform. * Establishing proposal signaling thresholds * Receive and hold presented proposals while being voted/accepted * Signaling (voting on) registered proposals * Delegating proposal execution to the DAO operation contract * Controlling the validity, resubmissions, and expirations of proposals #### Extension Contracts These individual contracts are designed to enhance the features and operations of the DAO by providing new specific implementations. These contracts usually have the same permissions as the DAO contract itself. (see is-dao-or-extension). #### Proposal Contracts Proposals are contracts that define updates to the DAO platform. They are meant to execute tasks reserved for the DAO's privileged executors (the ALEX DAO contract itself, or enabled extensions). These tasks can include platform state changes, executing actions, and introducing extensions to the platform. Each proposal is approved through a voting system implemented in the operator's extension. They are executed only once with the DAO contract as the transaction sender. ### Operations ### Proposals ***Lifecyle***

***Proposal created*** A proposal is ready to be used when its contract is finally deployed. ***New Proposal*** Procedure to register the address of a given contract that conforms to the predefined proposal interface (trait). The operator that creates the proposal automatically signals 1 vote for it. Resubmissions (i.e. proposing again) are restricted only to non-executed expired proposals. This operation is restricted to enabled operators. ***Signaling*** Signaling is the process of voting for a certain registered and non-expired proposal in a boolean fashion (i.e., adding or subtracting 1 vote). Operators can only signal the same proposal twice if it has been resubmitted. The signaling procedure will trigger the execution step automatically if the proposal's signal count meets the threshold for execution. This operation is restricted to enabled operators. ***Execution*** As described in the signaling procedure, execution happens automatically when the signal count for the proposal meets the threshold. The procedure is delegated to the DAO operation contract, which restricts the operation to authorized extensions or the DAO contract itself. Finally, the execution invokes the proposal contract's execution method. ***Expiration***\ \ Proposal expiration occurs at a certain point in time (in the underlying burn blockchain) when the block height surpasses the validity period for that proposal. The validity period is defined as the range of blocks from when the proposal was created until reaching the sum of that block plus a predefined delta (currently set to 144 blocks). **Validation Logic** Proposals have a validation status, which is accomplished if two conditions are met: * The proposal has not expired. * The proposal was created after the operator extension was set up, including any updates to operators or thresholds. This validation is used in both new proposals and signaling procedures. ### Extensions ***New extension*** New extensions can be registered in the DAO core operation contract. This involves adding the address of a previously deployed contract, which will act as an administrative module of the DAO with privileges to execute core operations (e.g. adding new operators, updating thresholds or states, executing proposals, adding new extensions, etc.). Only DAO operator members (i.e. the core contract alex-dao or previously registered and enabled extensions) can perform this step. Typically, new extensions are uno registered through proposal contracts when they receive a majority of votes. ***Availability*** During or after the registration of a module (extension), other DAO operator members can enable or disable the extension in a boolean fashion. Although disabled extensions will remain registered in the core contract, they will not be permitted to perform future operations while in that state. As with the registration process, only DAO operator members have the authority to change the status of extensions. ***Callbacks*** Extensions that conform to the predefined extension interface (trait) have access to the core contract’s "Extension Requests" special feature. This feature allows other enabled extensions to call the core contract, which in turn, can call back the initiating extension to perform a specific callback method with alex-dao privileges. This includes the sender that triggered the call and a provided payload. ## Examples ### A proposal: agp-222.clar The agp-222 contract is a proposal whose main purpose is to extend the DAO platform by attaching the AMM-Pool contract (a DAO platform extension) and performing a series of maintenance tasks on the DAO platform. For it to be executed, it must first be accepted by the platform. The process is as follows: * The extension (in this case, the amm-pool-v2-01 contract) is created along with this proposal contract. * Once both contracts are created and deployed, the proposal is submitted to the DAO platform through the operators (extension) contract. This contract verifies that the submission is made by a DAO-operator. * The proposal is then put to a vote by the remaining DAO-operators (it is assumed that the submitting operator votes in favor, and its vote is automatically counted with the submission). * At some point, the proposal either reaches a predefined threshold or it expires. If the threshold is reached, the operators contract invokes the executor-dao contract to run the proposal's execute() code with DAO privileges. In this way, the code in the proposal gains the necessary permissions, allowing it to invoke any required DAO platform functionality as if it were already part of the DAO. This enables the proposal to do things like: * Include new extensions to the platform (as well as remove, stop, pause, etc.). * Reconfigure token pools. * Reconfigure blocklists. * Confirm special cases of token migrations. * Etc. * After all actions by the proposal are executed, it is discarded and cannot execute its code again or regain DAO privileges. #### In this particular case As we mentioned before, in this particular case, the proposal performs two actions: 1. It extends the DAO platform(\*) by attaching the AMM-Pool contract (the extension deployed along with this proposal), making it ready to operate immediately. 2. It performs a series of maintenance tasks on the DAO platform. To perform the extension attachment to the platform, a new invocation is made to the executor-dao contract, which is responsible for keeping track of which extensions are in use (and subsequently allowing anyone to check if an invoking contract is an approved extension). The maintenance task included in this proposal, in this particular case, involves blocking a set of 89 abusive addresses to prevent their usage of the system.

(\*) DAO-platform = the DAO contracts or its extensions. (\*\*) DAO-operator: a contract already part of the DAO-platform or a user of the system with operator privileges. ### An extension: The AMM-pool The amm-pool-v2-01 contract is a platform extension that implements a token swap pool, focusing on the pool mechanics. In contrast, the auxiliary contract amm-registry-v2-01 acts as a pool registry. Here, each pool, along with its properties such as the pool owner's address, must be registered. This separation of concerns allows for a simple permission system, supporting privileged operations by certain actors. Both mentioned contracts are extensions of the DAO-platform and are allowed to invoke each other with full permissions. By design, the sensitive data (pool configuration, behavior, state, ownership, and other properties) is contained and ultimately managed by the registry contract. All operations in this registry contract require invocation by the DAO-platform. On the other hand, the amm-pool extension contract includes governance calls for system reconfiguration. Authentication here is broader than in the registry, allowing not only the DAO platform but also pool owners (who may not necessarily be DAO platform members) to reconfigure pools. In the latter case, the amm-pool checks pool ownership by the invoker and, if applicable, uses its permissions as a member of the DAO platform to invoke reconfiguration functions in the registry. # Security Audits ALEX has reached out to three security audit firms for a complete smart contract and code audit. [CoinFabrik](https://www.coinfabrik.com/), [Least Authority](https://leastauthority.com/) and [Clarity Alliance](https://www.clarityalliance.org/) audit reports are available for a full review here. We are also working with some of our top community security and smart contract experts like Hank & Jeff from Oby and the folks from Syvita Guild. Check the audit reports here: * [2021-11 Pool Equation](https://cdn.alexlab.co/pdf/AlexGo_Audit_202111_Pool_Equation.pdf) * [2022-01 Launchpad, Vault and Reserve Pool](https://cdn.alexlab.co/pdf/AlexGo_Audit_202201_Launchpad_Vault_Reserve.pdf) * [2022-02 Protocol Smart Contracts](https://cdn.alexlab.co/pdf/Least_Authority_ALEX_Protocol_Smart_Contracts_Final_Audit_Report.pdf) * [2022-02 DAO](https://cdn.alexlab.co/pdf/AlexGo_Audit_202202_DAO.pdf) * [2022-04 AutoAlex CRP](https://cdn.alexlab.co/pdf/AlexGo_Audit_202204_Launchpadv1.1_AutoALEX_CRP.pdf) * [2022-07 Orderbook](https://cdn.alexlab.co/pdf/AlexGo_Audit_20220709-Order_Book_$Spot$.pdf) * [2022-10 Orderbook (perpetual)](https://cdn.alexlab.co/pdf/Alex_Audit_2022-10.pdf) * [2022-12 Bridge Endpoints](https://cdn.alexlab.co/pdf/ALEX_Audit_bridge_coinfabrik_202212.pdf) * [2023-04 Bridge Backend and Endpoints](https://cdn.alexlab.co/pdf/ALEX_Audit_Bridge_2023-04.pdf) * [2023-10 Bitcoin Oracle and Bridge](https://cdn.alexlab.co/pdf/ALEX_Audit_202310_Bitcoin_Oracle_and_Bridge.pdf) * [2024-05 AutoToken v3](https://cdn.alexlab.co/pdf/Auto_Alex_v3_Audit_May2024.pdf) * [2025-01 Farming Campaign](https://cdn.alexlab.co/pdf/AlexGo_Audit_ALEX_Farming_Campaign_Audit_2025-01.pdf) * [2025-02 Self-Listing Pool](https://github.com/alexgo-io/cdn/blob/main/pdf/ALEX_Self-Listing_Pool_Audit_2025-02.pdf) * [2025-05 Discrete Automated Market Maker (Clarity Alliance)](https://cdn.alexlab.co/pdf/ALEX_Clarity_Alliance_2025-05-16.pdf) * [2025-05 Discrete Automated Market Maker (CoinFabrik)](https://cdn.alexlab.co/pdf/ALEX_DAMM_Audit_2025-05.pdf) {% hint style="info" %} 🔍 Looking to report a vulnerability or earn rewards for finding bugs? Check out our [Bug Bounty Program](https://github.com/alexgo-io/alexlab-doc/blob/main/developers/developers/bug-bounty.md), hosted in collaboration with Immunefi. {% endhint %} # REST API Front-end developers may use our REST API () to access the latest market data on ALEX. ## Pool *** {% openapi src="" path="/v1/allswaps" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/pool\_stats/{pool\_token\_id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/pool\_volume/{pool\_token\_id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/volume\_24h/{pool\_token\_id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/volume\_7d/{pool\_token\_id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/pool\_liquidity/{pool\_token\_id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/liquidity/{pool\_token\_id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/fee/{pool\_token\_id}" method="get" %} {% endopenapi %} ## Stats *** {% openapi src="" path="/v1/stats/tvl" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/stats/tvl/{token}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/stats/total\_supply/{token}" method="get" %} {% endopenapi %} ## Price *** {% openapi src="" path="/v1/price/{token}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/pool\_token\_price/{pool\_token\_id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/pool\_token\_stats" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/price\_history/{token}" method="get" %} {% endopenapi %} ## DEX *** {% openapi src="" path="/v1/pairs" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/tickers" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/ticker/{ticker\_id}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/orderbook/{ticker}" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/historical\_swaps/{pool\_token\_id}" method="get" %} {% endopenapi %} ## Coin-gecko *** {% openapi src="" path="/v2/coin-gecko/pairs" method="get" %} {% endopenapi %} {% openapi src="" path="/v2/coin-gecko/tickers" method="get" %} {% endopenapi %} ## Public *** {% openapi src="" path="/v1/public/pairs" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/public/amm-pool-stats" method="get" %} {% endopenapi %} # Networks Stacks networks environments and deployed addresses * [Mainnet](/developers/integrations/networks/mainnet) * [Testnet](/developers/integrations/networks/testnet) # Mainnet ## Deployed Protocol Contracts

Contract	Address
DAO	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.executor-dao`
Vault	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault`
Reserve Pool	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-reserve-pool`
Launchpad	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-launchpad-v1-1`
Lottery	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-lottery`
Trading Pool	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1`
Fixed Weight Pool	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01`
Simple Weight Pool	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.simple-weight-pool-alex`
Swap Router	(to route between Fixed Weight Pool and Simple Weight Pool) `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-v1-03`
Swap Bridge	(to route between Trading Pool and Fixed Weight Pool / Simple Weight Pool) `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-bridged`
ALEX Token	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token`
autoALEX Token	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alex`
Bridge Endpoint	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.bridge-endpoint-v1-01`
sUSDT	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-susdt`

## Token List Where applicable, ALEX uses "wrapped" token to ensure certain functionalities (mainly the support for the fixed notation) are added to the native, 3rd-party, tokens. These "wrapped" tokens do not hold any native tokens, but are "pass-throughs". They call the relevant functions of the native tokens (e.g. `transfer`) to complete the user requests, but ensure these are done in a consistent manner across all tokens handled by ALEX.

Token	Address
STX	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2`
ALEX	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex`
xBTC	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wxbtc`
sUSDT	`SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-susdt`
xUSD	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wxusd`
autoALEX	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.auto-alex-v3`
USDA	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wusda`
DIKO	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wdiko`
MIA	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wmia`
NYC	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wnyc`
BANANA	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wban`
SLIME	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wslm`
WELSH	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wcorgi`
VIBES	`SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wvibes`

### BRC20 Tokens BRC20 tokens on ALEX represent those BRC20 tokens that are pegged in from Bitcoin.

Token	Address
$B20	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-db20`
MAXI	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-maxi`
SHNT	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-shnt`
PIZA	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-piza`
LONG	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-long`
INSC	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-insc`
MAJO	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-majo`
DEXM	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-dexm`
ATMT	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-aiptp`
CVLT	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-cvlt`
LBOW	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-lbow`
SBTC	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-sbtc`
OXBT	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-oxbt`
₿	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-spacesignb`
ORDS	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-ords`
NYTO	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-nyto`
BENG	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-beng`
TRAC	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-trac`
SATS	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-sats`
TARO	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-taro`
10MM	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-10mm`
PEPE	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-pepe`
VMPX	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-vmpx`
@LFG	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-atlfg`
ORDI	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-ordi`
$BIT	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-dbit`
MXRC	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-mxrc`
IGLI	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-igli`
OHMS	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-ohms`
JAKE	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-jake`
MEME	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-meme`
NALS	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-nals`
XING	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-xing`
BANK	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-bank`
PASS	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-pass`
WZRD	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-wzrd`
MOON	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-moon`
DRAC	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-drac`
LOVE	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-love`
ZBIT	`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-zbit`

# Testnet We use our own testnet whose API node is hosted at , with a few useful modifications (such as [puppet mode controller](http://127.0.0.1:5000/s/sPu0USrFZJvbjvTbkBTh/)) to the stock testnet deployment. You can explore the state of the testnet at . Developers generally would interact directly with our contracts deployed on the testnet through the API node above, but we also make available for those who would like to interact from a browser. Please note the testnet may be reset from time to time for maintenance and other purposes. We try to minimise the frequency of these resets, but it can and does happen, so please do bear that in mind when interacting with our testnet. For any questions / follow-ups, please use our Discord channel (). ## Smart Contracts

Contract	Address
Vault	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.alex-vault`
Reserve Pool	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.alex-reserve-pool`
Fixed Weight Pool	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.fixed-weight-pool-v1-02`
Simple Weight Pool	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.simple-weight-pool-alex`
Swap Helper	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.swap-helper-v1-03`
ALEX Token	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.age000-governance-token`
autoALEX Token	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.auto-alex`
STX (wrapped)	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wstx`
xBTC	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wbtc`
xUSD	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wxusd`
USDA	`ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wusda`

# Whitepapers {% content-ref url="/pages/YhVjxAuEX7J4OU1WCUOJ" %} [Automated Market Making of Trading Pool](/developers/resources/whitepaper/automated-market-making-of-alex) {% endcontent-ref %} {% content-ref url="/pages/gPDRiSFpobKj7fsx0A9k" %} [Automated Market Making of Yield Token Pool](/developers/resources/whitepaper/automated-market-making-of-alex-1) {% endcontent-ref %} {% content-ref url="/pages/3SQRgRcuH3o8gDPUJWco" %} [Automated Market Making of Collateral Rebalancing Pool](/developers/resources/whitepaper/automated-market-making-of-collateral-rebalancing-pool) {% endcontent-ref %} {% content-ref url="/pages/poysgOiVe8QWvt5nbVoE" %} [Dive Into Collateral Rebalancing Pool!](/developers/resources/whitepaper/dive-into-collateral-rebalancing-pool) {% endcontent-ref %} {% content-ref url="" %} {% endcontent-ref %} # Automated Market Making of Trading Pool ## Abstract We introduce a new invariant function associated with generalised mean that underpins the ALEX AMM. ALEX builds DeFi primitives targeting developers looking to build ecosystem on Bitcoin, enabled by [Stacks](https://www.stacks.co/). With a suitable parameterisation, the invariant function supports both risky pairs (i.e. $$x y=L$$), stable pairs (i.e. $$x +y=L$$) and any linear combination in-between (i.e. Curve). We also show that our invariant function maps $$L$$ to the liquidity distribution of [Uniswap V3](https://uniswap.org/whitepaper-v3.pdf). ## Introduction At ALEX, we build DeFi primitives targeting developers looking to build ecosystem on Bitcoin, enabled by [Stacks](https://www.stacks.co/). As such, we focus on trading, lending and borrowing of crypto assets with Bitcoin as the settlement layer and Stacks as the smart contract layer. At the core of this focus is the automated market making ("AMM") protocol, which allows users to exchange one crypto asset with another trustlessly. This paper focuses on technical aspects of AMM. ## AMM and Invariant Function ALEX AMM is built on three beliefs: (i) it is mathematically neat and reflect economic demand and supply and (ii) it is a type of mean, like other AMMs. We will firstly review some desirable features of AMM that ALEX hopes to exhibit. ### Properties of AMM AMM protocol, which provides liquidity algorithmically, is the core engine of DeFi. In the liquidity pool, two or more assets are deposited and subsequently swapped resulting in both reserve and price movement. The protocol follows an invariant function $$f(X)=L$$, where $$X=\left(x\_1,x\_2,\dots,x\_d\right)$$ is $$d$$ dimension representing $$d$$ assets and $$L$$ is constant. When $$d=2$$, which is the common practise by a range of protocols, AMM $$f(x\_1,x\_2)=L$$ can be expressed as $$x\_2=g(x\_1)$$. Although it is not always true, $$g$$ tends to be twice differentiable and satisfies the following * monotonically decreasing, i.e. $$\frac{dg(x\_1)}{dx\_1}<0$$. This is because price is often defined as $$-\frac{dg(x\_1)}{dx\_1}$$. A decreasing function ensures price to be positive. * convex, i.e. $$\frac{d^2g(x\_1)}{dx\_1^2} \geq 0$$. This is equivalent to say that $$-\frac{dg(x\_1)}{dx\_1}$$ is a non-increasing function of $$x\_1$$. It is within the expectation of economic theory of demand and supply, as more reserve of $$x\_1$$ means declining price. Meanwhile, $$f$$ can usually be interpreted as a form of mean, for example, [mStable](https://docs.mstable.org) relates to arithmetic mean, where $$x\_1+x\_2=L$$ (constant sum formula); one of the most popular platforms [Uniswap](https://uniswap.org/whitepaper-v3.pdf) relates to geometric mean, where $$x\_1 x\_2=L$$ (constant product formula); [Balancer](https://balancer.fi/whitepaper.pdf), which our [collateral rebalancing pool](/developers/resources/whitepaper/automated-market-making-of-collateral-rebalancing-pool) employs, applies weighted geometric mean. Its AMM is $$x\_1^{w\_1} x\_2^{w\_2}=L$$ where $$w\_1$$ and $$w\_2$$ are fixed weights. ALEX AMM extends these to create a generalised mean. ### ALEX AMM After extensive research, we consider it possible for ALEX AMM to be connected to generalised mean defined as $$ \left( \frac{1}{d} \sum \_{i=1}^{d} x\_i^{p} \right)^{\frac{1}{p}} $$ where $$0 \leq p \leq 1$$. The expression might remind readers of $$p$$-norm when $$x\_i \geq 0$$. It is however not true when $$p<1$$ as triangle inequality doesn't hold. When $$d=2$$ and $$p=1-t$$ $$(0\leq t<1)$$ is fixed, the core component of generalised mean is assumed constant as below. $$ \begin{split}x\_1^{1-t}+x\_2^{1-t}&=L\\ -\frac{dx\_2}{dx\_1}&=\left(\frac{x\_2}{x\_1} \right)^{t}\end{split} $$ This equation is regarded reasonable as AMM, because (i) function $$g$$ where $$x\_2=g(x\_1)$$ is monotonically decreasing and convex; and (ii) The boundary value of $$t=0$$ and $$t=1$$ corresponds to constant sum and constant product formula respectively. When $$t$$ decreases from 1 to 0, price $$-\frac{dg(x\_1)}{x\_1}$$ gradually converges to 1, i.e. the curve converges from constant product to constant sum (see [Appendix 1](#appendix-1-generalised-mean-when-d-2) for the relevant proofs). Though purely theoretical at this stage, [Appendix 2](#appendix-2-liquidity-mapping-to-uniswap-v3) maps $$L$$ to the liquidity distribution of [Uniswap V3](https://uniswap.org/whitepaper-v3.pdf). This is motivated by an independent research from [Paradigm](https://www.paradigm.xyz/2021/06/uniswap-v3-the-universal-amm/). ## Trading Formulae Market transaction, which involves exchange of one crypto asset and another, satisfies the invariant function. Please note the formulae do not account for the fee re-investment, which results in a slight increase of $$L$$ after each transaction, like *Uniswap V2*. ### Out-Given-In In order to purchase $$\Delta y$$ amount of token Y from the pool, the buyer needs to deposit $$\Delta x$$ amount of token X. $$\Delta x$$ and $$\Delta y$$ satisfy the following $$ (x+\Delta x)^{1-t}+(y-\Delta y)^{1-t}=x^{1-t}+y^{1-t} $$ After each transaction, balance is updated as below: $$x\rightarrow x+\Delta x$$ and $$y\rightarrow y-\Delta y$$. Rearranging the formula results in $$ \Delta y=y-\left\[x^{1-t}+y^{1-t}-(x+\Delta x)^{1-t}\right]^{\frac{1}{1-t}} $$ When transaction cost exists, the actual deposit to the pool is less than $$\Delta x$$. Assuming $$\lambda\Delta x$$ is the actual amount and $$(1-\lambda)\Delta x$$ is the fee, above can now be expressed as $$ \begin{split} &(x+\lambda\Delta x)^{1-t}+(y-\Delta y)^{1-t}=x^{1-t}+y^{1-t}\ &\Delta y=y-\left\[x^{1-t}+y^{1-t}-(x+\lambda\Delta x)^{1-t}\right]^{\frac{1}{1-t}} \end{split} $$ To keep $$L$$ constant, the updated balance is: $$x\rightarrow x+\lambda\Delta x$$ and $$y\rightarrow y-\Delta y$$. ### In-Given-Out This is the opposite case to above. We are deriving $$\Delta x$$ from $$\Delta y$$. $$ \Delta x=\frac{1}{\lambda}{\left\[x^{1-t}+y^{1-t}-(y-\Delta y)^{1-t}\right]^{\frac{1}{1-t}}-x} $$ ### In-Given-Price Sometimes, trader would like to adjust the price, perhaps due to deviation of AMM price to the market value. Define $$p'$$ the AMM price after rebalancing the token X and token Y in the pool $$ p'=\left(\frac{y-\Delta y}{x+\lambda\Delta x}\right)^{t} $$ Then, the added amount of $$\Delta x$$ can be calculated from the formula below $$ \begin{split} &(x+\lambda\Delta x)^{1-t}+(y-\Delta y)^{1-t}=x^{1-t}+y^{1-t}\ &1+\left(\frac{y}{x}\right)^{1-t}=\left(1+\lambda\frac{\Delta x}{x}\right)^{1-t}+(\frac{y-\Delta y}{x})^{1-t}\ &1+p^{\frac{1-t}{t}}=\left(1+\lambda\frac{\Delta x}{x}\right)^{1-t}+p'^{\frac{1-t}{t}}\left(1+\lambda\frac{\Delta x}{x}\right)^{1-t}\ &\Delta x=\frac{x}{\lambda}\left\[\left(\frac{1+p^{\frac{1-t}{t}}}{1+p'^{\frac{1-t}{t}}}\right)^{\frac{1}{1-t}}-1\right]\ \end{split} $$ ## Appendix 1: Generalised Mean when d=2 ALEX's invariant function is $$f(x\_{1},x\_{2};p)=x{*1}^{p}+x*{2}^{p}=L.$$ It can be rearranged as $$x{2}=g(x\_{1})=(L-x\_{1}^{p})^{\frac{1}{p}}$$. $$x\_{1}$$ and $$x\_{2}$$ should both be positive meaning the liquidity pool contains both tokens. #### Theorem When $$0\