From 4826b76dde01384adeb25a67447526f09dd0886f Mon Sep 17 00:00:00 2001 From: Amarantha Kulkarni Date: Wed, 6 Sep 2023 14:18:20 -0700 Subject: [PATCH 1/8] Porting Clawback documentation to xrpl.org as the feature is in rippled 1.12.0 release --- .../tokens/clawback-of-issued-currency.md | 36 +++++++++++ .../transaction-types/clawback.md | 64 +++++++++++++++++++ dactyl-config.yml | 12 ++++ 3 files changed, 112 insertions(+) create mode 100644 content/concepts/tokens/clawback-of-issued-currency.md create mode 100644 content/references/protocol-reference/transactions/transaction-types/clawback.md diff --git a/content/concepts/tokens/clawback-of-issued-currency.md b/content/concepts/tokens/clawback-of-issued-currency.md new file mode 100644 index 0000000000..2484051174 --- /dev/null +++ b/content/concepts/tokens/clawback-of-issued-currency.md @@ -0,0 +1,36 @@ +--- +html: clawback-of-issued-currency.html +parent: tokens.html +blurb: Issuers can claw back their issued tokens for compliance purposes. +labels: + - Tokens +status: not_enabled +--- +# Clawback + +For regulatory purposes, some issuers must have the ability to recover issued tokens after they are distributed to accounts. For example, if an issuer were to discover that tokens were sent to an account sanctioned for illegal activity, the issuer could recover, or *claw back*, the funds. + +Issuers can create tokens that they can claw back by adding the `lsfAllowTrustLineClawback` flag to the issuing account. + +**Note:** You can only claw back issued tokens created by your account. You cannot claw back XRP in this way. + +Clawback is disabled by default. To use clawback, you must set the `lsfAllowTrustLineClawback` flag through an `AccountSet` transaction. The `AccountSet` transaction only succeeds if the account has an empty owner directory, meaning that the account has no trustlines, offers, escrows, payment channels, or checks. After you set this flag, it cannot reverted. The account permanently gains the ability to claw back issued assets on trustlines. + +If you attempt to set `lsfAllowTrustLineClawback` while `lsfNoFreeze` is set, the transaction returns `tecNO_PERMISSION`, because clawback cannot be enabled on an account that has already disclaimed the ability to freeze trustlines. +Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set, the transaction also returns `tecNO_PERMISSION`. + +## Example Clawback Transaction + +```json +{ + "TransactionType": "Clawback", + "Account": "rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S", + "Amount": { + "currency": "FOO", + "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", + "value": "314.159" + } +} +``` + +In execution, this transaction would claw back at most 314.159 FOO issued by rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S and held by rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW. If rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW does not have a trustline set up or that trustline's balance is 0, then the error `tecNO_LINE` is returned and a fee is consumed. \ No newline at end of file diff --git a/content/references/protocol-reference/transactions/transaction-types/clawback.md b/content/references/protocol-reference/transactions/transaction-types/clawback.md new file mode 100644 index 0000000000..02abb5b577 --- /dev/null +++ b/content/references/protocol-reference/transactions/transaction-types/clawback.md @@ -0,0 +1,64 @@ +--- +html: clawback.html +parent: transaction-types.html +blurb: Claw back an issued currency transfer between accounts in a trust set. +labels: + - Tokens +status: not_enabled +--- +# Clawback + +[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/Clawback.cpp "Source") + + + +Claw back an issued currency transfer between accounts in a trust set. + +## Example Clawback JSON + +```json +{ + "TransactionType": "Clawback", + "Account": "rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S", + "Amount": { + "currency": "FOO", + "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", + "value": "314.159" + } +} +``` + +[Clawback example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs.devnet.rippletest.net%2F&tx=%7B%22id%22%3A%22example_Clawback%22%2C%22command%22%3A%22Clawback%22%2C%22Account%22%3A%22rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S%22%2C%22Amount%22%3A%7B%22currency%22%3A%22FOO%22%2C%22issuer%22%3A%22rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW%22%2C%22value%22%3A%22314.159%22%7D%7D) + +## Clawback Fields + +In addition to the common fields, `Clawback` transactions use the following fields: + + +| Field | JSON Type | [Internal Type][] | Description | +|:-------------------|:----------|:------------------|:------------------| +| `TransactionType` | string | `UINT16` | Indicates the new transaction type `Clawback`. The integer value is `30`. The name is `ttCLAWBACK`. | +| `Account` | string | `ACCOUNT ID` | The account executing this transaction. The account must be the issuer of the asset being clawed back. Note that in the XRP Ledger, trustlines are bidirectional and, under some configurations, both sides can be seen as the "issuer" of an asset. In this specification, the term issuer is used to mean the side of the trustline that has an outstanding balance (that is, 'owes' the issued asset) that it wants to claw back.| +| `Flags` | number | `UINT32` | (Optional) The universal transaction flags that are applicable to all transactions (for example, `tfFullyCanonicalSig`) are valid. This proposal introduces no new transaction-specific flags. | +| `Amount` | object | `AMOUNT` | Indicates the amount being clawed back, as well as the counterparty from which the amount is being clawed back from. | + +It is not an error if the amount exceeds the holder's balance; in that case, the maximum available balance is clawed back. It returns `temBAD_AMOUNT` if the amount is zero. + +It is an error if the counterparty listed in `Amount` is the same as the `Account` issuing this transaction; the transaction fails execution with `temBAD_AMOUNT`. + +If there doesn't exist a trustline with the counterparty or that trustline's balance is 0, the error `tecNO_LINE` is returned. + +The sub-field `issuer` within `Amount` represents the token holder's account ID rather than the issuer's. + +## lsfAllowTrustLineClawback + +Clawback is disabled by default. To use clawback, you must set the `lsfAllowTrustLineClawback` flag through an `AccountSet` transaction. The `AccountSet` transaction only succeeds if the account has an empty owner directory, meaning that the account has no trustlines, offers, escrows, payment channels, or checks. After you set this flag, it cannot reverted. The account permanently gains the ability to claw back issued assets on trustlines. + +If you attempt to set `lsfAllowTrustLineClawback` while `lsfNoFreeze` is set, the transaction returns `tecNO_PERMISSION`, because clawback cannot be enabled on an account that has already disclaimed the ability to freeze trustlines. +Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set, the transaction also returns `tecNO_PERMISSION`. + + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} \ No newline at end of file diff --git a/dactyl-config.yml b/dactyl-config.yml index 0c28d55d38..96685af76c 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1127,6 +1127,12 @@ pages: targets: - ja +# TODO - Translate + - md: concepts/tokens/clawback-of-issued-currency.md + targets: + - en + - ja + - md: concepts/tokens/freezes.md targets: - en @@ -2287,6 +2293,12 @@ pages: targets: - ja +# TODO: Translate + - md: references/protocol-reference/transactions/transaction-types/clawback.md + targets: + - en + - ja + - md: references/protocol-reference/ledger-data/ledger-object-types/depositpreauth.md targets: - en From 49a67b7ceca7871b751a102b8c5141e016fb25eb Mon Sep 17 00:00:00 2001 From: Dennis Dawson Date: Wed, 6 Sep 2023 15:10:08 -0700 Subject: [PATCH 2/8] change trust lines to two words --- content/concepts/tokens/clawback-of-issued-currency.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/concepts/tokens/clawback-of-issued-currency.md b/content/concepts/tokens/clawback-of-issued-currency.md index 2484051174..537ec3363e 100644 --- a/content/concepts/tokens/clawback-of-issued-currency.md +++ b/content/concepts/tokens/clawback-of-issued-currency.md @@ -14,9 +14,9 @@ Issuers can create tokens that they can claw back by adding the `lsfAllowTrustLi **Note:** You can only claw back issued tokens created by your account. You cannot claw back XRP in this way. -Clawback is disabled by default. To use clawback, you must set the `lsfAllowTrustLineClawback` flag through an `AccountSet` transaction. The `AccountSet` transaction only succeeds if the account has an empty owner directory, meaning that the account has no trustlines, offers, escrows, payment channels, or checks. After you set this flag, it cannot reverted. The account permanently gains the ability to claw back issued assets on trustlines. +Clawback is disabled by default. To use clawback, you must set the `lsfAllowTrustLineClawback` flag through an `AccountSet` transaction. The `AccountSet` transaction only succeeds if the account has an empty owner directory, meaning that the account has no trust lines, offers, escrows, payment channels, or checks. After you set this flag, it cannot reverted. The account permanently gains the ability to claw back issued assets on trust lines. -If you attempt to set `lsfAllowTrustLineClawback` while `lsfNoFreeze` is set, the transaction returns `tecNO_PERMISSION`, because clawback cannot be enabled on an account that has already disclaimed the ability to freeze trustlines. +If you attempt to set `lsfAllowTrustLineClawback` while `lsfNoFreeze` is set, the transaction returns `tecNO_PERMISSION`, because clawback cannot be enabled on an account that has already disclaimed the ability to freeze trust lines. Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set, the transaction also returns `tecNO_PERMISSION`. ## Example Clawback Transaction @@ -33,4 +33,4 @@ Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is } ``` -In execution, this transaction would claw back at most 314.159 FOO issued by rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S and held by rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW. If rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW does not have a trustline set up or that trustline's balance is 0, then the error `tecNO_LINE` is returned and a fee is consumed. \ No newline at end of file +In execution, this transaction would claw back at most 314.159 FOO issued by rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S and held by rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW. If rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW does not have a trust line set up or that trust line's balance is 0, then the error `tecNO_LINE` is returned and a fee is consumed. From e6fbebb0ed2449d63099eea49682ec4e330ed628 Mon Sep 17 00:00:00 2001 From: Dennis Dawson Date: Wed, 6 Sep 2023 15:13:57 -0700 Subject: [PATCH 3/8] Change trust lines to two words, remove redundant *from* --- .../transactions/transaction-types/clawback.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/references/protocol-reference/transactions/transaction-types/clawback.md b/content/references/protocol-reference/transactions/transaction-types/clawback.md index 02abb5b577..3fee6f5a91 100644 --- a/content/references/protocol-reference/transactions/transaction-types/clawback.md +++ b/content/references/protocol-reference/transactions/transaction-types/clawback.md @@ -38,21 +38,21 @@ In addition to the common fields, `Clawback` transactions use the following fiel | Field | JSON Type | [Internal Type][] | Description | |:-------------------|:----------|:------------------|:------------------| | `TransactionType` | string | `UINT16` | Indicates the new transaction type `Clawback`. The integer value is `30`. The name is `ttCLAWBACK`. | -| `Account` | string | `ACCOUNT ID` | The account executing this transaction. The account must be the issuer of the asset being clawed back. Note that in the XRP Ledger, trustlines are bidirectional and, under some configurations, both sides can be seen as the "issuer" of an asset. In this specification, the term issuer is used to mean the side of the trustline that has an outstanding balance (that is, 'owes' the issued asset) that it wants to claw back.| +| `Account` | string | `ACCOUNT ID` | The account executing this transaction. The account must be the issuer of the asset being clawed back. Note that in the XRP Ledger, trust lines are bidirectional and, under some configurations, both sides can be seen as the "issuer" of an asset. In this specification, the term *issuer* is used to mean the side of the trust line that has an outstanding balance (that is, 'owes' the issued asset) that it wants to claw back.| | `Flags` | number | `UINT32` | (Optional) The universal transaction flags that are applicable to all transactions (for example, `tfFullyCanonicalSig`) are valid. This proposal introduces no new transaction-specific flags. | -| `Amount` | object | `AMOUNT` | Indicates the amount being clawed back, as well as the counterparty from which the amount is being clawed back from. | +| `Amount` | object | `AMOUNT` | Indicates the amount being clawed back, as well as the counterparty from which the amount is being clawed back. | It is not an error if the amount exceeds the holder's balance; in that case, the maximum available balance is clawed back. It returns `temBAD_AMOUNT` if the amount is zero. It is an error if the counterparty listed in `Amount` is the same as the `Account` issuing this transaction; the transaction fails execution with `temBAD_AMOUNT`. -If there doesn't exist a trustline with the counterparty or that trustline's balance is 0, the error `tecNO_LINE` is returned. +If there doesn't exist a trust line with the counterparty or that trust line's balance is 0, the error `tecNO_LINE` is returned. The sub-field `issuer` within `Amount` represents the token holder's account ID rather than the issuer's. ## lsfAllowTrustLineClawback -Clawback is disabled by default. To use clawback, you must set the `lsfAllowTrustLineClawback` flag through an `AccountSet` transaction. The `AccountSet` transaction only succeeds if the account has an empty owner directory, meaning that the account has no trustlines, offers, escrows, payment channels, or checks. After you set this flag, it cannot reverted. The account permanently gains the ability to claw back issued assets on trustlines. +Clawback is disabled by default. To use clawback, you must set the `lsfAllowTrustLineClawback` flag through an `AccountSet` transaction. The `AccountSet` transaction only succeeds if the account has an empty owner directory, meaning that the account has no trust lines, offers, escrows, payment channels, or checks. After you set this flag, it cannot reverted. The account permanently gains the ability to claw back issued assets on trust lines. If you attempt to set `lsfAllowTrustLineClawback` while `lsfNoFreeze` is set, the transaction returns `tecNO_PERMISSION`, because clawback cannot be enabled on an account that has already disclaimed the ability to freeze trustlines. Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set, the transaction also returns `tecNO_PERMISSION`. @@ -61,4 +61,4 @@ Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} \ No newline at end of file +{% include '_snippets/rippled_versions.md' %} From 620974f55124951259143567bd83121d0a7a35c0 Mon Sep 17 00:00:00 2001 From: ddawson Date: Thu, 7 Sep 2023 16:58:28 -0700 Subject: [PATCH 4/8] WIP clawback fixes --- content/_snippets/clawback-disclaimer.md | 1 + .../tokens/clawback-of-issued-currency.md | 36 ---------------- .../concepts/tokens/clawing-back-tokens.md | 41 +++++++++++++++++++ .../transaction-types/accountset.md | 1 + .../transaction-types/clawback.md | 4 +- 5 files changed, 45 insertions(+), 38 deletions(-) create mode 100644 content/_snippets/clawback-disclaimer.md delete mode 100644 content/concepts/tokens/clawback-of-issued-currency.md create mode 100644 content/concepts/tokens/clawing-back-tokens.md diff --git a/content/_snippets/clawback-disclaimer.md b/content/_snippets/clawback-disclaimer.md new file mode 100644 index 0000000000..7cc0525c8c --- /dev/null +++ b/content/_snippets/clawback-disclaimer.md @@ -0,0 +1 @@ +_Clawback functionality is part of the proposed [XLS-39d-clawback](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-39d-clawback) extension :not_enabled: to the XRP Ledger protocol. You can use the clawback feature on test networks, but there isn't an official amendment and they aren't available on the production Mainnet. Until there is an amendment, the details documented on these pages are subject to change._ diff --git a/content/concepts/tokens/clawback-of-issued-currency.md b/content/concepts/tokens/clawback-of-issued-currency.md deleted file mode 100644 index 537ec3363e..0000000000 --- a/content/concepts/tokens/clawback-of-issued-currency.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -html: clawback-of-issued-currency.html -parent: tokens.html -blurb: Issuers can claw back their issued tokens for compliance purposes. -labels: - - Tokens -status: not_enabled ---- -# Clawback - -For regulatory purposes, some issuers must have the ability to recover issued tokens after they are distributed to accounts. For example, if an issuer were to discover that tokens were sent to an account sanctioned for illegal activity, the issuer could recover, or *claw back*, the funds. - -Issuers can create tokens that they can claw back by adding the `lsfAllowTrustLineClawback` flag to the issuing account. - -**Note:** You can only claw back issued tokens created by your account. You cannot claw back XRP in this way. - -Clawback is disabled by default. To use clawback, you must set the `lsfAllowTrustLineClawback` flag through an `AccountSet` transaction. The `AccountSet` transaction only succeeds if the account has an empty owner directory, meaning that the account has no trust lines, offers, escrows, payment channels, or checks. After you set this flag, it cannot reverted. The account permanently gains the ability to claw back issued assets on trust lines. - -If you attempt to set `lsfAllowTrustLineClawback` while `lsfNoFreeze` is set, the transaction returns `tecNO_PERMISSION`, because clawback cannot be enabled on an account that has already disclaimed the ability to freeze trust lines. -Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set, the transaction also returns `tecNO_PERMISSION`. - -## Example Clawback Transaction - -```json -{ - "TransactionType": "Clawback", - "Account": "rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S", - "Amount": { - "currency": "FOO", - "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", - "value": "314.159" - } -} -``` - -In execution, this transaction would claw back at most 314.159 FOO issued by rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S and held by rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW. If rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW does not have a trust line set up or that trust line's balance is 0, then the error `tecNO_LINE` is returned and a fee is consumed. diff --git a/content/concepts/tokens/clawing-back-tokens.md b/content/concepts/tokens/clawing-back-tokens.md new file mode 100644 index 0000000000..10bac86f3d --- /dev/null +++ b/content/concepts/tokens/clawing-back-tokens.md @@ -0,0 +1,41 @@ +--- +html: clawing-back-tokens.html +parent: tokens.html +blurb: Issuers can claw back their tokens for compliance purposes if they enable the Clawback feature before issuing tokens. +labels: + - Tokens +status: not_enabled +--- +# Clawing Back Tokens +{% include '_snippets/_clawback-disclaimer.md' %} +For regulatory purposes, some issuers need the ability to recover tokens after they are distributed to accounts. For example, if an issuer were to discover that tokens were sent to an account sanctioned for illegal activity, the issuer could recover, or *claw back*, the funds. + +Issuers can gain the ability to claw back their tokens by enabling the **Allow Clawback** flag on their issuing account. This flag cannot be enabled if the issuer has already issued tokens. + +**Note:** You can only claw back issued tokens created by your account. You cannot claw back XRP in this way. + +Clawback is disabled by default. To use clawback, you must send an [AccountSet transaction][] to enable the **Allow Clawback** setting. **An issuer with any existing tokens cannot enable Clawback.** You can only enable Allow 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 even signer lists. + +If you attempt to set `lsfAllowTrustLineClawback` while `lsfNoFreeze` is set, the transaction returns `tecNO_PERMISSION`, because clawback cannot be enabled on an account that has already disclaimed the ability to freeze trust lines. +Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set, the transaction also returns `tecNO_PERMISSION`. + +## Example Clawback Transaction + +```json +{ + "TransactionType": "Clawback", + "Account": "rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S", + "Amount": { + "currency": "FOO", + "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", + "value": "314.159" + } +} +``` + +If successful, this transaction would claw back at most 314.159 FOO issued by rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S and held by rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} \ No newline at end of file diff --git a/content/references/protocol-reference/transactions/transaction-types/accountset.md b/content/references/protocol-reference/transactions/transaction-types/accountset.md index b0bf40046d..a93fec9a32 100644 --- a/content/references/protocol-reference/transactions/transaction-types/accountset.md +++ b/content/references/protocol-reference/transactions/transaction-types/accountset.md @@ -74,6 +74,7 @@ The available AccountSet flags are: | Flag Name | Decimal Value | Corresponding Ledger Flag | Description | |:----------------------------------|:--------------|:----------------------------------|:--------------| | `asfAccountTxnID` | 5 | (None) | Track the ID of this account's most recent transaction. Required for [`AccountTxnID`](transaction-common-fields.html#accounttxnid) | +| `asfAllowClawback` | 16 | `lsfAllowTrustlineClawback` | Allow account to claw back tokens it has issued. | | `asfAuthorizedNFTokenMinter` | 10 | (None) | Enable to allow another account to mint non-fungible tokens (NFTokens) on this account's behalf. Specify the authorized account in the `NFTokenMinter` field of the [AccountRoot](accountroot.html) object. To remove an authorized minter, enable this flag and omit the `NFTokenMinter` field. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ | | `asfDefaultRipple` | 8 | `lsfDefaultRipple` | Enable [rippling](rippling.html) on this account's trust lines by default. | | `asfDepositAuth` | 9 | `lsfDepositAuth` | Enable [Deposit Authorization](depositauth.html) on this account. _(Added by the [DepositAuth amendment][].)_ | diff --git a/content/references/protocol-reference/transactions/transaction-types/clawback.md b/content/references/protocol-reference/transactions/transaction-types/clawback.md index 3fee6f5a91..75fb662f56 100644 --- a/content/references/protocol-reference/transactions/transaction-types/clawback.md +++ b/content/references/protocol-reference/transactions/transaction-types/clawback.md @@ -1,7 +1,7 @@ --- html: clawback.html parent: transaction-types.html -blurb: Claw back an issued currency transfer between accounts in a trust set. +blurb: Claw back tokens you've issued. labels: - Tokens status: not_enabled @@ -12,7 +12,7 @@ status: not_enabled -Claw back an issued currency transfer between accounts in a trust set. +Claw back tokens issued by your account. This only works if you have enabled the **Allow Clawback** flag before issuing the tokens. ## Example Clawback JSON From 7f5752bf6f7448c407f99e620ee01b9b308d1391 Mon Sep 17 00:00:00 2001 From: ddawson Date: Fri, 8 Sep 2023 14:19:54 -0700 Subject: [PATCH 5/8] Address review comments. --- content/_snippets/clawback-disclaimer.md | 2 +- .../concepts/tokens/clawing-back-tokens.md | 6 ++- .../ledger-object-types/accountroot.md | 2 + .../transaction-types/accountset.md | 2 +- .../transaction-types/clawback.md | 38 +++++++++---------- dactyl-config.yml | 2 +- 6 files changed, 27 insertions(+), 25 deletions(-) diff --git a/content/_snippets/clawback-disclaimer.md b/content/_snippets/clawback-disclaimer.md index 7cc0525c8c..2da646741b 100644 --- a/content/_snippets/clawback-disclaimer.md +++ b/content/_snippets/clawback-disclaimer.md @@ -1 +1 @@ -_Clawback functionality is part of the proposed [XLS-39d-clawback](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-39d-clawback) extension :not_enabled: to the XRP Ledger protocol. You can use the clawback feature on test networks, but there isn't an official amendment and they aren't available on the production Mainnet. Until there is an amendment, the details documented on these pages are subject to change._ +_Requires the [Clawback amendment](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-39d-clawback)._ diff --git a/content/concepts/tokens/clawing-back-tokens.md b/content/concepts/tokens/clawing-back-tokens.md index 10bac86f3d..798e254073 100644 --- a/content/concepts/tokens/clawing-back-tokens.md +++ b/content/concepts/tokens/clawing-back-tokens.md @@ -7,14 +7,16 @@ labels: status: not_enabled --- # Clawing Back Tokens -{% include '_snippets/_clawback-disclaimer.md' %} + +{% include '_snippets/clawback-disclaimer.md' %} + For regulatory purposes, some issuers need the ability to recover tokens after they are distributed to accounts. For example, if an issuer were to discover that tokens were sent to an account sanctioned for illegal activity, the issuer could recover, or *claw back*, the funds. Issuers can gain the ability to claw back their tokens by enabling the **Allow Clawback** flag on their issuing account. This flag cannot be enabled if the issuer has already issued tokens. **Note:** You can only claw back issued tokens created by your account. You cannot claw back XRP in this way. -Clawback is disabled by default. To use clawback, you must send an [AccountSet transaction][] to enable the **Allow Clawback** setting. **An issuer with any existing tokens cannot enable Clawback.** You can only enable Allow 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 even signer lists. +Clawback is disabled by default. To use clawback, you must send an [AccountSet transaction][] 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. If you attempt to set `lsfAllowTrustLineClawback` while `lsfNoFreeze` is set, the transaction returns `tecNO_PERMISSION`, because clawback cannot be enabled on an account that has already disclaimed the ability to freeze trust lines. Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set, the transaction also returns `tecNO_PERMISSION`. diff --git a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md index 718c94baad..b93ff49e14 100644 --- a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md +++ b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md @@ -70,6 +70,8 @@ AccountRoot objects can have the following flag values: | Flag Name | Hex Value | Decimal Value | Corresponding [AccountSet Flag](accountset.html#accountset-flags) | Description | |-----------------------------------|--------------|-------------------|-----------------------------------|----| + `lsfAllowTrustLineClawback` | `0x80000000` | 2147483648 | +`asfAllowTrustLineClawback` | Enable [Clawback](clawing-back-tokens.html) for this account. | | `lsfDefaultRipple` | `0x00800000` | 8388608 | `asfDefaultRipple` | Enable [rippling](rippling.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. | | `lsfDepositAuth` | `0x01000000` | 16777216 | `asfDepositAuth` | This account has [DepositAuth](depositauth.html) enabled, meaning it can only receive funds from transactions it sends, and from [preauthorized](depositauth.html#preauthorization) accounts. _(Added by the [DepositAuth amendment][])_ | | `lsfDisableMaster` | `0x00100000` | 1048576 | `asfDisableMaster` | Disallows use of the master key to sign transactions for this account. | diff --git a/content/references/protocol-reference/transactions/transaction-types/accountset.md b/content/references/protocol-reference/transactions/transaction-types/accountset.md index a93fec9a32..35beca6269 100644 --- a/content/references/protocol-reference/transactions/transaction-types/accountset.md +++ b/content/references/protocol-reference/transactions/transaction-types/accountset.md @@ -74,7 +74,7 @@ The available AccountSet flags are: | Flag Name | Decimal Value | Corresponding Ledger Flag | Description | |:----------------------------------|:--------------|:----------------------------------|:--------------| | `asfAccountTxnID` | 5 | (None) | Track the ID of this account's most recent transaction. Required for [`AccountTxnID`](transaction-common-fields.html#accounttxnid) | -| `asfAllowClawback` | 16 | `lsfAllowTrustlineClawback` | Allow account to claw back tokens it has issued. | +| `asfAllowTrustLineClawback` | 16 | `lsfAllowTrustlineClawback` | Allow account to claw back tokens it has issued. _(Requires the [Clawback amendment][] :not_enabled:)_ Can only be set if the account has an empty owner directory (no trust lines, offers, escrows, payment channels, checks, or signer lists). After you set this flag, it cannot be reverted. The account permanently gains the ability to claw back issued assets on trust lines. | | `asfAuthorizedNFTokenMinter` | 10 | (None) | Enable to allow another account to mint non-fungible tokens (NFTokens) on this account's behalf. Specify the authorized account in the `NFTokenMinter` field of the [AccountRoot](accountroot.html) object. To remove an authorized minter, enable this flag and omit the `NFTokenMinter` field. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ | | `asfDefaultRipple` | 8 | `lsfDefaultRipple` | Enable [rippling](rippling.html) on this account's trust lines by default. | | `asfDepositAuth` | 9 | `lsfDepositAuth` | Enable [Deposit Authorization](depositauth.html) on this account. _(Added by the [DepositAuth amendment][].)_ | diff --git a/content/references/protocol-reference/transactions/transaction-types/clawback.md b/content/references/protocol-reference/transactions/transaction-types/clawback.md index 75fb662f56..ea2cee1a44 100644 --- a/content/references/protocol-reference/transactions/transaction-types/clawback.md +++ b/content/references/protocol-reference/transactions/transaction-types/clawback.md @@ -10,9 +10,11 @@ status: not_enabled [[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/Clawback.cpp "Source") - +{% include '_snippets/clawback-disclaimer.md' %} -Claw back tokens issued by your account. This only works if you have enabled the **Allow Clawback** flag before issuing the tokens. +Claw back tokens issued by your account. + +Clawback is disabled by default. To use clawback, you must send an [AccountSet transaction][] 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 Clawback JSON @@ -28,35 +30,31 @@ Claw back tokens issued by your account. This only works if you have enabled the } ``` -[Clawback example transaction. >](websocket-api-tool.html?server=wss%3A%2F%2Fs.devnet.rippletest.net%2F&tx=%7B%22id%22%3A%22example_Clawback%22%2C%22command%22%3A%22Clawback%22%2C%22Account%22%3A%22rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S%22%2C%22Amount%22%3A%7B%22currency%22%3A%22FOO%22%2C%22issuer%22%3A%22rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW%22%2C%22value%22%3A%22314.159%22%7D%7D) + ## Clawback Fields -In addition to the common fields, `Clawback` transactions use the following fields: - +{% include '_snippets/tx-fields-intro.md' %} | Field | JSON Type | [Internal Type][] | Description | |:-------------------|:----------|:------------------|:------------------| -| `TransactionType` | string | `UINT16` | Indicates the new transaction type `Clawback`. The integer value is `30`. The name is `ttCLAWBACK`. | -| `Account` | string | `ACCOUNT ID` | The account executing this transaction. The account must be the issuer of the asset being clawed back. Note that in the XRP Ledger, trust lines are bidirectional and, under some configurations, both sides can be seen as the "issuer" of an asset. In this specification, the term *issuer* is used to mean the side of the trust line that has an outstanding balance (that is, 'owes' the issued asset) that it wants to claw back.| -| `Flags` | number | `UINT32` | (Optional) The universal transaction flags that are applicable to all transactions (for example, `tfFullyCanonicalSig`) are valid. This proposal introduces no new transaction-specific flags. | -| `Amount` | object | `AMOUNT` | Indicates the amount being clawed back, as well as the counterparty from which the amount is being clawed back. | +| `Amount` | [Currency Amount][] | Amount |Indicates the amount being clawed back, as well as the counterparty from which the amount is being clawed back. The quantity to claw back, in the `value` sub-field, must not be zero. If this is more than the current balance, the transaction claws back the entire balance. The sub-field `issuer` within `Amount` represents the token holder's account ID, rather than the issuer's.| -It is not an error if the amount exceeds the holder's balance; in that case, the maximum available balance is clawed back. It returns `temBAD_AMOUNT` if the amount is zero. +The account executing this transaction must be the issuer of the asset being clawed back. Note that in the XRP Ledger, trust lines are bidirectional and, under some configurations, both sides can be seen as the *issuer* of an asset. In this specification, the term *issuer* is used to mean the side of the trust line that has an outstanding balance (that is, 'owes' the issued asset) that it wants to claw back. -It is an error if the counterparty listed in `Amount` is the same as the `Account` issuing this transaction; the transaction fails execution with `temBAD_AMOUNT`. -If there doesn't exist a trust line with the counterparty or that trust line's balance is 0, the error `tecNO_LINE` is returned. +## Error Cases -The sub-field `issuer` within `Amount` represents the token holder's account ID rather than the issuer's. - -## lsfAllowTrustLineClawback - -Clawback is disabled by default. To use clawback, you must set the `lsfAllowTrustLineClawback` flag through an `AccountSet` transaction. The `AccountSet` transaction only succeeds if the account has an empty owner directory, meaning that the account has no trust lines, offers, escrows, payment channels, or checks. After you set this flag, it cannot reverted. The account permanently gains the ability to claw back issued assets on trust lines. - -If you attempt to set `lsfAllowTrustLineClawback` while `lsfNoFreeze` is set, the transaction returns `tecNO_PERMISSION`, because clawback cannot be enabled on an account that has already disclaimed the ability to freeze trustlines. -Conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set, the transaction also returns `tecNO_PERMISSION`. +Besides errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html): +| Error Code | Description | +|:-----------|:------------| +| `temDISABLED` | Occurs if the [Clawback amendment](known-amendments.html#clawback) is not enabled. | +| `temBAD_AMOUNT` | Occurs if the holder's balance is 0. It is not an error if the amount exceeds the holder's balance; in that case, the maximum available balance is clawed back. Also occurs if the counterparty listed in `Amount` is the same as the `Account` issuing this transaction. | +| `tecNO-LINE` | Occurs there is no trust line with the counterparty or that trust line's balance is 0. | +| `tecNO-PERMISSION` | Occurs if you attempt to set `lsfAllowTrustlineClawback` while `lsfNoFreeze` is set. Also occurs, conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set. | {% include '_snippets/rippled-api-links.md' %} diff --git a/dactyl-config.yml b/dactyl-config.yml index 96685af76c..47140fda22 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1128,7 +1128,7 @@ pages: - ja # TODO - Translate - - md: concepts/tokens/clawback-of-issued-currency.md + - md: concepts/tokens/clawing-back-tokens.md targets: - en - ja From d5121328f96eb7293097273cdf44bc46a9d53459 Mon Sep 17 00:00:00 2001 From: ddawson Date: Fri, 8 Sep 2023 15:07:37 -0700 Subject: [PATCH 6/8] Fix format and links --- .../ledger-data/ledger-object-types/accountroot.md | 4 +--- .../transactions/transaction-types/accountset.md | 2 +- .../transactions/transaction-types/clawback.md | 4 ---- 3 files changed, 2 insertions(+), 8 deletions(-) diff --git a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md index b93ff49e14..f4bce39d9a 100644 --- a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md +++ b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md @@ -70,9 +70,7 @@ AccountRoot objects can have the following flag values: | Flag Name | Hex Value | Decimal Value | Corresponding [AccountSet Flag](accountset.html#accountset-flags) | Description | |-----------------------------------|--------------|-------------------|-----------------------------------|----| - `lsfAllowTrustLineClawback` | `0x80000000` | 2147483648 | -`asfAllowTrustLineClawback` | Enable [Clawback](clawing-back-tokens.html) for this account. | -| `lsfDefaultRipple` | `0x00800000` | 8388608 | `asfDefaultRipple` | Enable [rippling](rippling.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. | +`lsfAllowTrustLineClawback` | `0x80000000` | 2147483648 | `asfAllowTrustLineClawback` | Enable [Clawback](clawing-back-tokens.html) for this account. | `lsfDefaultRipple` | `0x00800000` | 8388608 | `asfDefaultRipple` | Enable [rippling](rippling.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. | | `lsfDepositAuth` | `0x01000000` | 16777216 | `asfDepositAuth` | This account has [DepositAuth](depositauth.html) enabled, meaning it can only receive funds from transactions it sends, and from [preauthorized](depositauth.html#preauthorization) accounts. _(Added by the [DepositAuth amendment][])_ | | `lsfDisableMaster` | `0x00100000` | 1048576 | `asfDisableMaster` | Disallows use of the master key to sign transactions for this account. | | `lsfDisallowIncomingCheck` | `0x08000000` | 134217728 | `asfDisallowIncomingCheck` | This account blocks incoming Checks. _(Requires the [DisallowIncoming amendment][] :not_enabled:.)_ | diff --git a/content/references/protocol-reference/transactions/transaction-types/accountset.md b/content/references/protocol-reference/transactions/transaction-types/accountset.md index 35beca6269..1e13354159 100644 --- a/content/references/protocol-reference/transactions/transaction-types/accountset.md +++ b/content/references/protocol-reference/transactions/transaction-types/accountset.md @@ -74,7 +74,7 @@ The available AccountSet flags are: | Flag Name | Decimal Value | Corresponding Ledger Flag | Description | |:----------------------------------|:--------------|:----------------------------------|:--------------| | `asfAccountTxnID` | 5 | (None) | Track the ID of this account's most recent transaction. Required for [`AccountTxnID`](transaction-common-fields.html#accounttxnid) | -| `asfAllowTrustLineClawback` | 16 | `lsfAllowTrustlineClawback` | Allow account to claw back tokens it has issued. _(Requires the [Clawback amendment][] :not_enabled:)_ Can only be set if the account has an empty owner directory (no trust lines, offers, escrows, payment channels, checks, or signer lists). After you set this flag, it cannot be reverted. The account permanently gains the ability to claw back issued assets on trust lines. | +| `asfAllowTrustLineClawback` | 16 | `lsfAllowTrustlineClawback` | Allow account to claw back tokens it has issued. _(Requires the Clawback amendment :not_enabled:)_ Can only be set if the account has an empty owner directory (no trust lines, offers, escrows, payment channels, checks, or signer lists). After you set this flag, it cannot be reverted. The account permanently gains the ability to claw back issued assets on trust lines. | | `asfAuthorizedNFTokenMinter` | 10 | (None) | Enable to allow another account to mint non-fungible tokens (NFTokens) on this account's behalf. Specify the authorized account in the `NFTokenMinter` field of the [AccountRoot](accountroot.html) object. To remove an authorized minter, enable this flag and omit the `NFTokenMinter` field. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ | | `asfDefaultRipple` | 8 | `lsfDefaultRipple` | Enable [rippling](rippling.html) on this account's trust lines by default. | | `asfDepositAuth` | 9 | `lsfDepositAuth` | Enable [Deposit Authorization](depositauth.html) on this account. _(Added by the [DepositAuth amendment][].)_ | diff --git a/content/references/protocol-reference/transactions/transaction-types/clawback.md b/content/references/protocol-reference/transactions/transaction-types/clawback.md index ea2cee1a44..7c426aedb1 100644 --- a/content/references/protocol-reference/transactions/transaction-types/clawback.md +++ b/content/references/protocol-reference/transactions/transaction-types/clawback.md @@ -30,10 +30,6 @@ Clawback is disabled by default. To use clawback, you must send an [AccountSet t } ``` - - ## Clawback Fields {% include '_snippets/tx-fields-intro.md' %} From 2c8d4a69ff588c4cd481537070cc99fcbe8ffb70 Mon Sep 17 00:00:00 2001 From: ddawson Date: Fri, 8 Sep 2023 15:41:49 -0700 Subject: [PATCH 7/8] fix line break --- .../ledger-data/ledger-object-types/accountroot.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md index f4bce39d9a..17f3444531 100644 --- a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md +++ b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md @@ -70,7 +70,8 @@ AccountRoot objects can have the following flag values: | Flag Name | Hex Value | Decimal Value | Corresponding [AccountSet Flag](accountset.html#accountset-flags) | Description | |-----------------------------------|--------------|-------------------|-----------------------------------|----| -`lsfAllowTrustLineClawback` | `0x80000000` | 2147483648 | `asfAllowTrustLineClawback` | Enable [Clawback](clawing-back-tokens.html) for this account. | `lsfDefaultRipple` | `0x00800000` | 8388608 | `asfDefaultRipple` | Enable [rippling](rippling.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. | +`lsfAllowTrustLineClawback` | `0x80000000` | 2147483648 | `asfAllowTrustLineClawback` | Enable [Clawback](clawing-back-tokens.html) for this account. | +|`lsfDefaultRipple` | `0x00800000` | 8388608 | `asfDefaultRipple` | Enable [rippling](rippling.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. | | `lsfDepositAuth` | `0x01000000` | 16777216 | `asfDepositAuth` | This account has [DepositAuth](depositauth.html) enabled, meaning it can only receive funds from transactions it sends, and from [preauthorized](depositauth.html#preauthorization) accounts. _(Added by the [DepositAuth amendment][])_ | | `lsfDisableMaster` | `0x00100000` | 1048576 | `asfDisableMaster` | Disallows use of the master key to sign transactions for this account. | | `lsfDisallowIncomingCheck` | `0x08000000` | 134217728 | `asfDisallowIncomingCheck` | This account blocks incoming Checks. _(Requires the [DisallowIncoming amendment][] :not_enabled:.)_ | From b770b82ea7915f06984f99a409ee6f0449fab834 Mon Sep 17 00:00:00 2001 From: ddawson Date: Fri, 8 Sep 2023 16:13:08 -0700 Subject: [PATCH 8/8] innocuous change to kick off build --- .../ledger-data/ledger-object-types/accountroot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md index 17f3444531..25f29814c0 100644 --- a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md +++ b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md @@ -96,4 +96,4 @@ The ID of an AccountRoot object is the [SHA-512Half][] of the following values, {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} +{% include '_snippets/rippled_versions.md' %} \ No newline at end of file