mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-20 19:55:54 +00:00
150 lines
6.6 KiB
Markdown
150 lines
6.6 KiB
Markdown
---
|
||
seo:
|
||
description: Issue a Multi-Purpose Token (MPT) with arbitrary metadata on the XRP Ledger.
|
||
metadata:
|
||
indexPage: true
|
||
labels:
|
||
- Multi-Purpose Token
|
||
- MPT
|
||
- Token Issuance
|
||
---
|
||
# Issue a Multi-Purpose Token (MPT)
|
||
|
||
A [Multi-Purpose Token (MPT)](../../../concepts/tokens/fungible-tokens/multi-purpose-tokens.md) 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](../../../concepts/tokens/fungible-tokens/multi-purpose-tokens.md#metadata-schema) defined in [XLS-89](https://xls.xrpl.org/xls/XLS-0089-multi-purpose-token-metadata-schema.html).
|
||
|
||
## Goals
|
||
|
||
By the end of this tutorial, you will be able to:
|
||
|
||
- Issue a new MPT using the `MPTokenIssuanceCreate` transaction.
|
||
- 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](https://github.com/XRPLF/xrpl.js). See [Get Started Using JavaScript](../../javascript/build-apps/get-started.md) 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](https://github.com/XRPLF/xrpl-dev-portal/tree/master/_code-samples/issue-mpt-with-metadata).
|
||
|
||
## Steps
|
||
|
||
### 1. Install dependencies
|
||
|
||
{% tabs %}
|
||
{% tab label="Javascript" %}
|
||
From the code sample folder, use npm to install dependencies:
|
||
|
||
```bash
|
||
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**:
|
||
- [Multi-Purpose Tokens (MPT)](../../../concepts/tokens/fungible-tokens/multi-purpose-tokens.md)
|
||
- **References**:
|
||
- [MPTokenIssuanceCreate Transaction](../../../references/protocol/transactions/types/mptokenissuancecreate.md)
|
||
|
||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|