0082 XLS-82d: Multi-Purpose Tokens (MPTs) integration into XRP Ledger DEX

[gregtatcam]

Title:       Multi-Purpose Tokens (MPTs) integration into XRP Ledger DEX
Type:        draft

Author:  
             Gregory Tsipenyuk
Affiliation: Ripple

MPT Integration into DEX

Abstract

This proposal adds Multi-purpose token (MPT) support to the XRPL DEX.. MPT is described in XLS-33. Current XRPL transactions that interact with the DEX are:

• AMMCreate: Create a new Automated Market Maker (AMM) instance for trading a pair of assets (fungible tokens or XRP).
• AMMDeposit: Deposit funds into an AMM instance and receive the AMM's liquidity provider tokens (LP Tokens) in exchange.
• AMMWithdraw: Withdraw assets from an AMM instance by returning the AMM's liquidity provider tokens (LP Tokens).
• AMMClawback: Enable token issuers to claw back tokens from wallets that have deposited into AMM pools.
• CheckCreate: Create a Check object in the ledger, which is a deferred payment that can be cashed by its intended destination.
• CheckCash: Attempts to redeem a Check object in the ledger to receive up to the amount authorized by the corresponding CheckCreate transaction.
• OfferCreate: An OfferCreate transaction places an Offer in the decentralized exchange.
• Payment: A Payment transaction represents a transfer of value from one account to another.

MPT will support all of the above transactions. MPT can be combined with IOU and XRP tokens in the transactions. For instance, a Payment could be a cross-token payment from MPT token to IOU token; AMM can be created for XRP and MPT token-pair; an order book offer can be created to buy some MPT token and to sell another MPT token. MPT doesn't modify the transactions fields, flags, and functionality. However, the JSON of the MPT amount field differs from the JSON of the IOU amount field. Instead of currency and issuer, MPT is identified by mpt_issuance_id. MPT amount value is INT or UINT, which must be less or equal to $63^2$. Below is an example of JSON MPT amount:

   "Amount": {
       "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308",
       "value": "110"
   }

Any transaction with MPT Amount has to use JSON format as described above. For any transaction, which uses MPT token, the token has to be created first by an issuer with MPTokenIssuanceCreate transaction and in most cases, except for AMMCreate and OfferCreate, the token has to be authorized by the holder account with MPTokenAuthorize transaction as described in XLS-33d.

This proposal provides JSON request examples for MPT-supported transactions and relevant API's. It highlights any differences compared to existing transaction functionality. For a comprehensive description of all transactions refer to XRPL documentation

MPT Supported Transactions

AMM

AMM is identified by a token pair. Any token or both tokens in AMM transactions can be MPT. I.e., in addition to the current combination of XRP/IOU and IOU/IOU token pair, AMM can have XRP/MPT, IOU/MPT, and MPT/MPT token pair. Each MPT in the pair is identified by mpt_issuance_id. If both tokens are MPT then each token must have a unique mpt_issuance_id. In case of AMMCreate the token pair is identified by Amount and Amount2. In case of AMMDeposit, AMMWithdraw, and AMMDelete the token pair is identified by Asset and Asset2 with the token type corresponding to Amount and Amount2 of AMMCreate. Asset and Asset2 are STIssue type, which represents a token by currency and issuer. If STIssue type represents MPT then mpt_issuance_id must be used instead. AMMDeposit and AMMWithdraw have optional fields Amount and Amount2, which if present must match the type of Asset and Asset2 respectively.

Create JSON Example

   {
       "Account": "rffMEZLzDQPNU6VYbWNkgQBtMz6gCYnMAG",
       "Amount": {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308",
           "value": "1000"
       },
       "Amount2": {
           "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308",
           "value": "1000"
       },
       "Fee": "2000000",
       "Flags": 0,
       "TradingFee": "0",
       "TransactionType": "AMMCreate"
   }

For each MPT token AMMCreate creates and authorizes MPToken object for AMM pseudo-account.

In addition to the current failure scenarios AMMCreate fails if:

• MPTokenIssuance object doesn't exist
• MPToken object doesn't exist and AMM creator is not the issuer of MPT
• MPTLocked flag is set and AMM creator is not the issuer of MPT
• MPTRequireAuth flag is set and AMM creator is not authorized
• MPTCanTransfer is not set and AMM creator is not the issuer of MPT
• MPTCanClawback is set

Deposit JSON Example

   {
       "Account": "rffMEZLzDQPNU6VYbWNkgQBtMz6gCYnMAG",
       "Amount": {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308",
           "value": "100"
       },
       "Amount2": {
           "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308",
           "value": "100"
       },
       "Asset": {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308"
       },
       "Asset2": {
           "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308"
       },
       "Fee": "10",
       "Flags": 524288,
       "TransactionType": "AMMDeposit"
   }

In addition to the current failure scenarios AMMDeposit fails if:

• MPTokenIssuance object doesn't exist
• MPToken object doesn't exist and the account is not the issuer of MPT
• MPTLocked flag is set and the account is not the issuer of MPT
• MPTRequireAuth flag is set and the account is not authorized
• MPTCanTransfer is not set and the account is not the issuer of MPT

Withdraw JSON Example

   {
       "Account": "rffMEZLzDQPNU6VYbWNkgQBtMz6gCYnMAG",
       "Amount": {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308",
           "value": "100"
       },
       "Amount2": {
           "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308",
            "value": "100"
       },
       "Asset": {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308"
       },
       "Asset2": {
           "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308"
       },
       "Fee": "10",
       "Flags": 1048576,
       "TransactionType": "AMMWithdraw"
   }

AMMWithdraw creates and authorizes MPToken object if Liquidity Provider doesn't own MPToken object for a withdrawn token.

In addition to the current failure scenarios AMMWithdraw fails if:

• MPTokenIssuance object doesn't exist
• MPTLocked flag is set and the account is not the issuer of MPT
• MPTRequireAuth flag is set and the account is not authorized
• MPTCanTransfer is not set and the account is not the issuer of MPT

Delete JSON Example

   {
   "Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
   "Asset": {
       "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308"
   },
   "Asset2": {
       "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308"
   },
   "Fee" : "10",
   "Flags" : 0,
   "Sequence" : 9,
   "TransactionType" : "AMMDelete"
}

In addition to the current failure scenarios AMMDelete fails if:

• MPTokenIssuance object doesn't exist
• MPToken object doesn't exist and the account is not the issuer of MPT

Clawback JSON Example

{
  "TransactionType": "AMMClawback",
  "Account": "rPdYxU9dNkbzC5Y2h4jLbVJ3rMRrk7WVRL",
  "Holder": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
  "Asset": {
      "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308"
  },
  "Asset2": {
      "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308"
  },
  "Amount": {
      "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308",
      "value" : "1000"
  },
  "Flags": 1
}

AMMClawback creates and authorizes MPToken object if Liquidity Provider doesn't own MPToken object for a withdrawn token.

In addition to the current failure scenarios AMMClawback fails if:

• MPTokenIssuance object doesn't exist
• MPTLocked flag is set and the account is not the issuer of MPT
• MPTRequireAuth flag is set and the account is not authorized
• MPTCanTransfer is not set and the account is not the issuer of MPT

CheckCreate JSON Example

   {
       "TransactionType": "CheckCreate",
       "Account": "rUn84CUYbNjRoTQ6mSW7BVJPSVJNLb1QLo",
       "Destination": "rfkE1aSy9G8Upk4JssnwBxhEv5p4mn2KTy",
       "SendMax": {
           "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308",
           "value": "100"
       },
       "Expiration": 570113521,
       "InvoiceID": "6F1DFD1D0FE8A32E40E1F2C05CF1C15545BAB56B617F9C6C2D63A6B704BEF59B",
       "DestinationTag": 1,
       "Fee": "12"
   }

In addition to the current failure scenarios CheckCreate fails if:

• MPTokenIssuance object doesn't exist
• MPToken object doesn't exist and the account is not the issuer of MPT
• MPTLocked flag is set and the account is not the issuer of MPT
• MPTRequireAuth flag is set and the account is not authorized
• MPTCanTransfer is not set and the account is not the issuer of MPT

CheckCash Transaction

   {
       "Account": "rfkE1aSy9G8Upk4JssnwBxhEv5p4mn2KTy",
       "TransactionType": "CheckCash",
       "Amount": {
           "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308",
           "value": "100"
       },
       "CheckID": "838766BA2B995C00744175F69A1B11E32C3DBC40E64801A4056FCBD657F57334",
       "Fee": "12"
   }

In addition to the current failure scenarios CheckCash fails if:

• MPTokenIssuance object doesn't exist
• MPToken object doesn't exist and the account is not the issuer of MPT
• MPTLocked flag is set and the account is not the issuer of MPT
• MPTRequireAuth flag is set and the account is not authorized
• MPTCanTransfer is not set and the account is not the issuer of MPT

OfferCreate Transaction

   {
       "Account": "rMTysmc799PzTvK228jNaua6w3b6VgYUjw",
       "Fee": "10",
       "Flags": 0,
       "TakerGets": {
           "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308",
           "value": "100"
       },
       "TakerPays": {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308",
           "value": "100"},
       "TransactionType": "OfferCreate"
   }

OfferCreate can have any token combination of TakerGets and TakerPays. I.e., in addition to the current combination of XRP/IOU and IOU/IOU tokens, OfferCreate can have XRP/MPT, IOU/MPT, and MPT/MPT tokens. OfferCreate automatically creates and authorizes MPToken object for the offer's owner account when the offer is consumed and MPToken object doesn't exist for TakerPays's mpt_issuance_id.

In addition to the current failure scenarios OfferCreate fails if:

• MPTokenIssuance object doesn't exist
• MPToken object doesn't exist and the account is not the issuer of MPT
• MPTLocked flag is set and the account is not the issuer of MPT
• MPTRequireAuth flag is set and the account is not authorized
• MPTCanTransfer is not set and the account is not the issuer of MPT

Payment Transaction

{
   "Account" : "rJ85Mok8YRNxSo7NnxKGrPuk29uAeZQqwZ",
   "DeliverMax" : {
      "mpt_issuance_id" : "00000010A407AF5856CCF3C42619DAA925813FC955C72983",
      "value" : "100"
   },
   "DeliverMin" : {
      "mpt_issuance_id" : "00000010A407AF5856CCF3C42619DAA925813FC955C72983",
      "value" : "90"
   },
   "Destination" : "rHKBGB4vhnnVFmfrj4sUx3F9riz2CiHgCK",
   "Fee" : "10",
   "Flags" : 131072,
   "Paths" : [
      [
         {
            "mpt_issuance_id" : "00000004A407AF5856CCF3C42619DAA925813FC955C72983"
         },
         {
            "mpt_issuance_id" : "0000000AA407AF5856CCF3C42619DAA925813FC955C72983"
         },
         {
            "mpt_issuance_id" : "00000010A407AF5856CCF3C42619DAA925813FC955C72983"
         }
      ]
   ],
   "SendMax" : "100000000",
}

Payment can have any cross-token payment combination. I.e., in addition to the current combination of XRP/IOU and IOU/IOU cross-token payment, Payment can have XRP/MPT, IOU/MPT, and MPT/MPT cross-token payment. MPT can be used to specify Paths, in which case mpt_issuance_id should be used instead of currency and issuer as shown in the example above. MPT doesn't support payment rippling. mpt_issuance_id identifies a unique MPT and it's impossible to reference the same MPT with different issuer.

In addition to the current failure scenarios Payment fails if:

• MPTokenIssuance object doesn't exist
• MPToken object doesn't exist and the account is not the issuer of MPT
• MPTLocked flag is set and the account is not the issuer of MPT
• MPTRequireAuth flag is set and the account is not authorized
• MPTCanTransfer is not set and the account is not the issuer of MPT
• MPTCanTrade is not set

API's

To use MPT in API's, currency and issuer fields must be replaced with mpt_issuance_id field as shown in the examples below.

path_find

   {
       "command": "path_find",
       "subcommand": "create",
       "source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
       "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
       "destination_amount": {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308",
           "value": "100"
       }
   }

ripple_path_find

   {
       "command": "ripple_path_find",
       "source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
       "source_currencies": [
       {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308"
       },
       ],
       "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
       "destination_amount": {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308",
           "value": "100"
       }
   }

amm_info

   {
       "command": "amm_info",
       "Asset": {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308"
       },
       "Asset2": {
           "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308"
       }
   }

ledger_entry

   {
       "command": "ledger_entry",
       "amm": {
           "Asset": {
               "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308"
           },
           "Asset2": {
               "mpt_issuance_id": "00000003430427B80BD2D09D36B70B969E12801065F22308"
           }
       },
       "ledger_index": "validated"
   }

book_offers

   {
       "id": 4,
       "command": "book_offers",
       "taker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
       "taker_gets": {
           "mpt_issuance_id": "00000002430427B80BD2D09D36B70B969E12801065F22308"
       },
       "taker_pays": {
           "currency": "USD",
           "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
       },
       "limit": 10
}

Appendices

STIssue serialization

STIssue type defines AMM token pair used in AMMDeposit, AMMWithdraw, and AMMDelete transactions. However, its current serialization format presents a challenge for integrating MPT into the DEX.

Currently, STIssue is serialized as a 160-bit currency code followed by a 160-bit account address. This format doesn't have spare bits to indicate whether the serialized STIssue represents a currency and account or an mpt_issuance_id. I.e. reading 320 bits doesn't provide enough information to unequivocally distinguish currency and account from mpt_issuance_id.

Proposed Solutions

Splitting mpt_issuance_id with black hole account flag:

• This option breaks down mpt_issuance_id into its sequence number and account.
• The account is serialized in the first 160 bits, followed by a dedicated black hole account in the next 160 bits.
• Finally, the sequence number (32 bits) is serialized last.
• Deserialization method reads 320-bit currency and account. If account is the black hole account then additional 32 bits have to be read and deserialized into a sequence number.
• This method maintains backward compatibility, doesn’t require a separate amendment, but adds 32 extra bits compared to the current format, or adds 160 bits compared to 192 bits required for serializing mpt_issuance_id.

160 bits MPT issuer account	160 bits black-hole account	32 bits sequence

Leveraging standard vs. non-standard currency code distinction:

• Standard currency codes begin with eight zero bits, followed by 88 reserved bits, followed by 24-bit currency code, and finally followed by 40 reserved bits. For instance, USD currency code in hex is 0000000000000000000000005553440000000000.
• Non-standard codes must not start with eight zero bits. For instance, this is a non-standard currency code: 015841551A748AD2C1F76FF6ECB0CCCD00000000.
• MPT could be serialized with a leading 16-bit value (0x0001) followed by the 192-bit mpt_issuance_id. The 16-bit value distinguishes mpt_issuance_id from both standard and non-standard currency code.
• Deserialization reads 160-bit currency and checks for the leading 0x0001 to identify MPT and reads additional 48 bits to assemble the mpt_issuance_id.
• However, rippled code doesn't enforce the non-standard code rule.
• An amendment could be introduced to enforce the non-standard currency code rule.
• Non-compliant currencies could be black-listed.
• This method saves 112 bits compared to the current format. But it requires an amendment to fail transactions with non-standard currency codes, which don’t adhere to the non-standard currency rule. It also requires a black-listed currencies that violate the rule.

16 bits mask 0x0001	160 bits MPT issuer account	32 bits sequence

As of 8/19/24, an entire ledger with index 90166625, has in total 140,602 currencies. Of which 4,782 are standard currencies, 135,889 are non-standard currencies. 22 of non-standard currencies start with eight zero bits. There are 28 Offers with non-standard currency, which start with eight zero bits. There are no AMMs or Checks with non-standard currency. While these non-standard currencies start with eight zero bits, none of them have 88 reserve zero bits followed by non-zero bits. None of the non-standard currencies start with 0x0001.

[donovanhide]

My preference would be strongly for the blackhole account flag for serializing the mpt_issuance_id. Having a white/blacklist of non-standard currencies is ugly and would add a hash map lookup for every Offer and AMM ledger entry in whole ledger operations.

typo:
s/red/read/

"then additional 32 bits have to be red and deserialized into a sequence number."

[melitus]

Can one use MFT to implement fractional NFT?

[kennyzlei]

Yes, you can use MPT to implement fractional NFT. You can use the MaximumAmount field in MPTokenIssuance transaction to indicate the number of fractional units of an NFT, where an account holding all units will have 100% ownership

https://xrpl.org/docs/references/protocol/ledger-data/ledger-entry-types/mptokenissuance

[Island-Ghost]

Can you migrate old tokens to the MPT?

[gregtatcam]

Not at the protocol level. A client application should be able to do this.

[Tapanito]

@gregtatcam what is the status of this specification? Can it be moved to a pull-request?

[gregtatcam]

I'd like to make sure that implementation and the specs is in sync. Hopefully I can do this in the next week or so.