Skip to content

Commit b454b3d

Browse files
committed
Merge branch 'rippled-2.4.0' of https://github.com/XRPLF/xrpl-dev-portal into rippled-2.4.0
2 parents 3b72641 + 9f56612 commit b454b3d

File tree

6 files changed

+92
-1
lines changed

6 files changed

+92
-1
lines changed
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
blurb: Deep Freeze ensures that frozen token holders can neither send nor receive frozen funds until their trust line is unfrozen.
3+
labels:
4+
- Tokens
5+
- Freeze
6+
- Deep Freeze
7+
---
8+
# Deep Freeze
9+
10+
Deep Freeze lets token issuers on the XRP Ledger prevent token misuse by frozen account holders. It enhances interactions between frozen assets and payments, ensuring that frozen token holders cannot receive funds until or unless their trust line is unfrozen. These changes enable token issuers to more easily comply with regulations on the XRPL. For example, it prevents 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).
11+
12+
Deep Freeze impacts trust lines that interact with payments, offers, DEX, and AMM. Issuers can block sending and receiving of funds for holders in deep freeze.
13+
14+
## Deep Freeze Mechanism
15+
16+
Deep Freeze is a setting on a trust line. It requires that the issuer implement a standard freeze on the trust line before enacting a deep freeze. The issuer cannot enact a deep freeze if they have enabled `No Freeze` on their account.
17+
18+
When an issuer enacts a deep freeze, the following rules apply to the tokens in that trust line:
19+
20+
- Payments can still occur directly between the two parties of the deep-frozen trust line.
21+
- 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.
22+
- The counterparty can neither send nor receive from others on the deep-frozen trust line.
23+
- The counterparty's offers to buy or sell the tokens in the deep-frozen trust line are considered unfunded.
24+
25+
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:
26+
27+
- It prevents other addresses from sending that financial institution's tokens to the individual address.
28+
- It also prevents the individual address from sending the token to other non-issuer addresses.
29+
30+
### RippleState Object
31+
32+
Deep Freeze introduces two flags, `lsfLowDeepFreeze` and `lsfHighDeepFreeze`, in the `RippleState` (trust line) object.
33+
34+
| Flag Name | Flag Value | Description |
35+
|-----------|-------------|-------------|
36+
| `lsfLowDeepFreeze` | `0x02000000` | The low account has deep-frozen the trust line, preventing the high account from sending and receiving the asset. |
37+
| `lsfHighDeepFreeze` | `0x04000000` | The high account has deep-frozen the trust line, preventing the low account from sending and receiving the asset. |
38+
39+
See [High vs. Low Account](../../../references/protocol/ledger-data/ledger-entry-types/ripplestate.md#high-vs-low-account).
40+
41+
### TrustSet Transaction
42+
43+
Deep Freeze introduces two flags, `tfSetDeepFreeze` and `tfClearDeepFreeze`, in the `TrustSet` transaction.
44+
45+
| Flag Name | Flag Value | Description |
46+
|-----------|-------------|-------------|
47+
| `tfSetDeepFreeze` | `0x00400000` | Deep freeze the trust line. |
48+
| `tfClearDeepFreeze` | `0x00800000` | Clear a deep-freeze on the trust line. |
49+
50+
A `TrustSet` transaction trying to set `tfSetDeepFreeze` succeeds if and only if one of the following is true:
51+
52+
- The holder is already frozen, indicated by `lsfLowFreeze`/`lsfHighFreeze` on the trust line.
53+
- `tfSetFreeze` is also set in the same `TrustSet` transaction.
54+
55+
Deep Freeze introduces an additional restriction on `TrustSet`:
56+
57+
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 without also clearing the deep freeze.
58+
59+
## Payment Engine
60+
61+
Payment Engine executes paths that are made of steps to connect the sender to the receiver. In general, funds can be deposited into a trust line through one of two steps:
62+
63+
- [Rippling](#rippling)
64+
- [Order book or AMM](#order-book)
65+
66+
### Rippling
67+
68+
Receipt of funds in a deep-frozen trust line as a result of a rippling step will fail.
69+
70+
### Order Book
71+
72+
If an offer owner is deep-frozen for the `TakerPays` token (buy amount), any offer is considered to be unfunded and the offer fails.
73+
74+
## OfferCreate transaction
75+
76+
Deep Freeze requires a change to the `OfferCreate` transaction:
77+
78+
`OfferCreate` returns `tecFROZEN` if the `TakerPays` (buy amount) token has been deep-frozen by the issuer.
79+
Moreover, any existing offers where the owner has been deep-frozen on the `TakerPays` token can no longer be consumed. It is considered an unfunded offer that is implicitly cancelled by new offers that cross it.
80+
81+
## How does MPT freeze/lock behavior differ from IOU?
82+
83+
The Multi-Purpose Token (MPT) freeze/lock functionality differs somewhat from how IOUs work. When an MPT holder is locked, they cannot send or receive MPT payments, so a single flag is sufficient.
84+
85+
For IOUs, the regular freeze only disallows sending. If the issuer wants to block receiving as well, they must apply a deep freeze.

docs/concepts/tokens/fungible-tokens/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ In addition to the shared balance, each account has its own settings on the trus
5252
- **Authorized**: A true/false value used with [Authorized Trust Lines](authorized-trust-lines.md) to allow the other side to hold tokens this account issues. The default is `false`. Once set to `true`, this cannot be changed back.
5353
- **No Ripple**: A true/false value to control whether tokens can [ripple](rippling.md) through this trust line. The default depends on the account's "Default Ripple" setting; for new accounts, "Default Ripple" is off which means that `true` is the default for No Ripple. Usually, issuers should allow rippling and non-issuers should disable rippling unless they are using trust lines for community credit.
5454
- **Freeze**: A true/false value indicating whether an [individual freeze](freezes.md#individual-freeze) is in effect on this trust line. The default is `false`.
55+
- **DeepFreeze**: A true/false value indicating whether a [deep freeze](deep-freeze.md) is in effect on this trust line. The default is `false`.
5556
- **Quality In** and **Quality Out** settings, which allow the account to value tokens issued by the other account on this trust line at less (or more) than face value. For example, if a stablecoin issuer charges a 3% fee for withdrawing tokens for the equivalent off-ledger assets, you could use these settings to value those tokens at 97% of face value. The default, `0`, represents face value.
5657

5758

docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,8 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e
8080
| `lsfHighNoRipple` | `0x00200000` | 2097152 | `tfSetNoRipple` | The high account [has disabled rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) from this trust line. |
8181
| `lsfLowFreeze` | `0x00400000` | 4194304 | `tfSetFreeze` | The low account has frozen the trust line, preventing the high account from transferring the asset. |
8282
| `lsfHighFreeze` | `0x00800000` | 8388608 | `tfSetFreeze` | The high account has frozen the trust line, preventing the low account from transferring the asset. |
83+
| `lsfLowDeepFreeze` | `0x02000000` | 33554432 |`tfSetLowDeepFreeze` | The low account has deep-frozen the trust line, preventing the high account from sending and receiving the asset. |
84+
| `lsfHighDeepFreeze` | `0x04000000` | 67108864 | `tfSetHighDeepFreeze` | The high account has deep-frozen the trust line, preventing the low account from sending and receiving the asset. |
8385

8486
The two accounts connected by the trust line can each change their own settings with a [TrustSet transaction][].
8587

docs/references/protocol/transactions/types/offercreate.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ Transactions of the OfferCreate type support additional values in the [`Flags` f
7070
| `temBAD_CURRENCY` | Occurs if the transaction specifies a token with the currency code "XRP". |
7171
| `temBAD_ISSUER` | Occurs if the transaction specifies a token with an invalid `issuer` value. |
7272
| `tecNO_ISSUER` | Occurs if the transaction specifies a token whose `issuer` value is not a funded account in the ledger. |
73-
| `tecFROZEN` | Occurs if the transaction involves a token on a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) trust line (including local and global freezes). |
73+
| `tecFROZEN` | Occurs if the transaction involves a token on a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) trust line (including local and global freezes). Occurs if the `TakerPays` (buy amount) token has been deep-frozen by the issuer. |
7474
| `tecUNFUNDED_OFFER` | Occurs if the owner does not hold a positive amount of the `TakerGets` currency. (Exception: if `TakerGets` specifies a token that the owner issues, the transaction can succeed.) |
7575
| `tecNO_LINE` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the necessary trust line does not exist. |
7676
| `tecNO_AUTH` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the the trust line that would receive the tokens exists but has not been authorized. |

docs/references/protocol/transactions/types/trustset.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@ Transactions of the TrustSet type support additional values in the [`Flags` fiel
5858
| `tfClearNoRipple` | `0x00040000` | 262144 | Disable the No Ripple flag, allowing [rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) on this trust line. |
5959
| `tfSetFreeze` | `0x00100000` | 1048576 | [Freeze](../../../../concepts/tokens/fungible-tokens/freezes.md) the trust line. |
6060
| `tfClearFreeze` | `0x00200000` | 2097152 | [Unfreeze](../../../../concepts/tokens/fungible-tokens/freezes.md) the trust line. |
61+
| `tfSetDeepFreeze` | `0x00400000` | 4194304 | [Deep Freeze](../../../../concepts/tokens/fungible-tokens/deep-freeze.md) the trust line. |
62+
| `tfClearDeepFreeze` | `0x00800000` | 8388608 | Clear the [Deep Freeze](../../../../concepts/tokens/fungible-tokens/deep-freeze.md) on the trust line. |
6163

6264
If a transaction tries to enable No Ripple but cannot, it fails with the result code `tecNO_PERMISSION`. Before the [fix1578 amendment][] became enabled, such a transaction would result in `tesSUCCESS` (making any other changes it could) instead.
6365

sidebars.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@
115115
- page: docs/concepts/tokens/fungible-tokens/multi-purpose-tokens.md
116116
- page: docs/concepts/tokens/fungible-tokens/clawing-back-tokens.md
117117
- page: docs/concepts/tokens/fungible-tokens/freezes.md
118+
- page: docs/concepts/tokens/fungible-tokens/deep-freeze.md
118119
expanded: false
119120
items:
120121
- page: docs/concepts/tokens/fungible-tokens/common-misconceptions-about-freezes.md

0 commit comments

Comments
 (0)