6.6 KiB
Issue a Multi-Purpose Token (MPT)
A Multi-Purpose Token (MPT) lets you to quickly access powerful, built-in tokenization features on the XRP Ledger with minimal code.
This tutorial shows you how to issue an MPT with on-chain metadata such as the token's ticker, name, or description, encoded according to the MPT metadata schema defined in XLS-89.
Goals
By the end of this tutorial, you will be able to:
- Issue a new MPT using the
MPTokenIssuanceCreatetransaction. - Encode or decode token metadata following MPT standards best practices.
Prerequisites
To complete this tutorial, you should:
- Have a basic understanding of the XRP Ledger and token issuance.
- Have an XRP Ledger client library set up in your development environment. This page provides examples for the following:
- JavaScript with the xrpl.js library. See Get Started Using JavaScript for setup steps.
Source Code
You can find the complete source code for this tutorial's example in the code samples section of this website's repository.
Steps
1. Install dependencies
{% tabs %} {% tab label="Javascript" %} From the code sample folder, use npm to install dependencies:
npm install xrpl
{% /tab %} {% /tabs %}
2. Set up client and fund issuer wallet
Import the client library, instantiate a client to connect to the XRPL, and fund a new wallet to act as the token issuer.
{% tabs %} {% tab label="Javascript" %} {% code-snippet file="/_code-samples/issue-mpt-with-metadata/js/issue-mpt-with-metadata.js" language="js" before="// Define metadata as JSON" /%} {% /tab %} {% /tabs %}
3. Define and encode MPT metadata
Define your token's metadata as a JSON object:
{% tabs %} {% tab label="Javascript" %} {% code-snippet file="/_code-samples/issue-mpt-with-metadata/js/issue-mpt-with-metadata.js" language="js" from="// Define metadata as JSON" before="// Encode the metadata" /%} {% /tab %} {% /tabs %}
The metadata schema supports both long field names (e.g., ticker, name, desc) and compact short keys (e.g., t, n, d). To save space on the ledger, it’s recommended to use short key names. The MPT metadata field has a 1024-byte limit, so using compact keys allows you to include more information.
The SDK libraries provide utility functions to encode or decode the metadata for you, so you don't have to. If long field names are provided in the metadata JSON, the encoding utility function automatically shortens them to their compact key equivalents before encoding. Similarly, when decoding, the decoding utility function converts the shorthands back to the respective long names.
{% tabs %}
{% tab label="Javascript" %}
Use the encodeMPTokenMetadata() function to encode metadata with xrpl.js.
{% code-snippet file="/_code-samples/issue-mpt-with-metadata/js/issue-mpt-with-metadata.js" language="js" from="// Encode the metadata" before="// Define the transaction" /%}
{% /tab %}
{% /tabs %}
{% admonition type="warning" name="Warning" %} While the encoding utility formats the JSON for you correctly and replaces the full key names with shorthands, it does not validate the metadata content or size. {% /admonition %}
4. Prepare the MPTokenIssuanceCreate transaction
Create the transaction object, specifying the issuer, asset scale, maximum amount, transfer/trade flags, and the encoded metadata.
| Field | Value |
|---|---|
TransactionType |
The type of transaction, in this case MPTokenIssuanceCreate. |
Account |
The wallet address of the account that is issuing the MPT. |
AssetScale |
The number of decimal places for the token. |
MaximumAmount |
The maximum supply of the token to be issued. |
TransferFee |
The transfer fee (if any) to charge for token transfers. |
Flags |
Flags to control transfer/trade permissions. |
MPTokenMetadata |
The hex-encoded metadata for the token. |
{% tabs %} {% tab label="Javascript" %} {% code-snippet file="/_code-samples/issue-mpt-with-metadata/js/issue-mpt-with-metadata.js" language="js" from="// Define the transaction" before="// Prepare, sign, and submit the transaction" /%} {% /tab %} {% /tabs %}
5. Submit the transaction
Sign and submit the transaction, then wait for validation.
{% tabs %} {% tab label="Javascript" %} {% code-snippet file="/_code-samples/issue-mpt-with-metadata/js/issue-mpt-with-metadata.js" language="js" from="// Prepare, sign, and submit the transaction" before="// Check transaction results" /%} {% /tab %} {% /tabs %}
6. Check transaction result
Verify that the transaction succeeded and retrieve the MPT issuance ID.
{% tabs %} {% tab label="Javascript" %} {% code-snippet file="/_code-samples/issue-mpt-with-metadata/js/issue-mpt-with-metadata.js" language="js" from="// Check transaction results" before="// Look up MPT Issuance entry" /%} {% /tab %} {% /tabs %}
{% admonition type="info" name="Note" %}
A tesSUCCESS result indicates that the MPT issuance transaction was processed successfully and the token was created.
{% /admonition %}
7. Confirm MPT issuance and decode metadata
Look up the MPT issuance entry in the validated ledger and decode the metadata to verify it matches your original input.
{% tabs %} {% tab label="Javascript" %} {% code-snippet file="/_code-samples/issue-mpt-with-metadata/js/issue-mpt-with-metadata.js" language="js" from="// Look up MPT Issuance entry" /%} {% /tab %} {% /tabs %}
The decoding utility function converts the metadata shorthand key names back to the respective long names.
See Also
- Concepts:
- References:
{% raw-partial file="/docs/_snippets/common-links.md" /%}