Skip to content

Minor changes to TokenEscrow specification #292

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 3, 2025
Merged

Minor changes to TokenEscrow specification #292

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
49dfef5
Update README.md
dangell7 Jun 26, 2025
b8d36bd
Update README.md
dangell7 Sep 8, 2025
ca058c4
Merge branch 'master' into fix-escrow-spec
dangell7 Sep 8, 2025
bfe8b9c
format
dangell7 Sep 8, 2025
d152b31
Update README.md
dangell7 Sep 8, 2025
303531d
Merge branch 'master' into fix-escrow-spec
dangell7 Oct 3, 2025
e132805
Merge branch 'master' into fix-escrow-spec
dangell7 Oct 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 11 additions & 12 deletions XLS-0085-token-escrow/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,10 +45,9 @@ This amendment extends the functionality of escrows to support both IOUs and MPT

The `EscrowCreate` transaction is modified as follows:

| Field | Required? | JSON Type | Internal Type | Description |
| ------------- | --------- | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Amount` | Yes | Object or String | Amount | The amount to deduct from the sender's balance and and set aside in escrow. Once escrowed, this amount can either go to the Destination address (after any `Finish` times/conditions) or returned to the sender (after any cancellation times/conditions). Can represent [XRP, in drops](https://xrpl.org/docs/references/protocol/data-types/basic-data-types#specifying-currency-amounts), an [IOU](https://xrpl.org/docs/concepts/tokens/fungible-tokens#fungible-tokens) token, or an [MPT](https://xrpl.org/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens). Must always be a positive value. |
| `CancelAfter` | False | Number | UInt32 | (Optional) The time, in seconds since the Ripple Epoch, when this escrow expires. This value is immutable; the funds can only be returned to the sender after this time. Required when creating an Escrow with IOU or MPT |
| Field | Required? | JSON Type | Internal Type | Description |
| -------- | --------- | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Amount` | Yes | Object or String | Amount | The amount to deduct from the sender's balance and and set aside in escrow. Once escrowed, this amount can either go to the Destination address (after any `Finish` times/conditions) or returned to the sender (after any cancellation times/conditions). Can represent [XRP, in drops](https://xrpl.org/docs/references/protocol/data-types/basic-data-types#specifying-currency-amounts), an [IOU](https://xrpl.org/docs/concepts/tokens/fungible-tokens#fungible-tokens) token, or an [MPT](https://xrpl.org/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens). Must always be a positive value. |

**Failure Conditions:**

Expand Down Expand Up @@ -78,7 +77,7 @@ The `EscrowCreate` transaction is modified as follows:

- **Adjustment from Source to Issuer:**
- **IOU Tokens**: The escrow `Amount` is deducted from the source's trustline balance.
- **MPTs**: The escrow `Amount` is deducted from the source's MPT balance. The `sfOutstandingBalance` of the MPT issuance remains unchanged. The `sfEscrowAmount` is increased on both the source's MPT and the MPT issuance.
- **MPTs**: The escrow `Amount` is deducted from the source's MPT balance. The `sfOutstandingBalance` of the MPT issuance remains unchanged. The `sfLockedAmount` is increased on both the source's MPT and the MPT issuance.
- **Escrow Object Creation:**
- The `Escrow` ledger object includes:
- `CancelAfter`: When the Escrow Expires (Required on IOU/MPT)
Expand Down Expand Up @@ -117,16 +116,16 @@ The `EscrowCreate` transaction is modified as follows:
- **IOU Tokens**: The escrow `Amount` is added to the destination's trustline balance.
- **MPTs**:
- If the escrow sender is the issuer of the asset that was escrowed and the destination is not the issuer, then:
1. The `EscrowedAmount` on the `MPTokenIssuance` of the asset that was held in escrow is decreased by `Amount`.
1. The `LockedAmount` on the `MPTokenIssuance` of the asset that was held in escrow is decreased by `Amount`.
2. The `Amount` on the destination's `MPToken` is increased by the escrow's `Amount`.
3. The `OutstandingAmount` on the `MPTokenIssuance` of the asset that was held in escrow is unchanged.
- If the escrow sender is not the issuer of the asset that was escrowed but the destination is the issuer of the asset, then:
1. The `EscrowedAmount` on the `MPTokenIssuance` of the asset that was held in escrow is decreased by `Amount`.
1. The `LockedAmount` on the `MPTokenIssuance` of the asset that was held in escrow is decreased by `Amount`.
2. No `MPToken` objects are changed because MPT issuers may not hold MPTokens.
3. The `OutstandingAmount` on the `MPTokenIssuance` of the asset that was held in escrow is decreased by `Amount` (i.e., this escrow finish is a "redemption").
- If neither the escrow source nor destination is the issuer of the asset that was escrowed, then
1. The `EscrowedAmount` on the `MPTokenIssuance` of the asset that was held in escrow is decreased by the escrow `Amount`.
2. The `EscrowedAmount` on the source's `MPToken` is decreased by the escrow `Amount`.
1. The `LockedAmount` on the `MPTokenIssuance` of the asset that was held in escrow is decreased by the escrow `Amount`.
2. The `LockedAmount` on the source's `MPToken` is decreased by the escrow `Amount`.
3. The `Amount` on the destination's `MPToken` is increased by the escrow `Amount`.
4. The `OutstandingAmount` on the `MPTokenIssuance` of the asset that was held in escrow is unchanged.
- **Deletion of Escrow Object:**
Expand Down Expand Up @@ -161,7 +160,7 @@ The `EscrowCreate` transaction is modified as follows:
- **MPTs**: If the MPT does not require authorization and the account submitting the transaction is the recipient, then the MPT will be created.
- **Adjustment from Issuer to Source:**
- **IOU Tokens**: The escrow `Amount` is added to the source's trustline balance.
- **MPTs**: The escrow `Amount` is added to the source's MPT balance. The `sfOutstandingBalance` of the MPT issuance remains unchanged. The `sfEscrowAmount` is decreased on both the source's MPT and the MPT issuance.
- **MPTs**: The escrow `Amount` is added to the source's MPT balance. The `sfOutstandingBalance` of the MPT issuance remains unchanged. The `sfLockedAmount` is decreased on both the source's MPT and the MPT issuance.
- **Deletion of Escrow Object:**
- The `Escrow` object is deleted after successful cancellation.

Expand Down Expand Up @@ -210,15 +209,15 @@ The `MPToken` ledger object is updated as follows:

| Field Name | JSON Type | Internal Type | Description |
| ---------------- | --------- | ------------- | -------------------------------------------------------------------- |
| `sfEscrowAmount` | Object | Amount | _(Optional)_ The total of all outstanding escrows for this issuance. |
| `sfLockedAmount` | String | UInt64 | _(Optional)_ The total of all outstanding escrows for this issuance. |

### 1.5.3 `MPTokenIssuance` Ledger Object

The `MPTokenIssuance` ledger object is updated as follows:

| Field Name | JSON Type | Internal Type | Description |
| ---------------- | --------- | ------------- | -------------------------------------------------------------------- |
| `sfEscrowAmount` | Object | Amount | _(Optional)_ The total of all outstanding escrows for this issuance. |
| `sfLockedAmount` | String | UInt64 | _(Optional)_ The total of all outstanding escrows for this issuance. |

### 1.5.4 `AccountRoot` Ledger Object

Expand Down