XLS-85d Token Escrow — Token-Enabled Escrows

[dangell7]

XLS-85d Token Escrow — Token-Enabled Escrows

Title: Token-Enabled Escrows
Type: Draft
Author:
    Denis Angell, XRPL-Labs [dangell7](https://github.com/dangell7)
Contributors:
    Richard Holland, XRPL-Labs [RichardAH](https://github.com/RichardAH)
    Ed Hennis, Ripple [ximinez](https://github.com/ximinez)
Affiliation: XRPL-Labs

This proposal, XLS85d, replaces XLS34d and draws inspiration from #133

Token-Enabled Escrows

The proposed amendment to the XRPL protocol, TokenEscrow, introduces changes to the ledger objects, transactions, and RPC methods to enable Escrows to use Trustline balances.

1. Problem Statement

The XRPL supports several types of on-ledger negotiable instruments, namely: Escrows and Checks. While each of these instruments is implemented as a first-class on-ledger object, only the Check object supports the use of Trustline balances. Escrows support only the native asset XRP. This limitation is a barrier to wider-spread use of these instruments for reasons including:

• Regulatory compliance.
• Unwillingness to hold a counter-party-free asset (i.e., XRP).
• Volatility and exchange-rate risk.

2. Constraints

The amendment has the following constraints:

• Allow Escrows to use Trustline balances.
• Allow Issuers to retain freeze and authorization control over their Issued tokens even when they are escrowed.
• Avoid unnecessary multiplication of on-ledger entities.
• Avoid unnecessarily burdening the ledger computationally.

3. Implementation

An Instrument can only be created over a Trustline balance if both parties (source and destination):

• Are authorized to hold the Trustline.
• Do not have a frozen Trustline for the issuer/currency pair.
• Can ripple the balance through its Issuer.

The destination may not have a Trustline yet. This is not a barrier to creating the Instrument provided that a hypothetical Trustline created at the same time the Instrument is created, from the destination account to the Issuer, for the relevant currency, would meet the above requirements.

3.1. One-Way Account Flag for Issuers

Introduce a new one-way account flag named lsfAllowTokenLocking that issuers can set to opt-in to the Token-Enabled Locking feature. This flag ensures that only issuers who have explicitly enabled this feature can have their issued tokens used within Escrows, enhancing security and compliance.

3.2. New Field: sfTransferRate

The TransferRate field on an Escrow ledger object indicates the current TransferRate at which the funds are escrowed.

• Initialization: Set at the time of instrument creation.
• Updates: Updated on subsequent funding/settlement events.
• Behavior: Always favors the instrument holder. If the TransferRate is better than the current transfer rate for the asset, settlement occurs at the better rate, and vice versa.

3.3. New Field: sfIssuerNode

Add an optional sfIssuerNode field to the Escrow ledger object, similar to the existing sfOwnerNode and sfDestinationNode fields. This field specifies the Issuer node associated with the issued tokens used in the Escrow, enabling better tracking and management of token flows within Escrows.

3.4. Updated sfAmount Logic

The sfAmount field is already the correct type to support Tokens. The only restrictions on it being a Token are within the ledger's logic. Update the logic to allow sfAmount to represent any valid issued token without unnecessary restrictions, thereby facilitating broader use cases for Escrows involving different tokens.

3.5. Escrow Creation and Settlement Logic

• Creation:

  • Subtract the specified amount from the corresponding TrustLine.
  • Set the amount in the new Escrow object, ensuring it is always positive.
  • Account for rounding differences, if any.
  • Add the new Escrow object to the Issuer's directory, similar to how XRP escrows are handled.

• Settlement:

  • Redeeming the Escrow moves the funds to the recipient's TrustLine.
  • If the TrustLine doesn't exist:
    • Creation is only permitted if the sender initiated the transaction.
    • The TrustLine is created with the relevant issuer and currency, ensuring compliance and security.

• Cancellation:

  • If the Escrow is canceled, the amount is returned to the sender's TrustLine.
  • If the TrustLine doesn't exist:
    • Creation is only permitted if the sender initiated the transaction.
    • The TrustLine is created with the relevant issuer and currency, ensuring compliance and security.

3.6. Impact on Trustlines

Issuers can freeze their side of a Trustline with either of the parties involved in the Instrument, preventing the Escrow from being resolved or canceled until the freeze is lifted.

Escrows in any state are a barrier to account deletion. Trustlines associated with active Escrows prevent the deletion of accounts holding those Trustlines.

Issuers can create an Escrow using their own token. The settlement of the Instrument follows the same guidelines as above.

Note: If an Issuer escrows their own token, the sfIssuerNode field will be left empty and the Escrow Object will only be added to the Issuers directory once.

4. Final Documentation & SDK Changes

 

The proposed changes would include modifications to the following ledger objects:

• RippleState
• Escrow

The proposed changes would include modifications to the following transactions:

• EscrowCreate

The proposed changes would include modifications to the following RPC methods:

• account_lines
• account_objects

 

4.1. Ledger Object Changes

 

4.1.2. Escrow Ledger Object

The following fields would be modified or added to the Escrow Ledger Object:

Field Name	JSON Type	Internal Type	Description
Amount	object or string	Amount	The amount to be delivered by the held payment.
TransferRate	number	UInt32	(Optional) The fee to charge when users finish an escrow, initially set on the creation of an escrow contract, and updated on subsequent finish transactions
sfIssuerNode	number	UInt64	(Optional) The Issuer node associated with the Escrow, enabling token-specific escrow management

 

4.2. Transaction Changes

 

4.2.1. EscrowCreate Transaction

The following fields would be modified on the EscrowCreate transaction:

Field	Required?	JSON Type	Internal Type	Description
Amount	Yes/No	object or string	Amount	Amount to deduct from the sender's TrustLine and set aside in escrow. Once escrowed, the amount can either go to the Destination address (after the FinishAfter time) or returned to the sender (after the CancelAfter time). This amount must always be positive.

 

4.3. RPC Method Changes

 

4.3.2. account_objects Method

Each Escrow Object has the following fields updated on the account_objects method:

Field	Type	Internal Type	Description
Amount	object or string	Amount	The amount to be delivered by the held payment.
TransferRate	number	UInt32	The fee to charge when users finish an escrow, initially set on the creation of an escrow contract, and updated on subsequent finish transactions
sfIssuerNode	number	UInt64	(Optional) The Issuer node associated with the Escrow, enabling token-specific escrow management

[xVet]

@dangell7 well done Denis, this is a highly requested feature - as well as Ed and Richard ❤️

Quick question, the transfer fee you mention and carry over to the escrow is the issuer transfer fee we know from IOUs and not a new fee, correct?

[xVet]

@dangell7 well done Denis, this is a highly requested feature - as well as Ed and Richard ❤️

Quick question, the transfer fee you mention and carry over to the escrow is the issuer transfer fee we know from IOUs and not a new fee, correct?

In addition, is the flag able to be set even if tokens have been issued already to allow backwards compatibility or is this only for new issued tokens?

[dangell7]

I don't think this works if we don;t allow already issued tokens to use it. I say allow to be set and unset at any time. Unsetting would remove the ability to create new escrows but should not effect already escrowed tokens.

[xVet]

One last thing - should the transfer rate not also be described as "(Optional)" ? Not all tokens have it and therefore not all escrows will.

[dangell7]

It's an optional field indeed. On Token escrows if there is no transfer rate we were/are storing the parity rate. So right now every Token Escrow will have a TransferRate but I can just as well remove that as its not 100% necessary. Thanks for pointing that out.

[xVet]

Thanks! Appreciate the time you put into this 🙏

[KhaledElawadi]

Like it !

Would prefer to add more programmability/functionality to the Escrow protocol though by enabling direct services such as "Escrow to AMM" and "Escrow to Listed Accounts".

The former would be useful for things like programmed token release/distribution to AMM and timed airdrop/incentives/rewards to AMM LP'ers and the latter for scheduled push payments to individuals/multiple accounts to accommodate things like Direct Debit and Loan/Mortgage repayments etc.

[tequdev]

I don't know much about MPToken, but could this support MPToken as well?