Merge pull request #2969 from XRPLF/migrate-ammclawbackdocs

Add AMMClawback reference docs
2025-11-04 11:55:50 +00:00 · 2025-01-29 16:15:47 -08:00
parent dc73f90f5e 3f33bbd160
commit 9a8d705bff
5 changed files with 82 additions and 3 deletions
--- a/docs/_snippets/common-links.md
+++ b/docs/_snippets/common-links.md
@@ -1,5 +1,6 @@
 [AMM amendment]: /resources/known-amendments.md#amm
 [AMM entry]: /docs/references/protocol/ledger-data/ledger-entry-types/amm.md
+[AMMClawback amendment]: /resources/known-amendments.md#ammclawback
 [AMM object]: /docs/references/protocol/ledger-data/ledger-entry-types/amm.md
 [AMMエントリ]: /docs/references/protocol/ledger-data/ledger-entry-types/amm.md
 [AMMオブジェクト]: /docs/references/protocol/ledger-data/ledger-entry-types/amm.md
@@ -7,6 +8,7 @@
 [AMMBid transactions]: /docs/references/protocol/transactions/types/ammbid.md
 [AMMBid]: /docs/references/protocol/transactions/types/ammbid.md
 [AMMBidトランザクション]: /docs/references/protocol/transactions/types/ammbid.md
+[AMMClawback transaction]: /docs/references/protocol/transactions/types/ammclawback.md
 [AMMCreate transaction]: /docs/references/protocol/transactions/types/ammcreate.md
 [AMMCreate transactions]: /docs/references/protocol/transactions/types/ammcreate.md
 [AMMCreate]: /docs/references/protocol/transactions/types/ammcreate.md
--- a/docs/references/protocol/transactions/types/ammclawback.md
+++ b/docs/references/protocol/transactions/types/ammclawback.md
@@ -0,0 +1,70 @@
+# AMMClawback
+
+<!--> Add link to github source after feature is merged into devnet. <-->
+[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/app/tx/detail/AMMClawback.cpp "Source")
+
+_(Added by the [AMM amendment][])_
+
+Claw back tokens from a holder who has deposited your issued tokens into an AMM pool.
+
+Clawback is disabled by default. To use clawback, you must send an [AccountSet transaction](https://xrpl.org/docs/references/protocol/transactions/types/accountset) to enable the **Allow Trust Line Clawback** setting. An issuer with any existing tokens cannot enable clawback. You can only enable **Allow Trust Line Clawback** if you have a completely empty owner directory, meaning you must do so before you set up any trust lines, offers, escrows, payment channels, checks, or signer lists. After you enable clawback, it cannot reverted: the account permanently gains the ability to claw back issued assets on trust lines.
+
+
+## Example {% $frontmatter.seo.title %} JSON
+
+```json
+{
+  "TransactionType": "AMMClawback",
+  "Account": "rPdYxU9dNkbzC5Y2h4jLbVJ3rMRrk7WVRL",
+  "Holder": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
+  "Asset": {
+      "currency" : "FOO",
+      "issuer" : "rPdYxU9dNkbzC5Y2h4jLbVJ3rMRrk7WVRL"
+  },
+  "Asset2" : {
+      "currency" : "BAR",
+      "issuer" : "rHtptZx1yHf6Yv43s1RWffM3XnEYv3XhRg"
+  },
+  "Amount": {
+      "currency" : "FOO",
+      "issuer" : "rPdYxU9dNkbzC5Y2h4jLbVJ3rMRrk7WVRL",
+      "value" : "1000"
+  }
+}
+```
+
+
+{% raw-partial file="/docs/_snippets/tx-fields-intro.md" /%}
+
+
+| Field              | JSON Type | [Internal Type][] | Required | Description |
+|:-------------------|:----------|:------------------|:---------|:------------------|
+| `Account` | String | AccountID | Yes | The issuer of the asset being clawed back. Only the issuer can submit this transaction. |
+| `Asset`   | Object | STIssue   | Yes | Specifies the asset that the issuer wants to claw back from the AMM pool. In JSON, this is an object with `currency` and `issuer` fields. The `issuer` field must match with `Account`. |
+| `Asset2`  | Object | STIssue   | Yes | Specifies the other asset in the AMM's pool. In JSON, this is an object with `currency` and `issuer` fields (omit `issuer` for XRP). |
+| `Amount`  | [Currency Amount](https://xrpl.org/docs/references/protocol/data-types/basic-data-types#specifying-currency-amounts) | Amount | No | The maximum amount to claw back from the AMM account. The `currency` and `issuer` subfields should match the `Asset` subfields. If this field isn't specified, or the `value` subfield exceeds the holder's available tokens in the AMM, all of the holder's tokens are clawed back. |
+| `Holder`  | String | AccountID | Yes | The account holding the asset to be clawed back. |
+
+
+## AMMClawback Flags
+
+| Flag Name | Hex Value | Decimal Value | Description |
+|----------|------------|---------------|-------------|
+| `tfClawTwoAssets` | `0x00000001` | 1 | Claw back the specified amount of `Asset`, and a corresponding amount of `Asset2` based on the AMM pool's asset proportion; both assets must be issued by the issuer in the `Account` field. If this flag isn't enabled, the issuer claws back the specified amount of `Asset`, while a corresponding proportion of `Asset2` goes back to the `Holder`. |
+
+
+## Error Cases
+
+Besides errors that can occur for all transactions, `AMMClawback` transactions can result in the following [transaction result codes](https://xrpl.org/docs/references/protocol/transactions/transaction-results):
+
+| Error Code         | Description |
+|:-------------------|:------------|
+| `tecNO_PERMISSION` | Occurs if you attempt to claw back tokens from an AMM without the `lsfAllowTrustlineClawback` flag enabled, or the `tfClawTwoAssets` flag is enabled when you didn't issue both assets in the AMM. Also occurs if the `Asset` issuer doesn't match `Account`. |
+| `tecAMM_BALANCE`   | Occurs if the `Holder` doesn't hold any LP tokens from the AMM pool. |
+| `temDISABLED`      | Occurs if the [AMMClawback amendment](#) is not enabled. |
+| `temBAD_AMOUNT`    | Occurs if the `Amount` field in the `AMMClawback` transaction is less than or equal to 0, or the `currency` and `issuer` subfields don't match between `Amount` and `Asset`. |
+| `temINVALID_FLAG`  | Occurs if you try enabling flags besides `tfClawTwoAssets`. |
+| `temMALFORMED`     | Occurs if the `issuer` subfield doesn't match between `Asset` and `Account`, `Account` is the same as the `Holder`, or `Asset` is XRP. |
+| `terNO_AMM`        | Occurs if the AMM pool specified by `Asset` and `Asset2` doesn't exist. |
+
+{% raw-partial file="/docs/_snippets/common-links.md" /%}
--- a/docs/references/protocol/transactions/types/ammcreate.md
+++ b/docs/references/protocol/transactions/types/ammcreate.md
@@ -44,7 +44,7 @@ Creates both an [AMM entry][] and a [special AccountRoot entry](../../ledger-dat
 | `Amount2`    | [Currency Amount][] | Amount            | Yes       | The second of the two assets to fund this AMM with. This must be a positive amount. |
 | `TradingFee` | Number              | UInt16            | Yes       | The fee to charge for trades against this AMM instance, in units of 1/100,000; a value of 1 is equivalent to 0.001%. The maximum value is `1000`, indicating a 1% fee. The minimum value is `0`. |

-One or both of `Amount` and `Amount2` can be [tokens](../../../../concepts/tokens/index.md); at most one of them can be [XRP](../../../../introduction/what-is-xrp.md). They cannot both have the same currency code and issuer. The tokens' issuers must have [Default Ripple](../../../../concepts/tokens/fungible-tokens/rippling.md#the-default-ripple-flag) enabled. If the [Clawback amendment][] is enabled, those issuers must not have enabled the Allow Clawback flag. The assets _cannot_ be LP tokens for another AMM.
+One or both of `Amount` and `Amount2` can be [tokens](../../../../concepts/tokens/index.md); at most one of them can be [XRP](../../../../introduction/what-is-xrp.md). They cannot both have the same currency code and issuer. The tokens' issuers must have [Default Ripple](../../../../concepts/tokens/fungible-tokens/rippling.md#the-default-ripple-flag) enabled. The assets _cannot_ be LP tokens for another AMM.

 ## Special Transaction Cost

@@ -62,7 +62,7 @@ Besides errors that can occur for all transactions, {% $frontmatter.seo.title %}
 | `tecINSUF_RESERVE_LINE` | The sender of this transaction does meet the increased [reserve requirement](../../../../concepts/accounts/reserves.md) of processing this transaction, probably because they need a new trust line to hold the LP Tokens, and they don't have enough XRP to meet the additional owner reserve for a new trust line. |
 | `tecNO_AUTH`        | At least one of the deposit assets uses [authorized trust lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the sender does not have authorization to hold that asset. |
 | `tecNO_LINE`        | The sender does not have a trust line for at least one of the deposit assets. |
-| `tecNO_PERMISSION`  | At least one of the deposit assets cannot be used in an AMM. For example, the issuer has enabled Clawback support. |
+| `tecNO_PERMISSION`  | At least one of the deposit assets cannot be used in an AMM. |
 | `tecUNFUNDED_AMM`   | The sender does not hold enough of the assets specified in `Amount` and `Amount2` to fund the AMM. |
 | `terNO_RIPPLE`      | The issuer of at least one of the assets has not enabled the [Default Ripple flag](../../../../concepts/tokens/fungible-tokens/rippling.md#the-default-ripple-flag). |
 | `temAMM_BAD_TOKENS` | The values of `Amount` and `Amount2` are not valid: for example, both refer to the same token. |
--- a/docs/references/protocol/transactions/types/ammdeposit.md
+++ b/docs/references/protocol/transactions/types/ammdeposit.md
@@ -15,6 +15,12 @@ Deposit funds into an [Automated Market Maker](../../../../concepts/tokens/decen

 If successful, this transaction creates a [trust line](../../../../concepts/tokens/fungible-tokens/index.md) to the AMM Account (limit 0) to hold the LP Tokens.

+{% admonition type="info" name="Note" %}
+You can't deposit either asset into an AMM if:
+- At least one of the pooled assets is frozen by the token issuer.
+- You aren't authorized to hold at least one of the pooled assets.
+{% /admonition %}
+
 ## Example {% $frontmatter.seo.title %} JSON

 ```json
@@ -129,7 +135,7 @@ Besides errors that can occur for all transactions, {% $frontmatter.seo.title %}
 | `tecAMM_EMPTY`          | The AMM currently holds no assets, so you cannot do a normal deposit. You must use the Empty AMM Special Case deposit instead. |
 | `tecAMM_NOT_EMPTY`      | The transaction specified `tfTwoAssetIfEmpty`, but the AMM was not empty. |
 | `tecAMM_FAILED`         | The conditions on the deposit could not be satisfied. For example, the requested effective price in the `EPrice` field is too low. |
-| `tecFROZEN`             | The transaction tried to deposit a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) token. |
+| `tecFROZEN`             | The transaction tried to deposit a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) token, or at least one of the paired tokens is frozen. |
 | `tecINSUF_RESERVE_LINE` | The sender of this transaction does meet the increased [reserve requirement](../../../../concepts/accounts/reserves.md) of processing this transaction, probably because they need a new trust line to hold the LP Tokens, and they don't have enough XRP to meet the additional owner reserve for a new trust line. |
 | `tecUNFUNDED_AMM`       | The sender does not have a high enough balance to make the specified deposit. |
 | `temBAD_AMM_TOKENS`     | The transaction specified the LP Tokens incorrectly. For example, the `issuer` is not the AMM's associated AccountRoot address or the `currency` is not the currency code for this AMM's LP Tokens, or the transaction specified this AMM's LP Tokens in one of the asset fields. |
--- a/sidebars.yaml
+++ b/sidebars.yaml
@@ -358,6 +358,7 @@
                    - page: docs/references/protocol/transactions/types/accountset.md
                    - page: docs/references/protocol/transactions/types/accountdelete.md
                    - page: docs/references/protocol/transactions/types/ammbid.md
+                    - page: docs/references/protocol/transactions/types/ammclawback.md
                    - page: docs/references/protocol/transactions/types/ammcreate.md
                    - page: docs/references/protocol/transactions/types/ammdelete.md
                    - page: docs/references/protocol/transactions/types/ammdeposit.md