Skip to content

update mpt docs for permissioneddomains #3251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: rippled-3.0.0
Choose a base branch
from
+30 −0
Open

update mpt docs for permissioneddomains #3251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f20f8c5
update mpt docs for permissioneddomains
oeggert Aug 20, 2025
015f3ab
add reviewer suggestions
oeggert Aug 21, 2025
45e0809
update error codes and amendment component
oeggert Nov 4, 2025
864c412
initialize 3.0 doc branch
oeggert Nov 4, 2025
b9a0772
Merge branch 'rippled-3.0.0' into sav-doc-updates
oeggert Nov 4, 2025
1143443
add @mDuo13 suggestions
oeggert Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/references/protocol/transactions/types/mptokenissuancecreate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ This example assumes that the issuer of the token is the signer of the transacti
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:------------------|:---------------------|:------------------|:----------|:------------|
| `AssetScale` | Number | UInt8 | No | Where to put the decimal place when displaying amounts of this MPT. 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. For example, if a US Dollar Stablecoin has an asset scale of _2_, then 1 unit of that MPT would equal 0.01 US Dollars. This indicates to how many decimal places the MPT can be subdivided. If omitted, the default is 0, meaning that the MPT cannot be divided into smaller than 1 unit. |
| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that grants access to the MPT. You must set the `tfMPTRequireAuth` flag to use permissioned domains.<br>{% amendment-disclaimer name="PermissionedDomains" /%}<br>{% amendment-disclaimer name="SingleAssetVault" /%} |
Copy link
Collaborator

@mDuo13 mDuo13 Nov 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. You don't need <br> tags here, since the disclaimer already uses its own <p> tag.
  2. Use "enable" instead of "set" for clarity when talking about flags. ("Set? To what?")
  3. This is currently (as expected) throwing errors because the SingleAssetVault amendment isn't in the VHS data yet. We should make a note to come back and double-check this before merging to the master branch, closer to release—but it's not a blocker for merging to the rippled-3.0.0 branch.
2025-11-25_155553_819960840
Suggested change
| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that grants access to the MPT. You must set the `tfMPTRequireAuth` flag to use permissioned domains.<br>{% amendment-disclaimer name="PermissionedDomains" /%}<br>{% amendment-disclaimer name="SingleAssetVault" /%} |
| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that grants access to the MPT. You must enable the `tfMPTRequireAuth` flag to use permissioned domains. {% amendment-disclaimer name="PermissionedDomains" /%} {% amendment-disclaimer name="SingleAssetVault" /%} |

| `TransferFee` | Number | UInt16 | No | 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 - Number | UInt64 | No | The maximum asset amount of this token that can ever be issued, as a base-10 number encoded as a string. The current default maximum limit is 9,223,372,036,854,775,807 (2^63-1). _This limit may increase in the future. If an upper limit is required, you must specify this field._ |
| `MPTokenMetadata` | String - Hexadecimal | Blob | No | Arbitrary metadata about this issuance. The limit for this field is 1024 bytes. By convention, the metadata should decode to JSON data describing what the MPT represents. The [XLS-89 specification](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0089-multi-purpose-token-metadata-schema) defines a recommended format for metadata. |
Expand All @@ -60,6 +61,20 @@ Transactions of the MPTokenIssuanceCreate type support additional values in the
| `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. |


## Error Cases

Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/index.md):

| Error Code | Description |
|:--------------------------|:------------|
| `tecDIR_FULL` | The owner directory of the account creating the `MPTokenIssuance` ledger entry is full. |
| `temBAD_TRANSFER_FEE` | The transfer fee specified is greater than the maximum allowed value of 50,000. |
| `temDISABLED` | The `MPTokensV1` amendment is disabled. You will also receive this error if you include a `DomainID` field in the transaction, but the `PermissionedDomains` and `SingleAssetVault` amendments are both disabled. |
| `tecINSUFFICIENT_RESERVE` | The account creating the `MPTokenIssuance` ledger entry doesn't have enough XRP to meet the owner reserve. |
| `temMALFORMED` | - A non-zero transfer fee is set, but the `tfMPTCanTransfer` flag is _not_ set.<br>- The `DomainID` points to an invalid permissioned domain; you can also receive this error if you include a `DomainID` without setting the `tfMPTRequireAuth` flag.<br>- The `MPTokenMetadata` field is an invalid length (0 or exceeds 1024 bytes).<br>- The `MaximumAmount` field is 0 or exceeds 9,223,372,036,854,775,807 (2^63-1). |
Copy link
Collaborator

@mDuo13 mDuo13 Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

temMALFORMED is one of the errors that can occur for any transaction type.

Suggested change
| `temMALFORMED` | - A non-zero transfer fee is set, but the `tfMPTCanTransfer` flag is _not_ set.<br>- The `DomainID` points to an invalid permissioned domain; you can also receive this error if you include a `DomainID` without setting the `tfMPTRequireAuth` flag.<br>- The `MPTokenMetadata` field is an invalid length (0 or exceeds 1024 bytes).<br>- The `MaximumAmount` field is 0 or exceeds 9,223,372,036,854,775,807 (2^63-1). |

Copy link
Collaborator Author

@oeggert oeggert Nov 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True, but I think it's helpful to explain what specifically you could be malforming to make it easier for someone to troubleshoot.

Maybe I could preface it with something like: "Besides generally malformed transactions, you can receive this error if ..."

Copy link
Collaborator

@mDuo13 mDuo13 Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are infinite ways to creatively malform a transaction, but if there are common uses or patterns that hit the specific cases described here, then I agree it makes sense to note it here with a preface like you suggested.



## See Also

- [MPTokenIssuance entry][]
Expand Down
15 changes: 15 additions & 0 deletions docs/references/protocol/transactions/types/mptokenissuanceset.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ This example locks the balances of all holders of the specified MPT issuance.

| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:---------------------|:------------------|:----------|-------------|
| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that grants access to the MPT. An empy value or `0` will remove permissioned domain access management. Any accounts that lose access to the MPT because of `DomainID` updates--unless explicitly authorized by the MPT issuer--lose the ability to send or receive MPTs they already hold. The `tfMPTRequireAuth` flag must have been set in the `MPTokenIssuanceCreate` transaction to use permissioned domains.<br>{% amendment-disclaimer name="PermissionedDomains" /%}<br>{% amendment-disclaimer name="SingleAssetVault" /%} |
Copy link
Collaborator

@mDuo13 mDuo13 Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Typo ("empy")
  2. Avoid future tense.
  3. Use an actual emdash instead of two hyphens. (Here's one you can copy-paste: — ) Or better yet, avoid phrasing sentences with this type of interjection in the first place.
  4. The description feels a little confusing about when you lose the ability to send or receive MPTs.
  5. The phrase "permissioned domain access management" feels a little ambiguous or confusing, like it's controlling who has access to manage the domain itself, and I don't think it's defined anywhere in those exact terms. Either rephrase into simpler language or shorten this description and link to a better description on a concept page.
  6. Rather than talk about the exact transaction flag from the create transaction, talk about the current state of the MPT issuance (among other reasons, maybe that flag is mutable).
Suggested change
| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that grants access to the MPT. An empy value or `0` will remove permissioned domain access management. Any accounts that lose access to the MPT because of `DomainID` updates--unless explicitly authorized by the MPT issuer--lose the ability to send or receive MPTs they already hold. The `tfMPTRequireAuth` flag must have been set in the `MPTokenIssuanceCreate` transaction to use permissioned domains.<br>{% amendment-disclaimer name="PermissionedDomains" /%}<br>{% amendment-disclaimer name="SingleAssetVault" /%} |
| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that grants access to the MPT. An empty value or `0` removes the permissioned domain from the MPT issuance so that only users who are explicitly approved by the issuer can send and receive the MPT. You can only set a `DomainID` if the MPT issuance has [**Require Auth**](/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens#transferability-controls) enabled.) {% amendment-disclaimer name="PermissionedDomains" /%} {% amendment-disclaimer name="SingleAssetVault" /%} |

Copy link
Collaborator

@mDuo13 mDuo13 Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note, I opened #3392 since it feels like we need better documentation on how to create and use allow-listing with MPTs (concept/tutorial/code sample/etc.).

| `MPTokenIssuanceID` | String - Hexadecimal | UInt192 | Yes | The identifier of the `MPTokenIssuance` to update. |
| `Holder` | String - [Address][] | AccountID | No | An individual token holder. If provided, apply changes to the given holder's balance of the given MPT issuance. If omitted, apply to all accounts holding the given MPT issuance. |

Expand All @@ -44,6 +45,20 @@ Transactions of the `MPTokenIssuanceSet` type support additional values in the `
| `tfMPTLock` | `0x00000001` | 1 | Enable to lock balances of this MPT issuance. |
| `tfMPTUnlock` | `0x00000002` | 2 | Enable to unlock balances of this MPT issuance. |


## Error Cases

Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/index.md):

| Error Code | Description |
|:--------------------------|:------------|
| `temDISABLED` | The `MPTokensV1` amendment is disabled. You will also receive this error if you include a `DomainID` field in the transaction, but the `PermissionedDomains` and `SingleAssetVault` amendments are both disabled. |
| `tecNO_DST` | The account specified in the `Holder` field doesn't exist. |
| `tecNO_PERMISSION` | - The `lsfMPTCanLock` flag isn't enabled, but you are attempting to lock or unlock an MPT.<br>- The `SingleAssetVault` amendment is disabled and you're trying to modify a `DomainID` field. |
| `temMALFORMED` | - You specified a `DomainID` and `Holder` value--only one can be set in a single transaction.<br>- You specified the same account for both `Acount` and `Holder`.<br>- The transaction isn't changing anything; it must either update a flag or modify the `DomainID`. |
Copy link
Collaborator

@mDuo13 mDuo13 Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

temMALFORMED is a code that can occur for any transaction type.

Suggested change
| `temMALFORMED` | - You specified a `DomainID` and `Holder` value--only one can be set in a single transaction.<br>- You specified the same account for both `Acount` and `Holder`.<br>- The transaction isn't changing anything; it must either update a flag or modify the `DomainID`. |

Copy link
Collaborator Author

@oeggert oeggert Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment in issuancecreate. I think it's helpful to explain how you'd malform this specific transaction.

| `tecOBJECT_NOT_FOUND` | The specified `MPToken`, `MPTokenIssuance`, or `PermissionedDomain` ledger entry doesn't exist. |


## See Also

- [MPTokenIssuance entry][]
Expand Down