@fbregante review

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.