From 634863e56fb17b29733fe201622fbbe5a463fb89 Mon Sep 17 00:00:00 2001 From: simsbluebox Date: Tue, 3 Sep 2024 17:44:27 -0300 Subject: [PATCH 1/8] new structure proposal: smart contracts, developers section (demo) --- SUMMARY.md | 14 ++-- developers/environments/README.md | 4 + .../amm-pool-mapping.md | 2 + developers/environments/mainnet.md | 5 ++ developers/{ => environments}/testnet.md | 0 .../token-list.md | 0 developers/smart-contracts/README.md | 84 ++++++++++++++++++- .../smart-contracts}/amm-pool-v2-01.clar.md | 2 +- .../amm-registry-v2-01.clar.md | 2 +- .../smart-contracts}/amm-vault-v2-01.clar.md | 2 +- .../trading-pool/README.md | 2 + trading-lending-and-borrowing/vault.md | 2 + 12 files changed, 107 insertions(+), 12 deletions(-) create mode 100644 developers/environments/README.md rename developers/{smart-contracts => environments}/amm-pool-mapping.md (98%) create mode 100644 developers/environments/mainnet.md rename developers/{ => environments}/testnet.md (100%) rename developers/{smart-contracts => environments}/token-list.md (100%) rename {trading-lending-and-borrowing/trading-pool => developers/smart-contracts}/amm-pool-v2-01.clar.md (99%) rename {trading-lending-and-borrowing/trading-pool => developers/smart-contracts}/amm-registry-v2-01.clar.md (99%) rename {trading-lending-and-borrowing/trading-pool => developers/smart-contracts}/amm-vault-v2-01.clar.md (95%) diff --git a/SUMMARY.md b/SUMMARY.md index f920e2d..53e2cbb 100644 --- a/SUMMARY.md +++ b/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,13 @@ ## 🎮 Developers -* [Testnet](developers/testnet.md) +* [Environments](developers/environments/README.md) + * [Mainnet](developers/environments/mainnet.md) + * [Token List](developers/environments/token-list.md) + * [Testnet](developers/environments/testnet.md) + * [AMM Pool Mapping](developers/environments/amm-pool-mapping.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) + * [amm-pool-v2-01.clar](developers/smart-contracts/amm-pool-v2-01.clar.md) + * [amm-registry-v2-01.clar](developers/smart-contracts/amm-registry-v2-01.clar.md) + * [amm-vault-v2-01.clar](developers/smart-contracts/amm-vault-v2-01.clar.md) * [REST API](developers/api-references.md) diff --git a/developers/environments/README.md b/developers/environments/README.md new file mode 100644 index 0000000..491076f --- /dev/null +++ b/developers/environments/README.md @@ -0,0 +1,4 @@ +# Environments + +* [Mainnet](mainnet.md) +* [Testnet](testnet.md) diff --git a/developers/smart-contracts/amm-pool-mapping.md b/developers/environments/amm-pool-mapping.md similarity index 98% rename from developers/smart-contracts/amm-pool-mapping.md rename to developers/environments/amm-pool-mapping.md index f0e71c5..be66d8c 100644 --- a/developers/smart-contracts/amm-pool-mapping.md +++ b/developers/environments/amm-pool-mapping.md @@ -1,3 +1,5 @@ +Demo note: this document seems to be outdated. We propose to remove it. + # 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 diff --git a/developers/environments/mainnet.md b/developers/environments/mainnet.md new file mode 100644 index 0000000..d2102c7 --- /dev/null +++ b/developers/environments/mainnet.md @@ -0,0 +1,5 @@ +# 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). + +
ContractAddress
DAOSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.executor-dao
VaultSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault
Reserve PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-reserve-pool
LaunchpadSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-launchpad-v1-1
LotterySP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-lottery
Trading PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1
Fixed Weight PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01
Simple Weight PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.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 TokenSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token
autoALEX TokenSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alex
Bridge EndpointSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.bridge-endpoint-v1-01
sUSDTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-susdt
diff --git a/developers/testnet.md b/developers/environments/testnet.md similarity index 100% rename from developers/testnet.md rename to developers/environments/testnet.md diff --git a/developers/smart-contracts/token-list.md b/developers/environments/token-list.md similarity index 100% rename from developers/smart-contracts/token-list.md rename to developers/environments/token-list.md diff --git a/developers/smart-contracts/README.md b/developers/smart-contracts/README.md index d2102c7..98600a2 100644 --- a/developers/smart-contracts/README.md +++ b/developers/smart-contracts/README.md @@ -1,5 +1,83 @@ -# Smart Contracts +Demo note: this bridge document will be reworked as an overall ALEXGO inventory (not only the trading pool contracts). -For the complete token list and the pool mapping, see [Token List](token-list.md) and [AMM Pool Mapping](amm-pool-mapping.md). +# ALEX DAO AMM Trading Pool -
ContractAddress
DAOSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.executor-dao
VaultSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault
Reserve PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-reserve-pool
LaunchpadSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-launchpad-v1-1
LotterySP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-lottery
Trading PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1
Fixed Weight PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01
Simple Weight PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.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 TokenSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token
autoALEX TokenSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alex
Bridge EndpointSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.bridge-endpoint-v1-01
sUSDTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-susdt
+This section provides an overview of the ALEX on-chain Trading Pool and its Automated Market Making (AMM) protocol. The AMM Trading Pool protocol consists of a set of smart contracts that facilitate trading operations within the ALEX DeFi ecosystem. Below, we list these contracts, explain how they interact with each other, and describe some common technical aspects. + +## Contracts map + +![](https://kroki.io/plantuml/svg/eNptjs0KgzAQhO8-xeK1pH9nEfoAQg8ee1njNgRiIrtRkNJ3b1SKB73OzDczTDqiN44gf1QV1Iyt9QaeIbgcPhlvdtGU2HWqT44a7-p6O2uHXFya8uVDT4zRBi85oMCcOUCZjJXI0w5PtCSHvJ4W_h886BhxcHFX8CZKkBCPJHACIT0wtalKSOL6aQGzbzZ_A1VuG6uQlDXxA1KNXfM=) + +### 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: 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 + +Each of the three contracts includes 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`. + +### Imported 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 all three Trading Pool contracts. 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`| diff --git a/trading-lending-and-borrowing/trading-pool/amm-pool-v2-01.clar.md b/developers/smart-contracts/amm-pool-v2-01.clar.md similarity index 99% rename from trading-lending-and-borrowing/trading-pool/amm-pool-v2-01.clar.md rename to developers/smart-contracts/amm-pool-v2-01.clar.md index 3db1a97..db3d503 100644 --- a/trading-lending-and-borrowing/trading-pool/amm-pool-v2-01.clar.md +++ b/developers/smart-contracts/amm-pool-v2-01.clar.md @@ -2,7 +2,7 @@ #### 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 diff --git a/trading-lending-and-borrowing/trading-pool/amm-registry-v2-01.clar.md b/developers/smart-contracts/amm-registry-v2-01.clar.md similarity index 99% rename from trading-lending-and-borrowing/trading-pool/amm-registry-v2-01.clar.md rename to developers/smart-contracts/amm-registry-v2-01.clar.md index 04504ac..31d0ef8 100644 --- a/trading-lending-and-borrowing/trading-pool/amm-registry-v2-01.clar.md +++ b/developers/smart-contracts/amm-registry-v2-01.clar.md @@ -2,7 +2,7 @@ #### 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. diff --git a/trading-lending-and-borrowing/trading-pool/amm-vault-v2-01.clar.md b/developers/smart-contracts/amm-vault-v2-01.clar.md similarity index 95% rename from trading-lending-and-borrowing/trading-pool/amm-vault-v2-01.clar.md rename to developers/smart-contracts/amm-vault-v2-01.clar.md index 711b2ee..21c07b6 100644 --- a/trading-lending-and-borrowing/trading-pool/amm-vault-v2-01.clar.md +++ b/developers/smart-contracts/amm-vault-v2-01.clar.md @@ -2,7 +2,7 @@ #### 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 diff --git a/trading-lending-and-borrowing/trading-pool/README.md b/trading-lending-and-borrowing/trading-pool/README.md index 40003fd..ad77550 100644 --- a/trading-lending-and-borrowing/trading-pool/README.md +++ b/trading-lending-and-borrowing/trading-pool/README.md @@ -1,3 +1,5 @@ +Demo note: this document will be adjusted with some updated operations context and an enriched glossary. A link to developers contract section will be included. + # Trading Pool ## Introduction diff --git a/trading-lending-and-borrowing/vault.md b/trading-lending-and-borrowing/vault.md index a00056a..ce7907a 100644 --- a/trading-lending-and-borrowing/vault.md +++ b/trading-lending-and-borrowing/vault.md @@ -1,3 +1,5 @@ +Demo note: A link to developers contract section will be included. + # 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. From f8405c6bd06487420cec268bc74182f648c2b9fe Mon Sep 17 00:00:00 2001 From: simsbluebox Date: Fri, 6 Sep 2024 18:30:43 -0300 Subject: [PATCH 2/8] Trading Pool contracts + Vault new structure (Overview + Developers section) --- SUMMARY.md | 6 +- developers/environments/amm-pool-mapping.md | 205 ------------------ developers/environments/mainnet.md | 16 +- developers/environments/token-list.md | 13 -- developers/smart-contracts/README.md | 27 ++- .../smart-contracts/amm-pool-v2-01.clar.md | 21 +- .../trading-pool/README.md | 127 +++++++---- trading-lending-and-borrowing/vault.md | 5 +- 8 files changed, 126 insertions(+), 294 deletions(-) delete mode 100644 developers/environments/amm-pool-mapping.md delete mode 100644 developers/environments/token-list.md diff --git a/SUMMARY.md b/SUMMARY.md index 53e2cbb..bdb9380 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -50,12 +50,10 @@ ## 🎮 Developers -* [Environments](developers/environments/README.md) +* [Networks](developers/environments/README.md) * [Mainnet](developers/environments/mainnet.md) - * [Token List](developers/environments/token-list.md) * [Testnet](developers/environments/testnet.md) - * [AMM Pool Mapping](developers/environments/amm-pool-mapping.md) -* [Smart Contracts](developers/smart-contracts/README.md) +* [Protocol Contracts](developers/smart-contracts/README.md) * [amm-pool-v2-01.clar](developers/smart-contracts/amm-pool-v2-01.clar.md) * [amm-registry-v2-01.clar](developers/smart-contracts/amm-registry-v2-01.clar.md) * [amm-vault-v2-01.clar](developers/smart-contracts/amm-vault-v2-01.clar.md) diff --git a/developers/environments/amm-pool-mapping.md b/developers/environments/amm-pool-mapping.md deleted file mode 100644 index be66d8c..0000000 --- a/developers/environments/amm-pool-mapping.md +++ /dev/null @@ -1,205 +0,0 @@ -Demo note: this document seems to be outdated. We propose to remove it. - -# 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). $$0ContractAddressDAOSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.executor-daoVaultSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vaultReserve PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-reserve-poolLaunchpadSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-launchpad-v1-1LotterySP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-lotteryTrading PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1Fixed Weight PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01Simple Weight PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.simple-weight-pool-alexSwap Router(to route between Fixed Weight Pool and Simple Weight Pool)
SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-v1-03Swap Bridge (to route between Trading Pool and Fixed Weight Pool / Simple Weight Pool)
SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-bridgedALEX TokenSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-tokenautoALEX TokenSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alexBridge EndpointSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.bridge-endpoint-v1-01sUSDTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.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. + +
TokenAddress
STXSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2
ALEXSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex
xBTCSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wxbtc
sUSDTSP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-susdt
xUSDSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wxusd
autoALEXSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.auto-alex-v3
USDASP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wusda
DIKOSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wdiko
MIASP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wmia
NYCSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wnyc
BANANASP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wban
SLIMESP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wslm
WELSHSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wcorgi
VIBESSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wvibes
+ +### BRC20 Tokens + +BRC20 tokens on ALEX represent those BRC20 tokens that are pegged in from Bitcoin. + +
TokenAddress
$B20SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-db20
MAXISP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-maxi
SHNTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-shnt
PIZASP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-piza
LONGSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-long
INSCSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-insc
MAJOSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-majo
DEXMSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-dexm
ATMTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-aiptp
CVLTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-cvlt
LBOWSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-lbow
SBTCSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-sbtc
OXBTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-oxbt
â‚¿SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-spacesignb
ORDSSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-ords
NYTOSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-nyto
BENGSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-beng
TRACSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-trac
SATSSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-sats
TAROSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-taro
10MMSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-10mm
PEPESP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-pepe
VMPXSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-vmpx
@LFGSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-atlfg
ORDISP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-ordi
$BITSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-dbit
MXRCSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-mxrc
IGLISP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-igli
OHMSSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-ohms
JAKESP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-jake
MEMESP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-meme
NALSSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-nals
XINGSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-xing
BANKSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-bank
PASSSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-pass
WZRDSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-wzrd
MOONSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-moon
DRACSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-drac
LOVESP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-love
ZBITSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-zbit
diff --git a/developers/environments/token-list.md b/developers/environments/token-list.md deleted file mode 100644 index f086dbb..0000000 --- a/developers/environments/token-list.md +++ /dev/null @@ -1,13 +0,0 @@ -# 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. - -
TokenAddress
STXSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2
ALEXSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex
xBTCSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wxbtc
sUSDTSP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-susdt
xUSDSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wxusd
autoALEXSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.auto-alex-v3
USDASP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wusda
DIKOSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wdiko
MIASP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wmia
NYCSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wnyc
BANANASP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wban
SLIMESP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wslm
WELSHSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wcorgi
VIBESSP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wvibes
- -## BRC20 Tokens - -BRC20 tokens on ALEX represent those BRC20 tokens that are pegged in from Bitcoin. - -
TokenAddress
$B20SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-db20
MAXISP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-maxi
SHNTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-shnt
PIZASP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-piza
LONGSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-long
INSCSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-insc
MAJOSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-majo
DEXMSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-dexm
ATMTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-aiptp
CVLTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-cvlt
LBOWSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-lbow
SBTCSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-sbtc
OXBTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-oxbt
â‚¿SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-spacesignb
ORDSSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-ords
NYTOSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-nyto
BENGSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-beng
TRACSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-trac
SATSSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-sats
TAROSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-taro
10MMSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-10mm
PEPESP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-pepe
VMPXSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-vmpx
@LFGSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-atlfg
ORDISP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-ordi
$BITSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-dbit
MXRCSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-mxrc
IGLISP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-igli
OHMSSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-ohms
JAKESP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-jake
MEMESP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-meme
NALSSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-nals
XINGSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-xing
BANKSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-bank
PASSSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-pass
WZRDSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-wzrd
MOONSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-moon
DRACSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-drac
LOVESP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-love
ZBITSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.brc20-zbit
diff --git a/developers/smart-contracts/README.md b/developers/smart-contracts/README.md index 98600a2..399d035 100644 --- a/developers/smart-contracts/README.md +++ b/developers/smart-contracts/README.md @@ -1,29 +1,34 @@ -Demo note: this bridge document will be reworked as an overall ALEXGO inventory (not only the trading pool contracts). +# ALEX DAO: Comprehensive Technical Design Overview -# ALEX DAO AMM Trading Pool +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. -This section provides an overview of the ALEX on-chain Trading Pool and its Automated Market Making (AMM) protocol. The AMM Trading Pool protocol consists of a set of smart contracts that facilitate trading operations within the ALEX DeFi ecosystem. Below, we list these contracts, explain how they interact with each other, and describe some common technical aspects. +## AMM Trading Pool -## Contracts map +This section provides an overview of the ALEX on-chain Trading Pool and its Automated Market Making (AMM) protocol. -![](https://kroki.io/plantuml/svg/eNptjs0KgzAQhO8-xeK1pH9nEfoAQg8ee1njNgRiIrtRkNJ3b1SKB73OzDczTDqiN44gf1QV1Iyt9QaeIbgcPhlvdtGU2HWqT44a7-p6O2uHXFya8uVDT4zRBi85oMCcOUCZjJXI0w5PtCSHvJ4W_h886BhxcHFX8CZKkBCPJHACIT0wtalKSOL6aQGzbzZ_A1VuG6uQlDXxA1KNXfM=) +### Contracts map -### Pool: amm-pool-v2-01.clar +![](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](./amm-pool-v2-01.clar.md) -### Registry: amm-registry-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](./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. +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) @@ -35,7 +40,7 @@ The smart contracts discussed in this section include features to control admini #### Admin access control -Each of the three contracts includes 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. +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 @@ -43,7 +48,7 @@ The `amm-pool-v2-01` and `amm-vault-v2-01` contracts have functionalities to set #### 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`. +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`. ### Imported Traits @@ -51,7 +56,7 @@ In Clarity language, a trait defines a public interface to which smart contracts #### sip-010-trait -This is a customized version of the Stacks' Standard Trait Definition for Fungible Tokens and is used by all three Trading Pool contracts. 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. +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) diff --git a/developers/smart-contracts/amm-pool-v2-01.clar.md b/developers/smart-contracts/amm-pool-v2-01.clar.md index db3d503..461f02f 100644 --- a/developers/smart-contracts/amm-pool-v2-01.clar.md +++ b/developers/smart-contracts/amm-pool-v2-01.clar.md @@ -174,16 +174,17 @@ All getter and setter functions in the contract handle pool information, delegat 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 diff --git a/trading-lending-and-borrowing/trading-pool/README.md b/trading-lending-and-borrowing/trading-pool/README.md index ad77550..f653bed 100644 --- a/trading-lending-and-borrowing/trading-pool/README.md +++ b/trading-lending-and-borrowing/trading-pool/README.md @@ -1,22 +1,18 @@ -Demo note: this document will be adjusted with some updated operations context and an enriched glossary. A link to developers contract section will be included. - # Trading Pool ## 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). $$0Caution on fixed notation +Regarding its implementation, the Trading Pool protocol consists of a set of smart contracts 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. - -For example, 1 should be passed as 10,000,000 (= 1e8), i.e. 1.00000000. +For more of the theory and fundaments behind the Alex AMM protocol refer to the [ALEX AMM Whitepaper](../../whitepaper/automated-market-making-of-alex/). ## Pool creation @@ -28,15 +24,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/smart-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 @@ -44,39 +35,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 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. The current version of the protocol supports chains of up to 4 pools. ## Helper functions @@ -90,18 +67,72 @@ 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 - -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 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 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`. + +## Glossary + +### 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. + +### Base Token +The base token is the cryptocurrency token that a user currently possesses and submits during a swap transaction. + +### 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. + +### 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. + +### Dx +The amount of the base token that a user inputs into a swap transaction. + +### Dy +The amount of the target token that a user receives from a swap transaction. + +### 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`. + +### 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. + +### Pool tokens +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`). + +### 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`. + +### 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-rebates) 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 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. + +### Ratio +In each pool, there are two predefined values that are used to calculate the relationship between the amounts of tokens involved in a swap operation. These ratios determine the maximum amount that can be deposited or exchanged within the pool. + +### 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. + +### 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`. + +### 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`. + +## 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. + +## Implementation +Refer to the Trading Pool contracts technical [documentation](../../developers/smart-contracts/README.md#alex-dao-amm-trading-pool). diff --git a/trading-lending-and-borrowing/vault.md b/trading-lending-and-borrowing/vault.md index ce7907a..3459283 100644 --- a/trading-lending-and-borrowing/vault.md +++ b/trading-lending-and-borrowing/vault.md @@ -1,5 +1,3 @@ -Demo note: A link to developers contract section will be included. - # 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. @@ -11,3 +9,6 @@ Aggregating the assets of all ALEX pools into a single vault allows for the offe Flash Loans are uncollateralized loans that must be repaid (plus interest) in the same transaction as it is borrowed. Since everything done with the loan must be completed in a single transaction, there are codified guarantees that make it impossible for borrowers to run away with the tokens. Flash Loan allows arbitrageurs to take advantages of any price discrepancies in two or more pools without the needs for holding any input tokens. + +# Implementation +Refer to the Vault contract technical [documentation](../developers/smart-contracts/README.md#vault-amm-vault-v2-01clar). From 28ba155edec73f334854153850ad8886437eb857 Mon Sep 17 00:00:00 2001 From: simsbluebox Date: Mon, 9 Sep 2024 10:32:51 -0300 Subject: [PATCH 3/8] Minor fix: folder names --- SUMMARY.md | 14 +++++++------- developers/{environments => networks}/README.md | 0 developers/{environments => networks}/mainnet.md | 0 developers/{environments => networks}/testnet.md | 0 .../README.md | 0 .../amm-pool-v2-01.clar.md | 0 .../amm-registry-v2-01.clar.md | 0 .../amm-vault-v2-01.clar.md | 0 .../trading-pool/README.md | 4 ++-- trading-lending-and-borrowing/vault.md | 2 +- 10 files changed, 10 insertions(+), 10 deletions(-) rename developers/{environments => networks}/README.md (100%) rename developers/{environments => networks}/mainnet.md (100%) rename developers/{environments => networks}/testnet.md (100%) rename developers/{smart-contracts => protocol-contracts}/README.md (100%) rename developers/{smart-contracts => protocol-contracts}/amm-pool-v2-01.clar.md (100%) rename developers/{smart-contracts => protocol-contracts}/amm-registry-v2-01.clar.md (100%) rename developers/{smart-contracts => protocol-contracts}/amm-vault-v2-01.clar.md (100%) diff --git a/SUMMARY.md b/SUMMARY.md index bdb9380..5e72cd8 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -50,11 +50,11 @@ ## 🎮 Developers -* [Networks](developers/environments/README.md) - * [Mainnet](developers/environments/mainnet.md) - * [Testnet](developers/environments/testnet.md) -* [Protocol Contracts](developers/smart-contracts/README.md) - * [amm-pool-v2-01.clar](developers/smart-contracts/amm-pool-v2-01.clar.md) - * [amm-registry-v2-01.clar](developers/smart-contracts/amm-registry-v2-01.clar.md) - * [amm-vault-v2-01.clar](developers/smart-contracts/amm-vault-v2-01.clar.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) diff --git a/developers/environments/README.md b/developers/networks/README.md similarity index 100% rename from developers/environments/README.md rename to developers/networks/README.md diff --git a/developers/environments/mainnet.md b/developers/networks/mainnet.md similarity index 100% rename from developers/environments/mainnet.md rename to developers/networks/mainnet.md diff --git a/developers/environments/testnet.md b/developers/networks/testnet.md similarity index 100% rename from developers/environments/testnet.md rename to developers/networks/testnet.md diff --git a/developers/smart-contracts/README.md b/developers/protocol-contracts/README.md similarity index 100% rename from developers/smart-contracts/README.md rename to developers/protocol-contracts/README.md diff --git a/developers/smart-contracts/amm-pool-v2-01.clar.md b/developers/protocol-contracts/amm-pool-v2-01.clar.md similarity index 100% rename from developers/smart-contracts/amm-pool-v2-01.clar.md rename to developers/protocol-contracts/amm-pool-v2-01.clar.md diff --git a/developers/smart-contracts/amm-registry-v2-01.clar.md b/developers/protocol-contracts/amm-registry-v2-01.clar.md similarity index 100% rename from developers/smart-contracts/amm-registry-v2-01.clar.md rename to developers/protocol-contracts/amm-registry-v2-01.clar.md diff --git a/developers/smart-contracts/amm-vault-v2-01.clar.md b/developers/protocol-contracts/amm-vault-v2-01.clar.md similarity index 100% rename from developers/smart-contracts/amm-vault-v2-01.clar.md rename to developers/protocol-contracts/amm-vault-v2-01.clar.md diff --git a/trading-lending-and-borrowing/trading-pool/README.md b/trading-lending-and-borrowing/trading-pool/README.md index f653bed..98366a3 100644 --- a/trading-lending-and-borrowing/trading-pool/README.md +++ b/trading-lending-and-borrowing/trading-pool/README.md @@ -24,7 +24,7 @@ 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`. -[Refer to the comprehensive list of Pool governed setters](./../../developers/smart-contracts/amm-pool-v2-01.clar.md#setters). +[Refer to the comprehensive list of Pool governed setters](../../developers/protocol-contracts/amm-pool-v2-01.clar.md#setters). ## 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. @@ -135,4 +135,4 @@ In the Automated Market Maker (AMM) Pool contract, slippage refers to the differ 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. ## Implementation -Refer to the Trading Pool contracts technical [documentation](../../developers/smart-contracts/README.md#alex-dao-amm-trading-pool). +Refer to the Trading Pool contracts technical [documentation](../../developers/protocol-contracts/README.md#alex-dao-amm-trading-pool). diff --git a/trading-lending-and-borrowing/vault.md b/trading-lending-and-borrowing/vault.md index 3459283..2268e03 100644 --- a/trading-lending-and-borrowing/vault.md +++ b/trading-lending-and-borrowing/vault.md @@ -11,4 +11,4 @@ Flash Loans are uncollateralized loans that must be repaid (plus interest) in th Flash Loan allows arbitrageurs to take advantages of any price discrepancies in two or more pools without the needs for holding any input tokens. # Implementation -Refer to the Vault contract technical [documentation](../developers/smart-contracts/README.md#vault-amm-vault-v2-01clar). +Refer to the Vault contract technical [documentation](../developers/protocol-contracts/README.md#vault-amm-vault-v2-01clar). From 76c4bb0f8fa20619c0f4ca7a1daf6799a0e271d7 Mon Sep 17 00:00:00 2001 From: simsbluebox Date: Mon, 9 Sep 2024 13:34:13 -0300 Subject: [PATCH 4/8] Pair review by @sofinico --- developers/networks/README.md | 4 +- developers/protocol-contracts/README.md | 6 ++- .../protocol-contracts/amm-pool-v2-01.clar.md | 2 +- .../amm-registry-v2-01.clar.md | 2 +- .../amm-vault-v2-01.clar.md | 2 +- .../trading-pool/README.md | 45 ++++++++++--------- trading-lending-and-borrowing/vault.md | 9 ++-- 7 files changed, 38 insertions(+), 32 deletions(-) diff --git a/developers/networks/README.md b/developers/networks/README.md index 491076f..8ee49cf 100644 --- a/developers/networks/README.md +++ b/developers/networks/README.md @@ -1,4 +1,6 @@ -# Environments +--- +description: Stacks networks environments and deployed addresses +--- * [Mainnet](mainnet.md) * [Testnet](testnet.md) diff --git a/developers/protocol-contracts/README.md b/developers/protocol-contracts/README.md index 399d035..9cfcfa9 100644 --- a/developers/protocol-contracts/README.md +++ b/developers/protocol-contracts/README.md @@ -1,4 +1,6 @@ -# ALEX DAO: Comprehensive Technical Design Overview +--- +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. @@ -50,7 +52,7 @@ The `amm-pool-v2-01` and `amm-vault-v2-01` contracts have functionalities to set 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`. -### Imported Traits +### 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. diff --git a/developers/protocol-contracts/amm-pool-v2-01.clar.md b/developers/protocol-contracts/amm-pool-v2-01.clar.md index 461f02f..a0f6d27 100644 --- a/developers/protocol-contracts/amm-pool-v2-01.clar.md +++ b/developers/protocol-contracts/amm-pool-v2-01.clar.md @@ -1,6 +1,6 @@ # 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). diff --git a/developers/protocol-contracts/amm-registry-v2-01.clar.md b/developers/protocol-contracts/amm-registry-v2-01.clar.md index 31d0ef8..e4510b1 100644 --- a/developers/protocol-contracts/amm-registry-v2-01.clar.md +++ b/developers/protocol-contracts/amm-registry-v2-01.clar.md @@ -1,6 +1,6 @@ # 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). diff --git a/developers/protocol-contracts/amm-vault-v2-01.clar.md b/developers/protocol-contracts/amm-vault-v2-01.clar.md index 21c07b6..8294d4c 100644 --- a/developers/protocol-contracts/amm-vault-v2-01.clar.md +++ b/developers/protocol-contracts/amm-vault-v2-01.clar.md @@ -1,6 +1,6 @@ # 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. In addition to supporting Trading Pool operations, the vault contract also offers a flash-loan feature for registered tokens, available to approved users. diff --git a/trading-lending-and-borrowing/trading-pool/README.md b/trading-lending-and-borrowing/trading-pool/README.md index 98366a3..5e346ea 100644 --- a/trading-lending-and-borrowing/trading-pool/README.md +++ b/trading-lending-and-borrowing/trading-pool/README.md @@ -10,13 +10,22 @@ Trading Pool implements Generalized Mean Equation and, with a suitable parameter 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). $$0Caution 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. - -## Implementation -Refer to the Trading Pool contracts technical [documentation](../../developers/protocol-contracts/README.md#alex-dao-amm-trading-pool). diff --git a/trading-lending-and-borrowing/vault.md b/trading-lending-and-borrowing/vault.md index 2268e03..d22953b 100644 --- a/trading-lending-and-borrowing/vault.md +++ b/trading-lending-and-borrowing/vault.md @@ -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/README.md#vault-amm-vault-v2-01clar). +{% 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/). @@ -9,6 +11,3 @@ Aggregating the assets of all ALEX pools into a single vault allows for the offe Flash Loans are uncollateralized loans that must be repaid (plus interest) in the same transaction as it is borrowed. Since everything done with the loan must be completed in a single transaction, there are codified guarantees that make it impossible for borrowers to run away with the tokens. Flash Loan allows arbitrageurs to take advantages of any price discrepancies in two or more pools without the needs for holding any input tokens. - -# Implementation -Refer to the Vault contract technical [documentation](../developers/protocol-contracts/README.md#vault-amm-vault-v2-01clar). From bd8e6265a78d7661196952f3e24aa76b7a37f75d Mon Sep 17 00:00:00 2001 From: simsbluebox Date: Mon, 9 Sep 2024 15:40:11 -0300 Subject: [PATCH 5/8] Minor heading fix --- developers/protocol-contracts/README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/developers/protocol-contracts/README.md b/developers/protocol-contracts/README.md index 9cfcfa9..9adce98 100644 --- a/developers/protocol-contracts/README.md +++ b/developers/protocol-contracts/README.md @@ -8,17 +8,15 @@ This document provides a detailed overview of the smart contracts that enable AL This section provides an overview of the ALEX on-chain Trading Pool and its Automated Market Making (AMM) protocol. -### Contracts map - ![](https://kroki.io/plantuml/svg/eNptjssKgzAQRfd-xeC2pK-1CP0AoQuX3YxxGgIxkZkoSOm_NyrFhW7vuefOMOmI3jiC_FFVUDO21ht4huBy-GS84aIpsetUn4ga7-p6O2uHXFya8uVDT4zRBi85oMDcOVCZjJXI005PtiRCXk-L_y9m34OVEQcXdxNvoqQJ8UgCJxDSA1ObxoQkrl8tYjb_BqrcbqxBSlb-A0UYXfM=) -#### Pool: amm-pool-v2-01.clar +### 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 +### 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. From 5e498077329701eef8f230af7445a453c9edc90f Mon Sep 17 00:00:00 2001 From: simsbluebox Date: Mon, 9 Sep 2024 15:55:45 -0300 Subject: [PATCH 6/8] Minor link fix --- trading-lending-and-borrowing/trading-pool/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/trading-lending-and-borrowing/trading-pool/README.md b/trading-lending-and-borrowing/trading-pool/README.md index 5e346ea..5b847d5 100644 --- a/trading-lending-and-borrowing/trading-pool/README.md +++ b/trading-lending-and-borrowing/trading-pool/README.md @@ -117,7 +117,7 @@ In the context of an add positions transaction, this amount specifies the maximu ### 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-rebates) to liquidity providers as a reward. +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. From cce17e2efb180bf1127b42c324d4996101fc2589 Mon Sep 17 00:00:00 2001 From: sofinico Date: Tue, 10 Sep 2024 01:41:16 +0200 Subject: [PATCH 7/8] Add URL redirects --- .gitbook.yaml | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .gitbook.yaml diff --git a/.gitbook.yaml b/.gitbook.yaml new file mode 100644 index 0000000..a46c5db --- /dev/null +++ b/.gitbook.yaml @@ -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 \ No newline at end of file From 117f0c7e4dcec5524ac70c29620fa08b464d1c03 Mon Sep 17 00:00:00 2001 From: simsbluebox Date: Tue, 10 Sep 2024 17:54:55 -0300 Subject: [PATCH 8/8] Reviews by @tenuki --- developers/networks/mainnet.md | 2 +- developers/networks/testnet.md | 2 +- .../protocol-contracts/amm-pool-v2-01.clar.md | 2 +- .../trading-pool/README.md | 56 +++++++++---------- trading-lending-and-borrowing/vault.md | 2 +- 5 files changed, 32 insertions(+), 32 deletions(-) diff --git a/developers/networks/mainnet.md b/developers/networks/mainnet.md index 2c95865..21a7d21 100644 --- a/developers/networks/mainnet.md +++ b/developers/networks/mainnet.md @@ -2,7 +2,7 @@ ## Deployed Protocol Contracts -
ContractAddress
DAOSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.executor-dao
VaultSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault
Reserve PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-reserve-pool
LaunchpadSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-launchpad-v1-1
LotterySP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-lottery
Trading PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1
Fixed Weight PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01
Simple Weight PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.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 TokenSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token
autoALEX TokenSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alex
Bridge EndpointSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.bridge-endpoint-v1-01
sUSDTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-susdt
+
ContractAddress
DAOSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.executor-dao
VaultSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault
Reserve PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-reserve-pool
LaunchpadSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-launchpad-v1-1
LotterySP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-lottery
Trading PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1
Fixed Weight PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01
Simple Weight PoolSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.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 TokenSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token
autoALEX TokenSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alex
Bridge EndpointSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.bridge-endpoint-v1-01
sUSDTSP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-susdt
## Token List diff --git a/developers/networks/testnet.md b/developers/networks/testnet.md index 1293367..5f90d43 100644 --- a/developers/networks/testnet.md +++ b/developers/networks/testnet.md @@ -12,5 +12,5 @@ For any questions / follow-ups, please use our Discord channel ([https://discord ## Smart Contracts -
ContractAddress
VaultST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.alex-vault
Reserve PoolST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.alex-reserve-pool
Fixed Weight PoolST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.fixed-weight-pool-v1-02
Simple Weight PoolST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.simple-weight-pool-alex
Swap HelperST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.swap-helper-v1-03
ALEX TokenST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.age000-governance-token
autoALEX TokenST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.auto-alex
STX (wrapped)ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wstx
xBTCST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wbtc
xUSDST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wxusd
USDAST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wusda
+
ContractAddress
VaultST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.alex-vault
Reserve PoolST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.alex-reserve-pool
Fixed Weight PoolST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.fixed-weight-pool-v1-02
Simple Weight PoolST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.simple-weight-pool-alex
Swap HelperST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.swap-helper-v1-03
ALEX TokenST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.age000-governance-token
autoALEX TokenST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.auto-alex
STX (wrapped)ST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wstx
xBTCST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wbtc
xUSDST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wxusd
USDAST29E61D211DD0HB0S0JSKZ05X0DSAJS5G5QSTXDX.token-wusda
diff --git a/developers/protocol-contracts/amm-pool-v2-01.clar.md b/developers/protocol-contracts/amm-pool-v2-01.clar.md index a0f6d27..97debc0 100644 --- a/developers/protocol-contracts/amm-pool-v2-01.clar.md +++ b/developers/protocol-contracts/amm-pool-v2-01.clar.md @@ -168,7 +168,7 @@ 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 diff --git a/trading-lending-and-borrowing/trading-pool/README.md b/trading-lending-and-borrowing/trading-pool/README.md index 5b847d5..90b8181 100644 --- a/trading-lending-and-borrowing/trading-pool/README.md +++ b/trading-lending-and-borrowing/trading-pool/README.md @@ -82,37 +82,17 @@ In certain cases, prior information is necessary to perform operations effective ## Glossary -### 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. - ### Base Token The base token is the cryptocurrency token that a user currently possesses and submits during a swap transaction. -### 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. - -### 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. - ### 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. -### 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`. - -### 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. - -### 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`). - -### 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`. +### 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`). @@ -125,17 +105,37 @@ The percentage of the transaction amount that is taken as a fee during a swap or ### 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. -### 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. - -### 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. - ### 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 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. + +### 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. diff --git a/trading-lending-and-borrowing/vault.md b/trading-lending-and-borrowing/vault.md index d22953b..f56a8ac 100644 --- a/trading-lending-and-borrowing/vault.md +++ b/trading-lending-and-borrowing/vault.md @@ -1,7 +1,7 @@ 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/README.md#vault-amm-vault-v2-01clar). +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