mirror of
https://github.com/alexgo-io/alex-v1-docs.git
synced 2026-01-12 14:33:49 +08:00
+pre-dave changes
This commit is contained in:
david weil
300
trading-lending-and-borrowing/contracts/amm-pool-v2-01.clar.md
Normal file
300
trading-lending-and-borrowing/contracts/amm-pool-v2-01.clar.md
Normal file
@@ -0,0 +1,300 @@
|
||||
### Contract: *amm-pool-v2-01.clar*.
|
||||
|
||||
###### **Location**: *`./alex-dao-2/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 and amm-vault-v2-01.clar. [LINK XXX XXX XXX]
|
||||
|
||||
**Storage**:
|
||||
DATA (data-var):
|
||||
* `paused` (bool)
|
||||
This data variable acts as a flag to determine and control the operational status of the contract within the system. When set to 'paused,' it will block all position and swap transactions.
|
||||
|
||||
CONSTANTS:
|
||||
* `x_a_list_no_deci`
|
||||
* `x_a_list`
|
||||
|
||||
Mathematical constants:
|
||||
These symbolic constants are employed to define and restrict decimal precision and boundary limits in calculations within the system.
|
||||
* `ONE_8`
|
||||
* `UNSIGNED_ONE_8`
|
||||
* `MAX_NATURAL_EXPONENT`
|
||||
* `MIN_NATURAL_EXPONENT`
|
||||
* `MILD_EXPONENT_BOUND`
|
||||
* `MAX_POW_RELATIVE_ERROR`
|
||||
|
||||
**Contract calls (interactions):**
|
||||
* `executor-dao`
|
||||
Calls are made to verify whether a certain contract-caller is designated as an extension.
|
||||
|
||||
* `amm-registry-v2-01`
|
||||
This contract is called to manage and configure the data and settings of AMM pools. In this document, it is referred to as the 'registry'.
|
||||
|
||||
* `amm-vault-v2-01`
|
||||
This contract is called to execute token transfers during the reduction of positions and swapping operations. Additionally, calls are made to add fees charged to the reserves.
|
||||
|
||||
* `token-amm-pool-v2-01`
|
||||
In operations to add or reduce positions, interactions with this contract involve minting and burning of LP (Liquidity Provider) Tokens and retrieving their balance amounts. In this document, it is referred to as the 'LP Token'.
|
||||
|
||||
* Tokens (`token-x-trait`, `token-y-trait`, `token-z-trait`, etc.)
|
||||
During the process of adding positions and executing swaps, a trait is used to invoke the relevant tokens to perform the necessary transfers involved in the transaction. This trait is a customized version of the Stacks' standard definition for Fungible Tokens (`sip-010`), with support for 8-digit fixed notation.
|
||||
|
||||
**Features:**
|
||||
POOL features:
|
||||
1) `create-pool`
|
||||
This function establishes a liquidity pool for a specified token pair (token-x/token-y). It starts by verifying that the `tx-sender` is not blacklisted through the `is-blocklisted-or-default` function [LINK XXX XXX XXX)]. Following this validation, the function delegates the pool creation task to the registry.
|
||||
Upon successful creation, the function automatically invokes `add-to-position` function [LINK XXX XXX XXX)] to initialize token positions for the specified pair within the new pool.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-x-trait <ft-trait>)
|
||||
(token-y-trait <ft-trait>)
|
||||
(factor uint)
|
||||
(pool-owner principal)
|
||||
(dx uint)
|
||||
(dy uint)
|
||||
```
|
||||
TBD: LINKS to NON-TECH DOC FOR BUSINESS CONCEPTS (factor, dx, dy, etc)
|
||||
|
||||
2) `add-to-position`
|
||||
The `add-to-position` function adds asset positions to an existing liquidity pool by transferring the respective tokens from the `tx-sender` to the system vault contract. It updates the pool details in the registry contract and mints LP tokens to the sender, representing their share of the pool and potential earnings. This minting operation is tracked using a unique pool identifier (POOL_ID).
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-x-trait <ft-trait>)
|
||||
(token-y-trait <ft-trait>)
|
||||
(factor uint)
|
||||
(dx uint)
|
||||
(max-dy (optional uint))
|
||||
```
|
||||
TBD: LINKS to NON-TECH DOC FOR BUSINESS CONCEPTS (max-dy, slippage, etc)
|
||||
|
||||
3) `reduce-position`
|
||||
This function performs the inverse operation of `add-to-position` by allowing users to withdraw asset positions from an existing token pair pool. Upon meeting all requirements (such as the operational status of the pool contract, a valid percentage, and sufficient liquidity pool supply), the function transfers the calculated amount from the vault to the sender and burns the corresponding LP tokens.
|
||||
Note that this function cannot be invoked by blacklisted senders.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-x-trait <ft-trait>)
|
||||
(token-y-trait <ft-trait>)
|
||||
(factor uint)
|
||||
(percent uint)
|
||||
```
|
||||
TBD: LINKS to NON-TECH DOC FOR BUSINESS CONCEPTS (percent)
|
||||
|
||||
4) Swap tokens functions:
|
||||
The swap tokens functions enable token exchanges between two given tokens within the liquidity pool. For a swap to occur, the pool contract must have a funded liquidity pool for the token pair. The basic steps are:
|
||||
|
||||
a) transferring a specified amount of token-x from the sender to the system vault
|
||||
b) transferring a calculated amount of token-y from the system vault to the sender while considering swap fees and expected minimum amounts
|
||||
c) registering the fee in token-x within the vault
|
||||
d) updating the pool registry's liquidity status
|
||||
|
||||
These steps are mirrored for swaps involving the reverse token pair (token-y/token-x).
|
||||
|
||||
If no direct pool exists for the desired pair, the contract provides helper functions to facilitate multi-hop swaps using intermediate token pools. This process, also known as multi-step swap, allows the exchange via a route like token-x/intermediate-token and intermediate-token/token-y. Note that this feature requires prior knowledge of the intermediary pools to connect the desired pair in the swap.
|
||||
|
||||
The current protocol version supports up to 4-pools-route operations which are implemented in the following functions:
|
||||
|
||||
- `swap-helper`
|
||||
Swaps a given token-x for a required token-y.
|
||||
1 pool route: token-x/token-y.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-x-trait <ft-trait>)
|
||||
(token-y-trait <ft-trait>)
|
||||
(factor uint)
|
||||
(dx uint)
|
||||
(min-dy (optional uint))
|
||||
```
|
||||
|
||||
- `swap-helper-a`
|
||||
Swaps a given token-x for a required token-z.
|
||||
2 pools route: token-x/token-y - token-y/token-z.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-x-trait <ft-trait>)
|
||||
(token-y-trait <ft-trait>)
|
||||
(token-z-trait <ft-trait>)
|
||||
(factor-x uint)
|
||||
(factor-y uint)
|
||||
(dx uint)
|
||||
(min-dz (optional uint))
|
||||
```
|
||||
|
||||
- `swap-helper-b`
|
||||
Swaps a given token-x for a required token-w.
|
||||
3 pools route: token-x/token-y - token-y/token-z - token-z/token-w.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-x-trait <ft-trait>)
|
||||
(token-y-trait <ft-trait>)
|
||||
(token-z-trait <ft-trait>)
|
||||
(token-w-trait <ft-trait>)
|
||||
(factor-x uint)
|
||||
(factor-y uint)
|
||||
(factor-z uint)
|
||||
(dx uint)
|
||||
(min-dw (optional uint))
|
||||
```
|
||||
|
||||
- `swap-helper-c`
|
||||
Swaps a given token-x for a required token-v.
|
||||
4 pools route: token-x/token-y - token-y/token-z - token-z/token-w - token-w/token-v.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-x-trait <ft-trait>)
|
||||
(token-y-trait <ft-trait>)
|
||||
(token-z-trait <ft-trait>)
|
||||
(token-w-trait <ft-trait>)
|
||||
(token-v-trait <ft-trait>)
|
||||
(factor-x uint)
|
||||
(factor-y uint)
|
||||
(factor-z uint)
|
||||
(factor-w uint)
|
||||
(dx uint)
|
||||
(min-dv (optional uint))
|
||||
```
|
||||
|
||||
Note: all these helpers use the swap supporting functions `swap-x-for-y` and `swap-y-for-x`.
|
||||
|
||||
TBD: LINKS to NON-TECH DOC FOR BUSINESS CONCEPTS (swap concept, min-dy)
|
||||
|
||||
Supporting features:
|
||||
The following functions are tools to assist the off-chain activities.
|
||||
1) Fee helpers (`fee-helper`, `fee-helper-a`, `fee-helper-b`, `fee-helper-c`)
|
||||
These functions retrieve current fees for an existing pool based on the specified tokens and factors.
|
||||
|
||||
2) Rate helpers (`get-helper`, `get-helper-a`, `get-helper-b`, `get-helper-c`)
|
||||
These functions retrieve exchange rates for a given amount in an existing pool based on the specified tokens and factors.
|
||||
|
||||
Note: The above functions, along with their variations, support intermediary routes similar to those in the swapping functions (e.g., token-x/token-y, token-x/token-y-token-y/token-z, etc.).
|
||||
|
||||
Governance features:
|
||||
1) `is-dao-or-extension`
|
||||
This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract.
|
||||
|
||||
**Input**:
|
||||
None.
|
||||
|
||||
2) `is-blocklisted-or-default`
|
||||
A read-only feature that verifies if a given address is blacklisted in the registry contract.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(sender principal)
|
||||
```
|
||||
|
||||
3) `is-paused`
|
||||
A read-only function that checks the operational status of the contract.
|
||||
|
||||
**Input**:
|
||||
None.
|
||||
|
||||
4) `pause`
|
||||
A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(new-paused bool)
|
||||
```
|
||||
|
||||
##### Getter and Setter functions
|
||||
All getter and setter functions in the contract handle pool information, delegating their retrieval or update operations to the corresponding functions in the registry contract [amm-registry-v2-01](xxx xxx).
|
||||
|
||||
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-max-in-ratio`
|
||||
* `set-max-out-ratio`
|
||||
* `set-oracle-enabled`
|
||||
* `set-oracle-average`
|
||||
* `set-threshold-x`
|
||||
* `set-threshold-y`
|
||||
* `set-fee-rate-x`
|
||||
* `set-fee-rate-y`
|
||||
|
||||
Getters:
|
||||
Main getters:
|
||||
* `get-pool-details-by-id`
|
||||
* `get-pool-details`
|
||||
* `get-switch-threshold`
|
||||
* `get-pool-exists`
|
||||
* `get-max-ratio-limit`
|
||||
* `get-invariant` (consumes the preceding registry's `get-switch-threshold`)
|
||||
|
||||
Pool configuration getter functions (query the registry via the aforementioned `get-pool-details` function):
|
||||
* `get-start-block`
|
||||
* `get-end-block`
|
||||
* `get-max-in-ratio`
|
||||
* `get-max-out-ratio`
|
||||
* `get-oracle-enabled`
|
||||
* `get-oracle-average`
|
||||
* `get-threshold-x`
|
||||
* `get-threshold-y`
|
||||
* `get-fee-rate-x`
|
||||
* `get-fee-rate-y`
|
||||
* `get-balances`
|
||||
* `get-price`
|
||||
* `get-fee-rebate`
|
||||
* `get-pool-owner`
|
||||
* `check-pool-status`
|
||||
* `get-oracle-resilient`
|
||||
* `get-oracle-instant`
|
||||
|
||||
Pool token information getter functions (query the registry via the aforementioned `get-pool-details` function):
|
||||
* `get-y-given-x`
|
||||
* `get-x-given-y`
|
||||
* `get-y-in-given-x-out`
|
||||
* `get-x-in-given-y-out`
|
||||
* `get-x-given-price`
|
||||
* `get-y-given-price`
|
||||
* `get-token-given-position`
|
||||
* `get-position-given-mint`
|
||||
* `get-position-given-burn`
|
||||
|
||||
##### Internal helper functions
|
||||
Token helpers:
|
||||
These helper functions facilitate the retrieval of specific token data using another known data as input:
|
||||
* `get-price-internal`
|
||||
* `get-y-given-x-internal`
|
||||
* `get-x-given-y-internal`
|
||||
* `get-y-in-given-x-out-internal`
|
||||
* `get-x-in-given-y-out-internal`
|
||||
* `get-x-given-price-internal`
|
||||
* `get-y-given-price-internal`
|
||||
* `get-token-given-position-internal`
|
||||
* `get-position-given-mint-internal`
|
||||
* `get-position-given-burn-internal`
|
||||
|
||||
Mathematical helpers:
|
||||
These helper functions aid in various calculations within the context of the contract, such as amounts, percentages, etc. Some of them utilize [mathematical constants](xxx xxx).
|
||||
`mul-down`, `mul-up`, `div-down`, `div-up`, `pow-down`, `pow-up`, `ln-priv`, `accumulate_division`
|
||||
`rolling_sum_div`, `pow-priv`, `exp-pos`, `accumulate_product`, `rolling_div_sum`, `pow-fixed`
|
||||
`exp-fixed`, `log-fixed`, `ln-fixed`
|
||||
|
||||
##### Errors defined in the contract
|
||||
* `ERR-NOT-AUTHORIZED`
|
||||
* `ERR-POOL-ALREADY-EXISTS`
|
||||
* `ERR-INVALID-POOL`
|
||||
* `ERR-BLOCKLISTED`
|
||||
* `ERR-INVALID-LIQUIDITY`
|
||||
* `ERR-PERCENT-GREATER-THAN-ONE`
|
||||
* `ERR-EXCEEDS-MAX-SLIPPAGE`
|
||||
* `ERR-ORACLE-NOT-ENABLED`
|
||||
* `ERR-ORACLE-AVERAGE-BIGGER-THAN-ONE`
|
||||
* `ERR-PAUSED`
|
||||
* `ERR-SWITCH-THRESHOLD-BIGGER-THAN-ONE`
|
||||
* `ERR-NO-LIQUIDITY`
|
||||
* `ERR-MAX-IN-RATIO`
|
||||
* `ERR-MAX-OUT-RATIO`
|
||||
* `ERR-X-OUT-OF-BOUNDS`
|
||||
* `ERR-Y-OUT-OF-BOUNDS`
|
||||
* `ERR-PRODUCT-OUT-OF-BOUNDS`
|
||||
* `ERR-INVALID-EXPONENT`
|
||||
* `ERR-OUT-OF-BOUNDS`
|
||||
@@ -0,0 +1,193 @@
|
||||
### Contract: *amm-registry-v2-01.clar*.
|
||||
|
||||
###### **Location**: *`./alex-dao-2/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`. [LINK xxx xxx xxx]
|
||||
|
||||
To achieve this, the contract allows for the creation and updating of pools. Pool creation involves persisting an entry in a datamap, using `token-x`, `token-y`, and `factor` as the key and containing all relevant pool information.
|
||||
|
||||
Additionally, the contract includes configuration getters and setters that support position and swap operations. It is also responsible for managing a list of blocklisted operators.
|
||||
|
||||
**Storage**:
|
||||
|
||||
DATA
|
||||
* `pools-data-map` (datamap
|
||||
key:
|
||||
{
|
||||
token-x: principal,
|
||||
token-y: principal,
|
||||
factor: uint
|
||||
}
|
||||
value:
|
||||
{
|
||||
pool-id: uint,
|
||||
total-supply: uint,
|
||||
balance-x: uint,
|
||||
balance-y: uint,
|
||||
pool-owner: principal,
|
||||
fee-rate-x: uint,
|
||||
fee-rate-y: uint,
|
||||
fee-rebate: uint,
|
||||
oracle-enabled: bool,
|
||||
oracle-average: uint,
|
||||
oracle-resilient: uint,
|
||||
start-block: uint,
|
||||
end-block: uint,
|
||||
threshold-x: uint,
|
||||
threshold-y: uint,
|
||||
max-in-ratio: uint,
|
||||
max-out-ratio: uint
|
||||
}
|
||||
)
|
||||
A datamap structure that persists complete pool information. The map key consists of the unique pool identifier `{token-x, token-y, factor}`, and the map value contains detailed pool attributes.
|
||||
|
||||
* `pools-id-map` (datamap key: uint value: { token-x: principal, token-y: principal, factor: uint })
|
||||
A datamap structure that facilitates the retrieval of pool details using the pool ID as the key. The stored values include `token-x` and `token-y` principals, and `factor`.
|
||||
|
||||
* `pool-nonce` (uint)
|
||||
A persisted variable used to generate a new pool ID incrementally. The stored value represents the last pool ID that was created.
|
||||
|
||||
* `switch-threshold` (uint)
|
||||
An internal variable used to set a fixed threshold for calculations. It is initialized with `u80000000` and can be retrieved and modified using `get-switch-threshold` and `set-switch-threshold` functions. The value of `switch-threshold` must be less than or equal to the constant `ONE_8`. This value is crucial for the mathematical formulas used within the `amm-pool-v2-01.clar` contract.
|
||||
|
||||
* `max-ratio-limit` (uint)
|
||||
An internal variable that defines the maximum ratio limit. It is initialized with the value of the constant `ONE_8`.
|
||||
|
||||
* `blocklist` (datamap key: principal value: bool)
|
||||
A datamap structure that stores a persisted list of blocklisted addresses for operating within the Alex Trading Pool.
|
||||
|
||||
Mathematical constants:
|
||||
This symbolic constant is employed to define and restrict decimal precision to 8 decimal places.
|
||||
|
||||
* `ONE_8`
|
||||
It is declared as `u100000000`.
|
||||
|
||||
**Contract calls (interactions):**
|
||||
* `executor-dao`
|
||||
This call is used to verify whether a certain contract caller is designated as an extension.
|
||||
|
||||
**Features:**
|
||||
|
||||
1) `create-pool`
|
||||
This function establishes a liquidity pool for a specified token pair (token-x/token-y). It begins by verifying that the `tx-sender` is an ALEX admin operator (see the function `is-dao-or-extension`), as it is intended to be used by the main `amm-pool-v2-01.clar` contract in the current model.
|
||||
The primary validation performed by this function ensures that the pool does not already exist; if it does, an error is thrown. This validation considers the factor and both token combinations (token-x/token/y or token-y/token-x) as unique identifiers. When a pool is created, an entry is added to the `pools-data-map` structure, using this unique identifier as the key to keep track of all pool information, including balances, fees, thresholds, and more. Additionally, the function generates an ID for the newly created pool (see `pool-nonce`).
|
||||
All remaining values in the datamap are initialized to zero (`u0`), except for `oracle-enabled`, which is set to `false`. Additionally, `start-block` and `end-block` are initialized with the maximum uint value to ensure the pool remains in a non-operational status until properly initialized. For a complete list of fields, refer to the `pools-data-map`.
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-x-trait <ft-trait>)
|
||||
(token-y-trait <ft-trait>)
|
||||
(factor uint)
|
||||
(pool-owner principal)
|
||||
```
|
||||
|
||||
2) `update-pool`
|
||||
This function updates a liquidity pool identified by the unique combination of `token-x`, `token-y`, and `factor`. It is a governed function that restricts the `tx-sender` to be an ALEX admin operator (see the function `is-dao-or-extension`).
|
||||
Similar to the aforementioned `create-pool` function, `update-pool` is designed to be used by the main `amm-pool-v2-01.clar` contract. However, in this case, it is used indirectly in position and swap operations.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-x principal)
|
||||
(token-y principal)
|
||||
(factor uint)
|
||||
(pool-data {
|
||||
pool-id: uint,
|
||||
total-supply: uint,
|
||||
balance-x: uint,
|
||||
balance-y: uint,
|
||||
pool-owner: principal,
|
||||
fee-rate-x: uint,
|
||||
fee-rate-y: uint,
|
||||
fee-rebate: uint,
|
||||
oracle-enabled: bool,
|
||||
oracle-average: uint,
|
||||
oracle-resilient: uint,
|
||||
start-block: uint,
|
||||
end-block: uint,
|
||||
threshold-x: uint,
|
||||
threshold-y: uint,
|
||||
max-in-ratio: uint,
|
||||
max-out-ratio: uint }
|
||||
)
|
||||
```
|
||||
|
||||
Governance features:
|
||||
1) `is-dao-or-extension`
|
||||
This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract.
|
||||
|
||||
**Input**:
|
||||
None.
|
||||
|
||||
2) `is-blocklisted-or-default`
|
||||
A read-only feature that verifies if a given address is blacklisted using the `blocklist` map.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(sender principal)
|
||||
```
|
||||
|
||||
3) `set-blocklist-many`
|
||||
A public function, governed by the `is-dao-or-extension` mechanism, that allows setting or updating the blocklisted status for a list of addresses (up to 1000 addresses).
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(list 1000 {
|
||||
sender: principal,
|
||||
blocked: bool
|
||||
})
|
||||
```
|
||||
|
||||
##### Getter and Setter functions
|
||||
Pool administration setters:
|
||||
* `set-switch-threshold`
|
||||
* `set-max-ratio-limit`
|
||||
* `set-fee-rebate`
|
||||
* `set-pool-owner`
|
||||
|
||||
Pool operation setters and getters:
|
||||
The following groups of functions support pool usage and configuration features consumed by the main `amm-pool-v2-01.clar` contract.
|
||||
|
||||
Setters:
|
||||
* `set-start-block`
|
||||
* `set-end-block`
|
||||
* `set-max-in-ratio`
|
||||
* `set-max-out-ratio`
|
||||
* `set-oracle-enabled`
|
||||
* `set-oracle-average`
|
||||
* `set-threshold-x`
|
||||
* `set-threshold-y`
|
||||
* `set-fee-rate-x`
|
||||
* `set-fee-rate-y`
|
||||
|
||||
Getters:
|
||||
* `get-switch-threshold`
|
||||
* `get-max-ratio-limit`
|
||||
* `get-pool-details-by-id`
|
||||
* `get-pool-details`
|
||||
* `get-pool-exists`
|
||||
|
||||
|
||||
##### Internal helper functions
|
||||
|
||||
* `set-blocklist`
|
||||
This is a private function designed to complement the aforementioned governance function `set-blocklist-many`.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(sender principal)
|
||||
(blocked bool)
|
||||
```
|
||||
|
||||
##### Errors defined in the contract
|
||||
* `ERR-NOT-AUTHORIZED`
|
||||
* `ERR-INVALID-POOL`
|
||||
* `ERR-INVALID-LIQUIDITY`
|
||||
* `ERR-POOL-ALREADY-EXISTS`
|
||||
* `ERR-PERCENT-GREATER-THAN-ONE`
|
||||
* `ERR-EXCEEDS-MAX-SLIPPAGE`
|
||||
* `ERR-ORACLE-NOT-ENABLED`
|
||||
* `ERR-ORACLE-AVERAGE-BIGGER-THAN-ONE`
|
||||
* `ERR-PAUSED`
|
||||
* `ERR-SWITCH-THRESHOLD-BIGGER-THAN-ONE`
|
||||
* `ERR-NO-LIQUIDITY`
|
||||
* `ERR-MAX-IN-RATIO`
|
||||
* `ERR-MAX-OUT-RATIO`
|
||||
179
trading-lending-and-borrowing/contracts/amm-vault-v2-01.clar.md
Normal file
179
trading-lending-and-borrowing/contracts/amm-vault-v2-01.clar.md
Normal file
@@ -0,0 +1,179 @@
|
||||
### Contract: *amm-vault-v2-01.clar*.
|
||||
|
||||
###### **Location**: *`./alex-dao-2/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` 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. [LINK xxx xxx xxx].
|
||||
In addition to supporting Trading Pool operations, the vault contract also offers a flash-loan feature for registered tokens, available to authorized users.
|
||||
|
||||
**Storage**:
|
||||
|
||||
DATA
|
||||
|
||||
* `paused` (bool)
|
||||
This data variable acts as a flag to determine and control the operational status of the contract within the system.
|
||||
|
||||
TOKEN DATA:
|
||||
* `approved-tokens` (datamap key: principal value: bool)
|
||||
A datamap structure that lists all the approved tokens for transfer and loan operations.
|
||||
|
||||
* `reserve` (datamap key: principal value: uint)
|
||||
A datamap structure that keeps record of all the reserves in the vault for a specific token.
|
||||
|
||||
FLASH-LOAN DATA:
|
||||
* `flash-loan-enabled` (bool)
|
||||
A flag variable indicating the status of the contract's flash-loan feature. Currently, this is only an informative flag.
|
||||
|
||||
* `flash-loan-fee-rate` (uint)
|
||||
This variable defines the fee rate charged for loan operations.
|
||||
|
||||
* `approved-flash-loan-users` (datamap key: principal value: bool)
|
||||
A datamap structure that lists all the approved users for loan operations.
|
||||
|
||||
Mathematical constants:
|
||||
This symbolic constant is employed to define and restrict decimal precision to 8 decimal places.
|
||||
|
||||
* `ONE_8`
|
||||
It is declared as `u100000000`.
|
||||
|
||||
**Contract calls (interactions):**
|
||||
* `executor-dao`
|
||||
This call is used to verify whether a certain contract caller is designated as an extension.
|
||||
|
||||
* `token-trait`
|
||||
Calls are made to token contracts that comply with the <ft-trait> defined in each token-trait variable to facilitate token transfers and retrieve balances during transfer and loan operations.
|
||||
|
||||
* `flash-loan-user-trait`
|
||||
Calls are made to token contracts that comply with the <flash-loan-trait> defined in the flash-loan-user-trait variable to execute loans for the approved flash-loan users and tokens.
|
||||
|
||||
**Features:**
|
||||
|
||||
1) `add-to-reserve`
|
||||
This function increases the existing reserves of a specific token by the given amount. It is governed by the `is-dao-or-extension` check to ensure that the `tx-sender` is an ALEX admin operator. Intended to be invoked by the main `amm-pool-v2-01.clar` contract during swap operations, this function is called following a transfer of the incoming token (token-x) to the vault contract. The `add-to-reserve` function is then executed with the token principal and the specified amount, representing the swap fees charged by the system for the transaction.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-trait principal)
|
||||
(amount uint)
|
||||
```
|
||||
|
||||
2) `remove-from-reserve`
|
||||
This function serves as the reverse operation of `add-to-reserve`, decreasing the specified amount for the given token. An additional check ensures that the amount is less than or equal to the token's current reserve in the vault.
|
||||
Although it is not currently called by any existing module, the function also verifies that the `tx-sender` is an ALEX admin operator via the `is-dao-or-extension` control.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-trait principal)
|
||||
(amount uint)
|
||||
```
|
||||
|
||||
3) `transfer-ft`
|
||||
Like `add-to-reserve`, this function is intended to be called by the `amm-pool-v2-01.clar` contract during swap operations and is governed by the `is-dao-or-extension` check. Controls are in place to ensure that the contract is operational (not paused) and that the given token is approved in the contract's list.
|
||||
If all these conditions are met, the function will execute a transfer of the specified amount from the vault to the designated recipient.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-trait <ft-trait>)
|
||||
(amount uint)
|
||||
(recipient principal)
|
||||
```
|
||||
|
||||
4) `transfer-ft-two`
|
||||
This function serves as a helper for calling the `transfer-ft` function twice with two different tokens and amounts for the same recipient within a single transaction. In the current model, this feature is utilized by the `amm-pool-v2-01.clar` contract during position reduction operations to return assets to the user.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-x-trait <ft-trait>)
|
||||
(dx uint)
|
||||
(token-y-trait <ft-trait>)
|
||||
(dy uint)
|
||||
(recipient principal)
|
||||
```
|
||||
|
||||
5) `transfer-sft`
|
||||
This function is similar to `transfer-ft`, but it is designed for semi-fungible tokens, which operate with a token ID. It includes the same controls as `transfer-ft` regarding the vault's operational status and approved tokens. Although this function is not called by the `amm-pool-v2-01.clar` contract in the current system design, it requires invocation by an ALEX admin operator, as governed by the `is-dao-or-extension` check.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(token-trait <sft-trait>)
|
||||
(token-id uint)
|
||||
(amount uint)
|
||||
(recipient principal)
|
||||
```
|
||||
|
||||
6) `flash-loan`
|
||||
This function is designed to lend the recipient (the `tx-sender`) a specified amount of tokens to execute an embedded function declared in the `flash-loan-trait`. The recipient then transfers back the same amount plus the corresponding fee (refer to `flash-loan-fee-rate`).
|
||||
As with previous features, controls are in place to check the vault's operational status, approve tokens and flash-loan users, and ensure there is sufficient balance to make the transfer.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(flash-loan-user-trait <flash-loan-trait>)
|
||||
(token-trait <ft-trait>)
|
||||
(amount uint)
|
||||
(memo (optional (buff 16)))
|
||||
```
|
||||
|
||||
Governance features:
|
||||
1) `is-dao-or-extension`
|
||||
This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract.
|
||||
|
||||
**Input**:
|
||||
None.
|
||||
|
||||
2) `is-paused`
|
||||
A read-only function that checks the operational status of the contract.
|
||||
|
||||
**Input**:
|
||||
None.
|
||||
|
||||
3) `pause`
|
||||
A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(new-paused bool)
|
||||
```
|
||||
|
||||
##### Getter and Setter functions
|
||||
Vault administration getter:
|
||||
* `get-reserve`
|
||||
|
||||
Flash-loan operation setters and getters:
|
||||
Setters:
|
||||
* `set-flash-loan-enabled`
|
||||
* `set-flash-loan-fee-rate`
|
||||
* `set-approved-flash-loan-user`
|
||||
* `set-approved-token`
|
||||
|
||||
Getters:
|
||||
* `get-flash-loan-enabled`
|
||||
* `get-flash-loan-fee-rate`
|
||||
|
||||
##### Internal helper functions
|
||||
|
||||
* `check-is-approved-flash-loan-user`
|
||||
This is a private function designed to verify whether a flash-loan user is approved in the contract's persisted datamap, `approved-flash-loan-users`.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(flash-loan-user-trait principal)
|
||||
```
|
||||
|
||||
* `check-is-approved-token`
|
||||
This is a private function designed to verify whether a token is approved in the contract's persisted datamap, `approved-tokens`.
|
||||
|
||||
**Input**:
|
||||
```lisp
|
||||
(flash-loan-token principal)
|
||||
```
|
||||
|
||||
Mathematical helpers:
|
||||
These helper functions aid in various calculations within the context of the contract.
|
||||
* `mul-down`
|
||||
* `mul-up`
|
||||
|
||||
##### Errors defined in the contract
|
||||
* `ERR-NOT-AUTHORIZED`
|
||||
* `ERR-PAUSED`
|
||||
* `ERR-INVALID-BALANCE`
|
||||
* `ERR-INVALID-TOKEN`
|
||||
* `ERR-AMOUNT-EXCEED-RESERVE`
|
||||
Reference in New Issue
Block a user