Add warnings for MPTokenMetadata - XLS-89d (#3041)

* add console warnings for incorrect MPTokenMetadata

* fix subscribe stream IT due to newly introduced network_id field

Author: Patel-Raj11

packages/xrpl/HISTORY.md

@@ -11,6 +11,7 @@ Subscribe to [the **xrpl-announce** mailing list](https://groups.google.com/g/xr
 * 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.
 * Fixed minified `build/xrpl-latest-min.js` to have all the latest xrpl package changes.
+* Add warning messages to `MPTokenIssuanceCreate` transaction as per [XLS-89d](https://github.com/XRPLF/XRPL-Standards/pull/293).
 
 ### Fixed
 * Fix `AccountRoot` ledger object to correctly parse `FirstNFTokenSequence` field

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

@@ -218,3 +218,27 @@ export interface PriceData {
     Scale?: number
   }
 }
+
+/**
+ * MPTokenMetadata object as per the XLS-89d standard.
+ */
+export interface MPTokenMetadata {
+  ticker: string
+  name: string
+  icon: string
+  asset_class: string
+  issuer_name: string
+  desc?: string
+  asset_subclass?: string
+  urls?: MPTokenMetadataUrl[]
+  additional_info?: string
+}
+
+/**
+ * MPTokenMetadataUrl object as per the XLS-89d standard.
+ */
+export interface MPTokenMetadataUrl {
+  url: string
+  type: string
+  title: string
+}

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

@@ -142,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
 }
 
 /**
@@ -181,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
 }
 
 /**
@@ -265,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
 }
 
 /**

packages/xrpl/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 */

packages/xrpl/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
@@ -700,3 +741,180 @@ export function isDomainID(domainID: unknown): domainID is string {
     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
+  )
+}

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

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