Merge pull request #3233 from XRPLF/mpt_metadata_sample

Add sample code for XLS-89d MPT Metadata

_code-samples/issue-mpt-with-metadata/README.md

@@ -0,0 +1,3 @@
+# Issue an MPT with Metadata
+
+Shows how to issue a Multi-Purpose Token (MPT) with metadata encoded according to the XLS-89 schema.

_code-samples/issue-mpt-with-metadata/js/README.md

@@ -0,0 +1,16 @@
+# Issue MPT with Metadata (JavaScript)
+
+Creates a sample MPT issuance with metadata encoded as JSON according to the [XLS-89 standard](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0089-multi-purpose-token-metadata-schema).
+
+Quick setup and usage:
+
+```sh
+npm i
+node issue-mpt-with-metadata.js
+```
+
+The script should output a validated transaction and end with a line such as the following:
+
+```text
+MPToken created successfully with issuance ID 005073C721E14A7613BAAF5E0B1A253459832FF8D0D81278.
+```

_code-samples/issue-mpt-with-metadata/js/issue-mpt-with-metadata.js

@@ -0,0 +1,85 @@
+import { stringToHex, hexToString } from '@xrplf/isomorphic/dist/utils/index.js'
+import { MPTokenIssuanceCreateFlags, Client } from 'xrpl'
+
+// Connect to network and get a wallet
+const client = new Client('wss://s.devnet.rippletest.net:51233')
+await client.connect()
+
+console.log('Funding new wallet from faucet...')
+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: [
+    {
+      url: 'https://exampleyield.co/tbill',
+      type: 'website',
+      title: 'Product Page'
+    },
+    {
+      url: 'https://exampleyield.co/docs',
+      type: 'docs',
+      title: 'Yield Token Docs'
+    }
+  ],
+  additional_info: {
+    interest_rate: '5.00%',
+    interest_type: 'variable',
+    yield_source: 'U.S. Treasury Bills',
+    maturity_date: '2045-06-30',
+    cusip: '912796RX0'
+  }
+}
+
+// Convert JSON to a string (without excess whitespace), then string to hex
+const mpt_metadata_hex = stringToHex(JSON.stringify(mpt_metadata))
+
+// Define the transaction, including other MPT parameters
+const mpt_issuance_create = {
+  TransactionType: 'MPTokenIssuanceCreate',
+  Account: wallet.address,
+  AssetScale: 4,
+  MaximumAmount: '50000000',
+  TransferFee: 0,
+  Flags: MPTokenIssuanceCreateFlags.tfMPTCanTransfer |
+            MPTokenIssuanceCreateFlags.tfMPTCanTrade,
+  MPTokenMetadata: mpt_metadata_hex
+}
+
+// Prepare, sign, and submit the transaction
+console.log('Sending MPTokenIssuanceCreate transaction...')
+const submit_response = await client.submitAndWait(mpt_issuance_create, { wallet, autofill: true })
+
+// Check transaction results and disconnect
+console.log(JSON.stringify(submit_response, null, 2))
+if (submit_response.result.meta.TransactionResult !== 'tesSUCCESS') {
+  const result_code = response.result.meta.TransactionResult
+  console.warn(`Transaction failed with result code ${result_code}.`)
+  process.exit(1)
+}
+
+const issuance_id = submit_response.result.meta.mpt_issuance_id
+console.log(`MPToken created successfully with issuance ID ${issuance_id}.`)
+
+// Look up MPT Issuance entry in the validated ledger
+console.log('Confirming MPT Issuance metadata in the validated ledger.')
+const ledger_entry_response = await client.request({
+  "command": "ledger_entry",
+  "mpt_issuance": issuance_id,
+  "ledger_index": "validated"
+})
+
+// Decode the metadata
+const metadata_blob = ledger_entry_response.result.node.MPTokenMetadata
+const decoded_metadata = JSON.parse(hexToString(metadata_blob))
+console.log('Decoded metadata:', decoded_metadata)
+
+
+client.disconnect()

_code-samples/issue-mpt-with-metadata/js/package.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "xrpl": "^4.4.0"
+  },
+  "type": "module"
+}

_code-samples/issue-mpt-with-metadata/py/README.md

@@ -0,0 +1,18 @@
+# Issue MPT with Metadata (Python)
+
+Creates a sample MPT issuance with metadata encoded as JSON according to the [XLS-89 standard](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0089-multi-purpose-token-metadata-schema).
+
+Quick setup and usage:
+
+```sh
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python issue-mpt-with-metadata.py
+```
+
+The script should output a validated transaction and end with a line such as the following:
+
+```text
+MPToken created successfully with issuance ID 0050773D6B8DF8C6BEA497016C8679728A217DE1C4D50AC5.
+```

_code-samples/issue-mpt-with-metadata/py/issue-mpt-with-metadata.py

@@ -0,0 +1,82 @@
+import json
+from xrpl.utils import str_to_hex, hex_to_str
+from xrpl.clients import JsonRpcClient
+from xrpl.wallet import generate_faucet_wallet
+from xrpl.transaction import submit_and_wait
+from xrpl.models import LedgerEntry, MPTokenIssuanceCreate, MPTokenIssuanceCreateFlag
+
+# Set up client and get a wallet
+client = JsonRpcClient("https://s.devnet.rippletest.net:51234")
+print("Funding new wallet from faucet...")
+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": [
+        {
+            "url": "https://exampleyield.co/tbill",
+            "type": "website",
+            "title": "Product Page"
+        },
+        {
+            "url": "https://exampleyield.co/docs",
+            "type": "docs",
+            "title": "Yield Token Docs"
+        }
+    ],
+    "additional_info": {
+        "interest_rate": "5.00%",
+        "interest_type": "variable",
+        "yield_source": "U.S. Treasury Bills",
+        "maturity_date": "2045-06-30",
+        "cusip": "912796RX0"
+    }
+}
+
+# Convert JSON to a string (without excess whitespace), then string to hex
+mpt_metadata_string = json.dumps(mpt_metadata, separators=(',', ':'))
+mpt_metadata_hex = str_to_hex(mpt_metadata_string)
+
+# Define the transaction, including other MPT parameters
+mpt_issuance_create = MPTokenIssuanceCreate(
+    account=wallet.address,
+    asset_scale=4,
+    maximum_amount="50000000",
+    transfer_fee=0,
+    flags=MPTokenIssuanceCreateFlag.TF_MPT_CAN_TRANSFER |
+          MPTokenIssuanceCreateFlag.TF_MPT_CAN_TRADE,
+    mptoken_metadata=mpt_metadata_hex
+)
+
+# Prepare, sign, and submit the transaction
+print("Sending MPTokenIssuanceCreate transaction...")
+response = submit_and_wait(mpt_issuance_create, client, wallet, autofill=True)
+print(json.dumps(response.result, indent=2))
+
+# Check transaction results
+result_code = response.result["meta"]["TransactionResult"]
+if result_code != "tesSUCCESS":
+    print(f"Transaction failed with result code {result_code}")
+    exit(1)
+
+issuance_id = response.result["meta"]["mpt_issuance_id"]
+print(f"MPToken successfully created with issuance ID {issuance_id}")
+
+# Look up MPT Issuance entry in the validated ledger
+print("Confirming MPT Issuance metadata in the validated ledger.")
+ledger_entry_response = client.request(LedgerEntry(
+    mpt_issuance=issuance_id,
+    ledger_index="validated"
+))
+
+# Decode the metadata
+metadata_blob = ledger_entry_response.result["node"]["MPTokenMetadata"]
+decoded_metadata = json.loads(hex_to_str(metadata_blob))
+print("Decoded metadata:", decoded_metadata)

_code-samples/issue-mpt-with-metadata/py/requirements.txt

@@ -0,0 +1 @@
+xrpl-py==4.3.0