diff --git a/docs/references/protocol/data-types/basic-data-types.md b/docs/references/protocol/data-types/basic-data-types.md index 40c6297b54..452e8eaa74 100644 --- a/docs/references/protocol/data-types/basic-data-types.md +++ b/docs/references/protocol/data-types/basic-data-types.md @@ -129,6 +129,16 @@ XRP is specified as a string containing an integer number of "drops" of XRP, whe "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" } ``` + +- **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": { + "mpt_issuance_id": + "0000012FFD9EE5DA93AC614B4DB94D7E0FCE415CA51BED47", + "value": "131" + } + ``` 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..f6a140038f 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 or 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 @@ -51,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 | |:-----------|:---------------------------|:-----------------------------------| @@ -72,6 +76,25 @@ For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25 "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59" } ``` +### MPT Amounts + +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 +{ + "mpt_issuance_id": + "0000012FFD9EE5DA93AC614B4DB94D7E0FCE415CA51BED47", + "value": "1000000" +} +``` + ### Specifying Without Amounts @@ -111,6 +134,20 @@ 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 + +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