diff --git a/developers/protocol-contracts/amm-pool-v3.clar.md b/developers/protocol-contracts/amm-pool-v3.clar.md index a25b6ba..f12f602 100644 --- a/developers/protocol-contracts/amm-pool-v3.clar.md +++ b/developers/protocol-contracts/amm-pool-v3.clar.md @@ -109,4 +109,73 @@ If the conditions can't be met, the function returns `0` values for all fields, | `pool-id` | `uint` | | `tick` | `int` | | `dy` | `uint` | -| `min-price` | `uint` | \ No newline at end of file +| `min-price` | `uint` | + +### Governance Features + +#### `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. + +#### `create-pool` + +A public function, governed through the `is-dao-or-extension`, that 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. +- 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`. + +##### Parameters + +| Name | Type | +| -------------- | ------------ | +| `token-x-trait`| `` | +| `token-y-trait`| `` | +| `bin-size` | `uint` | +| `pool-owner` | `principal` | +| `fee-rate-x` | `uint` | +| `fee-rate-y` | `uint` | +| `fee-rebate` | `uint` | + +#### `update-pool-fee` + +A public function, governed through `is-dao-or-extension`, that updates the fee configuration for an existing pool. It sets new values for the swap fee on each token and the rebate returned to liquidity providers. + +##### Parameters + +| Name | Type | +| ------------ | ------ | +| `pool-id` | `uint` | +| `fee-rate-x` | `uint` | +| `fee-rate-y` | `uint` | +| `fee-rebate` | `uint` | + +#### `set-pool-status` + +A public function, governed through `is-dao-or-extension`, that updates the operational status of a pool. It can mark a pool as `paused` or `sunset`, affecting its availability for swaps and liquidity actions. + +##### Parameters + +| Name | Type | +| --------- | ------ | +| `pool-id` | `uint` | +| `sunset` | `bool` | +| `paused` | `bool` | + +#### `claim-fees` + +A public function, governed through `is-dao-or-extension`, that allows the DAO to withdraw accumulated swap fees from a specific pool and tick. The function resets the stored fees to zero and transfers the collected amounts of both tokens to the specified address using the corresponding token contracts. + +##### Parameters + +| Name | Type | +| ----------------- | ----------- | +| `token-x-trait` | `` | +| `token-y-trait` | `` | +| `pool-id` | `uint` | +| `tick` | `int` | +| `fee-to-address` | `principal` | \ No newline at end of file