XLS-81D Permissioned DEX (#3032)

* Implementation of XLS-81d PermissionedDEX; Transaction and Request models are implemented;

Author: ckeshava

.ci-config/rippled.cfg

@@ -190,6 +190,7 @@ fixInvalidTxFlags
 # 2.5.0 Amendments
 PermissionDelegation
 Batch
+PermissionedDEX
 TokenEscrow
 SingleAssetVault
 

packages/ripple-binary-codec/test/hash.test.ts

@@ -32,6 +32,12 @@ describe('Hash128', function () {
       new Error('Invalid Hash length 17'),
     )
   })
+
+  it(`throws when constructed from non-hexadecimal string`, () => {
+    expect(() => Hash128.from('Z'.repeat(32))).toThrow(
+      new Error('Invalid hash string ' + 'Z'.repeat(32)),
+    )
+  })
 })
 describe('Hash160', function () {
   it('has a static width member', function () {
@@ -56,6 +62,12 @@ describe('Hash160', function () {
       Hash160.from('100000000000000000000000000000000000000000'),
     ).toThrow(new Error('Invalid Hash length 21'))
   })
+
+  it(`throws when constructed from non-hexadecimal string`, () => {
+    expect(() => Hash160.from('Z'.repeat(40))).toThrow(
+      new Error('Invalid hash string ' + 'Z'.repeat(40)),
+    )
+  })
 })
 
 describe('Hash192', function () {
@@ -83,6 +95,12 @@ describe('Hash192', function () {
       Hash192.from('10000000000000000000000000000000000000000000000000'),
     ).toThrow(new Error('Invalid Hash length 25'))
   })
+
+  it(`throws when constructed from non-hexadecimal string`, () => {
+    expect(() => Hash192.from('Z'.repeat(48))).toThrow(
+      new Error('Invalid hash string ' + 'Z'.repeat(48)),
+    )
+  })
 })
 
 describe('Hash256', function () {
@@ -105,6 +123,12 @@ describe('Hash256', function () {
     expect(h.nibblet(4)).toBe(0x0b)
     expect(h.nibblet(5)).toBe(0xd)
   })
+
+  it(`throws when constructed from non-hexadecimal string`, () => {
+    expect(() => Hash256.from('Z'.repeat(64))).toThrow(
+      new Error('Invalid hash string ' + 'Z'.repeat(64)),
+    )
+  })
 })
 
 describe('Currency', function () {

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 `PermissionedDEX` (XLS-81d)
 * 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.

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

@@ -45,4 +45,7 @@ export default interface DirectoryNode
   TakerGetsCurrency?: string
   /** The issuer of the TakerGets amount from the offers in this directory. */
   TakerGetsIssuer?: string
+
+  /** The domain that the offer directory is a part of. */
+  DomainID?: string
 }

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

@@ -2,6 +2,19 @@ import { Amount } from '../common'
 
 import { BaseLedgerEntry, HasPreviousTxnID } from './BaseLedgerEntry'
 
+export interface Book {
+  Book: {
+    /** The ID of the offer directory that links to this offer. */
+    BookDirectory: string
+
+    /**
+     * A hint indicating which page of the offer directory links to this entry,
+     * in case the directory consists of multiple pages.
+     */
+    BookNode: string
+  }
+}
+
 export default interface Offer extends BaseLedgerEntry, HasPreviousTxnID {
   LedgerEntryType: 'Offer'
   /** A bit-map of boolean flags enabled for this Offer. */
@@ -34,9 +47,17 @@ export default interface Offer extends BaseLedgerEntry, HasPreviousTxnID {
   OwnerNode: string
   /** The time this Offer expires, in seconds since the Ripple Epoch. */
   Expiration?: number
+  /** The domain that the offer must be a part of. */
+  DomainID?: string
+  /**
+   * An additional list of order book directories that this offer belongs to.
+   * Currently this field only applicable to hybrid offers.
+   */
+  AdditionalBooks?: Book[]
 }
 
 export enum OfferFlags {
   lsfPassive = 0x00010000,
   lsfSell = 0x00020000,
+  lsfHybrid = 0x00040000,
 }

packages/xrpl/src/models/methods/bookOffers.ts

@@ -39,6 +39,13 @@ export interface BookOffersRequest extends BaseRequest, LookupByLedgerRequest {
    * currency amounts.
    */
   taker_pays: BookOfferCurrency
+  /**
+   * The object ID of a PermissionedDomain object. If this field is provided,
+   * the response will include only valid domain offers associated with that
+   * specific domain. If omitted, the response will include only hybrid and open
+   * offers for the trading pair, excluding all domain-specific offers.
+   */
+  domain?: string
 }
 
 export interface BookOffer extends Offer {

packages/xrpl/src/models/methods/pathFind.ts

@@ -30,6 +30,11 @@ export interface PathFindCreateRequest extends BasePathFindRequest {
    * about, or to check the overall cost to make a payment along a certain path.
    */
   paths?: Path[]
+  /**
+   * The object ID of a PermissionedDomain object. If this field is included,
+   * then only valid paths for this domain will be returned.
+   */
+  domain?: string
 }
 
 /** Stop sending pathfinding information. */
@@ -97,6 +102,11 @@ export interface PathFindResponse extends BaseResponse {
      * Continues to send updates each time a new ledger closes.
      */
     full_reply: boolean
+    /**
+     * The object ID of a PermissionedDomain object, if the orderbook shown is
+     * for a specific domain.
+     */
+    domain?: string
     /**
      * The ID provided in the WebSocket request is included again at this
      * level.

packages/xrpl/src/models/methods/ripplePathFind.ts

@@ -38,6 +38,11 @@ export interface RipplePathFindRequest
    * and optional issuer field, like how currency amounts are specified.
    */
   source_currencies?: SourceCurrencyAmount[]
+  /**
+   * The object ID of a PermissionedDomain object. If this field is included,
+   * then only valid paths for this domain will be returned.
+   */
+  domain?: string
 }
 
 export interface RipplePathFindPathOption {

packages/xrpl/src/models/methods/subscribe.ts

@@ -39,6 +39,12 @@ export interface SubscribeBook {
   snapshot?: boolean
   /** If true, return both sides of the order book. The default is false. */
   both?: boolean
+  /**
+   * The object ID of a PermissionedDomain object. If this field is included,
+   * then the offers will be filtered to only show the valid domain offers for
+   * that domain.
+   */
+  domain?: string
 }
 
 /**

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

@@ -683,3 +683,16 @@ export function containsDuplicates(
 
   return false
 }
+
+const _DOMAIN_ID_LENGTH = 64
+
+/**
+ * Utility method used across OfferCreate and Payment transactions to validate the DomainID.
+ *
+ * @param domainID - The domainID is a 64-character string that is used to identify a domain.
+ *
+ * @returns true if the domainID is a valid 64-character string, false otherwise
+ */
+export function isDomainID(domainID: unknown): domainID is string {
+  return isString(domainID) && domainID.length === _DOMAIN_ID_LENGTH
+}