From 739e769c6bb73452b5f8de6df769a075b48837b9 Mon Sep 17 00:00:00 2001 From: Dennis Dawson Date: Fri, 21 Feb 2025 15:04:48 -0800 Subject: [PATCH 1/8] Add MPTs to basic data types and currency formats --- .../protocol/data-types/basic-data-types.md | 6 +++ .../protocol/data-types/currency-formats.md | 46 +++++++++++++------ 2 files changed, 38 insertions(+), 14 deletions(-) diff --git a/docs/references/protocol/data-types/basic-data-types.md b/docs/references/protocol/data-types/basic-data-types.md index 40c6297b54..231c0159b1 100644 --- a/docs/references/protocol/data-types/basic-data-types.md +++ b/docs/references/protocol/data-types/basic-data-types.md @@ -129,6 +129,12 @@ XRP is specified as a string containing an integer number of "drops" of XRP, whe "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" } ``` + +- **MPT** - Use `MPTAmount` to specify the value of an MPT. To specify a value of 13.1 units of an MPT: + + ``` + "MPTAmount": 13.1 + ``` For more information, see [Currency Formats](currency-formats.md). diff --git a/docs/references/protocol/data-types/currency-formats.md b/docs/references/protocol/data-types/currency-formats.md index 7082493d44..7aaf80dcb9 100644 --- a/docs/references/protocol/data-types/currency-formats.md +++ b/docs/references/protocol/data-types/currency-formats.md @@ -6,29 +6,32 @@ seo: label: - XRP - Tokens + - MPTs --- # Currency Formats -The XRP Ledger has two kinds of digital asset: XRP and [tokens](../../../concepts/tokens/index.md). Both types have high precision, although their formats are different. +The XRP Ledger has three kinds of digital asset: XRP, [tokens](../../../concepts/tokens/index.md), and [Multi-purpose Tokens (MPTs)](../../../concepts/tokens/fungible-tokens/multi-purpose-tokens.md). All three types have high precision, although their formats are different. + +_(Requires the [MPToken amendment][] {% not-enabled /%})_ ## Comparison -The following table summarizes some of the differences between XRP and tokens in the XRP Ledger: +The following table summarizes some of the differences XRP, tokens, and MPTs in the XRP Ledger: -| XRP | Tokens | -|:---------------------------------------------------------|:------------------| -| Has no issuer. | Always issued by an XRP Ledger account. | -| Specified as a string. | Specified as an object. | -| Tracked in [accounts](../ledger-data/ledger-entry-types/accountroot.md). | Tracked in [trust lines](../ledger-data/ledger-entry-types/ripplestate.md). | -| Can never be created; can only be destroyed. | Can be issued or redeemed freely. | -| Minimum value: `0`. (Cannot be negative.) | Minimum value: `-9999999999999999e80`. Minimum nonzero absolute value: `1000000000000000e-96`. -| Maximum value `100000000000` (1011) XRP. That's `100000000000000000` (1017) "drops". | Maximum value `9999999999999999e80`. | +| XRP | Tokens | MPTs | +|:---------------------------------------------------------|:------------------|:---------------------| +| Has no issuer. | Always issued by an XRP Ledger account. | Always issued by an XRP Ledger account. | +| Specified as a string. | Specified as an object. | Specified as an object. | +| Tracked in [accounts](../ledger-data/ledger-entry-types/accountroot.md). | Tracked in [trust lines](../ledger-data/ledger-entry-types/ripplestate.md). | Tracked in holder's account. | +| Can never be created; can only be destroyed. | Can be issued or redeemed freely. | Can be issued or redeemed freely. | +| Minimum value: `0`. (Cannot be negative.) | Minimum value: `-9999999999999999e80`. Minimum nonzero absolute value: `1000000000000000e-96`. | Minimum value: `0`. (Cannot be negative.) | +| Maximum value `100000000000` (1011) XRP. That's `100000000000000000` (1017) "drops". | Maximum value `9999999999999999e80`. | Maximum value `0x7FFFFFFFFFFFFFFF`. | | Precise to the nearest "drop" (0.000001 XRP) | 15 decimal digits of precision. | -| Can't be [frozen](../../../concepts/tokens/fungible-tokens/freezes.md). | The issuer can [freeze](../../../concepts/tokens/fungible-tokens/freezes.md) balances. | -| No transfer fees; XRP-to-XRP payments are always direct. | Can take indirect [paths](../../../concepts/tokens/fungible-tokens/paths.md) with each issuer charging a percentage [transfer fee](../../../concepts/tokens/transfer-fees.md). | -| Can be used in [Payment Channels](../../../concepts/payment-types/payment-channels.md) and [Escrow](../../../concepts/payment-types/escrow.md). | Not compatible with Payment Channels or Escrow. | +| Can't be [frozen](../../../concepts/tokens/fungible-tokens/freezes.md). | The issuer can [freeze](../../../concepts/tokens/fungible-tokens/freezes.md) balances. | The issuer can lock balances individually and globally. | +| No transfer fees; XRP-to-XRP payments are always direct. | Can take indirect [paths](../../../concepts/tokens/fungible-tokens/paths.md) with each issuer charging a percentage [transfer fee](../../../concepts/tokens/transfer-fees.md). | Can charge a transfer fee for secondary sales of the token. | +| Can be used in [Payment Channels](../../../concepts/payment-types/payment-channels.md) and [Escrow](../../../concepts/payment-types/escrow.md). | Not compatible with Payment Channels or Escrow. | Not compatible with Payment Channels. Can be used for escrow. | -For more information, see [What is XRP?](../../../introduction/what-is-xrp.md) and [Tokens](../../../concepts/tokens/index.md). +See [What is XRP?](../../../introduction/what-is-xrp.md), [Tokens](../../../concepts/tokens/index.md), and [Multi-purpose Tokens](../../../concepts/tokens/fungible-tokens/multi-purpose-tokens.md). ## Specifying Currency Amounts @@ -36,6 +39,7 @@ Use the appropriate format for the type of currency you want to specify: - [XRP Amounts](#xrp-amounts) - [Token Amounts](#token-amounts) +- [MPT Amounts](#mpt-amounts) ### XRP Amounts @@ -72,6 +76,16 @@ For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25 "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59" } ``` +### MPT Amounts + +Specify the amount of MPTs using the `MPTAmount` field. For example, to specify 1 million units of an MPT you would specify: + +```json +{ + "MPTAmount": "1000000" +} +``` + ### Specifying Without Amounts @@ -111,6 +125,10 @@ When sending token amounts in the XRP Ledger's peer-to-peer network, servers [se {% admonition type="success" name="Tip" %}For tokens that should not be divisible at all, see [Non-Fungible Tokens (NFTs)](../../../concepts/tokens/nfts/index.md).{% /admonition %} +## MPT Precision + + + ## Currency Codes [Currency Code]: #currency-codes From a8d3a7e350cae0e785d8aa5a3ee49f59c0a42879 Mon Sep 17 00:00:00 2001 From: Dennis Dawson Date: Mon, 24 Feb 2025 10:29:36 -0800 Subject: [PATCH 2/8] Update docs/references/protocol/data-types/basic-data-types.md Co-authored-by: Shawn Xie <35279399+shawnxie999@users.noreply.github.com> --- docs/references/protocol/data-types/basic-data-types.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/references/protocol/data-types/basic-data-types.md b/docs/references/protocol/data-types/basic-data-types.md index 231c0159b1..a6a8131428 100644 --- a/docs/references/protocol/data-types/basic-data-types.md +++ b/docs/references/protocol/data-types/basic-data-types.md @@ -133,7 +133,11 @@ XRP is specified as a string containing an integer number of "drops" of XRP, whe - **MPT** - Use `MPTAmount` to specify the value of an MPT. To specify a value of 13.1 units of an MPT: ``` - "MPTAmount": 13.1 + "Amount": { + "mpt_issuance_id": + "0000012FFD9EE5DA93AC614B4DB94D7E0FCE415CA51BED47", + "value": "131" + } ``` For more information, see [Currency Formats](currency-formats.md). From 3ceac2ea6404e02aada89b5b0c66ed4a9137aed1 Mon Sep 17 00:00:00 2001 From: Dennis Dawson Date: Mon, 24 Feb 2025 10:31:28 -0800 Subject: [PATCH 3/8] Update docs/references/protocol/data-types/basic-data-types.md Co-authored-by: Shawn Xie <35279399+shawnxie999@users.noreply.github.com> --- docs/references/protocol/data-types/basic-data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/protocol/data-types/basic-data-types.md b/docs/references/protocol/data-types/basic-data-types.md index a6a8131428..7960c70fad 100644 --- a/docs/references/protocol/data-types/basic-data-types.md +++ b/docs/references/protocol/data-types/basic-data-types.md @@ -130,7 +130,7 @@ XRP is specified as a string containing an integer number of "drops" of XRP, whe } ``` -- **MPT** - Use `MPTAmount` to specify the value of an MPT. To specify a value of 13.1 units of an MPT: +- **MPT** - Use `Amount` to specify the value of an MPT. To specify a value of 13.1 units of an MPT: ``` "Amount": { From 254e953c59f3761e80cfa04b1cbec04ee197d04c Mon Sep 17 00:00:00 2001 From: Dennis Dawson Date: Mon, 24 Feb 2025 10:31:40 -0800 Subject: [PATCH 4/8] Update docs/references/protocol/data-types/currency-formats.md Co-authored-by: Shawn Xie <35279399+shawnxie999@users.noreply.github.com> --- docs/references/protocol/data-types/currency-formats.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/protocol/data-types/currency-formats.md b/docs/references/protocol/data-types/currency-formats.md index 7aaf80dcb9..afd74e8b9c 100644 --- a/docs/references/protocol/data-types/currency-formats.md +++ b/docs/references/protocol/data-types/currency-formats.md @@ -29,7 +29,7 @@ The following table summarizes some of the differences XRP, tokens, and MPTs in | Precise to the nearest "drop" (0.000001 XRP) | 15 decimal digits of precision. | | Can't be [frozen](../../../concepts/tokens/fungible-tokens/freezes.md). | The issuer can [freeze](../../../concepts/tokens/fungible-tokens/freezes.md) balances. | The issuer can lock balances individually and globally. | | No transfer fees; XRP-to-XRP payments are always direct. | Can take indirect [paths](../../../concepts/tokens/fungible-tokens/paths.md) with each issuer charging a percentage [transfer fee](../../../concepts/tokens/transfer-fees.md). | Can charge a transfer fee for secondary sales of the token. | -| Can be used in [Payment Channels](../../../concepts/payment-types/payment-channels.md) and [Escrow](../../../concepts/payment-types/escrow.md). | Not compatible with Payment Channels or Escrow. | Not compatible with Payment Channels. Can be used for escrow. | +| Can be used in [Payment Channels](../../../concepts/payment-types/payment-channels.md) and [Escrow](../../../concepts/payment-types/escrow.md). | Not compatible with Payment Channels or Escrow. | Not compatible with Payment Channels or Escrow. | See [What is XRP?](../../../introduction/what-is-xrp.md), [Tokens](../../../concepts/tokens/index.md), and [Multi-purpose Tokens](../../../concepts/tokens/fungible-tokens/multi-purpose-tokens.md). From 392f8da033d061f0339c5b04c5c2240afa4d493d Mon Sep 17 00:00:00 2001 From: Dennis Dawson Date: Mon, 24 Feb 2025 10:31:51 -0800 Subject: [PATCH 5/8] Update docs/references/protocol/data-types/currency-formats.md Co-authored-by: Shawn Xie <35279399+shawnxie999@users.noreply.github.com> --- docs/references/protocol/data-types/currency-formats.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/references/protocol/data-types/currency-formats.md b/docs/references/protocol/data-types/currency-formats.md index afd74e8b9c..07526651de 100644 --- a/docs/references/protocol/data-types/currency-formats.md +++ b/docs/references/protocol/data-types/currency-formats.md @@ -82,7 +82,9 @@ Specify the amount of MPTs using the `MPTAmount` field. For example, to specify ```json { - "MPTAmount": "1000000" + "mpt_issuance_id": + "0000012FFD9EE5DA93AC614B4DB94D7E0FCE415CA51BED47", + "value": "1000000" } ``` From e276d90d37f8b2827f84a4f8ae66ad27cd3be3c4 Mon Sep 17 00:00:00 2001 From: Dennis Dawson Date: Mon, 24 Feb 2025 10:32:02 -0800 Subject: [PATCH 6/8] Update docs/references/protocol/data-types/currency-formats.md Co-authored-by: Shawn Xie <35279399+shawnxie999@users.noreply.github.com> --- docs/references/protocol/data-types/currency-formats.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/protocol/data-types/currency-formats.md b/docs/references/protocol/data-types/currency-formats.md index 07526651de..03d359b743 100644 --- a/docs/references/protocol/data-types/currency-formats.md +++ b/docs/references/protocol/data-types/currency-formats.md @@ -78,7 +78,7 @@ For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25 ``` ### MPT Amounts -Specify the amount of MPTs using the `MPTAmount` field. For example, to specify 1 million units of an MPT you would specify: +Specify the amount of MPTs using the `Amount` field. For example, to specify 1 million units of an MPT you would specify: ```json { From 732b137da4ee6233ffcb727dbaead57fb5835897 Mon Sep 17 00:00:00 2001 From: Dennis Dawson Date: Mon, 24 Feb 2025 11:25:27 -0800 Subject: [PATCH 7/8] add field table under MPT amounts, minor updates --- .../protocol/data-types/currency-formats.md | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/references/protocol/data-types/currency-formats.md b/docs/references/protocol/data-types/currency-formats.md index 03d359b743..f6a140038f 100644 --- a/docs/references/protocol/data-types/currency-formats.md +++ b/docs/references/protocol/data-types/currency-formats.md @@ -55,7 +55,7 @@ XRP amounts cannot be negative. ### Token Amounts -To specify an amount of a [(fungible) token](../../../concepts/tokens/index.md), use an Amount object. This is a JSON object with three fields: +To specify an amount of a [(fungible) token](../../../concepts/tokens/index.md), use an `Amount` object. Tokens use the `currency`, `value`, and `issuer` fields. | `Field` | Type | Description | |:-----------|:---------------------------|:-----------------------------------| @@ -78,7 +78,14 @@ For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25 ``` ### MPT Amounts -Specify the amount of MPTs using the `Amount` field. For example, to specify 1 million units of an MPT you would specify: +Specify the amount of MPTs using the `value` field. + +| `Field` | Type | Description | +|:-----------|:---------------------------|:-----------------------------------| +| `mpt_issuance_id` | String | Arbitrary unique identifier for a Multi-purpose Token. | +| `value` | [String Number][] | A string representing a positive integer value. Valid values for this field are between 0x0 and 0x7FFFFFFFFFFFFFFF. Use `AssetScale` to enable values as fractions of the MPT value. See [MPT Precision](#mpt-precision). | + +For example, to specify 1 million units of an MPT you would specify: ```json { @@ -129,7 +136,17 @@ When sending token amounts in the XRP Ledger's peer-to-peer network, servers [se ## MPT Precision +MPTs are always expressed in whole integers. You can change the `AssetScale` of your MPT to express the basic unit as a fraction of an MPT. The XRP Ledger doesn't use the `AssetScale` on-chain: this is for your convenience in specifying the basic unit. +For example, to express a value of 13.1 MPT, the MPT would require that the `AssetScale` be set to 1, and the `value` of the MPT set to 131. + +```json + "Amount": { + "mpt_issuance_id": + "0000012FFD9EE5DA93AC614B4DB94D7E0FCE415CA51BED47", + "value": "131" + } +``` ## Currency Codes [Currency Code]: #currency-codes From 492fb4651258831b9adf95fc605a3de47c7531ef Mon Sep 17 00:00:00 2001 From: Dennis Dawson Date: Tue, 25 Feb 2025 08:41:25 -0800 Subject: [PATCH 8/8] Update basic-data-types.md --- docs/references/protocol/data-types/basic-data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/protocol/data-types/basic-data-types.md b/docs/references/protocol/data-types/basic-data-types.md index 7960c70fad..452e8eaa74 100644 --- a/docs/references/protocol/data-types/basic-data-types.md +++ b/docs/references/protocol/data-types/basic-data-types.md @@ -130,7 +130,7 @@ XRP is specified as a string containing an integer number of "drops" of XRP, whe } ``` -- **MPT** - Use `Amount` to specify the value of an MPT. To specify a value of 13.1 units of an MPT: +- **MPT** - Use `Amount` to specify the value of an MPT. Assuming an `AssetScale` of *1*, you would specify a value of 13.1 units of an MPT as follows: ``` "Amount": {