Add MPT Metadata Schema section to concept docs

- Updates MPT Concept docs with metadata schema - Updates issue-mpt-with-metdata example code with new schema changes.
2025-11-04 03:45:49 +00:00 · 2025-10-14 11:09:07 +01:00
parent e1b97f7dba
commit bc0c698692
3 changed files with 118 additions and 30 deletions
--- a/_code-samples/issue-mpt-with-metadata/js/issue-mpt-with-metadata.js
+++ b/_code-samples/issue-mpt-with-metadata/js/issue-mpt-with-metadata.js
@@ -10,26 +10,26 @@ const { wallet } = await client.fundWallet()

 // Define metadata as JSON
 const mpt_metadata = {
-  ticker: 'TBILL',
-  name: 'T-Bill Yield Token',
-  desc: 'A yield-bearing stablecoin backed by short-term U.S. Treasuries and money market instruments.',
-  icon: 'https://example.org/tbill-icon.png',
-  asset_class: 'rwa',
-  asset_subclass: 'treasury',
-  issuer_name: 'Example Yield Co.',
-  urls: [
+  t: 'TBILL',
+  n: 'T-Bill Yield Token',
+  d: 'A yield-bearing stablecoin backed by short-term U.S. Treasuries and money market instruments.',
+  i: 'https://example.org/tbill-icon.png',
+  ac: 'rwa',
+  as: 'treasury',
+  in: 'Example Yield Co.',
+  us: [
    {
-      url: 'https://exampleyield.co/tbill',
-      type: 'website',
-      title: 'Product Page'
+      u: 'https://exampleyield.co/tbill',
+      c: 'website',
+      t: 'Product Page'
    },
    {
-      url: 'https://exampleyield.co/docs',
-      type: 'docs',
-      title: 'Yield Token Docs'
+      u: 'https://exampleyield.co/docs',
+      c: 'docs',
+      t: 'Yield Token Docs'
    }
  ],
-  additional_info: {
+  ai: {
    interest_rate: '5.00%',
    interest_type: 'variable',
    yield_source: 'U.S. Treasury Bills',
--- a/_code-samples/issue-mpt-with-metadata/py/issue-mpt-with-metadata.py
+++ b/_code-samples/issue-mpt-with-metadata/py/issue-mpt-with-metadata.py
@@ -12,26 +12,26 @@ wallet = generate_faucet_wallet(client, debug=True)

 # Define metadata as JSON
 mpt_metadata = {
-    "ticker": "TBILL",
-    "name": "T-Bill Yield Token",
-    "desc": "A yield-bearing stablecoin backed by short-term U.S. Treasuries and money market instruments.",
-    "icon": "https://example.org/tbill-icon.png",
-    "asset_class": "rwa",
-    "asset_subclass": "treasury",
-    "issuer_name": "Example Yield Co.",
-    "urls": [
+    "t": "TBILL",
+    "n": "T-Bill Yield Token",
+    "d": "A yield-bearing stablecoin backed by short-term U.S. Treasuries and money market instruments.",
+    "i": "example.org/tbill-icon.png",
+    "ac": "rwa",
+    "as": "treasury",
+    "in": "Example Yield Co.",
+    "us": [
        {
-            "url": "https://exampleyield.co/tbill",
-            "type": "website",
-            "title": "Product Page"
+            "u": "exampleyield.co/tbill",
+            "c": "website",
+            "t": "Product Page"
        },
        {
-            "url": "https://exampleyield.co/docs",
-            "type": "docs",
-            "title": "Yield Token Docs"
+            "u": "exampleyield.co/docs",
+            "c": "docs",
+            "t": "Yield Token Docs"
        }
    ],
-    "additional_info": {
+    "ai": {
        "interest_rate": "5.00%",
        "interest_type": "variable",
        "yield_source": "U.S. Treasury Bills",
--- a/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens.md
+++ b/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens.md
@@ -45,6 +45,94 @@ Every MPT issuance has a set of key properties defined in the ledger as an [MPTo

 After the MPT is issued, the on-chain data cannot be changed. However, the proposed [XLS-94: Dynamic MPT standard](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0094-dynamic-MPT) {% not-enabled /%} would allow fields to be marked as mutable during creation, so that those fields can be changed later.

+#### Metadata Schema
+
+To fit within the 1024-byte limit, MPT metadata must use compressed JSON keys. The following table describes these keys and their corresponding fields:
+
+| Field Name      | Key  | Type             | Required? | Description |
+|:--------------- |:---- |:---------------- |---------- |-------------|
+| ticker          | `t`  | String           | Yes       | The ticker symbol used to represent the token. Must be uppercase letters (A-Z) and digits (0-9) only. A maximum of 6 characters is recommended. |
+| name            | `n`  | String           | Yes       | The display name of the token. Any UTF-8 string is permitted.  |
+| desc            | `d`  | String           | No        | A short description of the token. Any UTF-8 string is permitted. |
+| icon            | `i`  | String           | Yes       | The URI to the token icon. Can be `hostname/path` (HTTPS is assumed), or full URI for other protocols. |
+| asset_class     | `ac` | String           | Yes️       | Categorizes tokens by their primary purpose and backing. See [Asset Class](#asset-class) for more details. |
+| asset_subclass  | `as` | String           | No        | An optional subcategory that is only required if the `asset_class` is `rwa`. See [Asset Subclass](#asset-subclass) for more details. |
+| issuer_name     | `in` | String           | Yes       | Name of the entity issuing the token. Any UTF-8 string is permitted. |
+| uris            | `us` | Array            | No        | The list of related URIs such as website, documentation, and social media. See [URIs](#uris) for more details.|
+| additional_info | `ai` | Object or String | No        | Freeform field for key token details like interest rate, maturity date, term, or other relevant info. Any valid JSON object or UTF-8 string is permitted. |
+
+##### Asset Class
+
+The `asset_class` field categorizes tokens by their primary purpose and backing. These categories help applications understand the nature of the token and its intended use case.
+
+| Category | Definition |
+|----------|------------|
+| `rwa` | Tokens representing real-world assets (RWAs), which derive value from legally enforceable claims on physical or off-chain financial assets. |
+| `memes` | Community-driven tokens without intrinsic backing or utility claims, primarily driven by internet culture or speculation. |
+| `wrapped` | Tokens representing assets from other blockchains, typically backed 1:1 by bridges or custodians. |
+| `gaming` | Tokens used in games or virtual worlds, often representing in-game currency, assets, or rewards. |
+| `defi` | Tokens native to or used within DeFi protocols, including governance tokens, DEX tokens, and lending assets. |
+| `other` | Tokens that do not clearly fit into the defined categories. This may include experimental, test, or tokens with unique use cases not covered elsewhere. |
+
+##### Asset Subclass
+
+When `asset_class` is set to `rwa`, an `asset_subclass` can be specified to provide more granular categorization. This describes what type of real-world asset backs the token and what legal or regulatory framework might apply.
+
+| Subclass | Definition |
+|----------|------------|
+| `stablecoin` | Tokens pegged to a stable value, typically fiat currencies like USD, which are backed by reserves like cash, treasuries, or crypto collateral. |
+| `commodity` | Tokens that represent physical commodities like gold, silver, or oil, often redeemable or legally linked to off-chain reserves. |
+| `real_estate` | Tokens representing ownership or claims on real estate, including fractionalized property shares or REIT-like instruments. |
+| `private_credit` | Tokens representing debt obligations from private entities, such as loans, invoices, or receivables. |
+| `equity` | Tokens representing ownership shares in companies, similar to traditional stock or equity instruments. |
+| `treasury` | Tokens backed by government debt instruments, such as U.S. Treasury bills or bonds. |
+| `other` | Tokens that do not fit into the predefined categories, including experimental, hybrid, or emerging real-world asset types. |
+
+##### URIs
+
+The `us` array contains a list of URI objects, each with a URI link, category, and human-readable title.
+
+| Field Name | Key | Type   | Required?  | Description |
+|:---------- |:--- |:------ |:--------- |:-------------|
+| uri        | `u` | String | Yes️       |`hostname/path` or full URI link to the related resource. |
+| category   | `c` | String | Yes       | The category of the link provided. Allowed values are: `website`, `social`, `docs`, `other`. |
+| title      | `t` | String | Yes       | Human-readable label for the link. |
+
+#### Example JSON Metadata
+
+The following example shows metadata for a treasury-backed token.
+
+```json
+{
+  "t": "TBILL",
+  "n": "T-Bill Yield Token",
+  "d": "A yield-bearing stablecoin backed by short-term U.S. Treasuries and money market instruments.",
+  "i": "example.org/tbill-icon.png",
+  "ac": "rwa",
+  "as": "treasury",
+  "in": "Example Yield Co.",
+  "us": [
+    {
+      "u": "exampleyield.co/tbill",
+      "c": "website",
+      "t": "Product Page"
+    },
+    {
+      "u": "exampleyield.co/docs",
+      "c": "docs",
+      "t": "Yield Token Docs"
+    }
+  ],
+  "ai": {
+    "interest_rate": "5.00%",
+    "interest_type": "variable",
+    "yield_source": "U.S. Treasury Bills",
+    "maturity_date": "2045-06-30",
+    "cusip": "912796RX0"
+  }
+}
+```
+
 ### Transferability Controls

 MPTs can be configured with different levels of transferability controls by adjusting the following flags: