mirror of
https://github.com/alexgo-io/alex-v1-docs.git
synced 2026-01-12 14:33:49 +08:00
Merge pull request #5 from CoinFabrik/feature/demo-pool-sections
Improve Trading Pool subsections
This commit is contained in:
fiftyeightandeight
5
.gitbook.yaml
Normal file
5
.gitbook.yaml
Normal file
@@ -0,0 +1,5 @@
|
||||
redirects:
|
||||
developers/testnet: developers/networks/testnet.md
|
||||
developers/smart-contracts: developers/networks/mainnet.md
|
||||
developers/smart-contracts/token-list: developers/networks/mainnet.md
|
||||
developers/smart-contracts/amm-pool-mapping: developers/protocol-contracts/README.md
|
||||
14
SUMMARY.md
14
SUMMARY.md
@@ -6,9 +6,6 @@
|
||||
|
||||
* [Our Design](trading-lending-and-borrowing/platform-architecture-that-supports-ecosystem-development.md)
|
||||
* [Trading Pool](trading-lending-and-borrowing/trading-pool/README.md)
|
||||
* [amm-pool-v2-01.clar](trading-lending-and-borrowing/trading-pool/amm-pool-v2-01.clar.md)
|
||||
* [amm-registry-v2-01.clar](trading-lending-and-borrowing/trading-pool/amm-registry-v2-01.clar.md)
|
||||
* [amm-vault-v2-01.clar](trading-lending-and-borrowing/trading-pool/amm-vault-v2-01.clar.md)
|
||||
* [Collateral Rebalancing Pool](trading-lending-and-borrowing/collateral-rebalancing-pool.md)
|
||||
* [Yield Token Pool](trading-lending-and-borrowing/automated-market-making-designed-for-lending-protocols.md)
|
||||
* [Vault](trading-lending-and-borrowing/vault.md)
|
||||
@@ -53,8 +50,11 @@
|
||||
|
||||
## 🎮 Developers
|
||||
|
||||
* [Testnet](developers/testnet.md)
|
||||
* [Smart Contracts](developers/smart-contracts/README.md)
|
||||
* [Token List](developers/smart-contracts/token-list.md)
|
||||
* [AMM Pool Mapping](developers/smart-contracts/amm-pool-mapping.md)
|
||||
* [Networks](developers/networks/README.md)
|
||||
* [Mainnet](developers/networks/mainnet.md)
|
||||
* [Testnet](developers/networks/testnet.md)
|
||||
* [Protocol Contracts](developers/protocol-contracts/README.md)
|
||||
* [amm-pool-v2-01.clar](developers/protocol-contracts/amm-pool-v2-01.clar.md)
|
||||
* [amm-registry-v2-01.clar](developers/protocol-contracts/amm-registry-v2-01.clar.md)
|
||||
* [amm-vault-v2-01.clar](developers/protocol-contracts/amm-vault-v2-01.clar.md)
|
||||
* [REST API](developers/api-references.md)
|
||||
|
||||
6
developers/networks/README.md
Normal file
6
developers/networks/README.md
Normal file
@@ -0,0 +1,6 @@
|
||||
---
|
||||
description: Stacks networks environments and deployed addresses
|
||||
---
|
||||
|
||||
* [Mainnet](mainnet.md)
|
||||
* [Testnet](testnet.md)
|
||||
@@ -1,4 +1,10 @@
|
||||
# Token List
|
||||
# Smart Contracts
|
||||
|
||||
## Deployed Protocol Contracts
|
||||
|
||||
<table><thead><tr><th width="167">Contract</th><th>Address</th></tr></thead><tbody><tr><td>DAO</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.executor-dao</code></td></tr><tr><td>Vault</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault</code></td></tr><tr><td>Reserve Pool</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-reserve-pool</code></td></tr><tr><td>Launchpad</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-launchpad-v1-1</code></td></tr><tr><td>Lottery</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-lottery</code></td></tr><tr><td>Trading Pool</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1</code></td></tr><tr><td>Fixed Weight Pool<td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01</code></td></tr><tr><td>Simple Weight Pool</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.simple-weight-pool-alex</code></td></tr><tr><td>Swap Router</td><td>(to route between Fixed Weight Pool and Simple Weight Pool)<br><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-v1-03</code></td></tr><tr><td>Swap Bridge </td><td>(to route between Trading Pool and Fixed Weight Pool / Simple Weight Pool)<br><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-bridged</code></td></tr><tr><td>ALEX Token</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token</code></td></tr><tr><td>autoALEX Token</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alex</code></td></tr><tr><td>Bridge Endpoint</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.bridge-endpoint-v1-01</code></td></tr><tr><td>sUSDT</td><td><code>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-susdt</code></td></tr></tbody></table>
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -6,7 +12,7 @@ These "wrapped" tokens do not hold any native tokens, but are "pass-throughs". T
|
||||
|
||||
<table><thead><tr><th width="154">Token</th><th>Address</th></tr></thead><tbody><tr><td>STX</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2</code></td></tr><tr><td>ALEX</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex</code></td></tr><tr><td>xBTC</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wxbtc</code></td></tr><tr><td>sUSDT</td><td><code>SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-susdt</code></td></tr><tr><td>xUSD</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wxusd</code></td></tr><tr><td>autoALEX</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.auto-alex-v3</code></td></tr><tr><td>USDA</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wusda</code></td></tr><tr><td>DIKO</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wdiko</code></td></tr><tr><td>MIA</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wmia</code></td></tr><tr><td>NYC</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wnyc</code></td></tr><tr><td>BANANA</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wban</code></td></tr><tr><td>SLIME</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wslm</code></td></tr><tr><td>WELSH</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wcorgi</code></td></tr><tr><td>VIBES</td><td><code>SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wvibes</code></td></tr></tbody></table>
|
||||
|
||||
## BRC20 Tokens
|
||||
### BRC20 Tokens
|
||||
|
||||
BRC20 tokens on ALEX represent those BRC20 tokens that are pegged in from Bitcoin.
|
||||
|
||||
16
developers/networks/testnet.md
Normal file
16
developers/networks/testnet.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# Testnet
|
||||
|
||||
We use our own testnet whose API node is hosted at [https://stacks-node-api.testnet.alexlab.co/](https://stacks-node-api.testnet.alexlab.co/), 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 [https://explorer.testnet.alexlab.co/?chain=mainnet](https://explorer.testnet.alexlab.co/?chain=mainnet).
|
||||
|
||||
Developers generally would interact directly with our contracts deployed on the testnet through the API node above, but we also make available [https://app.testnet.alexlab.co/](https://app.testnet.alexlab.co/) 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 ([https://discord.gg/alexlab](https://discord.gg/alexlab)).
|
||||
|
||||
## Smart Contracts
|
||||
|
||||
<table><thead><tr><th width="167">Contract</th><th>Address</th></tr></thead><tbody><tr><td>Vault</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.alex-vault</code></td></tr><tr><td>Reserve Pool</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.alex-reserve-pool</code></td></tr><tr><td>Fixed Weight Pool</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.fixed-weight-pool-v1-02</code></td></tr><tr><td>Simple Weight Pool</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.simple-weight-pool-alex</code></td></tr><tr><td>Swap Helper</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.swap-helper-v1-03</code></td></tr><tr><td>ALEX Token</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.age000-governance-token</code></td></tr><tr><td>autoALEX Token</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.auto-alex</code></td></tr><tr><td>STX (wrapped)</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wstx</code></td></tr><tr><td>xBTC</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wbtc</code></td></tr><tr><td>xUSD</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wxusd</code></td></tr><tr><td>USDA</td><td><code>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wusda</code></td></tr></tbody></table>
|
||||
|
||||
88
developers/protocol-contracts/README.md
Normal file
88
developers/protocol-contracts/README.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
description: 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.
|
||||
|
||||
|
||||
|
||||
### 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](./amm-pool-v2-01.clar.md)
|
||||
|
||||
### 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](./amm-registry-v2-01.clar.md)
|
||||
|
||||
## 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](./amm-vault-v2-01.clar.md)
|
||||
|
||||
## 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`|
|
||||
@@ -1,8 +1,8 @@
|
||||
# Pool
|
||||
|
||||
#### 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)
|
||||
#### 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](./amm-registry-v2-01.clar.md) and [amm-vault-v2-01.clar](./amm-vault-v2-01.clar.md).
|
||||
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](amm-registry-v2-01.clar.md) and [amm-vault-v2-01.clar](amm-vault-v2-01.clar.md).
|
||||
|
||||
## Storage
|
||||
|
||||
@@ -168,22 +168,23 @@ The following functions are tools to assist the off-chain activities.
|
||||
|
||||
### 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]\(xxx xxx).
|
||||
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](amm-registry-v2-01.clar.md).
|
||||
|
||||
#### 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-start-block`
|
||||
* `set-end-block`
|
||||
* `set-fee-rate-x`
|
||||
* `set-fee-rate-y`
|
||||
* `set-max-in-ratio`
|
||||
* `set-max-out-ratio`
|
||||
* `set-oracle-enabled`
|
||||
* `set-oracle-average`
|
||||
* `set-threshold-x`
|
||||
* `set-threshold-y`
|
||||
* `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
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Registry
|
||||
|
||||
#### 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)
|
||||
#### 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](./amm-pool-v2-01.clar.md).
|
||||
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](amm-pool-v2-01.clar.md).
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Vault
|
||||
|
||||
#### 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)
|
||||
#### 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](./amm-pool-v2-01.clar.md) 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.
|
||||
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](amm-pool-v2-01.clar.md) 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
|
||||
@@ -1,5 +0,0 @@
|
||||
# Smart Contracts
|
||||
|
||||
For the complete token list and the pool mapping, see [Token List](token-list.md) and [AMM Pool Mapping](amm-pool-mapping.md).
|
||||
|
||||
<table><thead><tr><th width="167">Contract</th><th>Address</th></tr></thead><tbody><tr><td>DAO</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.executor-dao</td></tr><tr><td>Vault</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault</td></tr><tr><td>Reserve Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-reserve-pool</td></tr><tr><td>Launchpad</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-launchpad-v1-1</td></tr><tr><td>Lottery</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-lottery</td></tr><tr><td>Trading Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1</td></tr><tr><td>Fixed Weight Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01</td></tr><tr><td>Simple Weight Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.simple-weight-pool-alex</td></tr><tr><td>Swap Router</td><td>(to route between Fixed Weight Pool and Simple Weight Pool)<br>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-v1-03</td></tr><tr><td>Swap Bridge </td><td>(to route between Trading Pool and Fixed Weight Pool / Simple Weight Pool)<br>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-bridged</td></tr><tr><td>ALEX Token</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token</td></tr><tr><td>autoALEX Token</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alex</td></tr><tr><td>Bridge Endpoint</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.bridge-endpoint-v1-01</td></tr><tr><td>sUSDT</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-susdt</td></tr></tbody></table>
|
||||
@@ -1,203 +0,0 @@
|
||||
# AMM Pool Mapping
|
||||
|
||||
Below table maps the pool listed on [https://app.alexlab.co/pool](https://app.alexlab.co/pool) to smart contracts with the relevant parameters
|
||||
|
||||
## Pool Types
|
||||
|
||||
We have three smart contracts in production that provide AMM.
|
||||
|
||||
### Trading Pool
|
||||
|
||||
[Trading Pool](../../trading-lending-and-borrowing/trading-pool/) is the latest AMM smart contract that developers should use whenever possible.
|
||||
|
||||
Trading Pool implements Generalised 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<t <1$$ then gives a Curve-like formula.
|
||||
|
||||
#### Contract address
|
||||
|
||||
`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1`
|
||||
|
||||
### Fixed Weight Pool
|
||||
|
||||
Fixed Weight Pool is based on Balancer and allows to create AMM pools with custom (i.e. non equal-weight), fixed-weight, pools.
|
||||
|
||||
Fixed Weight Pool has been deprecated since the introduction of [Trading Pool](amm-pool-mapping.md#trading-pool).
|
||||
|
||||
#### Contract address
|
||||
|
||||
`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01`
|
||||
|
||||
### Simple Weight Pool
|
||||
|
||||
Simple Weight Pool supports the constant product formula (i.e. $$x y=L$$).
|
||||
|
||||
Simple Weight Pool has been deprecated since the introduction of [Trading Pool](amm-pool-mapping.md#trading-pool).
|
||||
|
||||
#### Contract address
|
||||
|
||||
`SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.simple-weight-pool-alex`
|
||||
|
||||
## AMM Pools
|
||||
|
||||
### STX-xBTC-1
|
||||
|
||||
**Smart Contract**: [Trading Pool](amm-pool-mapping.md#trading-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wbtc`
|
||||
* `factor`: 1e8
|
||||
|
||||
### STX-sUSDT-1
|
||||
|
||||
**Smart Contract**: [Trading Pool](amm-pool-mapping.md#trading-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-susdt`
|
||||
* `factor`: 1e8
|
||||
|
||||
### STX-ALEX-1
|
||||
|
||||
**Smart Contract**: [Trading Pool](amm-pool-mapping.md#trading-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token`
|
||||
* `factor`: 1e8
|
||||
|
||||
### ALEX-ATALEXV2-1
|
||||
|
||||
**Smart Contract**: [Trading Pool](amm-pool-mapping.md#trading-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alex-v2`
|
||||
* `factor`: 1e8
|
||||
|
||||
### ALEX-DIKO-1
|
||||
|
||||
**Smart Contract**: [Trading Pool](amm-pool-mapping.md#trading-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wdiko`
|
||||
* `factor`: 1e8
|
||||
|
||||
### STX-VIBES-1
|
||||
|
||||
**Smart Contract**: [Trading Pool](amm-pool-mapping.md#trading-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wvibes`
|
||||
* `factor`: 1e8
|
||||
|
||||
### STX-ALEX-50-50
|
||||
|
||||
**Smart Contract**: [Fixed Weight Pool](amm-pool-mapping.md#fixed-weight-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token`
|
||||
* `weight-x`: 0.5e8
|
||||
* `weight-y`: 0.5e8
|
||||
|
||||
### STX-xBTC-50-50
|
||||
|
||||
**Smart Contract**: [Fixed Weight Pool](amm-pool-mapping.md#fixed-weight-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wbtc`
|
||||
* `weight-x`: 0.5e8
|
||||
* `weight-y`: 0.5e8
|
||||
|
||||
### STX-xUSD-50-50
|
||||
|
||||
**Smart Contract**: [Fixed Weight Pool](amm-pool-mapping.md#fixed-weight-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wxusd`
|
||||
* `weight-x`: 0.5e8
|
||||
* `weight-y`: 0.5e8
|
||||
|
||||
### xUSD-USDA-0.005
|
||||
|
||||
**Smart Contract**: [Trading Pool](amm-pool-mapping.md#trading-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wxusd`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wusda`
|
||||
* `factor`: 0.005e8
|
||||
|
||||
### ALEX-USDA-50-50
|
||||
|
||||
**Smart Contract**: [Simple Weight Pool](amm-pool-mapping.md#simple-weight-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wusda`
|
||||
|
||||
### STX-CORGI-1
|
||||
|
||||
**Smart Contract**: [Trading Pool](amm-pool-mapping.md#trading-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wcorgi`
|
||||
* `factor`: 1e8
|
||||
|
||||
### STX-MIA-50-50
|
||||
|
||||
**Smart Contract**: [Fixed Weight Pool](amm-pool-mapping.md#fixed-weight-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wmia`
|
||||
* `weight-x`: 0.5e8
|
||||
* `weight-y`: 0.5e8
|
||||
|
||||
### STX-NYCC-50-50
|
||||
|
||||
**Smart Contract**: [Fixed Weight Pool](amm-pool-mapping.md#fixed-weight-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wnycc`
|
||||
* `weight-x`: 0.5e8
|
||||
* `weight-y`: 0.5e8
|
||||
|
||||
### ALEX-BANABA-50-50
|
||||
|
||||
**Smart Contract**: [Simple Weight Pool](amm-pool-mapping.md#simple-weight-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wban`
|
||||
|
||||
### ALEX-SLIME-50-50
|
||||
|
||||
**Smart Contract**: [Simple Weight Pool](amm-pool-mapping.md#simple-weight-pool)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* `token-x`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token`
|
||||
* `token-y`: `SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wslm`
|
||||
@@ -1,16 +0,0 @@
|
||||
# Testnet
|
||||
|
||||
We use our own testnet whose API node is hosted at [https://stacks-node-api.testnet.alexlab.co/](https://stacks-node-api.testnet.alexlab.co/), 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 [https://explorer.testnet.alexlab.co/?chain=mainnet](https://explorer.testnet.alexlab.co/?chain=mainnet).
|
||||
|
||||
Developers generally would interact directly with our contracts deployed on the testnet through the API node above, but we also make available [https://app.testnet.alexlab.co/](https://app.testnet.alexlab.co/) 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 ([https://discord.gg/alexlab](https://discord.gg/alexlab)).
|
||||
|
||||
## Smart Contracts
|
||||
|
||||
<table><thead><tr><th width="167">Contract</th><th>Address</th></tr></thead><tbody><tr><td>Vault</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.alex-vault</td></tr><tr><td>Reserve Pool</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.alex-reserve-pool</td></tr><tr><td>Fixed Weight Pool</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.fixed-weight-pool-v1-02</td></tr><tr><td>Simple Weight Pool</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.simple-weight-pool-alex</td></tr><tr><td>Swap Helper</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.swap-helper-v1-03</td></tr><tr><td>ALEX Token</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.age000-governance-token</td></tr><tr><td>autoALEX Token</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.auto-alex</td></tr><tr><td>STX (wrapped)</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wstx</td></tr><tr><td>xBTC</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wbtc</td></tr><tr><td>xUSD</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wxusd</td></tr><tr><td>USDA</td><td>ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wusda</td></tr></tbody></table>
|
||||
|
||||
@@ -2,23 +2,30 @@
|
||||
|
||||
## Introduction
|
||||
|
||||
Please refer to our [white paper](../../whitepaper/automated-market-making-of-alex/) for a more rigorous treatment on the subject.
|
||||
In this section you will find an overview of the ALEX on-chain Trading Pool and its automated market making (AMM) protocol.
|
||||
|
||||
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.
|
||||
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 for another in a trustless manner.
|
||||
|
||||
Trading Pool implements Generalised 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 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<t <1$$ then gives a Curve-like formula.
|
||||
|
||||
## <mark style="color:red;">Caution on fixed notation</mark>
|
||||
Regarding its implementation, the Trading Pool protocol consists of a set of smart contracts built on the Stacks blockchain that facilitate trading operations within the ALEX DeFi ecosystem. Below, there are listed the main features of the pool.
|
||||
|
||||
Please note we use 8-digit fixed notation to represent decimals. If you interact directly with any of our contracts, you must provide all numbers in the correct format.
|
||||
{% hint style="info" %}
|
||||
For more of the theory and fundaments behind the Alex AMM protocol refer to the [ALEX AMM Whitepaper](../../whitepaper/automated-market-making-of-alex/).
|
||||
If you are looking for technical details and implementation design please refer to the [Developers Protocol Contracts section](../../developers/protocol-contracts/README.md#alex-dao-amm-trading-pool).
|
||||
{% endhint %}
|
||||
|
||||
For example, 1 should be passed as 10,000,000 (= 1e8), i.e. 1.00000000.
|
||||
{% hint style="danger" %}
|
||||
**Caution on fixed notation**: Please note we use 8-digit fixed notation to represent decimals. If you interact directly with any of our contracts, you must provide all numbers in the correct format. For example, 1 should be passed as 10,000,000 (= 1e8), i.e. 1.00000000.
|
||||
{% endhint %}
|
||||
|
||||
## Pool creation
|
||||
## Pool management
|
||||
|
||||
A pair can be registered (i.e. a pool can be created) by calling `create-pool` with the parameters including the traits of the two tokens (`token-x` and `token-y`), the factor $$t$$, the governance address (`pool-owner`) and the initial liquidity.
|
||||
### Pool creation
|
||||
|
||||
A pair can be registered (i.e. a pool can be created) by calling `create-pool` function indicating the traits of the two tokens (`token-x` and `token-y`), the factor $$t$$, the governance address (`pool-owner`) and the initial liquidity.
|
||||
|
||||
Trading Pool is permission-less in that anyone can register a pair with initial liquidity, so long as the two tokens are pre-approved (this is to prevent introducing malicious tokens to the platform).
|
||||
|
||||
@@ -26,15 +33,10 @@ Trading Pool is permission-less in that anyone can register a pair with initial
|
||||
|
||||
Certain privileged functions are available to `pool-owner` to govern the pool. The `pool-owner` address is set at the time of a pool creation. ALEX DAO, as part of its governance, has the power to update and replace the `pool-owner` address. Therefore, you can view this as ALEX DAO delegating the governance of each pool to its respective `pool-owner`.
|
||||
|
||||
* `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-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.
|
||||
[Refer to the comprehensive list of pool-governed setters](../../developers/protocol-contracts/amm-pool-v2-01.clar.md#setters).
|
||||
|
||||
## Liquidity provision
|
||||
|
||||
Liquidity can be added to or removed from the pool any time by calling `add-to-position` or `reduce-position`, respectively.
|
||||
## Pool liquidity operations
|
||||
Users can participate by adding (injecting liquidity with function `add-to-position`) or reducing (withdrawing with function `reduce-position`) assets positions in a specific pool that deals with a pair of tokens. When users add assets, they receive pool tokens (a.k.a. LP Tokens), which represent their share of the pool and potential earnings. When withdrawing assets, users return pool tokens.
|
||||
|
||||
### Adding liquidity
|
||||
|
||||
@@ -42,39 +44,25 @@ When adding liquidity to a pool, you need to specify the amount of token-x and h
|
||||
|
||||
Once the liquidity is added, the pool will mint a pool token as a proof of proportional ownership of the pool liquidity. The number of the pool token being minted is proportional to the amount of liquidity you added compared to the existing liquidity at the pool.
|
||||
|
||||
The pool token is transferrable and may be used at other protocols (for example, as a collateral).
|
||||
The pool token is transferable and may be used at other protocols (for example, as a collateral).
|
||||
|
||||
### Removing liquidity
|
||||
|
||||
When removing liquidity from a pool, you need to specify the percentage of your pool tokens that you want to liquidate, i.e. between 0 and 1.
|
||||
|
||||
The percentage will be converted to the number of pool tokens to be burnt and the corresponding amount of token-x and token-y will be sent to you.
|
||||
|
||||
### Pool tokens
|
||||
|
||||
The pool token implements [SIP013](https://github.com/stacksgov/sips/pull/42). Each pool is mapped to a unique id (`pool-id`) with associated liquidity mapped to the balance under that id.
|
||||
|
||||
### Fee rebates
|
||||
|
||||
Trading Pool re-invests any fee rebates to the relevant pool liquidity, i.e. the invariant increases slightly after each transaction, similar to Uniswap V2.
|
||||
|
||||
## Trading
|
||||
|
||||
When a pool for a specific token pair is funded, it allows users to exchange those tokens, with a fee for each swap.
|
||||
Users can swap one token with another by calling `swap-x-for-y` or `swap-y-for-x`. As the names imply, `swap-x-for-y` swaps token-x into token-y and `swap-y-for-x` swaps token-y into token-x.
|
||||
|
||||
In both cases you can specify your slippage limit (`min-dy` and `min-dx`, respectively), so that the call fails if the swapped amount does not meet your target.
|
||||
|
||||
### Fee
|
||||
|
||||
Fee is deducted from each transaction on the "in" leg, i.e. token-x for `swap-x-for-y` and token-y for `swap-y-for-x`. Fee is set at the [pool creation](./#pool-creation) and may be updated through the governance.
|
||||
|
||||
Part of the fee may be [rebated](./#fee-rebates) to liquidity providers as a reward.
|
||||
Users can specify the slippage limit (the minimum amount of the desired target token they expect to receive: `min-dy` and `min-dx`, respectively), so that the call fails if the swapped amount does not meet your target.
|
||||
|
||||
### Swap helper and routing
|
||||
|
||||
It may not be reasonable to expect developers or users to remember the correct order of token pairs. Therefore we provide `swap-helper` function that helps choose between `swap-x-for-y` and `swap-y-for-x` and swaps token-x into token-y without users having to know the correct order.
|
||||
It may not be reasonable to expect developers or users to remember the correct order of token pairs. Therefore, we provide `swap-helper` function that helps choose between `swap-x-for-y` and `swap-y-for-x` and swaps `token-x` into `token-y` without users having to know the correct order.
|
||||
|
||||
It is also useful to be able to combine multiple swaps into one. For example, it will be useful to be able to swap xUSD into xBTC in one transaction, based on two pools of STX/xUSD and STX/xBTC, instead of having to perform two swaps. To that end, we provide three helper functions - `swap-helper-a`, `swap-helper-b` and `swap-helper-c` that facilitates "multi-hop" swaps of two/three/four pools, respectively.
|
||||
Sometimes, a direct swap isn't possible. In such cases, the system employs 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. It is intended for scenarios where a direct pool for Token-A/Token-C does not exist, but there are pools for Token-A/Token-B and Token-B/Token-C. To facilitate multi-hop swaps, we provide three helper routing functions: `swap-helper-a`, `swap-helper-b`, and `swap-helper-c`. These functions support multi-hop swaps involving two, three, and four pools, respectively.
|
||||
|
||||
## Helper functions
|
||||
|
||||
@@ -88,18 +76,66 @@ Instant oracle (`get-oracle-instant`) gives you the latest pool-implied price (i
|
||||
|
||||
Resilient oracle (`get-oracle-resilient`) on the other hand gives you a trade-weighted price that is therefore more resilient to potential manipulation but is less up to date. Resilient oracle may be more suitable for, for example, benchmarking to lending and borrowing.
|
||||
|
||||
### Out given in
|
||||
### Liquidity provision
|
||||
|
||||
Sometimes you may want to know the expected amount of token-y if you were to swap certain amount of token-x. Or you may want to know the expected amount of token-x for some token-y. Two read-only functions - `get-y-given-x` and `get-x-given-y` will do that for you.
|
||||
In certain cases, prior information is necessary to perform operations effectively. For example, to determine the slippage limit, you need to know the specific amounts of token-x and token-y required to mint a certain number of pool tokens. Additionally, it can be useful to know how many pool tokens can be minted or burnt if a specific amount of token-x and token-y are provided. The relevant helper functions for these operations are: `get-position-given-mint`, `get-position-given-burn` and `get-token-given-position`.
|
||||
|
||||
## Glossary
|
||||
|
||||
### Base Token
|
||||
The base token is the cryptocurrency token that a user currently possesses and submits during a swap transaction.
|
||||
|
||||
### Dx
|
||||
The amount of the token-x involved in liquidity and trading operations.
|
||||
|
||||
### Dy
|
||||
The amount of the token-y involved in liquidity and trading operations.
|
||||
|
||||
### Factor
|
||||
The factor is a multiplier (scaling factor) defined within a token pair pool, playing a critical role in determining the value of `dy` (amount of target token) given `dx` (amount of base token) and the pool balances of each token. Together with the token principals, the factor constitutes the pool identifier that is utilized to retrieve the pool details.
|
||||
|
||||
### Fee
|
||||
The cost associated with performing a swap or other operations within the platform. It is deducted from each transaction on the "in" leg (i.e., token-x for `swap-x-for-y` and token-y for `swap-y-for-x`).
|
||||
The fee to be calculated is set at the [pool creation](#pool-creation) and may be updated through the governance.
|
||||
Part of the fee may be [rebated](#fee-rebate) to liquidity providers as a reward.
|
||||
|
||||
### Fee Rate
|
||||
The percentage of the transaction amount that is taken as a fee during a swap or other operations.
|
||||
|
||||
### Fee Rebate
|
||||
The portion of the swap fee that is reinvested into the relevant pool's liquidity, causing the pool's invariant to increase slightly after each transaction. This mechanism is similar to that of Uniswap V2.
|
||||
|
||||
### In given out
|
||||
|
||||
If you want to know the amount of token-x you may need to provide to get a target amount of token-y (or vice versa), you can use `get-x-in-given-y-out` and `get-y-in-give-x-out`, respectively.
|
||||
|
||||
### In given price
|
||||
|
||||
If you are an arbitrageur, you may want to know the amount of token-x or token-y you need to provide to rebalance the pool-implied price to a target. In such a case, you can use `get-x-given-price` or `get-y-given-price`.
|
||||
|
||||
### Liquidity provision
|
||||
### Liquidity Positions
|
||||
When a user provides liquidity to a pool, they are said to be adding liquidity positions (using the `add-to-position` function). The reverse operation occurs when users withdraw their assets, thus reducing their positions (using the `reduce-position` function). Both operations involve the minting and burning of LP Tokens, respectively, to represent the user's share of the pool.
|
||||
|
||||
Lastly, it will be useful to know, for example, to determine the slippage limit, how many token-x and token-y must be provided to mint certain number of pool tokens, to burn certain number of pool tokens, or how many pool tokens may be minted or burnt if certain number of token-x and token-y are provided. The relevant helper functions are `get-position-given-mint`, `get-position-given-burn` and `get-token-given-position`.
|
||||
### Maximum Dy (`max-dy`)
|
||||
In the context of an add positions transaction, this amount specifies the maximum quantity of token-y that the user is willing to deposit. If the required amount exceeds this specified limit, the transaction will be reverted with the error `ERR-EXCEEDS-MAX-SLIPPAGE`.
|
||||
|
||||
### Minimum Dy (`min-dy`)
|
||||
In the context of a swap transaction, this amount defines the minimum quantity of the target token that the user expects to receive. If the resulting amount falls below this specified threshold, the transaction will be reverted with the error `ERR-EXCEEDS-MAX-SLIPPAGE`.
|
||||
|
||||
### Out given in
|
||||
Sometimes you may want to know the expected amount of token-y if you were to swap certain amount of token-x. Or you may want to know the expected amount of token-x for some token-y. Two read-only functions - `get-y-given-x` and `get-x-given-y` will do that for you.
|
||||
|
||||
### Pool token / LP Token
|
||||
Pool token, also known as "LP Token" (Liquidity Provider Token); issued to users who contribute assets to a liquidity pool, representing their share of the pool and potential earnings.
|
||||
The token contract is `token-amm-pool-v2-01` and it implements [SIP013](https://github.com/stacksgov/sips/pull/42).
|
||||
Each pool is mapped to a unique id (`pool-id`) with associated liquidity mapped to the balance under that id (`token-id`).
|
||||
|
||||
### Ratio
|
||||
The ratio represents the relationship between the amounts of a token pair involved in pool operations. Each pool has two predefined values, `max-in-ratio` and `max-out-ratio`, which set the maximum amounts that can be involved in swap operations.
|
||||
|
||||
### Slippage
|
||||
In the Automated Market Maker (AMM) Pool contract, slippage refers to the difference between the calculated amount of the target token and the configured maximum or minimum limit during a transaction. If no limit is set, the default limits are `u340282366920938463463374607431768211455` (the maximum value for `uint` type in Clarity language: `2**128 - 1`) for the maximum and `u0` for the minimum. These limits are enforced within the pool contract and are validated using the custom error `ERR-EXCEEDS-MAX-SLIPPAGE`.
|
||||
|
||||
### Swap Transaction
|
||||
A swap transaction refers to a type of operation whereby a user exchanges a given quantity of one cryptocurrency token for another. Within the context of the ALEX Trading Pool, swap transactions are executed using predefined token pairs existing within a pre-established liquidity pool.
|
||||
|
||||
### Target Token
|
||||
Also known as the "quoted" token, the target token is the cryptocurrency token that a user will receive as a result of a swap transaction.
|
||||
|
||||
@@ -1,7 +1,9 @@
|
||||
# Vault
|
||||
|
||||
Vault holds and manages the assets of all ALEX pools. The separation of pool and vault has many benefits including, among others, cheaper transaction costs for users and quicker learning curve for developers when building custom pools on ALEX.
|
||||
|
||||
{% hint style="info" %}
|
||||
If you are looking for technical details and implementation design please refer to the [Developers Protocol Contracts section](../developers/protocol-contracts#vault-amm-vault-v2-01.clar).
|
||||
{% endhint %}
|
||||
|
||||
## Flash Loan
|
||||
|
||||
Aggregating the assets of all ALEX pools into a single vault allows for the offering of Flash Loan, [popularized by AAVE](https://aave.com/flash-loans/).
|
||||
|
||||
Reference in New Issue
Block a user