From f20f8c5c7dc05069fe6bb4cde651a09eecbe78ef Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Wed, 20 Aug 2025 14:46:27 -0700 Subject: [PATCH 1/2] update mpt docs for permissioneddomains --- .../transactions/types/mptokenissuancecreate.md | 10 ++++++++++ .../protocol/transactions/types/mptokenissuanceset.md | 11 +++++++++++ 2 files changed, 21 insertions(+) diff --git a/docs/references/protocol/transactions/types/mptokenissuancecreate.md b/docs/references/protocol/transactions/types/mptokenissuancecreate.md index 47f88057198..f9fa2d5efbc 100644 --- a/docs/references/protocol/transactions/types/mptokenissuancecreate.md +++ b/docs/references/protocol/transactions/types/mptokenissuancecreate.md @@ -37,6 +37,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 will manage access to the MPT. You must set the `tfMPTRequireAuth` flag to use permissioned domains. _(Requires the [PermissionedDomains amendment][] and [SingleAssetVault amendment][])_ | | `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-89d specification](https://github.com/XRPLF/XRPL-Standards/pull/293) defines a recommended format for metadata. | @@ -54,4 +55,13 @@ 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 | +|:--------------------------|:------------| +| `temDISABLED` | Either the `PermissionedDomains` or `SingleAssetVault` amendment is disabled. | +| `temMALFORMED` | The `DomainID` is `0` or empty; you can also receive this error if you include a `DomainID` without setting the `tfMPTRequireAuth` flag. | + {% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/protocol/transactions/types/mptokenissuanceset.md b/docs/references/protocol/transactions/types/mptokenissuanceset.md index dda812c3251..f8592a18fcc 100644 --- a/docs/references/protocol/transactions/types/mptokenissuanceset.md +++ b/docs/references/protocol/transactions/types/mptokenissuanceset.md @@ -27,6 +27,7 @@ _(Requires the [MPTokensV1 amendment][] {% not-enabled /%}.)_ | Field | JSON Type | [Internal Type][] | Required? | Description | |:--------------------|:---------------------|:------------------|:----------|-------------| +| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that will manage 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 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. _(Requires the [PermissionedDomains amendment][] and [SingleAssetVault amendment][])_ | | `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. | @@ -39,4 +40,14 @@ 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 | +|:--------------------------|:------------| +| `tecNO_PERMISSION` | You are trying to lock or unlock an MPT, but the `tfMPTCanLock` flag wasn't set in the `MPTokenIssuanceCreate` transaction. | +| `temDISABLED` | Either the `PermissionedDomains` or `SingleAssetVault` amendment is disabled. | +| `temMALFORMED` | You specified a `DomainID` and `Holder` value. You can only set one or the other in a single transaction. You can also receive this error if the transaction isn't changing anything; the transaction must either update a flag or modify the `DomainID`. | + {% raw-partial file="/docs/_snippets/common-links.md" /%} From 015f3abdfb0beaab046f46811aeab61f7edf0c32 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 21 Aug 2025 16:40:07 -0700 Subject: [PATCH 2/2] add reviewer suggestions --- .../protocol/transactions/types/mptokenissuancecreate.md | 4 ++-- .../protocol/transactions/types/mptokenissuanceset.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/references/protocol/transactions/types/mptokenissuancecreate.md b/docs/references/protocol/transactions/types/mptokenissuancecreate.md index f9fa2d5efbc..4211377817e 100644 --- a/docs/references/protocol/transactions/types/mptokenissuancecreate.md +++ b/docs/references/protocol/transactions/types/mptokenissuancecreate.md @@ -61,7 +61,7 @@ Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} | Error Code | Description | |:--------------------------|:------------| -| `temDISABLED` | Either the `PermissionedDomains` or `SingleAssetVault` amendment is disabled. | -| `temMALFORMED` | The `DomainID` is `0` or empty; you can also receive this error if you include a `DomainID` without setting the `tfMPTRequireAuth` flag. | +| `temDISABLED` | The `MPTokensV1` amendment is disabled. You will also receive this error if you include a `DomainID` field in the transaction, and either the `PermissionedDomains` or `SingleAssetVault` amendment is disabled. | +| `temMALFORMED` | The `DomainID` points to an invalid permissioned domain; you can also receive this error if you include a `DomainID` without setting the `tfMPTRequireAuth` flag. | {% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/protocol/transactions/types/mptokenissuanceset.md b/docs/references/protocol/transactions/types/mptokenissuanceset.md index f8592a18fcc..31566ed14b1 100644 --- a/docs/references/protocol/transactions/types/mptokenissuanceset.md +++ b/docs/references/protocol/transactions/types/mptokenissuanceset.md @@ -27,7 +27,7 @@ _(Requires the [MPTokensV1 amendment][] {% not-enabled /%}.)_ | Field | JSON Type | [Internal Type][] | Required? | Description | |:--------------------|:---------------------|:------------------|:----------|-------------| -| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that will manage 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 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. _(Requires the [PermissionedDomains amendment][] and [SingleAssetVault amendment][])_ | +| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that will manage 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. _(Requires the [PermissionedDomains amendment][] and [SingleAssetVault amendment][])_ | | `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. |