xrpl 4.4.0-smartescrow.0 → 4.4.0

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
   /**
@@ -47,10 +50,6 @@ export interface EscrowCreate extends BaseTransaction {
    * payment, such as a hosted recipient at the destination address.
    */
   DestinationTag?: number
-
-  FinishFunction?: string
-
-  Data?: string
 }
 
 /**
@@ -62,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)
 
@@ -79,13 +71,9 @@ export function validateEscrowCreate(tx: Record<string, unknown>): void {
     )
   }
 
-  if (
-    tx.FinishAfter === undefined &&
-    tx.Condition === undefined &&
-    tx.FinishFunction === undefined
-  ) {
+  if (tx.FinishAfter === undefined && tx.Condition === undefined) {
     throw new ValidationError(
-      'EscrowCreate: Either FinishAfter, Condition, or FinishFunction must be specified',
+      'EscrowCreate: Either Condition or FinishAfter must be specified',
     )
   }
 

package/src/models/transactions/escrowFinish.ts

@@ -38,8 +38,6 @@ export interface EscrowFinish extends BaseTransaction {
    * The credentials included must not be expired.
    */
   CredentialIDs?: string[]
-
-  ComputationAllowance?: number
 }
 
 /**

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

package/src/models/transactions/vaultCreate.ts

@@ -14,10 +14,11 @@ import {
   VAULT_DATA_MAX_BYTE_LENGTH,
   XRPLNumber,
   isXRPLNumber,
+  MAX_MPT_META_BYTE_LENGTH,
+  MPT_META_WARNING_HEADER,
+  validateMPTokenMetadata,
 } from './common'
 
-const META_MAX_BYTE_LENGTH = 1024
-
 /**
  * Enum representing withdrawal strategies for a Vault.
  */
@@ -71,6 +72,12 @@ export interface VaultCreate extends BaseTransaction {
 
   /**
    * Arbitrary metadata about the share MPT, in hex format, 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
 
@@ -85,13 +92,14 @@ export interface VaultCreate extends BaseTransaction {
   DomainID?: string
 }
 
+/* eslint-disable max-lines-per-function -- Not needed to reduce function */
+/* eslint-disable max-statements -- required to do all field validations */
 /**
  * Verify the form and type of an {@link VaultCreate} at runtime.
  *
  * @param tx - A {@link VaultCreate} Transaction.
  * @throws When the {@link VaultCreate} is malformed.
  */
-// eslint-disable-next-line max-lines-per-function -- required to do all field validations
 export function validateVaultCreate(tx: Record<string, unknown>): void {
   validateBaseTransaction(tx)
 
@@ -119,13 +127,13 @@ export function validateVaultCreate(tx: Record<string, unknown>): void {
     const metaHex = tx.MPTokenMetadata
     if (!isHex(metaHex)) {
       throw new ValidationError(
-        'VaultCreate: MPTokenMetadata must be a valid hex string',
+        'VaultCreate: MPTokenMetadata must be a valid non-empty hex string',
       )
     }
     const metaByteLength = metaHex.length / 2
-    if (metaByteLength > META_MAX_BYTE_LENGTH) {
+    if (metaByteLength > MAX_MPT_META_BYTE_LENGTH) {
       throw new ValidationError(
-        `VaultCreate: MPTokenMetadata exceeds ${META_MAX_BYTE_LENGTH} bytes (actual: ${metaByteLength})`,
+        `VaultCreate: MPTokenMetadata exceeds ${MAX_MPT_META_BYTE_LENGTH} bytes (actual: ${metaByteLength})`,
       )
     }
   }
@@ -139,4 +147,20 @@ export function validateVaultCreate(tx: Record<string, unknown>): void {
       'VaultCreate: Cannot set DomainID unless tfVaultPrivate flag is set.',
     )
   }
+
+  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 */
+/* eslint-enable max-statements */

package/src/models/transactions/vaultDeposit.ts

@@ -1,4 +1,4 @@
-import { Amount } from '../common'
+import { Amount, MPTAmount } from '../common'
 
 import {
   BaseTransaction,
@@ -24,7 +24,8 @@ export interface VaultDeposit extends BaseTransaction {
   /**
    * Asset amount to deposit.
    */
-  Amount: Amount
+  // TODO: remove MPTAmount when MPTv2 is released
+  Amount: Amount | MPTAmount
 }
 
 /**

package/src/models/transactions/vaultWithdraw.ts

@@ -1,4 +1,4 @@
-import { Amount } from '../common'
+import { Amount, MPTAmount } from '../common'
 
 import {
   BaseTransaction,
@@ -27,7 +27,8 @@ export interface VaultWithdraw extends BaseTransaction {
   /**
    * The exact amount of Vault asset to withdraw.
    */
-  Amount: Amount
+  // TODO: remove MPTAmount when MPTv2 is released
+  Amount: Amount | MPTAmount
 
   /**
    * An account to receive the assets. It must be able to receive the asset.