Add encodeMPTokenMetadata and decodeMPTokenMetadata utility functions (#3117)

* WIP commit

* WIP commit

* WIP commit

* WIP commit

* fix tests

* update history

* add more tests

* add JSDOC tag

* add stable stringify

* fix JSDoc comments

* refactor utility functions

* fix test name

* add encode deocde in integration test

Author: Patel-Raj11

package-lock.json

@@ -6,9 +6,12 @@ Subscribe to [the **xrpl-announce** mailing list](https://groups.google.com/g/xr
 
 ### Added
 * Export `Batch` (XLS-56) transaction types and utilities
+* Add `encodeMPTokenMetadata` and `decodeMPTokenMetadata` helper functions to encode and decode MPTokenMetadata as per XLS-89 standard.
 
 ### Fixed
 * Fix incorrect type checking in `validateVaultCreate` that prevented vault creation with MPT as an asset.
+* [Breaking change] Fix `MPTokenMetadata` type to adhere to the XLS-89 standard. Since XLS-89 is still in a forming state and undergoing changes, this breaking change is being released as a bug fix via patch version bump. If you are using `MPTokenMetadata` in your code, please verify that it adheres to the updated type definition.
+* [Breaking change] Fix `validateMPTokenMetadata` to correctly validate MPTokenMetadata as per XLS-89 standard. Since XLS-89 is still in a forming state and undergoing changes, this breaking change is being released as a bug fix via patch version bump. If you are using `validateMPTokenMetadata` in your code, expect it to change as per the XLS-89 standard.
 
 ## 4.4.2 (2025-09-25)
 

packages/xrpl/HISTORY.md

@@ -30,7 +30,8 @@
     "eventemitter3": "^5.0.1",
     "ripple-address-codec": "^5.0.0",
     "ripple-binary-codec": "^2.5.0",
-    "ripple-keypairs": "^2.0.0"
+    "ripple-keypairs": "^2.0.0",
+    "fast-json-stable-stringify": "^2.1.0"
   },
   "devDependencies": {
     "@types/node": "^18.18.38",

packages/xrpl/package.json

@@ -220,25 +220,109 @@ export interface PriceData {
 }
 
 /**
- * MPTokenMetadata object as per the XLS-89d standard.
+ * {@link MPTokenMetadata} object as per the XLS-89 standard.
+ * Use {@link encodeMPTokenMetadata} utility function to convert to a compact hex string for on-ledger storage.
+ * Use {@link decodeMPTokenMetadata} utility function to convert from a hex string to this format.
  */
 export interface MPTokenMetadata {
+  /**
+   * Ticker symbol used to represent the token.
+   * Uppercase letters (A-Z) and digits (0-9) only. Max 6 characters recommended.
+   *
+   * @example "TBILL"
+   */
   ticker: string
+
+  /**
+   * Display name of the token.
+   * Any UTF-8 string.
+   *
+   * @example "T-Bill Yield Token"
+   */
   name: string
+
+  /**
+   * Short description of the token.
+   * Any UTF-8 string.
+   *
+   * @example "A yield-bearing stablecoin backed by short-term U.S. Treasuries"
+   */
+  desc?: string
+
+  /**
+   * URI to the token icon.
+   * Can be a `hostname/path` (HTTPS assumed) or full URI for other protocols (e.g., ipfs://).
+   *
+   * @example "example.org/token-icon.png" or "ipfs://QmXxxx"
+   */
   icon: string
+
+  /**
+   * Top-level classification of token purpose.
+   * Allowed values: "rwa", "memes", "wrapped", "gaming", "defi", "other"
+   *
+   * @example "rwa"
+   */
   asset_class: string
-  issuer_name: string
-  desc?: string
+
+  /**
+   * Optional subcategory of the asset class.
+   * Required if `asset_class` is "rwa".
+   * Allowed values: "stablecoin", "commodity", "real_estate", "private_credit", "equity", "treasury", "other"
+   *
+   * @example "treasury"
+   */
   asset_subclass?: string
-  urls?: MPTokenMetadataUrl[]
-  additional_info?: string
+
+  /**
+   * The name of the issuer account.
+   * Any UTF-8 string.
+   *
+   * @example "Example Yield Co."
+   */
+  issuer_name: string
+
+  /**
+   * List of related URIs (site, dashboard, social media, documentation, etc.).
+   * Each URI object contains the link, its category, and a human-readable title.
+   */
+  uris?: MPTokenMetadataUri[]
+
+  /**
+   * Freeform field for key token details like interest rate, maturity date, term, or other relevant info.
+   * Can be any valid JSON object or UTF-8 string.
+   *
+   * @example { "interest_rate": "5.00%", "maturity_date": "2045-06-30" }
+   */
+  additional_info?: string | Record<string, unknown>
 }
 
 /**
- * MPTokenMetadataUrl object as per the XLS-89d standard.
+ * {@link MPTokenMetadataUri} object as per the XLS-89 standard.
+ * Used within the `uris` array of {@link MPTokenMetadata}.
  */
-export interface MPTokenMetadataUrl {
-  url: string
-  type: string
+export interface MPTokenMetadataUri {
+  /**
+   * URI to the related resource.
+   * Can be a `hostname/path` (HTTPS assumed) or full URI for other protocols (e.g., ipfs://).
+   *
+   * @example "exampleyield.com/tbill" or "ipfs://QmXxxx"
+   */
+  uri: string
+
+  /**
+   * The category of the link.
+   * Allowed values: "website", "social", "docs", "other"
+   *
+   * @example "website"
+   */
+  category: string
+
+  /**
+   * A human-readable label for the link.
+   * Any UTF-8 string.
+   *
+   * @example "Product Page"
+   */
   title: string
 }

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

@@ -13,6 +13,11 @@ export {
   convertTxFlagsToNumber,
   parseTransactionFlags,
 } from './utils/flags'
+export {
+  validateMPTokenMetadata,
+  decodeMPTokenMetadata,
+  encodeMPTokenMetadata,
+} from './utils/mptokenMetadata'
 export * from './methods'
 export * from './transactions'
 export * from './common'

packages/xrpl/src/models/index.ts

@@ -1,5 +1,10 @@
 import { ValidationError } from '../../errors'
 import { isHex, INTEGER_SANITY_CHECK, isFlagEnabled } from '../utils'
+import {
+  MAX_MPT_META_BYTE_LENGTH,
+  MPT_META_WARNING_HEADER,
+  validateMPTokenMetadata,
+} from '../utils/mptokenMetadata'
 
 import {
   BaseTransaction,
@@ -8,9 +13,6 @@ import {
   validateOptionalField,
   isString,
   isNumber,
-  MAX_MPT_META_BYTE_LENGTH,
-  MPT_META_WARNING_HEADER,
-  validateMPTokenMetadata,
 } from './common'
 import type { TransactionMetadataBase } from './metadata'
 
@@ -109,10 +111,9 @@ export interface MPTokenIssuanceCreate extends BaseTransaction {
   TransferFee?: number
 
   /**
-   * 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.
+   * Should follow {@link https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0089-multi-purpose-token-metadata-schema | XLS-89} standard.
+   * Use {@link encodeMPTokenMetadata} utility function to convert to convert {@link MPTokenMetadata} to a blob.
+   * Use {@link decodeMPTokenMetadata} utility function to convert from a blob to {@link MPTokenMetadata}.
    *
    * 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.