From b42ee3d1fba18b801b96b8c99e1fb14414385ad0 Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Wed, 4 Jun 2025 11:57:50 -0300 Subject: [PATCH] @fbregante review --- developers/protocol-contracts/amm-pool-v3.clar.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/developers/protocol-contracts/amm-pool-v3.clar.md b/developers/protocol-contracts/amm-pool-v3.clar.md index ef92194..3c32672 100644 --- a/developers/protocol-contracts/amm-pool-v3.clar.md +++ b/developers/protocol-contracts/amm-pool-v3.clar.md @@ -11,7 +11,7 @@ Unlike traditional AMMs that spread liquidity across the entire price curve, DAM This contract supports the full lifecycle of DAMM pools: - **Pool Creation** – DAO-controlled creation of new pools between two fungible tokens, specifying bin size and fee configuration. - **Liquidity Provision** – LPs add liquidity to specific ticks within a pool, receiving fungible LP tokens for each tick. -- **Liquidity Management** – LPs can reduce their positions by percentage, claiming back their share of assets and accrued fees. +- **Liquidity Management** – LPs can reduce their positions by percentage, claiming back their share of assets and accrued fees from a specific tick. - **Swapping** – Supports swaps of token X for token Y (and vice versa) within a tick. - **Administrative Control** – The ALEX DAO can pause or sunset pools and adjust fee parameters at any time. - **Fee Claiming** – Accumulated fees can be withdrawn by the DAO to a target address. @@ -68,7 +68,7 @@ The `percent` parameter represents the portion of the position to withdraw, usin #### `swap-x-for-y-ioc` -This function allows users to swap a specific amount of token X (`dx`) for token Y in a selected bin (`tick`) of a DAMM pool, using an **Immediate-Or-Cancel (IOC)** strategy. The swap will only proceed if the resulting price does not exceed the user-defined `max-price`. +This function allows users to swap a specific amount of token X (`dx`) for token Y in a selected bin (`tick`) of a DAMM pool, using an **Immediate-Or-Cancel (IOC)** strategy. The swap aims to provide the best possible rate for token Y. The effective upper price limit for the swap is the more restrictive of either the user-defined `max-price` or the natural upper price boundary (`price-end`) of the specified tick. If the requested `dx` would push the price beyond this effective cap, only a partial amount (or none) of `dx` will be swapped. The function validates the pool's status and token traits, calculates how much of token X can be swapped without breaching the price cap, applies fees and potential rebates, and executes the transfers. If conditions are not met (e.g. price exceeds `max-price` or insufficient liquidity), it returns zero values for all outputs. @@ -85,9 +85,7 @@ The function validates the pool's status and token traits, calculates how much o #### `swap-y-for-x-ioc` -This function is the reverse of `swap-x-for-y-ioc`, enabling a swap from token Y to token X within a specific bin (`tick`) of a DAMM pool. - -The execution logic is identical, except that the transaction will only proceed if the resulting price does not fall below the user-defined `min-price`. +This function is the reverse of `swap-x-for-y-ioc`, the execution logic is similar. The effective lower price limit for the swap is the less restrictive of either the user-defined `min-price` or the natural lower price boundary (`price-start`) of the specified tick. If the requested `dy` would push the price below this effective cap, only a partial amount (or none) will be swapped. If conditions are not met, it returns zero values for all outputs. ##### Parameters @@ -114,8 +112,8 @@ Creates a new DAMM pool between two SIP-010 fungible tokens. This function configures a pool with a specific `bin-size`, fee rates for each token, and a fee rebate percentage. It performs several validations before pool creation: -- Ensures that both tokens are different and the bin size is within the allowed list (`ALLOWED-BIN-SIZES`). -- Checks that a pool with the same token pair and bin size does not already exist. +- Ensures that both tokens are different and verifies the `bin-size` is one of the allowed values (`u1`, `u5`, `u10`, `u20`). +- Checks that a pool with the same token pair (`token-x`, `token-y`) and `bin-size` does not already exist. It also verifies that a pool with the reversed token pair (`token-y`, `token-x`) and the same `bin-size` is not already registered. - Validates that `fee-rate-x` and `fee-rate-y` are strictly less than 1e8 (`ONE_8`) and that `fee-rebate` does not exceed 100%. The pool is stored using a new `pool-id` generated by incrementing `pool-id-nonce`, and it is inserted into both the `pools` map and the `pool-id-by-token` index for lookup by token pair. The pool starts in an active state (not paused or sunset), and the owner is set to the supplied `pool-owner`. Finally, it emits an event with the pool ID, the pool parameters, and the transaction sender. @@ -282,7 +280,7 @@ Stores the state of each bin in a pool, indexed by `pool-id` and `tick`. It trac ## Contract calls -- `executor-dao`: calls are made to verify whether a certain `contract-caller` is designated as an extension. +- `executor-dao`: called by governance functions (e.g., `create-pool`, `update-pool-fee`) via `is-dao-or-extension` to verify if the `contract-caller` is an authorized extension or if `tx-sender` is the DAO itself. - `amm-liquidity-token-v3`: used to mint and burn LP tokens that represent user positions in specific ticks. - `token-x-trait` / `token-y-trait`: represent the fungible tokens involved in each pool. These trait contracts are used to perform transfers during swaps and liquidity updates.