Add support for XLS-85 Token Escrow (#5185)

- Specification: https://github.com/XRPLF/XRPL-Standards/pull/272
- Amendment: `TokenEscrow`
- Enables escrowing of IOU and MPT tokens in addition to native XRP.
- Allows accounts to lock issued tokens (IOU/MPT) in escrow objects, with support for freeze, authorization, and transfer rates.
- Adds new ledger fields (`sfLockedAmount`, `sfIssuerNode`, etc.) to track locked balances for IOU and MPT escrows.
- Updates EscrowCreate, EscrowFinish, and EscrowCancel transaction logic to support IOU and MPT assets, including proper handling of trustlines and MPT authorization, transfer rates, and locked balances.
- Enforces invariant checks for escrowed IOU/MPT amounts.
- Extends GatewayBalances RPC to report locked (escrowed) balances.

include/xrpl/protocol/LedgerFormats.h

@@ -145,7 +145,8 @@ enum LedgerSpecificFlags {
         0x10000000,               // True, reject new paychans
     lsfDisallowIncomingTrustline =
         0x20000000,               // True, reject new trustlines (only if no issued assets)
-    // 0x40000000 is available
+    lsfAllowTrustLineLocking =
+        0x40000000,               // True, enable trustline locking
     lsfAllowTrustLineClawback =
         0x80000000,               // True, enable clawback
 

include/xrpl/protocol/STAmount.h

@@ -703,6 +703,12 @@ isXRP(STAmount const& amount)
     return amount.native();
 }
 
+bool
+canAdd(STAmount const& amt1, STAmount const& amt2);
+
+bool
+canSubtract(STAmount const& amt1, STAmount const& amt2);
+
 // Since `canonicalize` does not have access to a ledger, this is needed to put
 // the low-level routine stAmountCanonicalize on an amendment switch. Only
 // transactions need to use this switchover. Outside of a transaction it's safe

include/xrpl/protocol/TER.h

@@ -360,6 +360,7 @@ enum TECcodes : TERUnderlyingType {
     tecWRONG_ASSET = 194,
     tecLIMIT_EXCEEDED = 195,
     tecPSEUDO_ACCOUNT = 196,
+    tecPRECISION_LOSS = 197,
 };
 
 //------------------------------------------------------------------------------

include/xrpl/protocol/TxFlags.h

@@ -92,6 +92,7 @@ constexpr std::uint32_t asfDisallowIncomingCheck           = 13;
 constexpr std::uint32_t asfDisallowIncomingPayChan         = 14;
 constexpr std::uint32_t asfDisallowIncomingTrustline       = 15;
 constexpr std::uint32_t asfAllowTrustLineClawback          = 16;
+constexpr std::uint32_t asfAllowTrustLineLocking           = 17;
 
 // OfferCreate flags:
 constexpr std::uint32_t tfPassive                          = 0x00010000;

include/xrpl/protocol/detail/features.macro

@@ -32,6 +32,7 @@
 // If you add an amendment here, then do not forget to increment `numFeatures`
 // in include/xrpl/protocol/Feature.h.
 
+XRPL_FEATURE(TokenEscrow,                Supported::yes, VoteBehavior::DefaultNo)
 XRPL_FIX    (EnforceNFTokenTrustlineV2,  Supported::yes, VoteBehavior::DefaultNo)
 XRPL_FIX    (AMMv1_3,                    Supported::yes, VoteBehavior::DefaultNo)
 XRPL_FEATURE(PermissionedDEX,            Supported::yes, VoteBehavior::DefaultNo)

include/xrpl/protocol/detail/ledger_entries.macro

@@ -354,6 +354,8 @@ LEDGER_ENTRY(ltESCROW, 0x0075, Escrow, escrow, ({
     {sfPreviousTxnID,        soeREQUIRED},
     {sfPreviousTxnLgrSeq,    soeREQUIRED},
     {sfDestinationNode,      soeOPTIONAL},
+    {sfTransferRate,         soeOPTIONAL},
+    {sfIssuerNode,           soeOPTIONAL},
 }))
 
 /** A ledger object describing a single unidirectional XRP payment channel.
@@ -405,6 +407,7 @@ LEDGER_ENTRY(ltMPTOKEN_ISSUANCE, 0x007e, MPTokenIssuance, mpt_issuance, ({
     {sfAssetScale,               soeDEFAULT},
     {sfMaximumAmount,            soeOPTIONAL},
     {sfOutstandingAmount,        soeREQUIRED},
+    {sfLockedAmount,             soeOPTIONAL},
     {sfMPTokenMetadata,          soeOPTIONAL},
     {sfPreviousTxnID,            soeREQUIRED},
     {sfPreviousTxnLgrSeq,        soeREQUIRED},
@@ -418,6 +421,7 @@ LEDGER_ENTRY(ltMPTOKEN, 0x007f, MPToken, mptoken, ({
     {sfAccount,                  soeREQUIRED},
     {sfMPTokenIssuanceID,        soeREQUIRED},
     {sfMPTAmount,                soeDEFAULT},
+    {sfLockedAmount,             soeOPTIONAL},
     {sfOwnerNode,                soeREQUIRED},
     {sfPreviousTxnID,            soeREQUIRED},
     {sfPreviousTxnLgrSeq,        soeREQUIRED},

include/xrpl/protocol/detail/sfields.macro

@@ -144,6 +144,7 @@ TYPED_SFIELD(sfOutstandingAmount,        UINT64,    25, SField::sMD_BaseTen|SFie
 TYPED_SFIELD(sfMPTAmount,                UINT64,    26, SField::sMD_BaseTen|SField::sMD_Default)
 TYPED_SFIELD(sfIssuerNode,               UINT64,    27)
 TYPED_SFIELD(sfSubjectNode,              UINT64,    28)
+TYPED_SFIELD(sfLockedAmount,             UINT64,    29, SField::sMD_BaseTen|SField::sMD_Default)
 
 // 128-bit
 TYPED_SFIELD(sfEmailHash,                UINT128,    1)

include/xrpl/protocol/detail/transactions.macro

@@ -44,7 +44,7 @@ TRANSACTION(ttPAYMENT, 0, Payment, Delegation::delegatable, ({
 /** This transaction type creates an escrow object. */
 TRANSACTION(ttESCROW_CREATE, 1, EscrowCreate, Delegation::delegatable, ({
     {sfDestination, soeREQUIRED},
-    {sfAmount, soeREQUIRED},
+    {sfAmount, soeREQUIRED, soeMPTSupported},
     {sfCondition, soeOPTIONAL},
     {sfCancelAfter, soeOPTIONAL},
     {sfFinishAfter, soeOPTIONAL},

include/xrpl/protocol/jss.h

@@ -391,6 +391,7 @@ JSS(load_fee);                // out: LoadFeeTrackImp, NetworkOPs
 JSS(local);                   // out: resource/Logic.h
 JSS(local_txs);               // out: GetCounts
 JSS(local_static_keys);       // out: ValidatorList
+JSS(locked);                  // out: GatewayBalances
 JSS(low);                     // out: BookChanges
 JSS(lowest_sequence);         // out: AccountInfo
 JSS(lowest_ticket);           // out: AccountInfo