xrpl 4.4.0-smartescrow.0 → 4.5.0-smartescrow.0

package/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,
 }

package/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 {

package/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.

package/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 {

package/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
 }
 
 /**
@@ -136,6 +142,11 @@ export interface LedgerStream extends BaseStream {
    * connected but has not yet obtained a ledger from the network.
    */
   validated_ledgers?: string
+
+  /**
+   * The network from which the ledger stream is received.
+   */
+  network_id?: number
 }
 
 /**
@@ -175,6 +186,11 @@ export interface LedgerStreamResponse {
    * connected but has not yet obtained a ledger from the network.
    */
   validated_ledgers?: string
+
+  /**
+   * The network from which the ledger stream is received.
+   */
+  network_id?: number
 }
 
 /**
@@ -259,6 +275,11 @@ export interface ValidationStream extends BaseStream {
    * validator is using a token, this is an ephemeral public key.
    */
   validation_public_key: string
+
+  /**
+   * The network from which the validations stream is received.
+   */
+  network_id?: number
 }
 
 /**

package/src/models/transactions/MPTokenIssuanceCreate.ts

@@ -8,6 +8,9 @@ import {
   validateOptionalField,
   isString,
   isNumber,
+  MAX_MPT_META_BYTE_LENGTH,
+  MPT_META_WARNING_HEADER,
+  validateMPTokenMetadata,
 } from './common'
 import type { TransactionMetadataBase } from './metadata'
 
@@ -104,10 +107,18 @@ export interface MPTokenIssuanceCreate extends BaseTransaction {
    * The field must NOT be present if the `tfMPTCanTransfer` flag is not set.
    */
   TransferFee?: number
+
   /**
-   * Arbitrary metadata about this issuance, in hex format.
+   * Optional arbitrary metadata about this issuance, encoded as a hex string and limited to 1024 bytes.
+   *
+   * The decoded value must be a UTF-8 encoded JSON object that adheres to the
+   * XLS-89d MPTokenMetadata standard.
+   *
+   * While adherence to the XLS-89d format is not mandatory, non-compliant metadata
+   * may not be discoverable by ecosystem tools such as explorers and indexers.
    */
-  MPTokenMetadata?: string | null
+  MPTokenMetadata?: string
+
   Flags?: number | MPTokenIssuanceCreateFlagsInterface
 }
 
@@ -131,15 +142,13 @@ export function validateMPTokenIssuanceCreate(
   validateOptionalField(tx, 'TransferFee', isNumber)
   validateOptionalField(tx, 'AssetScale', isNumber)
 
-  if (typeof tx.MPTokenMetadata === 'string' && tx.MPTokenMetadata === '') {
+  if (
+    typeof tx.MPTokenMetadata === 'string' &&
+    (!isHex(tx.MPTokenMetadata) ||
+      tx.MPTokenMetadata.length / 2 > MAX_MPT_META_BYTE_LENGTH)
+  ) {
     throw new ValidationError(
-      'MPTokenIssuanceCreate: MPTokenMetadata must not be empty string',
-    )
-  }
-
-  if (typeof tx.MPTokenMetadata === 'string' && !isHex(tx.MPTokenMetadata)) {
-    throw new ValidationError(
-      'MPTokenIssuanceCreate: MPTokenMetadata must be in hex format',
+      `MPTokenIssuanceCreate: MPTokenMetadata (hex format) must be non-empty and no more than ${MAX_MPT_META_BYTE_LENGTH} bytes.`,
     )
   }
 
@@ -178,5 +187,19 @@ export function validateMPTokenIssuanceCreate(
       )
     }
   }
+
+  if (tx.MPTokenMetadata != null) {
+    const validationMessages = validateMPTokenMetadata(tx.MPTokenMetadata)
+
+    if (validationMessages.length > 0) {
+      const message = [
+        MPT_META_WARNING_HEADER,
+        ...validationMessages.map((msg) => `- ${msg}`),
+      ].join('\n')
+
+      // eslint-disable-next-line no-console -- Required here.
+      console.warn(message)
+    }
+  }
 }
 /* eslint-enable max-lines-per-function */

package/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,
 }
 
 /**

package/src/models/transactions/common.ts

@@ -1,5 +1,5 @@
 /* eslint-disable max-lines -- common utility file */
-import { HEX_REGEX } from '@xrplf/isomorphic/utils'
+import { HEX_REGEX, hexToString } from '@xrplf/isomorphic/utils'
 import { isValidClassicAddress, isValidXAddress } from 'ripple-address-codec'
 import { TRANSACTION_TYPES } from 'ripple-binary-codec'
 
@@ -12,6 +12,7 @@ import {
   IssuedCurrency,
   IssuedCurrencyAmount,
   MPTAmount,
+  MPTokenMetadata,
   Memo,
   Signer,
   XChainBridge,
@@ -22,10 +23,50 @@ const MEMO_SIZE = 3
 export const MAX_AUTHORIZED_CREDENTIALS = 8
 const MAX_CREDENTIAL_BYTE_LENGTH = 64
 const MAX_CREDENTIAL_TYPE_LENGTH = MAX_CREDENTIAL_BYTE_LENGTH * 2
+export const MAX_MPT_META_BYTE_LENGTH = 1024
 
 // Used for Vault transactions
 export const VAULT_DATA_MAX_BYTE_LENGTH = 256
 
+// To validate MPTokenMetadata as per XLS-89d
+const TICKER_REGEX = /^[A-Z0-9]{1,6}$/u
+
+const MAX_MPT_META_TOP_LEVEL_FIELD_COUNT = 9
+
+const MPT_META_URL_FIELD_COUNT = 3
+
+const MPT_META_REQUIRED_FIELDS = [
+  'ticker',
+  'name',
+  'icon',
+  'asset_class',
+  'issuer_name',
+]
+
+const MPT_META_ASSET_CLASSES = [
+  'rwa',
+  'memes',
+  'wrapped',
+  'gaming',
+  'defi',
+  'other',
+]
+
+const MPT_META_ASSET_SUB_CLASSES = [
+  'stablecoin',
+  'commodity',
+  'real_estate',
+  'private_credit',
+  'equity',
+  'treasury',
+  'other',
+]
+
+export const MPT_META_WARNING_HEADER =
+  'MPTokenMetadata is not properly formatted as JSON as per the XLS-89d standard. ' +
+  "While adherence to this standard is not mandatory, such non-compliant MPToken's might not be discoverable " +
+  'by Explorers and Indexers in the XRPL ecosystem.'
+
 function isMemo(obj: unknown): obj is Memo {
   if (!isRecord(obj)) {
     return false
@@ -683,3 +724,197 @@ 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 &&
+    isHex(domainID)
+  )
+}
+
+/* eslint-disable max-lines-per-function -- Required here as structure validation is verbose. */
+/* eslint-disable max-statements -- Required here as structure validation is verbose. */
+
+/**
+ * Validates if MPTokenMetadata adheres to XLS-89d standard.
+ *
+ * @param input - Hex encoded MPTokenMetadata.
+ * @returns Validation messages if MPTokenMetadata does not adheres to XLS-89d standard.
+ */
+export function validateMPTokenMetadata(input: string): string[] {
+  const validationMessages: string[] = []
+
+  if (!isHex(input)) {
+    validationMessages.push(`MPTokenMetadata must be in hex format.`)
+    return validationMessages
+  }
+
+  if (input.length / 2 > MAX_MPT_META_BYTE_LENGTH) {
+    validationMessages.push(
+      `MPTokenMetadata must be max ${MAX_MPT_META_BYTE_LENGTH} bytes.`,
+    )
+    return validationMessages
+  }
+
+  let jsonMetaData: unknown
+
+  try {
+    jsonMetaData = JSON.parse(hexToString(input))
+  } catch (err) {
+    validationMessages.push(
+      `MPTokenMetadata is not properly formatted as JSON - ${String(err)}`,
+    )
+    return validationMessages
+  }
+
+  if (
+    jsonMetaData == null ||
+    typeof jsonMetaData !== 'object' ||
+    Array.isArray(jsonMetaData)
+  ) {
+    validationMessages.push(
+      'MPTokenMetadata is not properly formatted as per XLS-89d.',
+    )
+    return validationMessages
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- It must be some JSON object.
+  const obj = jsonMetaData as Record<string, unknown>
+
+  // validating structure
+
+  // check for maximum number of fields
+  const fieldCount = Object.keys(obj).length
+  if (fieldCount > MAX_MPT_META_TOP_LEVEL_FIELD_COUNT) {
+    validationMessages.push(
+      `MPTokenMetadata must not contain more than ${MAX_MPT_META_TOP_LEVEL_FIELD_COUNT} top-level fields (found ${fieldCount}).`,
+    )
+    return validationMessages
+  }
+
+  const incorrectRequiredFields = MPT_META_REQUIRED_FIELDS.filter(
+    (field) => !isString(obj[field]),
+  )
+
+  if (incorrectRequiredFields.length > 0) {
+    incorrectRequiredFields.forEach((field) =>
+      validationMessages.push(`${field} is required and must be string.`),
+    )
+    return validationMessages
+  }
+
+  if (obj.desc != null && !isString(obj.desc)) {
+    validationMessages.push(`desc must be a string.`)
+    return validationMessages
+  }
+
+  if (obj.asset_subclass != null && !isString(obj.asset_subclass)) {
+    validationMessages.push(`asset_subclass must be a string.`)
+    return validationMessages
+  }
+
+  if (
+    obj.additional_info != null &&
+    !isString(obj.additional_info) &&
+    !isRecord(obj.additional_info)
+  ) {
+    validationMessages.push(`additional_info must be a string or JSON object.`)
+    return validationMessages
+  }
+
+  if (obj.urls != null) {
+    if (!Array.isArray(obj.urls)) {
+      validationMessages.push('urls must be an array as per XLS-89d.')
+      return validationMessages
+    }
+    if (!obj.urls.every(isValidMPTokenMetadataUrlStructure)) {
+      validationMessages.push(
+        'One or more urls are not structured per XLS-89d.',
+      )
+      return validationMessages
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Required here.
+  const mptMPTokenMetadata = obj as unknown as MPTokenMetadata
+
+  // validating content
+  if (!TICKER_REGEX.test(mptMPTokenMetadata.ticker)) {
+    validationMessages.push(
+      `ticker should have uppercase letters (A-Z) and digits (0-9) only. Max 6 characters recommended.`,
+    )
+  }
+
+  if (!mptMPTokenMetadata.icon.startsWith('https://')) {
+    validationMessages.push(`icon should be a valid https url.`)
+  }
+
+  if (
+    !MPT_META_ASSET_CLASSES.includes(
+      mptMPTokenMetadata.asset_class.toLowerCase(),
+    )
+  ) {
+    validationMessages.push(
+      `asset_class should be one of ${MPT_META_ASSET_CLASSES.join(', ')}.`,
+    )
+  }
+
+  if (
+    mptMPTokenMetadata.asset_subclass != null &&
+    !MPT_META_ASSET_SUB_CLASSES.includes(
+      mptMPTokenMetadata.asset_subclass.toLowerCase(),
+    )
+  ) {
+    validationMessages.push(
+      `asset_subclass should be one of ${MPT_META_ASSET_SUB_CLASSES.join(
+        ', ',
+      )}.`,
+    )
+  }
+
+  if (
+    mptMPTokenMetadata.asset_class.toLowerCase() === 'rwa' &&
+    mptMPTokenMetadata.asset_subclass == null
+  ) {
+    validationMessages.push(
+      `asset_subclass is required when asset_class is rwa.`,
+    )
+  }
+
+  if (
+    mptMPTokenMetadata.urls != null &&
+    !mptMPTokenMetadata.urls.every((ele) => ele.url.startsWith('https://'))
+  ) {
+    validationMessages.push(`url should be a valid https url.`)
+  }
+
+  return validationMessages
+}
+/* eslint-enable max-lines-per-function */
+/* eslint-enable max-statements */
+
+function isValidMPTokenMetadataUrlStructure(input: unknown): boolean {
+  if (input == null) {
+    return false
+  }
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Required here.
+  const obj = input as Record<string, unknown>
+
+  return (
+    typeof obj === 'object' &&
+    isString(obj.url) &&
+    isString(obj.type) &&
+    isString(obj.title) &&
+    Object.keys(obj).length === MPT_META_URL_FIELD_COUNT
+  )
+}

package/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
   /**
@@ -62,14 +65,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)
 

package/src/models/transactions/escrowFinish.ts

@@ -9,6 +9,7 @@ import {
   validateRequiredField,
   MAX_AUTHORIZED_CREDENTIALS,
 } from './common'
+import { TransactionMetadataBase } from './metadata'
 
 /**
  * Deliver XRP from a held payment to the recipient.
@@ -42,6 +43,12 @@ export interface EscrowFinish extends BaseTransaction {
   ComputationAllowance?: number
 }
 
+export interface EscrowFinishMetadata extends TransactionMetadataBase {
+  // if ComputationAllowance is present and the Smart Escrow runs
+  GasUsed?: number
+  WasmReturnCode?: number
+}
+
 /**
  * Verify the form and type of an EscrowFinish at runtime.
  *

package/src/models/transactions/index.ts

@@ -1,4 +1,4 @@
-export { BaseTransaction, isMPTAmount } from './common'
+export { BaseTransaction, isMPTAmount, validateMPTokenMetadata } from './common'
 export {
   validate,
   PseudoTransaction,

package/src/models/transactions/metadata.ts

@@ -1,6 +1,7 @@
 import { Amount, MPTAmount } from '../common'
 
 import { BaseTransaction } from './common'
+import { EscrowFinish, EscrowFinishMetadata } from './escrowFinish'
 import {
   MPTokenIssuanceCreate,
   MPTokenIssuanceCreateMetadata,
@@ -105,4 +106,6 @@ export type TransactionMetadata<T extends BaseTransaction = Transaction> =
     ? NFTokenCancelOfferMetadata
     : T extends MPTokenIssuanceCreate
     ? MPTokenIssuanceCreateMetadata
+    : T extends EscrowFinish
+    ? EscrowFinishMetadata
     : TransactionMetadataBase

package/src/models/transactions/offerCreate.ts

@@ -1,11 +1,14 @@
 import { ValidationError } from '../../errors'
 import { Amount } from '../common'
+import { hasFlag } from '../utils'
 
 import {
   BaseTransaction,
   GlobalFlagsInterface,
   validateBaseTransaction,
   isAmount,
+  validateOptionalField,
+  isDomainID,
 } from './common'
 
 /**
@@ -42,6 +45,11 @@ export enum OfferCreateFlags {
    * the TakerPays amount in exchange.
    */
   tfSell = 0x00080000,
+  /**
+   * Indicates the offer is hybrid. (meaning it is part of both a domain and open order book)
+   * This flag cannot be set if the offer doesn't have a DomainID
+   */
+  tfHybrid = 0x00100000,
 }
 
 /**
@@ -83,6 +91,7 @@ export interface OfferCreateFlagsInterface extends GlobalFlagsInterface {
   tfImmediateOrCancel?: boolean
   tfFillOrKill?: boolean
   tfSell?: boolean
+  tfHybrid?: boolean
 }
 
 /**
@@ -106,6 +115,8 @@ export interface OfferCreate extends BaseTransaction {
   TakerGets: Amount
   /** The amount and type of currency being requested by the offer creator. */
   TakerPays: Amount
+  /** The domain that the offer must be a part of. */
+  DomainID?: string
 }
 
 /**
@@ -140,4 +151,18 @@ export function validateOfferCreate(tx: Record<string, unknown>): void {
   if (tx.OfferSequence !== undefined && typeof tx.OfferSequence !== 'number') {
     throw new ValidationError('OfferCreate: invalid OfferSequence')
   }
+
+  validateOptionalField(tx, 'DomainID', isDomainID, {
+    txType: 'OfferCreate',
+    paramName: 'DomainID',
+  })
+
+  if (
+    tx.DomainID == null &&
+    hasFlag(tx, OfferCreateFlags.tfHybrid, 'tfHybrid')
+  ) {
+    throw new ValidationError(
+      'OfferCreate: tfHybrid flag cannot be set if DomainID is not present',
+    )
+  }
 }

package/src/models/transactions/payment.ts

@@ -8,6 +8,7 @@ import {
   GlobalFlagsInterface,
   validateBaseTransaction,
   isAccount,
+  isDomainID,
   validateRequiredField,
   validateOptionalField,
   isNumber,
@@ -160,6 +161,18 @@ export interface Payment extends BaseTransaction {
    * The credentials included must not be expired.
    */
   CredentialIDs?: string[]
+  /**
+   * The domain the sender intends to use. Both the sender and destination must
+   * be part of this domain. The DomainID can be included if the sender intends
+   * it to be a cross-currency payment (i.e. if the payment is going to interact
+   * with the DEX). The domain will only play it's role if there is a path that
+   * crossing an orderbook.
+   *
+   * Note: it's still possible that DomainID is included but the payment does
+   * not interact with DEX, it simply means that the DomainID will be ignored
+   * during payment paths.
+   */
+  DomainID?: string
   Flags?: number | PaymentFlagsInterface
 }
 
@@ -199,6 +212,11 @@ export function validatePayment(tx: Record<string, unknown>): void {
     throw new ValidationError('PaymentTransaction: InvoiceID must be a string')
   }
 
+  validateOptionalField(tx, 'DomainID', isDomainID, {
+    txType: 'PaymentTransaction',
+    paramName: 'DomainID',
+  })
+
   if (tx.Paths !== undefined && !isPaths(tx.Paths)) {
     throw new ValidationError('PaymentTransaction: invalid Paths')
   }
@@ -208,12 +226,6 @@ export function validatePayment(tx: Record<string, unknown>): void {
   }
 
   checkPartialPayment(tx)
-
-  if (tx.DeliverMax != null) {
-    throw new ValidationError(
-      'PaymentTransaction: Cannot have DeliverMax in a submitted transaction',
-    )
-  }
 }
 
 function checkPartialPayment(tx: Record<string, unknown>): void {