Amendment Idea: IOU-MPT Converter

[mvadari]

  title: IOU-MPT Converter
  description: A method of directly converting an IOU token to an MPT token on-chain, with the consent of the issuer(s)
  created: 2025-10-09
  author: Mayukha Vadari (@mvadari)
  status: Idea
  category: Amendment

IOU-MPT Converter

Abstract

This spec provides a mechanism for issuers of IOU tokens to convert their tokens to an MPT. It ensures that the issuer must consent to what MPT is used for the conversion, to avoid scams, but also gives the holder the flexibility to do the conversion and deal with possible dust remnants of the IOU token themselves. It also supports setting up a conversion for blackholed issuers who may no longer be able to directly set up an MPT issuance on their issuing account.

Motivation

Trust lines are a fundamental building block for many XRP Ledger tokenization features. They have been around for the past 13 years, since the inception of the XRP Ledger. However, they can be rather difficult to use - they take up a lot of space (at least 234 bytes each), they represent a bidirectional debt relationship (while most people are used to thinking about debt as unidirectional), and they don't have a method of storing on-chain metadata.

Multi-Purpose Tokens aim to fix all of those problems - they only take up about 52 bytes, they represent a unidirectional debt relationship, and they have an issuance object where on-chain metadata (and other token-related information) can live. As a result, many issuers that have issued IOU tokens may want to migrate to MPTs.

However, this is essentially impossible to do directly, mainly due to the IOU's bidirectional debt relationship and its unique method of representing floating points. This is the problem that this spec attempts to solve.

1. Overview

We propose:

• Modifying the MPTokenIssuance ledger entry
• Modifying the MPTokenIssuanceCreate transaction
• Creating the TrustlineConvert transaction

This feature will require an amendment, tentatively titled IOUToMPT.

2. Ledger Entry: MPTokenIssuance

2.1. Fields

All existing fields stay. The following fields are added:

Field Name	Constant?	Required?	Default Value	JSON Type	Internal Type	Description
OriginalIOU	Yes	No	N/A	object	Issue	The IOU that corresponds with this MPT (and may be converted to this MPT).
IOUScale	Yes	No	0	number	UInt8	The scale of the IOU. One IOU will be converted to $10^n$ MPT units, where $n$ is the IOUScale value.

3. Transaction: MPTokenIssuanceCreate

3.1. Fields

All existing fields stay. The following fields are added:

Field Name	Required?	JSON Type	Internal Type	Description
OriginalIOU		object	Issue	The IOU issuer/currency pair that can be traded in/converted to this MPT.
IssuerSignature		object	Object	The signature of the original IOU's issuer over the transaction, if different from the transaction's Account.
IOUScale		number	UInt8	The scale of the IOU. One IOU will be converted to $10^{-n}$ MPT units, where $n$ is the IOUScale value.

3.1.1. IssuerSignature

An inner object that contains the signature of the Lender over the transaction. The fields contained in this object are:

Field Name	Required?	JSON Type	Internal Type	Default Value	Description
SigningPubKey		string	STBlob	N/A	The Public Key to be used to verify the validity of the signature.
TxnSignature		string	STBlob	N/A	The signature of over all signing fields.
Signers		list	STArray	N/A	An array of transaction signatures from the OriginalIOU.issuer signers to indicate their approval of this transaction.

The final transaction must include exactly one of

1. The SigningPubKey and TxnSignature fields, or
2. The Signers field and, optionally, an empty SigningPubKey.

The total fee for the transaction will be increased due to the extra signatures that need to be processed, similar to the additional fees for multisigning. The minimum fee will be $(|signatures| + 1) \times base_fee$ where $|signatures| == max(1, |tx.IssuerSignature.Signers|)$

The total fee calculation for signatures will now be $(1 + |tx.Signers| + |signatures|) \times base_fee$. In other words, even without a tx.Signers list, the minimum fee will be $2 \times base_fee$.

This field is not a signing field (it will not be included in transaction signatures, though the TxnSignature or Signers field will be included in the stored transaction).

This field will ignore blackholing on the original issuer account, to allow blackholed issuers to still convert their issued tokens to MPTs.

3.2. Failure Conditions

The existing failure conditions remain.

In addition:

• OriginalIOU is not an IOU (i.e. XRP or an MPT)
• IssuerSignature does not contain valid signing information for OriginalIOU.issuer
• OriginalIOU is not present, but IssuerSignature or IOUScale is included.
• OriginalIOU.issuer does not exist
• OriginalIOU.issuer $==$ Account, but IOUSignature is provided
• OriginalIOU.issuer $!=$ Account, but IOUSignature is not provided

3.3. State Changes

The state changes remain the same.

4. Transaction: TrustlineConvert

This transaction converts IOU balances to MPT balances. The holder submits this transaction.

4.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	✔️	string	UInt16	The transaction type (TrustlineConvert).
Account	✔️	string	AccountID	The account sending the transaction.
MPTokenIssuanceID	✔️	string	UInt192	The ID of the MPT to convert to.

4.2. Failure Conditions

• There is no object corresponding to MPTokenIssuanceID
• The object corresponding to MPTokenIssuanceID is not an MPTokenIssuanceobject
• The MPTokenIssuance object corresponding to MPTokenIssuanceID does not have an OriginalIOU field
• The user does not have a trustline for OriginalIOU
• The user does not have sufficient reserve for a new MPToken object (if one does not already exist for MPTokenIssuanceID)
• The token requires authorization and the user has not been authorized

4.3. State Changes

If the transaction is successful:

• Create an MPToken object for the MPTokenIssuanceID token, with the Account as the holder (if one does not already exist).
• Subtract as many $10^{-n}$ balances as possible from the trustline between Account and OriginalIOU.issuer (where $n$ is MPTokenIssuance.IOUScale).
• If $m*10^{-n}$ was subtracted in the previous step, $m$ is added to the MPToken.MPTAmount.
• If the trustline is in a zero state (in terms of flags and balances), it is deleted.

Note that any dust (balance less than $10^{-n}$) is left in the trustline. This can be deleted by sending it back to the issuer with a Payment transaction.

5. Security

The issuer of the original IOU must consent to allowing the transition to the MPT in all cases - either because they are also the issuer of the MPT, or because they signed for it in IssuerSignature. This prevents the creation of spam/scam tokens to drain IOU balances.

Dust in the IOU is not deleted from the trustline on purpose - depending on the trustline, this may be very valuable.

n+1. Open Questions

• Might need an object on the IOU side to prevent a one-to-many IOU-MPT relationship
  • Or is that actually desirable?
  • Could also set up flags to make this configurable
• Should there be a flag on TrustlineConvert that allows the user to delete the trustline regardless (deleting the dust)?
  • Tradeoff is basically users not knowing how to deal with the dust vs issuer abuse
• Should the issuer also be able to submit the TrustlineConvert transaction (though without being able to delete the dust)?
  • If so, should both the IOU and MPT issuers be allowed to do so, if they are separate?

Appendix

Appendix A: FAQ

A.1: Is there some way to deal with blackholed issuers who still have their keys? Is there another way for them to prove that that's their token?

• Best option there is probably to just issue a separate MPT and encourage people to burn the IOU in exchange for the MPT - the two steps can be Batched together to do so in a trustless manner
• Or set up a big trade on the DEX for this at the conversion rate you want

[ximinez]

My immediate concern is with the idea that it ignores blackholing on the IOU issuer. First, because there is no concept of blackholing on ledger. It's not an account flag so much as issuers setting an "impossible" regular key, and disabling their master key. So I guess you're proposing to ignore the disabled master key. The problem with that is that there are other reasons to disable a master key - like the secret being compromised. We don't want a scenario where an account that is happily chugging along using their regular key finds their trust lines disappearing because a malicious actor with their compromised key created an MPT.

Also, I'm imagining some holders of blackholed IOUs would strongly object to them having any kind of change.

Finally, with MPT support coming to the DEX, this could, in principal, be handled without more new transactions by the issuer making a giant offer to convert IOUs to MPTs at a 10^n:1 price, and letting holders cross the offer.

[mvadari]

The problem with that is that there are other reasons to disable a master key - like the secret being compromised. We don't want a scenario where an account that is happily chugging along using their regular key finds their trust lines disappearing because a malicious actor with their compromised key created an MPT.

Yeah that's fair. We could potentially make it so that it's only supported for accounts that have set ACCOUNT_ZERO or some other known inaccessible account as their regular key, or we could remove the blackholed support. No objection either way, this whole spec is a spitball idea.

Finally, with MPT support coming to the DEX, this could, in principal, be handled without more new transactions by the issuer making a giant offer to convert IOUs to MPTs at a 10^n:1 price, and letting holders cross the offer.

I made that suggestion in the FAQ for blackholed issuers that lost their keys.

[shortthefomo]

"This field will ignore blackholing on the original issuer account, to allow blackholed issuers to still convert their issued tokens to MPTs."

How can you guarantee that issuers of all tokes have not in one single case shared that key?

In which case their token could unwantingly be converted to a MPT?

[mvadari]

See the conversation above

[mDuo13]

After MPT DEX support is live, wouldn't most use cases for this standard be served by the issuer simply placing an offer to buy their trust line tokens and sell the MPT they're converting it to? The flow would be similar to this, but the conversion details wouldn't need to be locked into the MPT Issuance.

1. Issuer places an offer to buy the trust line token and sell the MPT, with the ratio reflecting the desired AssetScale.
2. Holders place offers (using tfSell) to convert their trust line token balances into the MPT version.
3. Assuming the holder traded their whole trust line balance, they would need to separately set their trust line settings (limit, etc.) back to zero to delete the trust line.

The DEX approach would also allow for pretty flexible conversions, like you wouldn't even necessarily need to use the cold wallet of the original trust line token to place the "conversion" offer, like if they're blackholed. And you could potentially even offer more flexible conversions, like letting people trade in their trust line token for their choice of different MPTs with different properties.

The only thing that wouldn't really work is converting to an MPT that can't be traded in the DEX. (Or would it? The phrasing of the Can Trade flag says holders can't trade in the DEX, but maybe the issuer could still do so?)

Basically, I think most of the functionality of this amendment should be basically already available as part of MPT-DEX.

[Bronek]

I think the same problem would be addressable if we had a concept of "infinite supply order" that would integrate with DEX.

it would have to be obviously owned by the issuer of both tokens (pays / gets) and would effectively work by atomically

• destroying tokens on one side
• issuing tokens on the other
• both operations performed at a fixed immutable rate

Permission delegation would be useful here, to enable this object to be created by an issuer of one token only (with permission from the other issuer) or even by a 3rd party (with permission from both issuers)

Basically a new flag in ltOFFER entry and in ttOFFER_CREATE TX, with changes in DEX to actually perform the destroying / issuing.

I would call the new flags "denomination" since this is similar to how denominations in TradFi work .

[mDuo13]

I don't think you need an infinite supply. You can set the max on the IOU side to be the total outstanding amount issued (queryable via gateway_balances API method).

I also don't think you technically need any permission from the old issuer's side, necessarily. Sure, it would be nice to grant legitimacy, and there's a discovery aspect as well, but the issuer of the new MPT can accomplish all this by placing a trade, even from a hot wallet as long as it's sufficiently well-funded.

[Bronek]

Good point re. permission. One side of this order is meant to create (issue) new tokens, and that requires permission to increase the outstanding amount in the MPTokenIssuance object, meaning the order either has to be created by the issuer (i.e. the owner of MPTokenIssuance), or has to have delegated permission to increase the supply in this way.

As for the other side - I planned that the old tokens would get atomically destroyed in the same TX but you are right, it is possible that the order creator will simply hold onto them and perhaps send them later to their original issuer (destroying the old tokens in this way). However this loses one important benefit of such "denomination order". If the old tokens are held somewhere rather than atomically destroyed when the new ones are created, this means that the total supply of old + new tokens no longer remains stable. That is a useful property, alongside with the fixed guaranteed rate of exchange.

As for the infinite supply - you are right again, this is limited by the maximum issuance size in the MPTokenIssuance.

The same mechanism could be used not only for exchange IOU to MPT, but also IOU to IOU, MPT to IOU or MPT to MPT (it's just a question of how the issuance and permissions are managed).