Skip to content
Prerelease Docs
/
/
Reference Documentation
Edit

Dynamic MPT Reference

The Dynamic MPT amendment does not create any new data types, but it modifies several transactions and the MPTokenIssuance ledger entry.

  • Transactions:
    • MPTokenIssuanceCreate - The new MutableFlags field specifies which fields or flags are mutable after issuance.
    • MPTokenIssuanceSet - Several new fields let you update mutable metadata, transfer fees, and flags.
  • Ledger Entries:

MPTokenIssuanceCreate Transaction Changes

To allow future changes to specific fields or flags of a token, issuers must clearly specify which ones should be mutable when creating the MPTokenIssuance object.

Example JSON

This example creates an MPT issuance with mutable metadata:

{
  "TransactionType": "MPTokenIssuanceCreate",
  "Account": "rNFta7UKwcoiCpxEYbhH2v92numE3cceB6",
  "AssetScale": 4,
  "TransferFee": 0,
  "MaximumAmount": "50000000",
  "Flags": 83659,
  "MutableFlags": 65536, // tmfMPTCanMutateMetadata
  "MPTokenMetadata": "464F4F",
  "Fee": "12",
  "Flags": 122,
  "Sequence": 99536574
}

MPTokenIssuanceCreate Fields

MPTokenIssuanceCreate transactions can include the following new field:

FieldJSON TypeInternal TypeRequired?Description
MutableFlagsNumberUInt32NoIndicates specific fields or flags that are mutable after issuance. This is a bitwise combination of flags that determine mutability. See MPTokenIssuanceCreate Mutable Flags
Warning

Only the specified fields and flags may be declared mutable; all other fields remain immutable.

MPTokenIssuanceCreate Mutable Flags

The following flags are stored in the MutableFlags field, which is separate from the Flags field of the MPTokenIssuanceCreate transaction:

Flag NameHex ValueDecimal ValueDescription
tmfMPTCanMutateCanLock0x000000022If enabled, the MPT's Can Lock flag, which gives the issuer the power to lock/unlock holders' balances, can change.
tmfMPTCanMutateRequireAuth0x000000044If enabled, the MPT's Require Auth flag, which indicates that individual holders must be authorized, can change.
tmfMPTCanMutateCanEscrow0x000000088If enabled, the MPT's Can Escrow flag, which indicates that the token can be placed in escrow, can change.
tmfMPTCanMutateCanTrade0x0000001016If enabled, the MPT's Can Trade flag, which indicates that individual holders can trade their balances using the XRP Ledger DEX or AMM, can change.
tmfMPTCanMutateCanTransfer0x0000002032If enabled, the MPT's Can Transfer flag, which indicates that tokens held by non-issuers can be transferred to other accounts, can change.
tmfMPTCanMutateCanClawback0x0000004064If enabled, the MPT's Can Clawback flag, which indicates that the issuer can claw back value from individual holders, can change.
tmfMPTCanMutateMetadata0x0001000065536If enabled, the MPTokenMetadata field, which stores additional information about the token, can change.
tmfMPTCanMutateTransferFee0x00020000131072If enabled, the TransferFee field, which determines the fee percentage charged on transfers between users, can change.

Error Cases

The following failure conditions have been added to the MPTokenIssuanceCreate transaction:

Error CodeDescription
temDISABLEDThe MutableFlags field is present but the DynamicMPT amendment is not enabled.
temINVALID_FLAGThe MutableFlags field contains an invalid value.

MPTokenIssuanceSet Transaction Changes

When updating mutable flags, issuers can enable or disable any flag that was marked as mutable during the creation of the MPTokenIssuance object.

Example JSON

This example udpates the MPT metadata:

{
  "TransactionType": "MPTokenIssuanceSet",
  "Account": "rNFta7UKwcoiCpxEYbhH2v92numE3cceB6",
  "MPTokenIssuanceID": "05EECEBE97A7D635DE2393068691A015FED5A89AD203F5AA",
  "MPTokenMetadata": "575C5C", // Updated metadata from `464F4F` to `575C5C`
  "Fee": "10",
  "Flags": 1,
  "Sequence": 99536577
}

MPTokenIssuanceSet Fields

MPTokenIssuanceSet transactions can include the following new fields:

FieldJSON TypeInternal TypeRequired?Description
MPTokenMetadataStringBlobNoNew metadata to replace the existing value. Setting an empty value removes the field. Only valid if lsmfMPTCanMutateMetadata was set when creating the MPTokenIssuance object.
TransferFeeNumberUInt16NoThe new transfer fee value. Setting this to zero removes the field. Only valid if lsmfMPTCanMutateTransferFee was enabled when creating the MPTokenIssuance object. See Transfer Fee Rules.
MutableFlagsNumberUInt32NoSet or clear flags that were marked as mutable when creating the MPTokenIssuance object. See MPTokenIssuanceSet Mutable Flags.

MPTokenIssuanceSet Mutable Flags

The following flags are stored in the MutableFlags field, which is separate from the Flags field of the MPTokenIssuanceSet transaction:

Flag NameHex ValueDecimal ValueDescription
tmfMPTSetCanLock0x000000011Enables the MPT's Can Lock flag, which allows the token to be locked both individually and globally.
tmfMPTClearCanLock0x000000022Disables the MPT's Can Lock flag, which prevents both individual and global locking of the token.
tmfMPTSetRequireAuth0x000000044Enables the MPT's RequireAuth flag, which requires individual holders to be authorized to hold the token.
tmfMPTClearRequireAuth0x000000088Disables the MPT's RequireAuth flag, which means holders don't need to be authorized to hold the token.
tmfMPTSetCanEscrow0x0000001016Enables the MPT's Can Escrow flag, which allows holders to place balances into escrow.
tmfMPTClearCanEscrow0x0000002032Disables the MPT's Can Escrow flag, which means holders can't place balances into escrow.
tmfMPTSetCanTrade0x0000004064Enables the MPT's Can Trade flag, which allows holders to trade balances on the XRPL DEX.
tmfMPTClearCanTrade0x00000080128Disables the MPT's CanTrade flag, which stops holders from trading balances on the XRPL DEX.
tmfMPTSetCanTransfer0x00000100256Enables the MPT's CanTransfer flag, which allows tokens to be transferred to non-issuer accounts.
tmfMPTClearCanTransfer0x00000200512Disables the MPT's CanTransfer flag, which means transfers to non-issuer accounts are not allowed. Note that when CanTransfer is disabled, the TransferFee field is automatically removed.
tmfMPTSetCanClawback0x000004001024Enables the MPT's Can Clawback flag, which allows the issuer to claw back tokens.
tmfMPTClearCanClawback0x000008002048Disables the MPT's Can Clawback flag, which means the token cannot be clawed back.
Note

You cannot enable and disable the same setting in one transaction. For example, using both the tmfMPTSetCanLock flag and the tmfMPTClearCanLock flag is invalid.

Transfer Fee Rules

The ability to modify the TransferFee depends on two flags:

  • lsfMPTCanTransfer: must already be enabled to allow any non-zero TransferFee. Note that this flag can be modified through tmfMPTSetCanTransfer or tmfMPTClearCanTransfer if lsmfMPTCanMutateCanTransfer is set.
  • lsmfMPTCanMutateTransferFee: must be enabled at creation of the MPT issuance to allow any modification of the TransferFee field.
Note

If the MPT's transfer fee and Can Transfer flag are both mutable, you can enable Can Transfer first, then modify the transfer fee in a second transaction.

The following table describes how setting a zero or non-zero transfer fee through the MPTokenIssuanceSet transaction behaves, based on the existing state of the MPTokenIssuance object on-ledger. The first two columns represent the ledger state (lsfMPTCanTransfer and lsmfMPTCanMutateTransferFee), while the third column represents the TransferFee value being set in the transaction.

Can TransferCan Mutate Transfer FeeTransfer Fee ValueResultDescription
DisabledEnabledZero✅Removes the TransferFee field.
DisabledDisabledZero❌Not allowed to modify TransferFee.
DisabledEnabled/DisabledNon-zero❌Always invalid regardless of mutability.
EnabledEnabledNon-zero✅Modifies the TransferFee field.
EnabledDisabledNon-zero❌Not allowed to modify TransferFee.
EnabledEnabledZero✅Removes the TransferFee field.
EnabledDisabledZero❌Not allowed to modify TransferFee.

Error Cases

The following failure conditions have been added to the MPTokenIssuanceSet transaction:

Error CodeDescription
tecNO_PERMISSIONThe sender does not have permission to modify the specified field or flag. For example:
  • The MutableFlags field attempts to modify a flag that was not declared as mutable during creation.
  • The MPTokenMetadata field is provided but lsmfMPTCanMutateMetadata was not set during creation.
  • The TransferFee field is provided but lsmfMPTCanMutateTransferFee was not set during creation.
  • A non-zero TransferFee is specified but lsfMPTCanTransfer is not currently enabled on the issuance.
temDISABLEDThe MutableFlags, MPTokenMetadata, or TransferFee is present but the DynamicMPT amendment is not enabled.
temBAD_TRANSFER_FEEThe TransferFee exceeds the maximum allowed value of 50,000.
temINVALID_FLAGThe MutableFlags field contains an invalid value, including 0. You may also receive this error if both set and clear flags are specified for the same property (for example, both tmfMPTSetCanLock and tmfMPTClearCanLock).
temMALFORMEDThe transaction is malformed. For example:
  • The Holder field is provided when mutating the MPT issuance.
  • The Flags field is set when mutation fields (MutableFlags, MPTokenMetadata, or TransferFee) are present.
  • The MPTokenMetadata field exceeds the maximum length of 1024 bytes.
  • A non-zero TransferFee and tmfMPTClearCanTransfer are included in the same transaction.

MPTokenIssuance Entry Changes

MPTokenIssuance ledger entries can include the following new field:

FieldJSON TypeInternal TypeRequired?Description
MutableFlagsNumberUInt32NoIndicates which fields or flags of this token issuance can be modified after creation. See MPTokenIssuance Mutable Flags.

MPTokenIssuance Mutable Flags

The following flags are stored in the MutableFlags field, which is separate from the Flags field of the MPTokenIssuance ledger entry:

Flag NameHex ValueDecimal ValueDescription
lsmfMPTCanMutateCanLock0x000000022Indicates the Can Lock flag can be changed.
lsmfMPTCanMutateRequireAuth0x000000044Indicates the Require Auth flag can be changed.
lsmfMPTCanMutateCanEscrow0x000000088Indicates the Can Escrow flag can be changed.
lsmfMPTCanMutateCanTrade0x0000001016Indicates the Can Trade flag can be changed.
lsmfMPTCanMutateCanTransfer0x0000002032Indicates the Can Transfer flag can be changed.
lsmfMPTCanMutateCanClawback0x0000004064Indicates the Can Clawback flag can be changed.
lsmfMPTCanMutateMetadata0x0001000065536Allows the MPTokenMetadata field to be modified.
lsmfMPTCanMutateTransferFee0x00020000131072Allows the TransferFee field to be modified.

Amendment Information

AmendmentDynamicMPT
Amendment ID58E92F338758479C06084E1B6BA366BAD8F75E5329A7F0EEAFFFDA51E5106B7F
StatusIn Development
Default Vote (Latest stable release)No
Pre-amendment functionality retired?No