0094 XLS-94d: Dynamic Multi-Purpose Tokens

[yinyiqian1]

Title:       Dynamic Multi-Purpose Tokens
Type:        draft

Author:      Yinyi Qian
Affiliation: Ripple

Dynamic Multi-Purpose Tokens

Abstract

This proposal introduces a new amendment DynamicMPT as an extension to XLS-33 Multi-Purpose Tokens. Dynamic Multi-Purpose Tokens (Dynamic MPTs) enable specific fields and flags within an MPTokenIssuance to be declared as mutable at the time of creation. By enabling controlled mutability, this feature accommodates evolving token use cases and compliance demands. Modifications to these mutable metadata can be made via the MPTokenIssuanceSet transaction.

1. Overview

This proposal introduces:

• Transaction update for MPTokenIssuanceCreate:

  • A new optional field:
    • sfMutableFlags - indicates specific fields or flags are mutable after issuance.

• Ledger object update in MPTokenIssuance:

  • A new optional field:
    • sfMutableFlags - indicates specific fields or flags are mutable after issuance.

• Transaction update for MPTokenIssuanceSet:

  • New optional fields:
    • sfMPTokenMetadata - updates MPTokenMetadata
    • sfTransferFee - updates TransferFee
    • sfMutableFlags - sets/clears flags (e.g.tfMPTSetCanLock, tfMPTClearCanLock)

This feature will require an amendment, DynamicMPT.

2. Declaring Mutability via MPTokenIssuanceCreate

If issuers want the ability to modify certain fields or flags after issuance, they must explicitly declare those fields or flags as mutable when creating the MPTokenIssuance.
Only a limited set of fields and flags may be declared mutable; all other fields remain permanently immutable.

2.1. Declaring Mutability

Issuers can specify mutability during MPTokenIssuanceCreate via the optional MutableFlags field.

Bits in MutableFlags indicate specific fields or flags may be modified after issuance. The fields or flags include:

• Fields:
  • MPTokenMetadata
  • TransferFee
• Flags:
  • Refer to XLS-33 Multi-Purpose Tokens: Transaction-specific Fields (under Flags field)

2.2. New Optionbal Field: MutableFlags

Field Name	Required?	JSON Type	Internal Type	Description
MutableFlags		number	UInt32	Indicate specific fields or flags mutable

Bit Layout of MutableFlags — Declaring Mutability at Creation (MPTokenIssuanceCreate)

Flag Name	Hex Value	Decimal Value	Description
[Reserved]	️0x0001	1	[Reserved; used by lsfMPTLocked]
tfMPTCanMutateCanLock	️0x0002	2	Indicates flag lsfMPTCanLock can be changed
tfMPTCanMutateRequireAuth	️0x0004	4	Indicates flag lsfMPTRequireAuth can be changed
tfMPTCanMutateCanEscrow	0x0008	8	Indicates flag lsfMPTCanEscrow can be changed
tfMPTCanMutateCanTrade	0x0010	16	Indicates flag lsfMPTCanTrade can be changed
tfMPTCanMutateCanTransfer	️0x0020	32	Indicates flag lsfMPTCanTransfer can be changed
tfMPTCanMutateCanClawback	️0x0040	64	Indicates flag lsfMPTCanClawback can be changed
tfMPTCanMutateMetadata	0x00010000	65536	Allows field MPTokenMetadata to be modified
tfMPTCanMutateTransferFee	0x00020000	131072	Allows field TransferFee to be modified

Note: Flag value 0x0001 is used by lsfMPTLocked. It is not a valid value for MutableFlags.

2.3. Failure Conditions

Failure Condition	Error Code
Invalid values in MutableFlags field	temINVALID_FLAG
MutableFlags is present but featureDynamicMPT is disabled	temDISABLED

3. On-Ledger Data Structure Change

This proposal introduces updates to the MPTokenIssuance ledger object, including a new optional field MutableFlags.

3.1. New Optionbal Field: MutableFlags

A new optional field, MutableFlags (SField sfMutableFlags), is added to the MPTokenIssuance ledger object.

Field Name	Required?	JSON Type	Internal Type
MutableFlags		number	UINT32

Bit Layout of MutableFlags - Recording Mutability On-Ledger (MPTokenIssuance)

Flag Name	Hex Value	Decimal Value	Description
[Reserved]	️0x0001	1	[Reserved; used by lsfMPTLocked]
lsfMPTCanMutateCanLock	️0x0002	2	Indicates flag lsfMPTCanLock can be changed
lsfMPTCanMutateRequireAuth	️0x0004	4	Indicates flag lsfMPTRequireAuth can be changed
lsfMPTCanMutateCanEscrow	0x0008	8	Indicates flag lsfMPTCanEscrow can be changed
lsfMPTCanMutateCanTrade	0x0010	16	Indicates flag lsfMPTCanTrade can be changed
lsfMPTCanMutateCanTransfer	️0x0020	32	Indicates flag lsfMPTCanTransfer can be changed
lsfMPTCanMutateCanClawback	️0x0040	64	Indicates flag lsfMPTCanClawback can be changed
lsfMPTCanMutateMetadata	0x00010000	65536	Allows field MPTokenMetadata to be modified
lsfMPTCanMutateTransferFee	0x00020000	131072	Allows field TransferFee to be modified

Note: Flag value 0x0001 is used by lsfMPTLocked. It is not a valid value for MutableFlags.

4. Modifying MPTokenIssuance via MPTokenIssuanceSet

This proposal extends the functionality of the MPTokenIssuanceSet transaction, allowing the issuer of the MPTokenIssuance to update fields or flags that were explicitly marked as mutable during creation.

For details on the original MPTokenIssuanceSet transaction see: The MPTokenIssuanceSet Transaction

4.1. New Fields

Field Name	Required?	JSON Type	Internal Type
MPTokenMetadata		string	BLOB

New metadata to replace the existing value.
The transaction will be rejected if lsfMPTCanMutateMetadata was not set in MutableFlags.

---

Field Name	Required?	JSON Type	Internal Type
TransferFee		number	UINT16

Updated transfer fee value.
The transaction will be rejected if lsfMPTCanMutateTransferFee was not set in MutableFlags.

---

Field Name	Required?	JSON Type	Internal Type
MutableFlags		number	UINT32

Set or clear the flags which were marked as mutable.

The valid MutableFlags values:

Flag Name	Hex Value	Decimal Value	Description
tfMPTSetCanLock	️0x0001	1	Sets the lsfMPTCanLock flag. Enables the token to be locked both individually and globally.
tfMPTClearCanLock	️0x0002	2	Clears the lsfMPTCanLock flag. Disables both individual and global locking of the token.
tfMPTSetRequireAuth	️0x0004	4	Sets the lsfMPTRequireAuth flag. Requires individual holders to be authorized.
tfMPTClearRequireAuth	️0x0008	8	Clears the lsfMPTRequireAuth flag. Holders are not required to be authorized.
tfMPTSetCanEscrow	0x0010	16	Sets the lsfMPTCanEscrow flag. Allows holders to place balances into escrow.
tfMPTClearCanEscrow	0x0020	32	Clears the lsfMPTCanEscrow flag. Disallows holders from placing balances into escrow.
tfMPTSetCanTrade	0x0040	64	Sets the lsfMPTCanTrade flag. Allows holders to trade balances on the XRPL DEX.
tfMPTClearCanTrade	0x0080	128	Clears the lsfMPTCanTrade flag. Disallows holders from trading balances on the XRPL DEX.
tfMPTSetCanTransfer	️0x0100	256	Sets the lsfMPTCanTransfer flag. Allows tokens to be transferred to non-issuer accounts.
tfMPTClearCanTransfer	️0x0200	512	Clears the lsfMPTCanTransfer flag. Disallows transfers to non-issuer accounts.
tfMPTSetCanClawback	️0x0400	1024	Sets the lsfMPTCanClawback flag. Enables the issuer to claw back tokens via Clawback or AMMClawback transactions.
tfMPTClearCanClawback	️0x0800	2048	Clears the lsfMPTCanClawback flag. The token can not be clawed back.

Note: Setting and clearing the same flag simultaneously will be rejected. For example, you can not provide both tfMPTSetCanLock and tfMPTClearCanLock.

---

4.2. Failure Conditions

Failure Condition	Error Code
MutableFlags contains invalid value	temINVALID_FLAG
MPTokenHolder is provided when MutableFlags, MPTokenMetadata, or TransferFee is present	temMALFORMED
Flags (except tfUniversal) is provided when MutableFlags, MPTokenMetadata, or TransferFee is present	temMALFORMED
Setting and clearing the same flag simultaneously, e.g., specifying both tfMPTSetCanLock and tfMPTClearCanLock	temMALFORMED
MutableFlags, MPTokenMetadata, or TransferFee is present but featureDynamicMPT is disabled	temDISABLED
MPTokenIssuanceID does not exist	tecOBJECT_NOT_FOUND
Account is not the issuer of the target MPTokenIssuance	tecNO_PERMISSION
MutableFlags attempts to modify flags not declared as mutable	tecNO_PERMISSION
MPTokenMetadata is present but was not marked as mutable	tecNO_PERMISSION
TransferFee is present but was not marked as mutable	tecNO_PERMISSION

5. Examples

5.1. MPTokenMetadata is Mutable

5.1.1. MPTokenIssuanceCreate Transaction

{
  "TransactionType": "MPTokenIssuanceCreate",
  "Account": "rIssuer...",
  "AssetScale": "2",
  "MaximumAmount": "100000000",
  "MutableFlags": 65536, // lsfMPTCanMutateMetadata
  "MPTokenMetadata": "464F4F",
  "TransferFee": 100,
  "Fee": 10
}

• tfMPTCanChangeMetadata is set, indicating the MPTokenMetadata field can be modified.

5.1.2. MPTokenIssuanceSet Transaction

Sample 1(successful):

{
  "TransactionType": "MPTokenIssuanceSet",
  "Account": "rIssuer...",
  "MPTokenMetadata": "575C5C",
  "Fee": 10
}

• MPTokenMetadata was set mutable, so this will update the metadata from 464F4F to 575C5C.

Sample 2(rejected):

{
  "TransactionType": "MPTokenIssuanceSet",
  "Account": "rIssuer...",
  "MutableFlags": 1, // tfMPTSetCanLock (0x0001)
  "MPTokenMetadata": "575C5C",
  "Fee": 10
}

• This transaction attempts to set the lsfMPTCanLock flag by including tfMPTSetCanLock in the MutableFlags field. However, the mutation will be rejected because lsfMPTCanLock was not marked during creation.

5.2. TransferFee and Some Flags are Mutable

5.2.1. MPTokenIssuanceCreate Transaction

{
  "TransactionType": "MPTokenIssuanceCreate",
  "Account": "rIssuer...",
  "AssetScale": "2",
  "MaximumAmount": "100000000",
  "Flags": 8,
  "MutableFlags": 131082,  // tfMPTCanMutateTransferFee + tfMPTCanMutateCanLock + tfMPTCanMutateCanEscrow
  "MPTokenMetadata": "464F4F",
  "TransferFee": 100,
  "Fee": 10
}

• tfMPTCanMutateTransferFee is set, indicating the TransferFee field can be modified.
• tfMPTCanMutateCanLock and tfMPTCanMutateCanEscrow are set, indicating lsfMPTCanLock and lsfMPTCanEscrow can be modified.

5.2.2. MPTokenIssuanceSet Transaction

Sample 1(successful):

{
  "TransactionType": "MPTokenIssuanceSet",
  "Account": "rIssuer...",
  "MutableFlags": 33,  // tfMPTSetCanLock(0x0001) + tfMPTClearCanEscrow (0x0020)
  "TransferFee": 200,
  "Fee": 10
}

• TransferFee was set mutable. It will be updated to 200.
• Set the lsfMPTCanLock flag and clear the lsfMPTCanEscrow flag, which were marked as mutable.

Sample 2(rejected):

{
  "TransactionType": "MPTokenIssuanceSet",
  "Account": "rIssuer...",
  "MutableFlags": 4, // tfMPTSetRequireAuth (0x0004)
  "TransferFee": 200,
  "Fee": 10
}

• This will be rejected. It tries to set lsfMPTRequireAuth, which is not mutable.

Sample 3(rejected):

{
  "TransactionType": "MPTokenIssuanceSet",
  "Account": "rIssuer...",
  "TransferFee": 200,
  "Fee": 10,
  "MPTokenMetadata": "575C5C"
}

• This will be rejected. It tries to set MPTokenMetadata, which is not mutable.

[shawnxie999]

Can't we use MPTokenIssuanceSet instead of a new txn MPTokenModify?

[yinyiqian1]

MPTokenIssuanceSet is setting additional flags which is not among MPTokenIssuanceCreate flags. (starting lsf, but no corresponding tf). And we can avoid additional checks, for example, when some flag is present, Holder field can not exist. The details are in Appendix: FAQ

[gregtatcam]

IMO having MPTokenIssuanceSet and MPTokenIssuanceModify is confusing since both modify on-ledger object. Sure, we can avoid some additional checks but I'm not sure it's a good reason for having two transactions instead of one.

[shawnxie999]

@gregtatcam I initially thought the same, but same this transaction needs to modify the flags, where as MPTokenIssuanceSet has its own flags like "Lock", so it may possibly create more confusion if we reuse MPTokenIssuanceSet. Another alternative transaction name I thought would be appropriate would be MPTokenIssuanceMutate - to make it clear that this txn is responsible for "mutating" the mutable fields/flags.

[sappenin]

MPTokenIssuanceSet is setting additional flags which is not among MPTokenIssuanceCreate flags. (starting lsf, but no corresponding tf).

Can you clarify this one? It's unclear to me how we're precluded from updating MPTokenIssuanceSet to contain more flags to indicate new flag settings.

In addition, we have a style of setting flags that typically looks like this. Shouldn't we continue to follow that pattern/style (whether we use MPTokenIssuanceSet or MPTokenIssuanceModify)?

[yinyiqian1]

Taking lock/unlock as an example,

MPTokenIssuanceSet is for lock/unlock MPT.
MPTokenIssuanceModify is for modifying the ability to lock/unlock MPT by updating lsfMPTCanLock.

Only MPTokenIssuanceSet can set/clear lsfMPTLocked, by setting tfMPTLock/tfMPTUnlock. (MPTokenIssuanceCreate can not)
MPTokenIssuanceCreate can set MPTokenIssuanceCreate flags.
MPTokenIssuanceModify is used to update these MPTokenIssuanceCreate flags and some MPTokenIssuanceCreate fields.

[shawnxie999]

lsfMPTokenIssuanceMutable/tfMPTokenIssuanceMutable starts at 0x00000080. can we possibly use a larger number? I am thinking that MPT might introduce more operational flags in the future.

[yinyiqian1]

how about starting at 0x00010000?

[shawnxie999]

I think tfMPTokenIssuanceMutable can be 0x00800000 (the largest we can have since universal flag range ) takes up the leading byte. Then tfMPTokenMetadataMutable can be 0x00400000 and tfTransferFeeMutable can be 0x00200000

[yinyiqian1]

I have one concern, if there's some new feature proposing a global mask, like tfInnerBatchTxn, it may require space in the higher-order bits. We might need to reserve some of those upper bits to accommodate such extensions.
So if we want to separate the mutability masks with operational masks, we might require some mid bits.

[shawnxie999]

universal flag uses 0xff000000 as the range, so as long we we use the bits lower than that we should be fine

[lmaisons]

It sounds like lsfMPTokenIssuanceMutable implies that there are multiple combinations of "Flags" and "MutableFlags" that can functionally represent the same mutability state. Is that correct? If so, that seems perilous.

[yinyiqian1]

The granular mutability that controlled by Flags only include mutability for MPTokenIssuance specific Fields (not include Flags itself), for example, allowing modifying MPTokenMetadata and TransferFee.
MutableFlags cover different scope, only valid for modifying Operational Flags like lsfMPTCanClawback, lsfMPTCanTransfer, etc. (But it can not change Mutability flags like lsfMPTokenMetadataMutable).
Global mutability is controlled by lsfMPTokenIssuanceMutable, it's covering all the granular mutability in fields(controlled by Flags) and in Operational Flags(controlled by MutableFlags).
Operational Flags and Mutability flags are defined in 2.1 Mutability Rules

[sappenin]

I'm still a bit confused by the purpose of tf/lsfMPTokenIssuanceMutable flags.

Here's why: For setting mutability via a transaction, developers can use the tf flags (tfMPTokenMetadataMutable, tfTransferFeeMutable , and anything in MutableFlags). For storing these choices, this proposal seems to be storeing all existing lsf Flags on MPTokenIssuance.Flags (plus lsfMPTokenMetadataMutable and lsfTransferFeeMutable ) and all the other mutabilty choices in MPTokenIssuance.MutableFlags.

So what will we be missing if we simply removed tf/lsfMPTokenIssuanceMutable?

[yinyiqian1]

tf/lsfMPTokenIssuanceMutable is just a convenience to make all eligible fields mutable.
We can not modify tf/lsfMPTokenIssuanceMutable once it's set.
There's another thread discussing if we want to keep this global flag.

[mvadari]

(updated the XLS number)

[gregtatcam]

Is tfMPTokenIssuanceMutable just a convenience to make all eligible fields mutable?

[sappenin]

Just seeing this -- if it's just a convenience we should remove it. Setting flags is trivial and adding convenience flags actually makes understanding these flags more difficult, which reduces convenience.

[yinyiqian1]

@shashwatmittal92 Do you have any opinions?

[shashwatmittal92]

I agree. If the actual mutability is enabled through other flags, then we don't need one for convenience.

[sappenin]

We seem to have alignment on removing the tfMPTokenIssuanceMutable and lsfMPTokenIssuanceMutable global flags, and instead specify all flags directly.

Can this document be updated to reflect that? It will make further discussion easier to reason about.

[yinyiqian1]

I've just updated the confirmed parts. The sections that still need discussion are in a separate thread.

[sappenin]

I find some of the flag-terminology in the current proposal to be confusing, so am curious to hear feedback around the following suggestions:

1. Rename MutableFlags to MutabilityFlags so that it's clear these aren't "Flags that are mutable", but are instead the set of flags that dictate mutability of other flags.

2. Stop using the word mutate for the lsf and tf flags that indicate whether or not TransferFee and TokenMetadata can be changed/updated. Even though these flags currently have the mutable word in their names, these actually feel like Operational Flags (evidence of this is that they're located in Flags instead of in MutableFlags). With that in mind, how about calling those lsfMPTCanChangeTokenMetadata and lsfMPTCanChangeTransferFee instead?

[shashwatmittal92]

I like this @yinyiqian1 let's go with lsfMPTCanChangeTokenMetadata and lsfMPTCanChangeTransferFee.

[sappenin]

Can we expand section 2.2.2 Field to show the discrete flags? Something like this:

Flag	Hex Value	Description
[Reserved]	0x0001	[Reserved; used by lsfMPTLocked]
lsfMPTCanMutateCanLock	0x0002
lsfMPTCanMutateRequireAuth	0x0004
lsfMPTCanMutateCanEscrow	0x0008
lsfMPTCanMutateCanTrade	0x0010
lsfMPTCanMutateCanTransfer	0x0020
lsfMPTCanMutateCanClawback	0x0040

[yinyiqian1]

Do you have any preference using MutableFlags field to set the values or just use separate flags like tfMPTCanMutateCanLock, tfMPTCanMutateRequireAuth, etc.?

[sappenin]

This is a great question. At present, I have a somewhat low-conviction opinion: I lean slightly towards just "put all the flags in one spot". I decided to create a gist to simulate what that might look like, just to try it on for size:

https://gist.github.com/sappenin/d0cf2e78c7aeac7f1b50f9bf83c853e0/edit

I'm curious if you like or dislike any particular design modification in there. In particular, I have the following current opinions overall (open to more discussion though):

1. Per the above, I have a somwhat low conviction around where mutability flags should live (lean slightly towards, "just put everything in one place")
2. I have pretty high conviction that we should not introduce the new MPTokenIssuanceModify transaction, and instead should just use MPTokenIssuanceSet. This sticks to existing patterns/style in rippled (for better or worse).
3. I have medium/high conviction that we should maintain the same style of twiddling flags as other transaction like TrustSet and AccountSet (where there's a set/unset-xyz primitive) in use.

[yinyiqian1]

If we use MPTokenIssuanceSet to set/clear flags, we would need about 2 times number of bits than the operational flags.
If we won't run out of bits in the future, it's fine.

Do we need to separate operational flags and mutability flags? For example, if we use the MPTokenIssuanceCreate Flags defined in https://gist.github.com/sappenin/d0cf2e78c7aeac7f1b50f9bf83c853e0, tfMPTCanChangeMetadata's value is 0x00000080 , right after tfMPTCanClawback. If we have more operational flags to add in the future, the flag layout will be mixed together.

I am concerned if we put tfMPTLock, tfMPTUnlock, tfMPTSetCanLock, tfMPTClearCanLock under the same transaction. tfMPTLock and tfMPTUnlock are post-issuance behaviours, can be applied globally or individually with Holder field.
But tfMPTSetCanLock, tfMPTClearCanLock are metadata for the MPTokenIssuance. And we do not support Holder field if we are modifying the metadata.

@shashwatmittal92 Do you have any opinions?

[yinyiqian1]

Just some update:
I updated the draft by applying the set/clear flag pair, which is more consistent with the other transactions(AccountSet, TrustSet).
Regarding using the existing MPTokenIssuanceSet transaction, I'm concerned about the bit layout clarity and future extensibility. For example, tfMPTLock is used to lock a token, while tfMPTSetCanLock is intended to mutate the metadata. Imagine a future operational flag like tfMPTAuth — used to authorize an individual holder, for example. Do we want to give it a hex value larger than the tfMPTClearCanClawback? It's not extended cleanly which will increase the risk of confusion by mixing the operational purpose with the metadata mutation.

[yinyiqian1]

Just updated by applying the existing MPTokenIssuanceSet transaction, while introducing a new field MutableFlags

[yinyiqian1]

Per the XLS Contributing process, it is my opinion that we have reached a "well-refined standard."
I propose that we move this discussion to a file (via #302) and work on final changes using additional PRs, for better change-tracking.

Please comment here if you would like to object to moving this spec/discussion forward in the process into a DRAFT spec.