XLS 85d: Token Escrow (XRPLF#3027)

* XLS-85d: Token Escrow -- Implementation for xrpl.js; This commit includes models, unit-tests and integ-tests for the associated transactions

* specify TokenEscrow in the rippled.cfg file

* variable renaming in the escrowCreate integ tests

* remove references to wallet1 in escrowCreate integ tests

* rename useBase10 function as isBase10 method

---------

Co-authored-by: Mayukha Vadari <mvadari@gmail.com>
Co-authored-by: achowdhry-ripple <achowdhry@ripple.com>
Co-authored-by: Omar Khan <khancodegt@gmail.com>

Author: 4 people

.ci-config/rippled.cfg

@@ -190,6 +190,7 @@ fixInvalidTxFlags
 # 2.5.0 Amendments
 PermissionDelegation
 Batch
+TokenEscrow
 SingleAssetVault
 
 # This section can be used to simulate various FeeSettings scenarios for rippled node in standalone mode

packages/ripple-binary-codec/src/types/uint-64.ts

@@ -8,12 +8,15 @@ const HEX_REGEX = /^[a-fA-F0-9]{1,16}$/
 const BASE10_REGEX = /^[0-9]{1,20}$/
 const mask = BigInt(0x00000000ffffffff)
 
-function useBase10(fieldName: string): boolean {
-  return (
-    fieldName === 'MaximumAmount' ||
-    fieldName === 'OutstandingAmount' ||
-    fieldName === 'MPTAmount'
-  )
+const BASE10_AMOUNT_FIELDS = new Set([
+  'MaximumAmount',
+  'OutstandingAmount',
+  'MPTAmount',
+  'LockedAmount',
+])
+
+function isBase10(fieldName: string): boolean {
+  return BASE10_AMOUNT_FIELDS.has(fieldName)
 }
 
 /**
@@ -64,7 +67,7 @@ class UInt64 extends UInt {
     }
 
     if (typeof val === 'string') {
-      if (useBase10(fieldName)) {
+      if (isBase10(fieldName)) {
         if (!BASE10_REGEX.test(val)) {
           throw new Error(`${fieldName} ${val} is not a valid base 10 string`)
         }
@@ -101,7 +104,7 @@ class UInt64 extends UInt {
     fieldName = '',
   ): string {
     const hexString = bytesToHex(this.bytes)
-    if (useBase10(fieldName)) {
+    if (isBase10(fieldName)) {
       return BigInt('0x' + hexString).toString(10)
     }
 

packages/xrpl/HISTORY.md

@@ -5,6 +5,7 @@ Subscribe to [the **xrpl-announce** mailing list](https://groups.google.com/g/xr
 ## Unreleased
 
 ### Added
+* Support for `Token Escrow` (XLS-85)
 * Support for `Single Asset Vault` (XLS-65)
 * Adds `XRPLNumber` amount type used in Vault transactions. This supports integer, decimal, or scientific notation strings.
 * Adds `ClawbackAmount` amount type used in transactions related to Clawback.

packages/xrpl/src/models/ledger/AccountRoot.ts

@@ -146,6 +146,11 @@ export interface AccountRootFlagsInterface {
    * This address can claw back issued IOUs. Once enabled, cannot be disabled.
    */
   lsfAllowTrustLineClawback?: boolean
+
+  /**
+   * Allow IOUs to be used as escrow amounts for an issuer
+   */
+  lsfAllowTrustLineLocking?: boolean
 }
 
 export enum AccountRootFlags {
@@ -210,4 +215,9 @@ export enum AccountRootFlags {
    * This address can claw back issued IOUs. Once enabled, cannot be disabled.
    */
   lsfAllowTrustLineClawback = 0x80000000,
+  /**
+   * If the issuer's account does not have the lsfAllowTrustLineLocking flag set,
+   * then Escrow ledger-objects cannot be created with such IOUs.
+   */
+  lsfAllowTrustLineLocking = 0x40000000,
 }

packages/xrpl/src/models/ledger/Escrow.ts

@@ -19,7 +19,8 @@ export default interface Escrow extends BaseLedgerEntry, HasPreviousTxnID {
    * successful.
    */
   Destination: string
-  /** The amount of XRP, in drops, to be delivered by the held payment. */
+  /** The amount to be delivered by the held payment. Can represent XRP, an IOU token, or an MPT.
+   * Must always be a positive value. */
   Amount: string
   /**
    * A PREIMAGE-SHA-256 crypto-condition, as hexadecimal. If present, the
@@ -61,4 +62,16 @@ export default interface Escrow extends BaseLedgerEntry, HasPreviousTxnID {
    * this object, in case the directory consists of multiple pages.
    */
   DestinationNode?: string
+
+  /**
+   * The transfer rate or fee at which the funds are escrowed, stored at creation
+   *  and used during settlement. Applicable to both IOUs and MPTs.
+   */
+  TransferRate?: number
+
+  /**
+   * The ledger index of the issuer's directory node associated with the Escrow.
+   * Used when the issuer is neither the source nor destination account.
+   */
+  IssuerNode?: number
 }

packages/xrpl/src/models/ledger/MPToken.ts

@@ -8,4 +8,5 @@ export interface MPToken extends BaseLedgerEntry, HasPreviousTxnID {
   MPTAmount?: MPTAmount
   Flags: number
   OwnerNode?: string
+  LockedAmount?: string
 }

packages/xrpl/src/models/ledger/MPTokenIssuance.ts

@@ -10,4 +10,5 @@ export interface MPTokenIssuance extends BaseLedgerEntry, HasPreviousTxnID {
   TransferFee?: number
   MPTokenMetadata?: string
   OwnerNode?: string
+  LockedAmount?: string
 }

packages/xrpl/src/models/transactions/accountSet.ts

@@ -61,6 +61,8 @@ export enum AccountSetAsfFlags {
   asfDisallowIncomingTrustline = 15,
   /** Permanently gain the ability to claw back issued IOUs */
   asfAllowTrustLineClawback = 16,
+  /** Issuers allow their IOUs to be used as escrow amounts */
+  asfAllowTrustLineLocking = 17,
 }
 
 /**

packages/xrpl/src/models/transactions/escrowCreate.ts

@@ -1,9 +1,11 @@
 import { ValidationError } from '../../errors'
+import { Amount, MPTAmount } from '../common'
 
 import {
   Account,
   BaseTransaction,
   isAccount,
+  isAmount,
   isNumber,
   validateBaseTransaction,
   validateOptionalField,
@@ -18,11 +20,12 @@ import {
 export interface EscrowCreate extends BaseTransaction {
   TransactionType: 'EscrowCreate'
   /**
-   * Amount of XRP, in drops, to deduct from the sender's balance and escrow.
-   * Once escrowed, the XRP can either go to the Destination address (after the.
-   * FinishAfter time) or returned to the sender (after the CancelAfter time).
+   * 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,
+   * an IOU token, or an MPT. Must always be a positive value.
    */
-  Amount: string
+  Amount: Amount | MPTAmount
   /** Address to receive escrowed XRP. */
   Destination: Account
   /**
@@ -58,14 +61,7 @@ export interface EscrowCreate extends BaseTransaction {
 export function validateEscrowCreate(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
 
-  if (tx.Amount === undefined) {
-    throw new ValidationError('EscrowCreate: missing field Amount')
-  }
-
-  if (typeof tx.Amount !== 'string') {
-    throw new ValidationError('EscrowCreate: Amount must be a string')
-  }
-
+  validateRequiredField(tx, 'Amount', isAmount)
   validateRequiredField(tx, 'Destination', isAccount)
   validateOptionalField(tx, 'DestinationTag', isNumber)