Skip to content
Documentation/
/
/
MPTokenIssuanceSet
Last updated

MPTokenIssuanceSet

[Source]

Update a mutable property of a Multi-purpose Token (MPT) issuance, including locking (freezing) or unlocking the tokens globally or for an individual holder.

This transaction is also the only way to register the issuer and auditor EC-ElGamal public keys required for confidential transfers.

Requires the MPTokensV1 amendment.

Example MPTokenIssuanceSet JSON

This example locks the balances of all holders of the specified MPT issuance.

{
    "TransactionType": "MPTokenIssuanceSet",
    "Account": "rNFta7UKwcoiCpxEYbhH2v92numE3cceB6",
    "MPTokenIssuanceID": "05EECEBE97A7D635DE2393068691A015FED5A89AD203F5AA",
    "Fee": "10",
    "Flags": 1,
    "Sequence": 99536577
}
Query example transaction

MPTokenIssuanceSet Fields

In addition to the common fields, MPTokenIssuanceSet transactions use the following fields:

FieldJSON TypeInternal TypeRequired?Description
AuditorEncryptionKeyStringBlobNoOptional 33-byte EC-ElGamal public key used for regulatory oversight. Must be provided together with IssuerEncryptionKey in the same transaction.

Requires the ConfidentialTransfer amendment.

DomainIDString - HashUInt256NoThe 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 enabled.

Requires the PermissionedDomains amendment.

Requires the SingleAssetVault amendment.

HolderString - AddressAccountIDNoAn 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.
ImmutableFlagsNumberUInt32NoA bitwise combination of flags declaring which fields and capability-setting flags become immutable and can never be changed again after this transaction. See MPTokenIssuanceSet Immutable Flags.

Requires the DynamicMPT amendment.

IssuerEncryptionKeyStringBlobNoThe 33-byte EC-ElGamal public key used for the issuer's mirror balances.

Requires the ConfidentialTransfer amendment.

MPTokenIssuanceIDString - HexadecimalUInt192YesThe identifier of the MPTokenIssuance to update.
MPTokenMetadataString - HexadecimalBlobNoNew metadata to replace the existing value. Setting an empty value removes the field. Mutable by default; can't be updated if the MPTokenMetadata field was made immutable.

Requires the DynamicMPT amendment.

TransferFeeNumberUInt16NoThe new transfer fee value. Setting this to zero removes the field. Mutable by default; can't be updated if the TransferFee field was made immutable. See Transfer Fee Rules.

Requires the DynamicMPT amendment.

MPTokenIssuanceSet Flags

Transactions of the MPTokenIssuanceSet type support additional values in the Flags field, as follows:

Flag NameHex ValueDecimal ValueDescription
tfMPTLock0x000000011Lock the balances of this MPT issuance. Can only be combined with a Holder or DomainID in the same transaction.
tfMPTUnlock0x000000022Unlock the balances of this MPT issuance. Can only be combined with a Holder or DomainID in the same transaction.
tfMPTSetCanLock0x000000044Enable the MPT's Can Lock flag, which lets the issuer lock and unlock holders' balances. Once enabled, this flag cannot be disabled.

Requires the DynamicMPT amendment.

tfMPTSetRequireAuth0x000000088Enable the MPT's Require Auth flag, which requires individual holders to be authorized. Once enabled, this flag cannot be disabled.

Requires the DynamicMPT amendment.

tfMPTSetCanEscrow0x0000001016Enable the MPT's Can Escrow flag, which lets holders place their balances into escrow. Once enabled, this flag cannot be disabled.

Requires the DynamicMPT amendment.

tfMPTSetCanTrade0x0000002032Enable the MPT's Can Trade flag, which lets holders trade their balances on the XRP Ledger DEX or AMM. Once enabled, this flag cannot be disabled.

Requires the DynamicMPT amendment.

tfMPTSetCanTransfer0x0000004064Enable the MPT's Can Transfer flag, which lets tokens be transferred to accounts other than the issuer. Once enabled, this flag cannot be disabled.

Requires the DynamicMPT amendment.

tfMPTSetCanClawback0x00000080128Enable the MPT's Can Clawback flag, which lets the issuer claw back value from individual holders. Once enabled, this flag cannot be disabled.

Requires the DynamicMPT amendment.

tfMPTSetCanHoldConfidentialBalance0x00000100256Enable confidential transfers for this MPT issuance. This is a one-way operation and cannot be disabled once enabled.

Requires the ConfidentialTransfer amendment.

Note that a single transaction can enable more than one capability-setting flag (tfMPTSet...) at once, and can also update the MPTokenMetadata, TransferFee, and ImmutableFlags fields in the same transaction. These changes can't be combined with a tfMPTLock or tfMPTUnlock flag, or with a Holder.

Requires the DynamicMPT amendment.

MPTokenIssuanceSet Immutable Flags

Requires the DynamicMPT amendment.

The following flags are set in the ImmutableFlags field, which is separate from the Flags field. Setting a flag makes the corresponding field or capability-setting flag immutable.

Caution

Immutability is permanent. A field or flag declared immutable can never be changed, so declare a property immutable only if you're absolutely sure you don't want to change it in future.

Flag NameHex ValueDecimal ValueDescription
tifMPTCanLock0x000000022If enabled, the Can Lock flag, which gives the issuer the power to lock and unlock holders' balances, cannot be changed.
tifMPTRequireAuth0x000000044If enabled, the Require Auth flag, which indicates that individual holders must be authorized, cannot be changed.
tifMPTCanEscrow0x000000088If enabled, the Can Escrow flag, which indicates that the token can be placed in escrow, cannot be changed.
tifMPTCanTrade0x0000001016If enabled, the Can Trade flag, which indicates that individual holders can trade their balances using the XRP Ledger DEX or AMM, cannot be changed.
tifMPTCanTransfer0x0000002032If enabled, the Can Transfer flag, which indicates that tokens held by non-issuers can be transferred to other accounts, cannot be changed.
tifMPTCanClawback0x0000004064If enabled, the Can Clawback flag, which indicates that the issuer can claw back value from individual holders, cannot be changed.
tifMPTCanHoldConfidentialBalance0x00000080128If enabled, the Can Hold Confidential Balance flag, which indicates that confidential transfers and conversions are enabled for this token issuance, cannot be changed.

Requires the ConfidentialTransfer amendment.

tifMPTMetadata0x0001000065536If enabled, the MPTokenMetadata field cannot be modified.
tifMPTTransferFee0x00020000131072If enabled, the TransferFee field cannot be modified.

Transfer Fee Rules

Requires the DynamicMPT amendment.

The TransferFee field is mutable by default. Whether you can set or remove it depends on two conditions:

  • The TransferFee field must not be immutable. If it was made immutable with tifMPTTransferFee, any attempt to set it fails.
  • A non-zero TransferFee requires the Can Transfer flag. This flag must either already be enabled on the issuance, or be enabled in the same transaction with tfMPTSetCanTransfer.

Assuming the field is not immutable, the following table describes how setting a zero or non-zero TransferFee behaves. The first column represents whether Can Transfer is enabled, either already set on the MPTokenIssuance object on-ledger, or being enabled in the same transaction with tfMPTSetCanTransfer. The second column represents the TransferFee value being set in the transaction.

Can TransferTransfer Fee ValueResultDescription
EnabledNon-zero✅Sets the TransferFee field.
EnabledZero✅Removes the TransferFee field.
Not enabledNon-zero❌A non-zero fee requires Can Transfer.
Not enabledZero✅No effect; there is no TransferFee to remove.

Error Cases

Besides errors that can occur for all transactions, MPTokenIssuanceSet transactions can result in the following transaction result codes:

Error CodeDescription
temDISABLEDThe transaction requires logic that is disabled. Common causes include:
- The MPTokensV1 amendment is disabled.
- You include a DomainID field in the transaction, but the PermissionedDomains and SingleAssetVault amendments aren't both enabled.
- The ImmutableFlags, MPTokenMetadata, or TransferFee field is present, but the DynamicMPT amendment is not enabled.

Requires the DynamicMPT amendment.

temBAD_TRANSFER_FEEYou can receive this error if:
- The TransferFee exceeds the maximum allowed value of 50,000.

Requires the DynamicMPT amendment.


- A non-zero TransferFee is set in the same transaction that enables confidential balances with tfMPTSetCanHoldConfidentialBalance.

Requires the ConfidentialTransfer amendment.

temINVALID_FLAGYou can receive this error if:
- Both tfMPTLock and tfMPTUnlock are set.
- The ImmutableFlags field is present but contains no flags or an undefined flag.

Requires the DynamicMPT amendment.

tecNO_DSTThe account specified in the Holder field doesn't exist.
tecNO_PERMISSIONYou can receive this error if:
- The Can Lock flag isn't enabled, but you are attempting to lock or unlock an MPT.
- You attempt to modify a field or enable a capability-setting flag that was made immutable.

Requires the DynamicMPT amendment.

temMALFORMEDBesides generally malformed transactions, you can receive this error if:
- You specified both a DomainID and a Holder; only one can be set in a single transaction.
- You specified the same account for both Account and Holder.
- The transaction isn't changing anything; it must either update a flag or modify the DomainID.
- A lock or unlock flag is combined with a field update or the enabling of a capability-setting flag in the same transaction.

Requires the DynamicMPT amendment.


- You provided an AuditorEncryptionKey without an IssuerEncryptionKey.
- You provided a Holder together with IssuerEncryptionKey or AuditorEncryptionKey.
- You set the tfMPTSetCanHoldConfidentialBalance flag together with a Holder.
- The IssuerEncryptionKey or AuditorEncryptionKey is not a valid 33-byte compressed public key.

Requires the ConfidentialTransfer amendment.

tecOBJECT_NOT_FOUNDThe specified MPToken, MPTokenIssuance, or PermissionedDomain ledger entry doesn't exist.

See Also

MPTokenIssuanceDestroy

NFTokenAcceptOffer