ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-06 17:27:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2908 from XRPLF/mpt_concept_and_refs

Browse Source 
Add MPTs to xrpl.org docs
This commit is contained in:
Amarantha Kulkarni
2024-12-20 14:21:11 -08:00
committed by GitHub
parent 3e918ae3bb f5e9a88941
commit 6f27b62a54
16 changed files with 825 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/references/protocol/transactions/metadata.md
View File

@@ -254,7 +254,15 @@ Transactions (`tx` and `account_tx`) involving NFTs can contain the following fi
| `nftoken_id` | String | Shows the `NFTokenID` for the `NFToken` that changed on the ledger as a result of the transaction. Only present if the transaction is `NFTokenMint` or `NFTokenAcceptOffer`. See [NFTokenID](../data-types/nftoken.md#nftokenid). |
| `nftoken_ids` | Array | Shows all the `NFTokenIDs` for the `NFTokens` that changed on the ledger as a result of the transaction. Only present if the transaction is `NFTokenCancelOffer`. |
| `offer_id` | String | Shows the `OfferID`of a new `NFTokenOffer` in a response from a `NFTokenCreateOffer` transaction. |
## MPT Fields
_(Requires the [MPToken amendment][] {% not-enabled /%})_
### Synthetic mpt_issuance_id field
`MPTokenIssuanceID` is an identifier that allows you to specify an `MPTokenIssuance` in RPCs. The server adds a synthetically parsed `mpt_issuance_id` field to API responses to avoid the need for client-side parsing of the `MPTokenIssuanceID`.
### Transaction Metadata
An `mpt_issuance_id` field is provided in JSON transaction metadata (not available for binary) for all successful `MPTokenIssuanceCreate` transactions. The following APIs are impacted: `tx`, `account_tx`, `subscribe` and `ledger`.
## delivered_amount

8
docs/references/protocol/transactions/types/clawback.md
View File

@@ -35,8 +35,12 @@ Clawback is disabled by default. To use clawback, you must send an [AccountSet t
| Field | JSON Type | [Internal Type][] | Description |
|:-------------------|:----------|:------------------|:------------------|
| `Amount` | [Currency Amount][] | Amount |Indicates the amount being clawed back, as well as the counterparty from which the amount is being clawed back. The quantity to claw back, in the `value` sub-field, must not be zero. If this is more than the current balance, the transaction claws back the entire balance. The sub-field `issuer` within `Amount` represents the token holder's account ID, rather than the issuer's.|
| `Holder` | string | AccountID | (Optional) Specifies the holder's address from which to claw back. The holder must already own an `MPToken` object with a non-zero balance. _(Requires the [MPToken amendment][] {% not-enabled /%})_ |
{% admonition type="info" name="Note" %}For an IOU (trust line) in the XRP Ledger, the party that created a token is called the _issuer_, but trust lines are bidirectional and, under some configurations, both sides can be seen as the issuer. In this transaction, the token issuer's address is in the `Account` field, and the token holder's address is in the `Amount` field's `issuer` sub-field.{% /admonition %}
{% admonition type="info" name="Note" %}To claw back funds from an MPT holder, the issuer must have specified that the MPT allows clawback by setting the `tfMPTCanClawback` flag when creating the MPT using the `MPTokenIssuanceCreate` transaction. Assuming an MPT was created with this flag set, clawbacks are allowed using the `Clawback` transaction.{% /admonition %}
{% admonition type="info" name="Note" %}In the XRP Ledger, the party that created a token is called the _issuer_, but trust lines are bidirectional and, under some configurations, both sides can be seen as the issuer. In this transaction, the token issuer's address is in the `Account` field, and the token holder's address is in the `Amount` field's `issuer` sub-field.{% /admonition %}
## Error Cases
@@ -48,6 +52,6 @@ Besides errors that can occur for all transactions, {% $frontmatter.seo.title %}
| `temDISABLED` | Occurs if the [Clawback amendment](/resources/known-amendments.md#clawback) is not enabled. |
| `temBAD_AMOUNT` | Occurs if the holder's balance is 0. It is not an error if the amount exceeds the holder's balance; in that case, the maximum available balance is clawed back. Also occurs if the counterparty listed in `Amount` is the same as the `Account` issuing this transaction. |
| `tecNO_LINE` | Occurs there is no trust line with the counterparty or that trust line's balance is 0. |
| `tecNO_PERMISSION` | Occurs if you attempt to set `lsfAllowTrustlineClawback` while `lsfNoFreeze` is set. Also occurs, conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set. |
| `tecNO_PERMISSION` | Occurs if you attempt to set `lsfAllowTrustlineClawback` while `lsfNoFreeze` is set. Also occurs, conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set. |
{% raw-partial file="/docs/_snippets/common-links.md" /%}

37
docs/references/protocol/transactions/types/mptokenauthorize.md Normal file
View File

@@ -0,0 +1,37 @@
---
html: mptokenauthorize.html
parent: transaction-types.html
blurb: Allow an account to hold an amount of a particular MPT.
labels:
- Multi-purpose Tokens, MPTs
---
# MPTokenAuthorize
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/app/tx/detail/MPTokenAuthorize.cpp "Source")
_(Requires the [MPToken amendment][] {% not-enabled /%})_
This transaction enables an account to hold an amount of a particular MPT issuance. When applied successfully, it creates a new `MPToken` object with an initial zero balance, owned by the holder account.
If the issuer has set `lsfMPTRequireAuth` (allow-listing) on the `MPTokenIssuance`, the issuer must submit an `MPTokenAuthorize` transaction as well in order to give permission to the holder. If `lsfMPTRequireAuth` is not set and the issuer attempts to submit this transaction, it will fail.
<!-- ## MPTokenAuthorize Fields -->
{% raw-partial file="/docs/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:--------------------|:--------------------|:------------------|:-------------------|
| `Account` | string | `AccountID` | This address can indicate either an issuer or a potential holder of a MPT. |
| `TransactionType` | object | `UInt16` | Indicates the new transaction type MPTokenAuthorize. The integer value is 29. |
| `MPTokenIssuanceID` | string | `UIn192` | Indicates the ID of the MPT involved. |
| `Holder` | string | `AccountID` | (Optional) Specifies the holder's address that the issuer wants to authorize. Only used for authorization/allow-listing; must be empty if submitted by the holder. |
| `Flags` | number | `UInt32` | See [MPTokenAuthorize Flags](#mptokenauthorize-flags). |
### MPTokenAuthorize Flags
Transactions of the MPTokenAuthorize type support additional values in the Flags field, as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:-------------------|:-------------|:--------------|:------------------------------|
| `tfMPTUnauthorize` | `0x00000001` | 1 | If set, and transaction is submitted by a holder, it indicates that the holder no longer wants to hold the `MPToken`, which will be deleted as a result. If the holder's `MPToken` has a non-zero balance while trying to set this flag, the transaction fails. On the other hand, if set, and transaction is submitted by an issuer, it would mean that the issuer wants to unauthorize the holder (only applicable for allow-listing), which would unset the `lsfMPTAuthorized` flag on the `MPToken`. |
{% raw-partial file="/docs/_snippets/common-links.md" /%}

63
docs/references/protocol/transactions/types/mptokenissuancecreate.md Normal file
View File

@@ -0,0 +1,63 @@
---
html: mptokenissuancecreate.html
parent: transaction-types.html
blurb: Issue a new Multi-purpose Token.
labels:
- Multi-purpose Tokens, MPTs
---
# MPTokenIssuanceCreate
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/app/tx/detail/MPTokenIssuanceCreate.cpp "Source")
_(Requires the [MPToken amendment][] {% not-enabled /%})_
The `MPTokenIssuanceCreate` transaction creates an [MPTokenIssuance](../../ledger-data/ledger-entry-types/mptokenissuance.md) object and adds it to the relevant directory node of the creator account. This transaction is the only opportunity an issuer has to specify any token fields that are defined as immutable (for example, MPT Flags).
If the transaction is successful, the newly created token is owned by the account (the creator account) that executed the transaction.
Whenever your query returns an `MPTokenIssuance` transaction response, there will always be an `mpt_issuance_id` field on the Transaction Metadata page.
## Example MPTokenIssuanceCreate JSON
This example assumes that the issuer of the token is the signer of the transaction.
```json
{
"TransactionType": "MPTokenIssuanceCreate",
"Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
"AssetScale": 2,
"TransferFee": 314,
"MaximumAmount": "50000000",
"Flags": 83659,
"MPTokenMetadata": "FOO",
"Fee": "10"
}
```
<!-- ## MPTokenIssuanceCreate Fields -->
{% raw-partial file="/docs/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:----------------|:--------------------|:------------------|:-------------------|
| `TransactionType` | string | UInt16 | Indicates the new transaction type MPTokenIssuanceCreate. |
| `AssetScale` | number | UInt8 | (Optional) An asset scale is the difference, in orders of magnitude, between a standard unit and a corresponding fractional unit. More formally, the asset scale is a non-negative integer (0, 1, 2, …) such that one standard unit equals 10^(-scale) of a corresponding fractional unit. If the fractional unit equals the standard unit, then the asset scale is 0. Note that this value is optional, and will default to 0 if not supplied. |
| `Flags` | number | UInt16 | Specifies the flags for this transaction. See [MPTokenIssuanceCreate Flags](#mptokenissuancecreate-flags). |
| `TransferFee` | number | UInt16 | (Optional) The value specifies the fee to charged by the issuer for secondary sales of the Token, if such sales are allowed. Valid values for this field are between 0 and 50,000 inclusive, allowing transfer rates of between 0.000% and 50.000% in increments of 0.001. The field _must not_ be present if the tfMPTCanTransfer flag is not set. If it is, the transaction should fail and a fee should be claimed. |
| `MaximumAmount` | string | UInt64 | (Optional) The maximum asset amount of this token that should ever be issued, as a base 10 encoded string. For issuances that do not have a maximum limit, set this value to 9,223,372,036,854,775,807 (2^63-1). |
| `MPTokenMetadata` | string | Blob | Arbitrary metadata about this issuance, in hex format. The limit for this field is 1024 bytes. |
## MPTokenIssuanceCreate Flags
Transactions of the MPTokenIssuanceCreate type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:-------------------|:-------------|:--------------|:------------------------------|
| `tfMPTCanLock` | `0x00000002` | `2` | If set, indicates that the MPT can be locked both individually and globally. If not set, the MPT cannot be locked in any way. |
| `tfMPTRequireAuth` | `0x00000004` | `4` | If set, indicates that individual holders must be authorized. This enables issuers to limit who can hold their assets. |
| `tfMPTCanEscrow` | `0x00000008` | `8` | If set, indicates that individual holders can place their balances into an escrow. |
| `tfMPTCanTrade` | `0x00000010` | `16` | If set, indicates that individual holders can trade their balances using the XRP Ledger DEX. |
| `tfMPTCanTransfer` | `0x00000020` | `32` | If set, indicates that tokens can be transferred to other accounts that are not the issuer. |
| `tfMPTCanClawback` | `0x00000040` | `64` | If set, indicates that the issuer can use the Clawback transaction to claw back value from individual holders. |
{% raw-partial file="/docs/_snippets/common-links.md" /%}

36
docs/references/protocol/transactions/types/mptokenissuancedestroy.md Normal file
View File

@@ -0,0 +1,36 @@
---
html: mptokenissuancedestroy.html
parent: transaction-types.html
blurb: Remove a Multi-purpose Token from the ledger.
labels:
- Multi-purpose Tokens, MPTs
---
# MPTokenIssuanceDestroy
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/app/tx/detail/MPTokenIssuanceDestroy.cpp "Source")
_(Requires the [MPToken amendment][] {% not-enabled /%})_
The `MPTokenIssuanceDestroy` transaction is used to remove an `MPTokenIssuance` object from the directory node in which it is being held, effectively removing the token from the ledger ("destroying" it).
If this operation succeeds, the corresponding `MPTokenIssuance` is removed and the owner’s reserve requirement is reduced by one. This operation must fail if there are any holders of the MPT in question.
## Example MPTokenIssuanceDestroy JSON
```json
{
"TransactionType": "MPTokenIssuanceDestroy",
"Fee": "10",
"MPTokenIssuanceID": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000"
}
```
<!-- ## MPTokenIssuanceDestroy Fields -->
{% raw-partial file="/docs/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:--------------------|:--------------------|:------------------|:-------------------|
| `TransactionType` | string | UInt16 | Indicates the new transaction type MPTokenIssuanceDestroy. |
| `MPTokenIssuanceID` | string | UInt192 | Identifies the `MPTokenIssuance` object to be removed by the transaction. |
{% raw-partial file="/docs/_snippets/common-links.md" /%}

46
docs/references/protocol/transactions/types/mptokenissuanceset.md Normal file
View File

@@ -0,0 +1,46 @@
---
html: mptokenissuanceset.html
parent: transaction-types.html
blurb: Set mutable properties for an MPT.
labels:
- Multi-purpose Tokens, MPTs
---
# MPTokenIssuanceSet
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/app/tx/detail/MPTokenIssuanceSet.cpp "Source")
_(Requires the [MPToken amendment][] {% not-enabled /%})_
Use this transaction to update a mutable property for a Multi-purpose Token.
## Example
```json
{
"TransactionType": "MPTokenIssuanceSet",
"Fee": "10",
"MPTokenIssuanceID": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000",
"Flags": 1
}
```
<!-- ## MPTokenIssuanceSet Fields -->
{% raw-partial file="/docs/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:-------------------|:--------------------|:------------------|:-------------------|
| `TransactionType` | string | UInt16 | Indicates the new transaction type `MPTokenIssuanceSet`. |
| `MPTokenIssuanceID`| string | UInt192 | The `MPTokenIssuance` identifier. |
| `Holder` | string | AccountID | (Optional) XRPL Address of an individual token holder balance to lock/unlock. If omitted, this transaction applies to all any accounts holding MPTs. |
| `Flag` | number | UInt64 | Specifies flags for this transaction. See [MPTokenIssuanceSet Flags](#mptokenissuanceset-flags). |
### MPTokenIssuanceSet Flags
Transactions of the `MPTokenIssuanceSet` type support additional values in the `Flags` field, as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:-------------------|:-------------|:--------------|:------------------------------|
| `tfMPTLock` | `0x00000001` | 1 | If set, indicates that all MPT balances for this asset should be locked. |
| `tfMPTUnlock` | `0x00000002` | 2 | If set, indicates that all MPT balances for this asset should be unlocked. |
{% raw-partial file="/docs/_snippets/common-links.md" /%}

32
docs/references/protocol/transactions/types/payment.md
View File

@@ -63,6 +63,7 @@ The `Payment` transaction type functions differently depending on how you fill i
| [Cross-currency Payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Send tokens from one holder to another. The `Amount` or `SendMax` can be XRP or tokens, but can't both be XRP. These payments [ripple through](../../../../concepts/tokens/fungible-tokens/rippling.md) the issuer and can take longer [paths](../../../../concepts/tokens/fungible-tokens/paths.md) through several intermediaries if the transaction specifies a path set. [Transfer fees](../../../../concepts/tokens/transfer-fees.md) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md) to connect different currencies, or currencies with the same currency code and different issuers. |
| [Partial payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Sends _up to_ a specific amount of any currency. Uses the [`tfPartialPayment` flag](#payment-flags). May include a `DeliverMin` amount specifying the minimum that the transaction must deliver to be successful; if the transaction does not specify `DeliverMin`, it can succeed by delivering _any positive amount_. |
| Currency conversion | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Required | Yes | Consumes offers in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md) to convert one currency to another, possibly taking [arbitrage](https://en.wikipedia.org/wiki/Arbitrage) opportunities. The `Amount` and `SendMax` cannot both be XRP. Also called a _circular payment_ because it delivers money to the sender. This type of transaction may be classified as an "exchange" and not a "payment". |
| MPT Payment | Object | Omitted | Omitted | Yes | Send MPTs to a holder. See [MPT Payments](#mpt-payments). |
[Direct XRP Payment]: ../../../../concepts/payment-types/direct-xrp-payments.md
[Creating or redeeming tokens]: ../../../../concepts/tokens/index.md
@@ -138,4 +139,35 @@ The `tfLimitQuality` flag is most useful when combined with [partial payments](.
In the above example with a ¥95/$15 offer and a ¥5/$2 offer, the situation is different if my transaction has both `tfPartialPayment` and `tfLimitQuality` enabled. If we keep my `SendMax` of 20 USD and a destination `Amount` of 100 CNY, then the limit quality is still `5`. However, because I am doing a partial payment, the transaction sends as much as it can instead of failing if the full destination amount cannot be sent. This means that my transaction consumes the ¥95/$15 offer, whose quality is about `6.3`, but it rejects the ¥5/$2 offer because that offer's quality of `2.5` is worse than the quality limit of `5`. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates.
## MPT Payments
_(Requires the [MPToken amendment][] {% not-enabled /%})_
When you send a payment using MPTs, the _Amount_ field requires only the `mpt_issuance_id` and the `value`. The `MPTokenIssuanceID` is used to uniquely identify the MPT for the transaction.
Version 1 MPTokens only support direct MPT payment between accounts. They cannot be traded in the decentralized exchange.
### Sample MPT Payment transaction
```json
{
"Account": "rLWSJKbwYSzG32JuGissYd66MFTvfMk4Bt",
"Amount": {
"mpt_issuance_id": "006419063CEBEB49FC20032206CE0F203138BFC59F1AC578",
"value": "100"
},
"DeliverMax": {
"mpt_issuance_id": "006419063CEBEB49FC20032206CE0F203138BFC59F1AC578",
"value": "100"
},
"SendMax": {
"mpt_issuance_id": "006419063CEBEB49FC20032206CE0F203138BFC59F1AC578",
"value": "100"
},
"Destination": "raZ3wTTKiMHn3BiStvz4ET9rbCHfU1DMak",
"Fee": "120",
"Flags": 0,
}
```
{% raw-partial file="/docs/_snippets/common-links.md" /%}