0039 XLS-39d: Clawback

[nbougalis]

Updated: XLS-39 Clawback Specification

• Note: the PR was XLS-39d: Clawback specification #104

  Title:        Clawback Support
  Revision:     1 (2022-12-20)

  Author:       Nikolaos D. Bougalis

1. Clawback Support

1.1. Abstract

Although the XRP Ledger offers rich support for tokens (a.k.a. IOUs or issued assets), including offering issuers the ability to freeze issuances, in order to meet regulatory requirements, some issuers need to be able to go further, by having the ability to "clawback" their issued assets.

---

‼️ This proposal deals only with issued assets. The proposed clawback
support cannot be used to claw back XRP.

---

1.1.1. Advantages and Disadvantages

Advantages

• Issuers that are restricted from issuing on ledger because of regulatory requirements requiring the ability to clawback funds will be able to issue tokens.
• By being able to "clawback" issuers can ensure that the "on-chain" view is representative of the balance.
• Arguably, "clawback" results in simpler-to-interpret data structures on ledger, compared to "freeze" which freezes an entire balance and requires additional interpretation/display by clients.
• Compared to other on-ledger features (e.g. freeze), clawback is minimal and trivial to implement.

Disadvantages

• Introduces an additional transaction, along with the complexity that comes with that.
• Requires additional documentation, including highlighting the fact that clawback cannot be applied to XRP.

1.2. Creating and Transferring Tokens on XRPL

1.2.1. On-Ledger Data Structures

This proposal introduces no new on ledger structures.

Transactions

This proposal introduces one new transaction: Clawback:

The Clawback transaction

The Clawback transaction modifies a trustline object, by adjusting the balance accordingly and, if instructed to, by changing relevant flags. If possible (i.e. if the Clawback transaction would leave the trustline is in the "default" state), the transaction will also remove the trustline.

The transaction supports all the existing "common" fields for a transaction.

Transaction-specific Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	✔️	string	UINT16

Indicates the new transaction type NFTokenMint. The integer value is 30. The recommended name is ttCLAWBACK.

Field Name	Required?	JSON Type	Internal Type
Account	✔️	string	ACCOUNT ID

Indicates the account which is 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 oustanding balance (i.e. 'owes' the issued asset) that it wishes to claw back.

---

Field Name	Required?	JSON Type	Internal Type
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 is not an error if the amount is zero; in this case, the transaction does not claw back any funds but may adjust flags, as indicated by the Flags field.

It is an error if the counterparty listed in Amount is the same as the Account issuing this transaction; the transaction should fail execution with temBAD_AMOUNT.

---

Field Name	Required?	JSON Type	Internal Type
Flags	✔️	number	UINT32

Specifies the flags for this transaction. The universal transaction flags that are applicable to all transactions (e.g., tfFullyCanonicalSig) are valid. This proposal introduces the following new, transaction-specific flags:

Flag Name	Flag Value	Description
tfClawbackClearAuth	0x00000001	If set, either the lsfHighAuth or lsfLowAuth flag (as appropriate) will be removed from the trust line. It is not an error to request to clear a flag that isn't set.
tfClawbackFreeze	0x00000002	If set, either the lsfHighFreeze or lsfLowFreeze flag (as appropriate) will be set in the trust line. It is not an error to request to set a flag that isn't set.
tfClawbackThaw	0x00000004	If set, either the lsHighFreeze or lsfLowFreeze flaf (as appropriate) will be removed from the trust line. It is not an error to request to clear a flag that isn't set.

---

Field Name	Required?	JSON Type	Internal Type
Reference		string	UINT256

An optional 256-bit value, serving as a reference to such other data as the issuer deems appropriate to associate with this Clawback operation.

In addition, the issuer can include a memo with the transaction. Care should be taken by issuers since transactions (and therefore the memos included in them) are publicly accessible.

---

Example Clawback transaction

{
  "TransactionType": "Clawback",
  "Account": "rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S",
  "Amount": "LimitAmount": {
      "currency": "FOO",
      "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
      "value": "314.159"
    },
  "Flags": 2147483659,
  "Fee": 10,
  "Memos": [
        {
            "Memo": {
                "MemoType": "526561736f6e",
                "MemoData": "5468697320636c61776261636b2077617320617574686f72697a6564206279204a6f652e"
            }
        }
    ],
}

Execution

In executing, this transaction would claw back at most 314.159 FOO issued by rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S and held by rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW. If rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW did not have a trustline set up or that trustline was set to 0 then the error tecNO_LINE would be returned and a fee would be consumed.

1.3. Account Root modifications

This proposal introduces 1 additional flas for the Flags field of AccountRoot:

Flag Name	Flag Value
lsfNoClawback	0x02000000

1.3.1 lsfNoClawback

Issuers may wish to disclaim the ability to claw back assets. They can do so by setting this flag using the AccountSet transaction, which should be augmented to allow the flag to be set. Like the lsfNoFreeze flag, once set the lsfNoClawback flag cannot be unset.

1.4 Amendment

This transaction will require an amendment. The proposed name is XLS-39-Clawback.

[Mwni]

1. What is the reason for the auth and freeze modification flags? Can't this be done with a regular TrustSet?
2. Why should there be the Reference field when this could be put into a memo instead?

[nbougalis]

1. Sometimes it may be convenient to perform a group of operations atomically. In the absence of a "Multi-Transaction Transactor" (I have ideas on that!) the easiest way is to add support for some common-sense operations that are likely to be "bundled" together. By way of example, an issuer may be legally compelled to claw back a particular amount, but may also want to freeze the trust line out of an abundance of caution. Or, after initially freezing a trust line and investigating, the issuer decides to claw back some amount, and release the freeze.
2. Good question. If all you're looking to store is a small unique identifier, then a 256-bit value (or, really, a 128-bit UUID value) is better because it is encoded more compactly than a memo is. But I'm not opposed to changing Reference to be a 128-bit value or eliminating altogether.

[Mwni]

Agreed on (1). But it's better to name these flags identical to the ones known from TrustSet. Namely tfClearAuth, tfSetFreeze and tfClearFreeze, to signal that these are identical operations. On (2), given how flexible the memo field is, the Reference field appears redundant.

[intelliot]

Agree with @Mwni : the Reference field should be removed from this spec, because it is unnecessary and redundant. Instead, there should be a Memo standard where the same reference data can be captured in a memo in a standardized way. The Reference Memo standard can be part of XLS-39, or it could be a separate spec - either way is fine.

[shawnxie999]

@intelliot could you elaborate on what you mean by capturing memo in a standardized way? What kind of change needs to be done with the existing Memo field?

[intelliot]

A spec needs to specify the format of the data that goes in the Memos. The Memos field is general and allows any arbitrary data to be stored. If that's fine, then you can leave it alone. But I think it is more likely that you'll want to specify a standard so that users and automated systems know how to interpret the data.

https://xrpl.org/transaction-common-fields.html#memos-field

For example, if you want to say that the MemoType must be Reference, then put that in a spec. Similarly, should the MemoData be a 256-bit value, a 128-bit UUID value, or something else? Also, how should it be encoded?

[dangell7]

I like this. I'm curious how this would work for the more advanced IOU functionality? Things like Escrow, PayChan and/or AMM (assuming they are passed).

[shawnxie999]

AFAIK, escrow and payment channels are only for XRP.

[ckniffen]

@shawnxie999 for now but there is a PR for an amendment to add support

[shawnxie999]

@ckniffen do you have a link to the proposal or PR?

[shawnxie999]

nevermind i found it

[shawnxie999]

Just briefly read through XLS-34, I don't think it will cause any conflict with the Clawback functionality. However, after XLS-34 is live, Clawback won't be able to to claw back the funds that are locked in Escrow or Payment Channel. And if clawing back the funds that are locked is something that we want, then we would need to re-assess this option in more depth and have the feature update be part of another amendment after XLLS-34 goes live

[WietseWind]

I think the selected text below should not be NFTokenMint 😇 ?

[nbougalis]

Oops, yes.

[ledhed2222]

LOL @nbougalis stockholm syndrome?

[WietseWind]

I'd like to propose an inverted flag: instead of disabling Clawback ability as an issuer with lsfNoClawback, have issuers enable explicitly with lsfAllowClawback, which can be set once.

I think this is a better way to grandfather in existing issuances / issuer accounts. This way existing issuers can only enable it once. Blackholed accounts used to issue tokens instead of IOUs cannot enable. Otherwise blackholed accounts will forever show as being able to Clawback, which may worry users. While they can't (blackholed), showing the issuing account as being able to is confusing.

Opposed to showing the existing (blackholed) accounts cannot Clawback, and also: cannot enable (blacholed).

[WietseWind]

Alternatively the default state of the clawback could be based on the freeze setting. If issuer already set NoFreeze, they automatically get NoClawback.

[nbougalis]

Alternatively the default state of the clawback could be based on the freeze setting. If issuer already set NoFreeze, they automatically get NoClawback.

The challenge with that is that we can't go adjusting all AccountRoot objects to set the right flag when the amendment activates. Which leaves us with the option I mentioned earlier:

when the lsfNoFreeze flag is set, the lsfNoClawback flag becomes implicit. That is:

bool canClawback(std::uint32_t flags)
{
   return (flags & (lsfNoFreeze | lsfNoClawback) == 0);
}

[mDuo13]

I think I'm on board with redefining the NoFreeze flag to encompass clawback operations. Even though they're slightly different powers, they serve the same goals (regulatory compliance) and it seems to me that most people who want to have or give up one feature would make the same choice with the other one: either you want a "bank like" token with both clawback and freeze capabilities, or you want a "cash like" token with neither.

[WietseWind]

Ah sorry @nbougalis - you are right, your return (flags & (lsfNoFreeze | lsfNoClawback) == 0) does the trick indeed.

I second @mDuo13.

[shawnxie999]

I think incorporating clawback into freeze flag gives more flexibility to the issuer. Freeze allows the issuer to toggle clawback on/off on the trustline level as opposed to a lsfNoClawback that is on the account level. The current proposal grants everyone on the ledger the ability to clawback by default, and I don't think it is a good design to expose such a feature that is made specific for regulatory compliance to be enabled by default. Also I think forcing the issuer to freeze the trustline before clawing back is a good safety measure since clawback is an action that should be used with caution. So I definitely think that using the freeze flag to enable/disable clawback is really good from a safety measure perspective as well as from a design perspective.

If an account has set lsfNoFreeze flag, they probably don't care about clawback either since they have no intention of enforcing regulatory compliance

[mDuo13]

The Reference field seems functionally very similar to the InvoiceID field of Payments. I guess that's intentional? Unfortunately InvoiceID is not quite the right name for this scenario, but we could still reuse the InvoiceID field here. (There is precedent for doing this anyway with Escrows' OfferSequence field.)

The tantalizing thing is that the canonical/binary format does not have a particular attachment to the fields' names, so it should be possible to implement aliases for field names. It's totally plausible we could reuse the field ID for InvoiceID but change the name in JSON, with no effects on the p2p network and how it processes the existing field—it would be harder to do this while maintaining backwards compatibility with client apps, though—you'd have to make the mapping of field name↔ID sensitive to the context of what transaction type it's in. (I know we previously talked about doing something like this by renaming the Amount field of Payments to DeliverMax, and nothing came of it; that's even more difficult because Amount is used in several transaction types and contexts.)

I would even consider changing the field name to be Reference and making it a common field of all transactions so we don't have to worry about the need for this coming up on more transactions. I bet the community could find more uses for an arbitrary Reference ID that any transaction can include: for example, maybe a Hook could trigger a specific event when receiving a transaction with a hash matching the ID, or you could use the Reference with PaymentChannelClaim to reference a receipt or something that exhaustively lists what the Claims have been redeemed for, or something else like that.

I guess in the end it only matters if we're concerned about running out of 256-bit "uncommon field" IDs. If we aren't, it's not necessary to reuse identifiers across transactions, but it does feel like this scenario is niche enough that might be worth the awkwardness of "InvoiceID" as a field name to conserve more IDs for the future. We're not that close to running out of 256-bit fields yet, but they are one of the types we have the most of (second only to UInt32's) so it might be a prudent bit of future-proofing.

[WietseWind]

I agree @ Reference being a much better name than InvoiceID. The field is being used though, so it could be a pretty tricky breaking change for some. But one worth it, imo. With the relatively low amount of use it would probably even be easy to track down the parties using it & informing them.

[mDuo13]

Another understated detail of this proposal is that it adds a way to disable the Auth flag of a trust line. Currently there is no way to revoke authorization of a trust line. I'm still not sure why it was designed that way, but I'm fairly certain it was a choice. Maybe @JoelKatz or someone can clarify why.

In the absence of a counterargument I'm fine with adding that ability to clawbacks, but for consistency I think it would also make sense to modify TrustSet to add a flag to remove auth from a trust line too. (If this is controversial, maybe that flag should also be locked away if have No Freeze turned on.)

[shawnxie999]

Clear auth flag more seems like something that should belong to the TrustSet than Clawback. Not quite sure why this flag is included in this spec at all

[shawnxie999]

my recommendation is to leave out the clear auth flag from this spec. If we think this is something that should be added, it should be a separate change by itself, where TrustSet is updated and then Clawback if applicable

[shawnxie999]

I have updated the updated version of this spec in this pull request

The major change from the original spec here is that Clawback is made completely to be an extension of freeze, such that a trustline can only be clawed back if and only if the trustline has been frozen. Because of this, the lsfNoClawback flag is removed from the AccountRoot.

It's still open to whether we still want to keep this flag or not, but I think for the sake of good design, both clawback and freeze should be bundled together as they are related for compliance. In a real world use case, token holder's trustline will be frozen first, then the issuer has the option to claw back from them.