docs: add governance features

developers/protocol-contracts/amm-pool-v3.clar.md

@@ -110,3 +110,72 @@ If the conditions can't be met, the function returns `0` values for all fields,
 | `tick`          | `int`        |
 | `dy`            | `uint`       |
 | `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`| `<ft-trait>` |
+| `token-y-trait`| `<ft-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`   | `<ft-trait>` |
+| `token-y-trait`   | `<ft-trait>` |
+| `pool-id`         | `uint`      |
+| `tick`            | `int`       |
+| `fee-to-address`  | `principal` |