Merge pull request #2908 from XRPLF/mpt_concept_and_refs

Add MPTs to xrpl.org docs

Author: amarantha-k

docs/_snippets/common-links.md

@@ -134,6 +134,7 @@
 [LedgerHashesエントリ]: /docs/references/protocol/ledger-data/ledger-entry-types/ledgerhashes.md
 [LedgerHashesオブジェクト]: /docs/references/protocol/ledger-data/ledger-entry-types/ledgerhashes.md
 [Marker]: /docs/references/http-websocket-apis/api-conventions/markers-and-pagination.md
+[MPToken amendment]: /resources/known-amendments.md#mptokensv1
 [MultiSign amendment]: /resources/known-amendments.md#multisign
 [MultiSignReserve amendment]: /resources/known-amendments.md#multisignreserve
 [NFTokenAcceptOffer transaction]: /docs/references/protocol/transactions/types/nftokenacceptoffer.md

docs/_snippets/mpts-disclaimer.md

@@ -0,0 +1,3 @@
+{% admonition type="info" name="Attention" %}
+Multi-purpose Token functionality is part of the proposed XLS-33d extension to the XRP Ledger protocol. You can use these functions on test networks for now. Until there is an amendment in a stable release, the details documented on these pages are subject to change.
+{% /admonition %}

docs/concepts/tokens/fungible-tokens/index.md

@@ -16,7 +16,7 @@ Fungible tokens are interchangeable and indistinguishable from one another. They
 
 Trust lines are structures in the XRP Ledger for holding fungible [tokens](../index.md). Trust lines enforce the XRP Ledger's rule that you cannot cause someone else to hold a token they don't want. This precaution is necessary to enable the XRP Ledger's use case for [community credit](../index.md#community-credit) among other benefits.
 
-A trust line is defined as a [RippleState](../../references/protocol/ledger-data/ledger-entry-types/ripplestate) object. Each trust line is a _bidirectional_ relationship consisting of:
+A trust line is defined as a [RippleState](../../../references/protocol/ledger-data/ledger-entry-types/ripplestate) object. Each trust line is a _bidirectional_ relationship consisting of:
 
 - The identifiers for the two [accounts](../../accounts/index.md) that the trust line connects.
 - A single, shared balance, which is positive from the perspective of one account and negative from the other perspective.

docs/concepts/tokens/fungible-tokens/multi-purpose-tokens.md

@@ -0,0 +1,66 @@
+---
+blurb: Multi-purpose tokens offer a more compact, flexible token type than trust lines.
+labels:
+  - Tokens
+  - MPTs
+  - Multi-purpose Tokens
+status: not_enabled
+---
+# Multi-purpose Tokens
+
+_(Requires the [MPToken amendment][] {% not-enabled /%})_
+
+Multi-purpose tokens (MPTs) are a more compact and flexible type of fungible token.
+
+MPTs let you take advantage of ready-to-use tokenization features with a few lines of code. You can create many token experiences from one token program itself. Notable features include:
+
+- MPTs store their metadata directly on the XRPL blockchain.
+- A 1024-byte URI field provides a metadata pointer that allows you to use an off-chain source for metadata in addition to the on-chain source. This lets your application access necessary information directly from the chain, prompting higher interoperability for tokens, without losing the ability to attach additional information. 
+- MPTs can have a fixed token supply where you set a cap on the maximum number of tokens that can be minted. 
+- You can define MPTs as non-transferable, tokens that can only be transferred back to the issuer, but not among tokenholders. Useful for cases such as issuing airline credits or loyalty rewards.
+- Issuers can set transfer fees to collect on-chain revenue each time the token is traded among tokenholders. 
+- MPTs also have advanced compliance features: 
+    - The ability to lock tokens held by a tokenholder to support compliance requirements.
+    - The ability to set a global lock for all MPT balances across all tokenholders.
+    - The issuer can configure MPTs that can be clawed back from tokenholder wallets, either to revoke them, or to reassign them in the case of lost wallet keys. 
+    - An opt-in feature can allow only wallets authorized by the issuer to hold issued tokens.
+
+## MPTs versus Trust Lines
+
+Unlike trust lines, MPTs do not represent bidirectional debt relationships. Instead, MPTs function more like a unidirectional trust line with only one balance. This reduces the overhead to support common tokenization requirements, including non-monetary use cases such as tracking reputation points in an online game.
+
+MPTs offer a less complicated conceptual model than trust lines. 
+
+MPTs require significantly less space than trust lines. They require roughly 52 bytes for each MPT held by a token holder, compared to at least 234 bytes for every new trust line.
+
+They reduce the long-term infrastructure and storage burdens for node operators, increasing network resiliency.
+
+MPTs also improve node perfomance when processing large volumes of transactions.
+
+MPTs are unidirectional. While trust lines use "balance netting," MPTs have only a single balance.
+
+An account can issue a maximum of 32 unique MPT issuances. If an issuer wants to support more than this number of MPTs, they can open additional accounts.
+
+Since token holders will not acquire an MPT without first making an off-ledger trust decision, MPTs have no trust limits. For example, a common use case for an MPT is a fiat-backed stablecoin, where a token holder wouldn't purchase more stablecoins than they would feel comfortable holding.
+
+Unlike some existing capabilities of the ledger, MPTs are not subject to rippling, and  do not require configurability settings related to that functionality.
+
+## MPTs versus IOUs
+
+On a technical level, MPTs provide a fundamentally different way to represent fungible tokens on the ledger.  While IOUs are represented by trustlines and have bilateral debt relationships, MPTs use a simpler, unilateral relationship captured by an MPToken object. This results in substantial space savings on the ledger. The representation of a fungible token as a token object instead of a trustline makes it easier to enable functionality for real-world financial assets on-chain, such as token-level metadata, fixed supply, and fixed-point balance.
+
+On a usage level, MPTs provide a straightforward conceptual model compared to trustlines and rippling. Developers can more easily build web3 applications around `MPToken` and `MPTokenIssuance` objects, with some similarities to the conceptual model of XLS-20 NFTs.  It is also simpler for ordinary users to understand what tokens are available, what tokens they have issued, and what they hold in their wallet.  For both issuers and holders of MPTs, there will typically be a smaller XRP reserve compared to the equivalent representations with IOU trustlines.
+
+MPTs are intended to be complementary to IOUs.  While there might be use cases where either MPTs or IOUs might be suitable, there will likely be a need for both over the long term.  There will be use cases such as credit lines for lending and borrowing that might be better represented by IOUs long term.  The MPT feature set should evolve in an incremental manner to unlock more common use cases first and deliver additional feature support at a later time. During the MPT development period, some cases might still be better represented by an IOU, then later be better supported with MPTs.
+
+## See Also
+ 
+- **References:**
+    - [MPToken](../../../references/protocol/ledger-data/ledger-entry-types/mptoken.md)
+    - [MPTokenIssuance](../../../references/protocol/ledger-data/ledger-entry-types/mptokenissuance.md)
+    - [MPTokenAuthorize](../../../references/protocol/transactions/types/mptokenauthorize.md)
+    - [MPTokenIssuanceCreate](../../../references/protocol/transactions/types/mptokenissuancecreate.md)
+    - [MPTokenIssuanceDestroy](../../../references/protocol/transactions/types/mptokenissuancedestroy.md)
+    - [MPTokenIssuanceSet](../../../references/protocol/transactions/types/mptokenissuanceset.md)
+
+{% raw-partial file="/docs/_snippets/common-links.md" /%}

docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders.md

@@ -0,0 +1,158 @@
+---
+blurb: Get the holders for a given `MPTokenIssuanceID` and ledger sequence.
+labels:
+  - Accounts
+  - XRP
+---
+
+# mpt_holders
+
+_(Requires the [MPToken amendment][] {% not-enabled /%})_
+
+For a given `MPTokenIssuanceID` and ledger sequence, `mpt_holders` returns all holders of that MPT and their balance. This method likely returns very large data sets, so you should expect to implement paging via the `marker` field. This API is only available using Clio, not rippled.
+
+## Request Format
+
+*Websocket*
+
+```json
+{
+  "command": "mpt_holders",
+  "mpt_issuance_id": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000",
+  "ledger_index": "validated"
+}
+```
+
+*JSON-RPC*
+
+```json
+{
+  "method": "mpt_holders",
+  "params": [
+    {
+      "mpt_issuance_id": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000",
+      "ledger_index": "validated"
+    }
+  ]
+}
+```
+
+
+The request contains the following parameters:
+
+| Field             | Type                 | Required? | Description |
+|:------------------|:---------------------|:----------|-------------|
+| `mpt_issuance_id` | string               | Yes       | The `MPTokenIssuance` to query. |
+| `ledger_index`    | string or number (positive integer) | No | The ledger index of the max ledger to use, ora shortcut string to choose a ledger automatically. You must specify either ledger_index or ledger_hash. |
+| `ledger_hash`     | string               | No        | A 32-byte hex string for the ledger version to use. You must specify either ledger_index or ledger_hash. |
+| `marker`          | string               | No        | Used to continue your query where it left off in paginating. |
+| `limit`           | number (positive integer) | No   | Specify a limit to the number of MPTs returned. |
+
+## Response Format
+
+```json
+{
+    "mpt_issuance_id": "000004C463C52827307480341125DA0577DEFC38405B0E3E",
+    "limit":50,
+    "ledger_index": 2,
+    "mptokens": [{
+        "account": "rEiNkzogdHEzUxPfsri5XSMqtXUixf2Yx",
+        "flags": 0,
+        "mpt_amount": "20",
+        "mptoken_index": "36D91DEE5EFE4A93119A8B84C944A528F2B444329F3846E49FE921040DE17E65"
+    },
+    {
+        "account": "rrnAZCqMahreZrKMcZU3t2DZ6yUndT4ubN",
+        "flags": 0,
+        "mpt_amount": "1",
+        "mptoken_index": "D137F2E5A5767A06CB7A8F060ADE442A30CFF95028E1AF4B8767E3A56877205A"
+    }],
+    "validated": true
+}
+```
+
+### Response Fields
+
+The response follows the [standard format][], with the result containing the following fields:
+
+| Field                  | Type    | Description                               |
+|:-----------------------|:--------|:------------------------------------------|
+| `mpt_issuance_id`      | string  | The `MPTokenIssuance` queried             |
+| `mptokens`             | array   | An array of mptokens. Includes all relevant fields in the underlying MPToken object. |
+| `marker`               | string  | Used to continue querying where we left off when paginating. Omitted if there are no more entries after this result. |
+| `limit`                | number  | The limit, as specfied in the request
+| `ledger_index`         | number  | The index of the ledger used. |
+
+An `mptoken` object has the following parameters:
+
+| Field                  | Type    | Description |
+|:-----------------------|:--------|:------------------------------------------|
+| `account`              | string  | The account address of the holder who owns the `MPToken`. |
+| `flags`                | number  | The flags assigned to the`MPToken` object. |
+| `mpt_amount`           | string  | Base 10-encoded amount of the holder's balance. |
+| `mptoken_index`        | string  | Key of the `MPToken` object. |
+
+##### Example
+Example of a `tx` response:
+
+```json
+{
+   "result": {
+      "Account": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL",
+      "AssetScale": 2,
+      "Fee": "10",
+      "Flags": 64,
+      "Sequence": 303,
+      "SigningPubKey": "ED39955DEA2D083C6CBE459951A0A84DB337925389ACA057645EE6E6BA99D4B2AE",
+      "TransactionType": "MPTokenIssuanceCreate",
+      "TxnSignature": "80D7B7409980BE9854F7217BB8E836C8A2A191E766F24B5EF2EA7609E1420AABE6A1FDB3038468679081A45563B4D0B49C08F4F70F64E41B578F288A208E4206",
+      "ctid": "C000013100000000",
+      "date": 760643692,
+      "hash": "E563D7942E3E4A79AD73EC12E9E4C44B7C9950DF7BF5FDB75FAD0F5CE0554DB3",
+      "inLedger": 305,
+      "ledger_index": 305,
+      "meta": {
+         "AffectedNodes": [...],
+         "TransactionIndex": 0,
+         "TransactionResult": "tesSUCCESS",
+         "mpt_issuance_id": "0000012F72A341F09A988CDAEA4FF5BE31F25B402C550ABE"
+      },
+      "status": "success",
+      "validated": true
+   }
+}
+```
+
+##### Object
+An `mpt_issuance_id` field is provided in JSON MPTokenIssuance objects (not available for binary). The following APIs are impacted: `ledger_data` and `account_objects`.
+
+##### Example
+Example of an `account_objects` response:
+
+```json
+{
+   "result": {
+      "account": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL",
+      "account_objects": [
+          {
+              "AssetScale": 2,
+            "Flags": 64,
+            "Issuer": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL",
+            "LedgerEntryType": "MPTokenIssuance",
+            "OutstandingAmount": "100",
+            "OwnerNode": "0",
+            "PreviousTxnID": "BDC5ECA6B115C74BF4DA83E36325A2F55DF9E2C968A5CC15EB4D009D87D5C7CA",
+            "PreviousTxnLgrSeq": 308,
+            "Sequence": 303,
+            "index": "75EC6F2939ED6C5798A5F369A0221BC4F6DDC50F8614ECF72E3B976351057A63",
+            "mpt_issuance_id": "0000012F72A341F09A988CDAEA4FF5BE31F25B402C550ABE"
+         }
+      ],
+      "ledger_current_index": 309,
+      "status": "success",
+      "validated": false
+   }
+}
+```
+
+{% raw-partial file="/docs/_snippets/common-links.md" /%}