XLS20 NFT Upgrader

[ma06rii]

XLS20 NFT Upgrader

Key terms

IOU token - A custom issued token currency on the XRP Ledger, more information about tokens can be found here

XLS14 NFT - A proof of concept standard proposed for Non-Fungible Tokens (NFTs) on the XRP Ledger, more information can be found here

XLS20 NFT - A proposed standard for native support of NFTs on the XRP Ledger, more information can be found here

What are we doing?

The XLS20 upgrade to the XRP Ledger represents a significant step forward in ledger capabilities and enables the support of NFTs as representations on the ledger.

From our research NFTs exist in a number of ways on the current ledger, but mostly in the form of XLS14, IOUs, and much less so XLS19 tokens.

The developer team at Peerkat would like to propose a tool to initially facilitate the upgrade of XLS14 and IOU tokens to the new XLS20 standard, with a view to allowing other developers to extend this tooling.

This idea is open to suggestions/feedback and open to anyone who would like to contribute.

Proposal

Overview

The proposed approach is akin to swapping one token for another.

As a headline, token holders are responsible for upgrading their own NFT in their wallet. They will have a specific address to send the NFT to, which would ideally be hosted and managed by the original XLS14 or IOU token issuer. The token holder would be able to send their tokens using a wallet service such as Xumm App or any other XRPL wallet. The token holder will be responsible for checking and accepting an offer for the new XLS20 token.

Many NFT projects have chosen to create their own issued token (IOU) currencies to represent their NFTs. The idea is that the community can engage in their projects whilst awaiting for the XLS20 NFT standard.

Please see diagram below which describes the proposed upgrade process for XLS14 or IOU tokens:-

Configuration settings

Prior to running the upgrader service, the administrator who is hosting the service (ideally this will be the original issuer of the XLS14 or IOU token), will need to setup initial configuration settings using environment variables as follows :-

NAME	EXAMPLE VALUE	REQUIRED / OPTIONAL	DESCRIPTION
BRAND_UPGRADER_PUBLIC_WALLET_ADDRESS	rswwgRPNWtxXf9HnkjzBJuHLHVVAbgdVAF	Required	XRPL wallet address which the upgrader service will use to receive the IOU or XLS14 tokens for upgrade.
BRAND_UPGRADER_PRIVATE_WALLET_KEY	GF0BQ0LythNRnD/Ew6HygIs2eCQlzmo8hs+Mnp8KGJE=	Required	An encrypted value of the private key for the upgrader service XRPL wallet. This value should be encrypted for security reasons. If this key can be viewed or accessed by anyone else; it could lead to loss of funds. The security of private keys can be further extended with the use of “Secret Management Services”.
CURRENT_NFT_ISSUER_PUBLIC_WALLET_ADDRESS	rEswiCbj7mPXrhAnvQPTGwZW65tNY8mTFt	Required	XRPL wallet address of the specific IOU or XLS14 token that is targeted for upgrade.
CURRENT_NFT_CURRENCY_CODE	6E66742E7669766964696F762E6C697665202020	Required	The currency code of the specific IOU or XLS14 token that is targeted for upgrade. More information about the “currency code” can be found here
NEW_NFT_TRANSFERABLE_FLAG	8	Required	Flag to dictate how a transaction to mint a new XLS20 NFT should behave. More information about flags for “NFTokenMint” transactions can be found here
NEW_NFT_TOKEN_URI	ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf4dfuylqabf3oclgtqy55fbzdi	Optional	URI to the data of the new XLS20 NFT. More information about this can be found here
NEW_NFT_SECONDARY_TRANSFERS_FEE	314	Optional	Fee charged by the issuer, upon secondary sales of the new XLS20 NFT. More information about the NFToken “TransferFee” can be found here
NEW_NFT_TOKEN_TAXON	1	Optional	A positive integer value assigned to the new XLS20 NFTs. This is to help track multiple NFTokens. More information about the NFToken “Taxon” can be found here
NFT_CANCEL_UPGRADE_EXPIRATION_MINTUES	14400	Optional	A positive integer value to determine how long to wait before allowing an upgraded IOU or XLS14 token to be burnt (i.e. sending the token to a Blackholed XRPL wallet address).
NFT_UPGRADER_SERVICE_FEE	21000000	Required	Amount of XRP drops required to cover the costs of XRPL transactions incurred by the upgrader service when upgrading an IOU or XLS14 token. (1 XRP = 1000000 XRP drops). This fee can be determined by the administrator of the upgrader service. More information about drops can be found here
IOU_TOKEN_ACCEPTED_CONVERSION_RATE	0.5	Required	Amount of IOU tokens required per XLS20 NFT. (In this example case 0.5 IOU tokens are required per XLS20 token.)
EMAIL_SUPPORT_CONTACT	[email protected]	Required	Email address of the upgrader service administrator. This can be used to help respond to User queries
FREE_UPGRADES_ENABLED	true	Required	Sets whether Users will be able to upgrade their XLS14 or IOU token for free

Service detail

1. Upon launch of the upgrader service, the server will check if a trustline exists for the brand upgrader wallet account to receive the target XLS14 NFT or IOU token
   1. If not, then a new trustline is created
      1. Server will fail if no trustline is present or a trustline is not able to be created
2. Brand publicly advertises the following NFT upgrader details :-
   1. The NFT upgrader service XRPL wallet address
   2. (Optional feature) A link to upgrader service dashboard :- "htttps://nft-upgrader.example.com/dashboard"
   3. (Optional feature) A link to view status of an upgrade for a specific Users XRPL wallet address :- "htttps://nft-upgrader.example.com/status/:{AccountHolderXRPLAddress}"
   4. A route for the upgrader service administrator to check the status of the upgrader service “GET /service/status”
   5. A route for the upgrader service administrator to get an array of “SellOffer” IDs of any outstanding offers that have been created for a given XRPL Address “GET /service/sell-offer-token-id/:{XRPLAddressOfSender}”
3. User can choose to upgrade by sending a “Payment” of their current XLS14 NFT or specified amount of IOU token to the advertised brand upgrader wallet address
   1. If “free upgrades” are disabled by the NFT upgrader service administrator, then the user will be required to send a service fee for the upgrade.
   2. If the user sends more than one quantity of a token, then they may be required to send the equivalent multiple of the NFT upgrader service fee
4. The service will subscribe to transactions being received to the upgrader service wallet account
5. When an amount of an XLS14 NFT or specified amount of IOU token is received to the brand upgrader wallet account; some internal criteria checks will be performed, more information about these checks can be found below.
6. If all requirements are satisfied then a new XLS20 token will be sent to the initial sender of the XLS14 NFT or IOU token
   1. The upgrader service will first check if there are any “returned” or “unclaimed” XLS20 NFTs within the brand upgrader wallet account
      1. If so, then a “SellOffer” will be created for one of the available XLS20 NFTs. The “Destination” field will be set to the wallet address of the initial sender of the XLS14 NFT or IOU token
   2. Otherwise, if there are no existing “returned” or “unclaimed” XLS20 NFTs in the brand upgrader wallet account, then the following tasks apply
      1. A “TokenTaxon” value can be added to new XLS20 NFT (this could help track of new individual NFTs created from an XLS14 NFT collection that has more than one quantity)
      2. A new XLS20 NFT will be minted
         1. using “TokenTaxon” value
         2. using a “TransferFee” (optionally pre-specified at launch of the service by the “new_nft_secondary_transfers_fee” environment variable)
      3. A “SellOffer '' will be created and the “Destination” field will be set to the wallet address of the initial sender of the XLS14 NFT or IOU token
7. For upgrade requests that consist of more than one quantity “Steps (6) to (7)” above can be repeated
8. If the “Destination” account intentionally cancels a “SellOffer” for the new XLS20 NFT; then the account holder may have the opportunity to request for the original XLS14 NFT or IOU token amount back
   1. The account holder can send a small “Payment” (which is predefined by "nft_upgrader_service_fee") with a predetermined default “memo” message to the brand upgrader wallet account
   2. The upgrader service will run some internal criteria checks, more information about these checks can be found below.
   3. If all requirements are satisfied, then the original amount of XLS14 NFT or IOU token will be sent back to the sender
9. If the “Destination” account, unintentionally cancels a “SellOffer” for the new XLS20 NFT; then the account holder can request for a new “SellOffer” by sending a small “Payment” to the brand upgrader wallet account
   1. The account holder can send a small “Payment” (which is predefined by “nft_upgrader_service_fee”) with a predetermined default “memo” message to the brand upgrader wallet account
   2. The upgrader service will run some internal criteria checks, more information about these checks can be found below.
   3. If all requirements are satisfied, then “Step (7)” above will be repeated and the “Destination” will be set to the wallet address of the sender of the “Payment”
10. Burn the upgraded XLS14 NFT or IOU token
    1. XLS14 NFT or IOU token sent as “Payment” back to the original token “Issuer” account with a predetermined default “memo” message.
    2. (Optional feature) If token upgrade cancellation is enabled. The administrator of the NFT upgrader service can choose to allow XLS14 or IOU token balances to build up. Then manually send a small “Payment” (i.e. 100000 XRP drops) to the brand upgrader wallet account. This ”Payment” can trigger an action to burn all XLS14 NFTs or IOU token balances that are no longer eligible to be reversed
11. A local database will be used to log activity
    1. Log all transactions received to the brand upgrader wallet account
    2. Log all new XLS20 NFTs minted
    3. Log all transaction creating a “SellOffer” for XLS20 NFTs
    4. Log all transactions that send “Payment” of XLS14 NFT or IOU tokens back to the original "Issuer" XRPL account
    5. Log all “Payment” transactions received to request for XLS14 token or IOU token to be returned
12. (Optional feature) Dashboard Frontend :-
    1. Summary Page:- HTML page that shows a few activity metrics, summaries, and information regarding the NFT upgrader service settings.
    2. Upgrade Details Page:- HTML page for the upgrader service to show upgrade details of a particular XRPL address. This can be used to show the “SellOffer” ID which is required to accept the new XLS20 NFT
13. (Optional feature) Within a specified period of time (predetermined by “nft_cancel_upgrade_expiration_minutes” environment variable) after successful delivery of a new XLS20 NFT. The account holder can decide to reverse the transaction and get the original amount of XLS14 NFT or IOU token back
    1. The account holder will need to create a “SellOffer” with a zero “Amount” and set the “Destination” back to the initial NFT upgrader service wallet address
    2. The account holder would then need to send a small “Payment” (as predefined by “nft_upgrader_service_fee” environment variable) with a predetermined default “memo” message to the brand upgrader wallet address.
    3. The upgrader service will run some internal criteria checks
    4. If all requirements are satisfied; and the “NFT cancel upgrade expiration” period has not lapsed; then the upgrader service will accept the “SellOffer” and the amount of XLS14 NFT or IOU token will be returned as a “Payment” (If the transaction fails, the user may need to contact the upgrader service administrator for further help)

Internal criteria checks

A series of tasks could be performed before the upgrader service executes an action via the XRPL. This is to ensure that valid transactions have been received and appropriate resources are available to complete a request. Below is an list of example tasks which could be performed, but this list is not exhaustive :-

• Is a service fee required for intended action
• Has the correct service fee been paid
• Has a valid transaction been received
• Is there a sufficient amount of XRP balance to complete the intended transaction

Default memo messages

The memo messages below must be included when sending payments to the NFT upgrader service XRPL wallet. These are defined messages that must be used by everyone who would like to use this upgrade implementation. The messages will help the NFT upgrader service complete the correct tasks for the intended actions. The payments are usually initiated by a token holder who would like to trigger certain actions regarding upgrading their XLS14 NFT or IOU token.

MEMO MESSAGE	DESCRIPTION
create-nft-upgrade	This text would be included as a memo message when sending the initial XLS14 or IOU token “Payment” to the NFT Upgrader Service XRPL wallet
resend-nft-upgrade	This text would be included as a memo message when sending a service fee “Payment” to the NFT Upgrader Service XRPL wallet, for a new “SellOffer” to be created
reverse-nft-upgrade	This text would be included as a memo message when sending a service fee “Payment” to the NFT Upgrader Service XRPL wallet, for an upgrade to be reversed
burn-upgraded-nfts	This text would be included as a memo message when the NFT Upgrader Service XRPL wallet sends a “Payment” of the accumulated XLS14 or IOU token balances to the original token “Issuer” account (ideally this would be sent to a blackholed account)

Considerations

Token “Issuers” can use the NFT upgrader service dashboard to help communicate “SellOffer” IDs to token holders. It can also help provide transparency and token holder trust in the upgrade process.

A public register can be used to maintain a list of verified ‘brand upgrader details’ for different projects. This can help token holders find accurate information. This register can be created by a third party or included in existing lists such as the xrp.community.

A third party could develop an Xumm xApp dedicated to supporting token holders through the upgrade process. This could help support a user-friendly experience for token holders when upgrading.

A possible downside of this approach is that token holders are required to trust that the administrator of the NFT upgrader service will burn the received XLS14 NFTs or IOU tokens by sending it to a blackholed account, which will most likely be the original "Issuer" account of the token. If this service is run by the initial ”Issuer” of the XLS14 NFT or IOU token, it is assumed they would want to maintain the integrity of their project.

Please note that this proposed implementation may not be suitable to support upgrading all XLS14 NFTs. A token holder could check if their XLS14 or IOU token is upgradeable by looking up a public register of projects offering or running the “NFT Upgrader Service”.

Sologenic will be providing their own dedicated ‘swap’ service to upgrade XLS14/SOLO tokens. More information about this ‘swap’ service can be found here.