0077 XLS-77d Deep Freeze

[shawnxie999]

Title:       XLS-77d Deep-freeze
Type:        draft
Revision:    3 (2024-10-25)
Author:      Shawn Xie
Affiliation: Ripple

Deep-freeze

Abstract

This amendment empowers token issuers on the XRP Ledger to prevent token misuse by frozen account holders. The document outlines enhancements to the interactions between frozen assets and payments, ensuring that frozen token holders cannot receive funds until or unless their trustline is unfrozen. These changes will enable token issuers to more easily comply with regulations on the XRPL. For example, prevent tokens from flowing to wallets identified on sanctions lists, thereby enhancing regulatory compliance for use cases such as regulated stablecoins and real-world assets (RWA).

1. Overview

This proposal introduces a new deep-freeze feature for the trustlines that interacts with payment, offers, DEX and AMM. In essence, issuers can block sending and receiving of funds for holders who have been deep-frozen.

2. Specification

2.1. Deep-freeze Mechanism

The Deep-freeze feature is a setting on a trust line and requires that the issuer must have "regularly frozen" the trust line before they can enact a deep-freeze. The issuer cannot enact a deep-freeze if they have enabled No Freeze on their account.

When an issuer enacts Deep-freeze, the following rules apply to the tokens in that trust line:

• Payments can still occur directly between the two parties of the deep-frozen trust line.
• The counterparty of that trust line can no longer increase or decrease its balance on the deep-frozen trust line, except in direct payments to the issuer. The counterparty can only send the deep-frozen currencies directly to the issuer.
• The counterparty can neither send nor receive from others on the deep-frozen trustline
• The counterparty's offers to buy or sell the tokens in the deep-frozen trustline are considered unfunded

An individual address can deep-freeze its trust line to an issuer or financial institution. This has no effect on transactions between the institution and other users. However it does the following:

• It prevents other addresses from sending that financial institution's tokens to the individual address.
• It also prevents the individual address from sending the token to other non-issuer addresses.

2.1.1. RippleState Object

Two new flags lsfLowDeepFreeze and lsfHighDeepFreeze are introduced in the RippleState (trustline) object.

Flag Name	Flag Value	Description
lsfLowDeepFreeze	0x02000000	The low account has deep-frozen the trust line, preventing the high account from sending and receiving the asset.
lsfHighDeepFreeze	0x04000000	The high account has deep-frozen the trust line, preventing the low account from sending and receiving the asset.

2.1.2. TrustSet Transaction

Two new flags tfSetDeepFreeze and tfClearDeepFreeze are introduced in the TrustSet transaction.

Flag Name	Flag Value	Description
tfSetDeepFreeze	0x00400000	Deep freeze the trust line.
tfClearDeepFreeze	0x00800000	Clear the deep-freeze on the trust line.

The TrustSet transaction trying to set tfSetDeepFreeze will succeed if and only if one of the following is true:

• The holder is already frozen, indicated by lsfLowFreeze/lsfHighFreeze on the trust line.
• tfSetFreeze is also set in the same TrustSet transaction.

The TrustSet also introduces an additional restriction:

• If the trust line is deep-frozen by the issuer (indicated by lsfLowDeepFreeze/lsfHighDeepFreeze), the TrustSet transaction fails if the issuer sets the tfClearFreeze flag without also setting the tfClearDeepFreeze flag. In other words, the issuer cannot clear the regular freeze on a trust line unless they also clear the deep-freeze.

2.2. Payment Engine

Payment engine executes paths that is made of steps to connect the sender to the receiver. In general, funds can be deposited into a trustline through one of two steps:

• Rippling
• Order book or AMM

This proposal proposes changes to both steps above to ensure a deep-frozen trustline cannot increase its balance.

2.2.1. Rippling

This proposal suggests an update: the receipt of funds in a deep-frozen trust line as a result of a rippling step will fail.

Example

Let's take a look at an example of how deep-freeze impacts rippling:

+-------+           USD           +---------+           USD           +-------+
| Alice | ----------------------> | Gateway | ----------------------> |  Bob  |
+-------+                         +---------+ (Bob is deep-frozen)    +-------+

Consider the following scenario:

1. Issuer account issues USD to both Alice and Bob, each of which has a trustline.
2. Issuer deep-freezes Bob's trustline by submitting a TrustSet with tfSetFreeze and tfSetDeepFreeze flags.
3. Alice attempts to send a USD Payment to Bob. The transaction fails because Bob's USD trustline has been deep-frozen and can no longer receive funds.

2.2.2. Order Book and AMM

In the payment engine, offers and AMM pools can be consumed in the path when a cross-currency payment is involved, resulting in a change to the trustline balance. This proposal introduces behavior changes to the order book step when trustlines have been deep-frozen.

2.2.2.1. Order Book

This proposal introduces a change to the order book step: if the offer owner has been deep-frozen for the TakerPays token (buy amount), the offer is considered to be unfunded and the step fails.

Example

Let's take a look at an example of how deep-freeze impacts order book:

                                                                 Bob's Offer
+-------+         USD            +---------+        USD       +--------------+      XRP     +-------+
| Alice | ---------------------> | Gateway | ---------------> | Sell: 100 XRP| -----------> | Carol |
+-------+     SendMax: 100 USD   +---------+                  +--------------+              +-------+
              Amount: 100 XRP                                 | Buy: 100 USD |       
                                                              +--------------+
                                                            (Bob is deep-frozen)                             

Consider the following scenario:

1. Issuer account issues USD to both Alice and Bob, each of which has a trustline.
2. Issuer deep-freezes Bob's trustline by submitting a TrustSet with tfSetFreeze and tfSetDeepFreeze flags.
3. Alice attempts to send XRP to Carol through a Payment transaction using Bob's offer to exchange USD for XRP. Alice fails to send XRP to Carol because Bob's offer is unfunded due to the deep-frozen trustline.

2.2.2.2. AMM

The AMM step does not require any changes because, currently, an AMM step fails if the AMM account is frozen for any involved asset. Since a deep-frozen asset would already be regularly frozen, no additional checks are needed when an asset is deep-frozen.

2.3. OfferCreate transaction

This proposal introduces a new change to the OfferCreate transaction:

• OfferCreate returns tecFROZEN if the TakerPays (buy amount) token has been deep-frozen by the issuer

Moreover, any existing offers where the owner has been deep-frozen on the TakerPays token can no longer be consumed and will be considered as an unfunded offer that will be implicitly cancelled by new Offers that cross it.

2.4. AMMWithdraw transaction

This proposal does not need to change the AMMWithdraw transaction due to the deep-freeze, as all deep-frozen tokens have already been regularly frozen, preventing the withdrawal of either regularly frozen or deep-frozen tokens.

3. Invariants

Possible invariants:

• Disallowing any increase in the balance of an deep-frozen trustline as a result of any type of transaction.
• A trust line cannot have the lsfLowDeepFreeze flag set without also having the lsfLowFreeze flag set, and the same applies to the lsfHighDeepFreeze flag.

4. FAQ

Why can't we embed the disallow-receiving into the existing freeze without introducing a new flag?

Altering the existing freeze functionality to disallow receiving would be a significant breaking change, potentially disrupting the workflows of current users. Instead, it is preferable to introduce a configurable flag, offering additional flexibility without affecting the existing behavior.

Why can't this be a separate feature named "block-receiving"?

The block-receiving feature shares similarities with the existing freeze functionality, as both aim to prevent unauthorized or blacklisted parties from transferring funds. Creating it as a separate feature would introduce unnecessary complexities, such as the need to add a new account-level flag to toggle the feature. Integrating it into the existing framework avoids these complications while maintaining consistency.

How does MPT freeze/lock behavior differ from IOU?

The MPT freeze/lock functionality differs somewhat from how IOUs work today. When an MPT holder is locked, they cannot send or receive MPT payments, so a single flag is sufficient. In contrast, for IOUs, the regular freeze only disallows sending. If the issuer wants to block receiving as well, they must apply a deep-freeze.

[WietseWind]

Thanks for the proposal!

Considering the title: may I propose that we change "blackholing" to "Permafrosting"? 😬

[tequdev]

Are there any usecases issuer sets only tfSetFreeze after this amendments enabled?

[shawnxie999]

In most scenarios, setting only tfSetFreeze is sufficient to meet compliance requirements and prevent transferring funds. But, there might be some rare scenarios or compliance needs where a deep-freeze is needed to ensure a blacklisted account can no longer receive or send funds.

[ckeshava]

Prior to this proposal, a regularly-frozen trust line can still recieve the (the frozen) IOU. However, the sanctioned counter-party cannot sell it. So, the sanctioned account could keep accumulating the IOUs and eventually send it back to the issuing address. Is this an accurate description of the workflow? Are there any other implications ?

[sappenin]

@shawnxie999 Is this one pretty baked? If so, want to open a PR for this one? (consider something like this comment if you want).

[shawnxie999]

Per the new XLS Contributing process, it is my opinion that we have reached a "well-refined standard."

As such, I propose that we move this discussion to a file (via #260) and work on final changes using additional PRs, for better change-tracking.

Please comment here if you would like to object to moving this spec/discussion forward in the process into a DRAFT spec.

(Note that per the Contributing guidelines, moving a spec into the DRAFT state does not mean any kind of endorsement, nor does it mean that this specification will become adopted. It is solely meant as a mechanism to enable better change tracking using PRs.)

[ckeshava]

1. GlobalFreeze applies to all the tokens issued by an address, whereas deep-freeze can be tailored for individual trust lines.

GlobalFreeze suspends all Offers from selling the IOU under consideration. However, Offers which want to buy the IOU could still successfully complete. This is also a difference in behavior compared to DeepFreeze. Is this comparison accurate ?

2. If an individual address enables deep-freeze on its trust line with a financial institution, what are the implications on the relevant Offers? The regular-freeze feature does not impact Offers in this circumstance. Please see third paragraph from the end in this section: https://xrpl.org/docs/concepts/tokens/fungible-tokens/freezes#individual-freeze

3. Although the implementation has accounted for Check feature, the spec does not make a mention of Checks. This proposal modifies the behavior of CheckCreate and CheckCash transactions, is that right?

[ckeshava]

Regarding point-2, it appears that DeepFreeze differs from RegularFreeze whilst handling Offers. This is based on this implementation file: https://github.com/XRPLF/rippled/pull/5187/files#diff-aaa8dff0ed4bb7864a9d2aa7410ae8bde37b4ca91c7594413ab5691c0964e8e5

[shawnxie999]

1. Have you tested this scenario where offers can still buy an IOU despite being globally frozen? I don't believe this is possible because when an offer tries to buy an IOU, there will always involve someone trying to sell, which should always fail.
2. It means the individual address can no longer transfer IOU with other holders. However, in the real world a holder should never be able to freeze the issuer.
3. Yes, it should prohibit cashing a check if the IOU is deep frozen. Spec needs to be updated

[vvysokikh1]

1. As far as current implementation goes, when global freeze is enacted, it is not possible at all to create new offers involving a globally frozen asset. So technically it's not possible to cross such existing offers.

[ckeshava]

1. No, I have not tested it. I'm basing my understanding off the documentation. I understand your point 👍
2. Yes, I understand that. If an individual address deep-freezes a trust-line with an issuer, then all the outstanding offers for that specific IOU will become unfunded. This behavior is different with the regular-freeze, I wanted to clarify this aspect.
3. Alright, so only CheckCash transaction could throw an error with regards to a deep-frozen trust line. CheckCreate and CheckCancel do not throw any tecFROZEN errors. Is that correct ?

[shawnxie999]

2. Would be good to clarify with @vvysokikh1. I forgot what the behavior is when an individual address regular-freezes the issuer (doc may not necessarily be correct)
3. Yes, that's the decision for now. Only CheckCash is important to prevent transfer of funds.