0035 XLS-35d: URIToken — Lightweight first-class NFTs for XRPL Protocol Chains

[RichardAH]

Updated version: PR #110 XLS-35d: URITokens — Lightweight first-class NFTs

XLS-35d URIToken — Lightweight first-class NFTs for XRPL Protocol Chains

Title: URIToken Amendment
Revision: 3 (2023-02-09)
Author:
	Richard Holland
	Wietse Wind
Affiliation: XRPL-Labs, XRPLF

Problem Statement

XLS-20 is a Non-Fungible Token standard that is currently active and in-use on the XRP Ledger main-net. Despite this, many developers and users of the XRPL remain unsatisfied by its complexity, unusual edge-cases, lack of first-class object NFTs, and general difficulty to understand and write integrations for. We therefore propose a light-weight alternative: URIToken.

Amendment

The URIToken Amendment provides a lightweight alternative to XLS20 suitable for both main-net and side-chains.

The amendment adds:

A new type of ledger object: ltURI_TOKEN
A new serialized field: URITokenID
Five new transaction types:

• URITokenMint
• URITokenBurn
• URITokenBuy
• URITokenCreateSellOffer
• URITokenCancelSellOffer

New Ledger Object Type: URIToken

The ltURI_TOKEN object is an owned first-class on-ledger object which lives in its owner's directory. It is uniquely identified by the combined hash of its Issuer (minter) and the URI. Therefore an issuer can only issue one URIToken per URI. Upon creation (minting) the Issuer is the object's first Owner. You cannot mint on behalf of a third party. As with other first class objects, each URIToken locks up an owner reserve on the account that currently owns it. Disposing of a URIToken frees up these reserved funds.

The object has the following fields:

Field	Type	Required	Description
sfIssuer	AccountID	✔️	The minter who issued the token.
sfOwner	AccountID	✔️	The current owner of the token.
sfURI	VL blob	✔️	The URI the token points to.
sfFlags	UInt32	✔️	A flag indicating whether or not the URIToken is burnable, and whether or not it is for sale.
sfDigest	Hash256	❌	An sha512half integrity digest of the contents pointed to by the URI
sfAmount	Amount	❌	If the URIToken is for sale, then this is the amount the seller is asking for.
sfDestination	AccountID	❌	If the URIToken is for sale and this field has been set then only this AccountID may purchase the token.

Example URIToken object:

{
   "Flags":0,
   "Issuer":"rN38hTretqygfgcvADnJwZzHu5rawAvmkX",
   "LedgerEntryType":"URIToken",
   "Owner":"rN38hTretqygfgcvADnJwZzHu5rawAvmkX",
   "URI":"68747470733A2F2F6D656469612E74656E6F722E636F6D2F666752755A7A662D374B5541414141642F6465616C2D776974682D69742D73756E676C61737365732E676966"
}

New Transaction Type: URITokenMint

Field	Type	Required	Description
sfURI	VL blob	✔️	The URI the token points to.
sfDigest	Hash256	❌	An SHA512-Half integrity digest of the contents pointed to by the URI
sfFlags	UInt32	❌	tfBurnable (0x00000001) or 0 or absent

If sfDigest is specified then the minted token will contain the hash specified by this field. For the end user this means they can verify the content served at the URI against this immutable hash, to ensure, for example that the properties of the NFT are not maliciously altered by changing the content at the URI. It may also be desirable to have a dynamic NFT where the content is intended to be altered, in which case simply omit sfDigest during minting, and the resulting URIToken will not contain this field.

‼️ If sfFlags is present and set to tfBurnable then the URIToken may be later burned by the Issuer. If the Hooks amendment is active on the chain this flag also indicates that the Issuer is a strong transactional stakeholder. In this event the Issuer's hooks will be executed whenever an attempt to buy or sell this URIToken occurs, and those hooks may reject the transaction and prevent it from happening if their own internal logic is not satisfied. It is therefore highly advisable to check whether or not a URIToken has tfBurnable set before purchasing or accepting it in trade.

Example Mint:

{
   "Account":"raKG2uCwu71ohFGo1BJr7xqeGfWfYWZeh3",
   "Digest":"894E3B7ECDC9F6D00EE1D892F86E9BF0098F86BBD6CBB94D6ABFD78030EB5B9B",
   "TransactionType":"URITokenMint",
   "URI":"68747470733A2F2F6D656469612E74656E6F722E636F6D2F666752755A7A662D374B5541414141642F6465616C2D776974682D69742D73756E676C61737365732E6A736F6E"
}

New Transaction Type: URITokenBurn

Field	Type	Required	Description
sfURITokenID	Hash256	✔️	The Keylet for the URIToken object being destroyed

The current owner of the URIToken can burn it at any time.

The Issuer of the token may also burn it at any time but only if tfBurnable was set during minting.

Burning a URIToken removes the specified ltURI_TOKEN object from the ledger and from the owner’s directory.

Example Burn:

{
   "Account":"r9XAC6zP5Db4qZBgRbweKUPtroxYnydTEQ",
   "TransactionType":"URITokenBurn",
   "URITokenID":"0FAC3CD45FCB800BB9CCCF907775E7D4FB167847D8999FF05CE7456D6C3A70FA",
}

New Transaction Type: URITokenCreateSellOffer

A user may offer to sell their URIToken for a preset amount. A given URIToken may have at most one current sell offer. There are no buy offers. If a user executes a URITokenBuy then it must immediately cross an existing sell offer.

To offer the URIToken for sale: specify its URITokenID, an Amount to sell for, and optionally a Destination. If Destination is set then only the specified account may purchase the URIToken. If the Amount is 0 then a Destination must be set. (This prevents an accidental "transfer to anyone" scenario.)

If a previous sell offer was present on the URIToken then it is simply replaced with the new offer.

Field	Type	Required	Description
sfURITokenID	Hash256	✔️	The Keylet for the URIToken object being offered for sale
sfAmount	Amount	✔️	The minimum amount a buyer must pay to purchase this URIToken. May be an IOU or XRP.
sfDestination	AccountID	❌	If provided then only this account may purchase the URIToken.

Example Sell:

{
   "Account":"r9XAC6zP5Db4qZBgRbweKUPtroxYnydTEQ",
   "Amount":"100000",
   "Flags":524288,
   "TransactionType":"URITokenCreateSellOffer",
   "URITokenID":"0FAC3CD45FCB800BB9CCCF907775E7D4FB167847D8999FF05CE7456D6C3A70FA",
}

New Transaction Type: URITokenBuy

A user may purchase a URIToken from another user if that URIToken has an active sell offer on it.

Whether a URIToken is for sale is indicated by the presence of the Amount field in the lt_URI_TOKEN object. If a Destination is also present in the object then only that AccountID may perform the purchase.

To purchase the URIToken, a user specifies its URITokenID and a purchase Amount. The purchase amount must be at least the amount specified in the sell offer (but may also exceed if the user wishes to tip the seller.) The purchase amount must be the same currency as the amount in the sell offer. No pathing is allowed in this transaction. The user must have sufficient currency available to cover the purchase.

Field	Type	Required	Description
sfURITokenID	Hash256	✔️	The Keylet for the URIToken object being purchased.
sfAmount	Amount	✔️	The purchase price the buyer is willing to send. Must be the same currency as the sell offer. May not be less than the sale amount.

Example Buy:

{
   "Account":"rpiLN1C94hGKGpLUbhsadVHzdSXtB2Ldra",
   "Amount":"100001",
   "TransactionType":"URITokenBuy",
   "URITokenID":"0FAC3CD45FCB800BB9CCCF907775E7D4FB167847D8999FF05CE7456D6C3A70FA"
}

New Transaction Type: URITokenCancelSellOffer

When a user has offered their URIToken for sale and later changes their mind, they may perform a clear operation. A clear operation simply clears the current sell offer from the URIToken.

Field	Type	Required	Description
sfURITokenID	Hash256	✔️	The Keylet for the URIToken object being cleared of any active sell offer.

Example Clear

{
   "Account":"rpiLN1C94hGKGpLUbhsadVHzdSXtB2Ldra",
   "TransactionType":"URITokenCancelSellOffer",
   "URITokenID":"0FAC3CD45FCB800BB9CCCF907775E7D4FB167847D8999FF05CE7456D6C3A70FA"
}

Schema / Metadata Content

The URI pointed to by a URIToken should resolve to a JSON document that follows the below schema.

This schema may be extended over time as additional categories and use-cases present themselves.

‼️ Note that the Digest, if provided during Minting, is the hash of this JSON document not the content pointed to by the JSON document. The Digest is calculated by taking the SHA-512 Half of the stringified, whitespace trimmed content JSON.

• Schema gist: https://gist.github.com/WietseWind/83cd89906ed79fb510ec1eae3fc70bb6
• Sample digest generator gist: https://gist.github.com/WietseWind/d5072777814b6f239c3baba5cbe29e39

JSON Schema

export interface xls35category {
  code: string
  description: string
}

// EXAMPLES (!)
export const xls35categories: xls35category[] = [
  { code: '0000',      description: 'Testing-purpose token' },

  { code: '0001',      description: 'Art' },
  { code: '0001.0001', description: 'Physical art' },
  { code: '0001.0002', description: 'Digital art' },

  { code: '0002',      description: 'Licenses' },
  { code: '0002.0001', description: 'Software licenses' },

  { code: '0003',      description: 'Admission tickets' },

  { code: '0004',      description: 'Ownership (physical)' },
  { code: '0004.0001', description: 'Land (plots)' },
  { code: '0004.0002', description: 'Time shares' },
]

export interface xls35attachment {
  description?: string
  filename: string
  url: string
}

export interface xls35schema {
  // Custom schema for additional information
  schema?: {
    url: string
    digest?: string
  }
  
  // Custom external information, to match your own specified schema (^^)
  content?: {
    url: string
    digest?: string
  }

  // Basic information: to allow instant rendering, ...
  details: {
    title: string
    categories?: xls35category[]
    publisher?: {
      name: string
      url?: string
      email?: string
    }
    previewUrl?: {
      thumbnail: string
      regular?: string
      highres?: string
    }
    group?: {
      code?: string
      title: string
    }
    attachments?: xls35attachment[]
  }  
}

Example JSON document

{
   "content":{
      "url":"https://someuri"
   },
   "details":{
      "title":"Some URIToken",
      "categories":[
         "0000"
      ],
      "publisher":{
         "name":"XRPL-Labs"
      }
   }
}

Computing the Digest over your JSON document

Pseudo-code:

metadata = {
  "details": {
    "title": "Some Title"
  }
}

jsonstring = json_encode(metadata)
whitespaceremoved = trim(jsonstring)
hash = sha512(whitespaceremoved)
sha512half = slice(hash, 0, 64)

digest = sha512half

[Silkjaer]

From a quick review, the main differences between the current XLS-20 NFToken implementation and this URIToken proposal, from the user perspective are:

1. No royalties
   • Royalties are in any form circumventable anyway through OTC payments, trades through L1 smart contracts
2. No brokerage mode
   • The broker mode provides flexibility in terms of letting someone else sell on your behalf (and other similar use cases), but are more often used to lock people in a certain marketplace.
3. No offers
   • XLS-20 allows for buy and sell offers, but rely on either brokers and/or the seller/buyers to cross offers, dissimilar to the native IOU/XRP orderbook. XLS-35d will rely solely on centralized (or smart contract) marketplaces to collect multiple offers/bids.
4. Reserve per URIToken
   • Rather than a opaque reserve-model, charging reserves per NFTokenPage, this will charge a reserve per URIToken.

From a technical point of view, XLS-20 made it a pain to analyse metadata and has introduced a heavy (compared to other objects) burden to full history data stores, as one simple change to an NFToken can affect multiple NFTokenPages, which are included in full (previous and final fields) in metadata for the transactions. XLS-35d make URITokens first class citizens, and metdata will be limited to changes on the individual object itself.

I do like the simplicity of this implementation – if you know the XRPL already, learning and using this is straightforward. Can't help but think it's a year too late for the mainnet, but it may be interesting for sidechain?

[Silkjaer]

I think it would be great to separate the metadata standard and the technical implementation, maybe relying on the work that has been put into XLS-24d #69?

[RichardAH]

The schema is in a sense a meta-schema. You can easily point it at another schema(including at xls-24d schemas.) It's important to have a well defined thing at the end of URITokens from day one otherwise we will end up with no standard at all (as in XLS20). Hence including this small meta schema in the XLS itself.

[nixer89]

Thank you for updating the XLS after our discussion earlier @RichardAH. Great work as usual!

I am missing just a few things:

1. Can you please add a sentence about owner reserves and how an URIToken counts toward the reserve. (I know it states that they are "first class ledger objects" which means that they increase the owner count by one. But making that more clear would be much appreciated)

2. Are Issuers of URIToken able to delete their account?
   If not, how is that taken care of?
   Are there any new properties at the Issuer account (similar to MintenTokens and BurnedTokens counter for XLS20?) to check if an Account has issued a URIToken?

3. In regards to the public websocket API: any new methods?
   As example:
   Will there be a new endpoint where you can get all URIToken issued by a specific account (which is currently missing with XLS20, but actually much required)
   Will there be an endpoints to retrieve all URIToken an Account owns?

Thank you in advance :-)

Daniel

[RichardAH]

You can delete an account with URITokens. These are simply burned.

So far no new rpc for this amendment although such could be useful. Just use the normal account_objects rpc or manually iterate the owner dir using ledger_entry.

There’s no counters for number of tokens minted / burned either, and I’m not sure they would be useful even if added, because suppose you know 100 tokens were minted but you don’t know what they were (what their URIs were). Then you need to look up the account’s txn history for mint operations anyway. And if you’re doing that you already know how many were created. Fortunately you can immediately find the token once you know it was minted because it is directly indexed on the ledger (has its own unique keylet).

[RichardAH]

I added a sentence under the New Object heading about the reserves, good suggestion.

[sappenin]

Is there any way to allow a URIToken to be "non-tradable"? E.g., If I want to mint a token, transfer it to you, but preclude you from being able to trade or transfer it to anyone else except me (the issuer?).

The use-case here would be any sort of digital asset that shouldn't be freely transferable, for whatever reason -- regulatory, or just some policy of the issuer.

[sappenin]

Reading through some of the other comments, I think I missed that these tokens maybe won't be expressly tradable on the DEX, but am more curious about transferability.

[nixer89]

The URITokens and neither the xls20 NFTs are using any DEX function. There is no order book involved and no automatic order matching.

Both are traded via some sort of accept offer which an account has to issue.

Anyway, reading from the docs, there is no such thing as a transferable flag for URITokens. So they seem to be freely tradable to any person and an issuer can not block the trade.

[RichardAH]

Is there any way to allow a URIToken to be "non-tradable"? E.g., If I want to mint a token, transfer it to you, but preclude you from being able to trade or transfer it to anyone else except me (the issuer?).

The use-case here would be any sort of digital asset that shouldn't be freely transferable, for whatever reason -- regulatory, or just some policy of the issuer.

If you set the URIToken to burnable when it is minted then a hook running on the issuer account becomes strongly executed upon dealing. Therefore that hook, if so programmed, could enforce non-transfer rules (block transfer altogether or only allow transfer to select accounts or accounts with some sort of attestation mark)

[shortthefomo]

I'm not for this amendment. It introduces yet another skew on the existing NFT token.This will now confuse end users as both would be "NFT's". This amendment also does very little to indicate how the two would be inter operable.

The only way I would support this is if interoperability between the two was the basis of the design. Allowing a NFT to be converted between one of the two standards via a function calls eg NFTconvertStandard(standard)

It is rather frustrating that oh it's to complicated let's serve up a light version, yet again is brought forth.

I understand what's there is not overly simplistic for some usecases but it is what we have and iterations on that would be better served. As a side chain option this can be sandboxes there but on the mainnet I'm against this proposal.

[RichardAH]

Interoperability would be a third amendment. Feel free to write such an amendment if you feel it is necessary. Checks escrows and pay channels live side by side on the ledger I don’t see why nft pages and URIToken can’t also. Anyway this isn’t a political discussion. Lots of people have opinions about what code should run on the XRPL but only the validators opinions matter in the end.

[shortthefomo]

Having read through further comments on this, and yours. Agree this is not a political discussion, still hope to see some focus on the interoperability part.

[cjcobb23]

I agree that the current NFT implementation is suboptimal due to it's complexity. However, I do think adding a second NFT standard to the ledger also adds complexity and confusion. I wonder if its possible to alleviate much of the issues with the current NFT implementation at the API level, which wouldn't require an amendment.

[Silkjaer]

For uses with Hooks, it's a problem that NFTokens are not real ledger objects. API level changes can make things easier, but it won't help L1 programmability.

Some things I think should be considered for XLS-20 is: metadata optimizations (it's very cost inefficient to store several full NFTokenPages with previous/final fields on FH servers, even for simple transfers of a NFToken), the mess around brokerage (it should be clear when and how a broker can broker). Third, NFTokens should be indexable, and not only in L2, and this is afaik only possible if we gracefully converts NFTokens to ledger objects. If that happens I'd argue that a simpler NFT (URIToken) is not necessary and the brokerage complexity can just be ignored (or introduce a flag to disallow brokerage).

[ximinez]

NFTokens are not real ledger objects, but NFTokenPages are, so why can't Hooks work with those?

If the problem is that Hooks don't work with this functionality, then IMHO it makes more sense to "fix" Hooks than it does to introduce a whole new set of functionality.

[ledhed2222]

This is a really interesting idea! I too have concerns about interop between this and XLS20. However, I believe eth doesn't have any explicit interop between their various nft standards, but correct me if I'm wrong. If no interop is going to be pursued, then I can see this standard and xls20 competing for user share, where this is meant to be lightweight and not feature-complete compared with xls20. However Richard, in that world app developers still have to consider both standards, which increases complexity for some app developers, right? In other words, I'm not sure it helps you with regard to hooks. Of course, this might decrease complexity for end-users.

Also, this is just a quibble, the combination of multiple actions within one transaction seems to defy how typical XRPL transaction APIs work. I would personally vote to add more transactions, rather than leaving the functionality of the transaction up to the flags, which overloads the meaning of the flags field with both how the transaction will act and what flags will be set on the resulting URI token.

[nbougalis]

I'd recommend (a) using an NFT-style page directory as it has significant advantages over the existing owner directory page mechanism; (b) using one transactor per operation, in keeping with the existing behavior of XRPL; and (c) you may want to think about case-insensitive URIs and the implications for this.

[RichardAH]

I have changed the design to use 5 explicit transaction types for the 5 modes of operation (albeit still using only one transactor). I don't think we mind that URIs are case sensitive, in fact it could be important that they are.

[shortthefomo]

Does this spec take into account the NFTokenMinter flag that can be set on the AccountObject? I see no mention of this here? Where by another account can mint a token on behalf of the issuer? https://xrpl.org/nftoken-authorized-minting.html#assigning-an-authorized-minter

[nixer89]

The NFTokenMinter flag is part of of the XLS20 Amendment. You should not use fields from other amendments in your own / new amendment. Only the ones which are part of the XRPL core code base. Or create new ones.

eg: What if someone spins up a new genesis ledger and does not enable XLS20 but xls35? The NFTokenMinter property would not be available because xls20 is not active.

[RichardAH]

Does this spec take into account the NFTokenMinter flag that can be set on the AccountObject? I see no mention of this here? Where by another account can mint a token on behalf of the issuer? https://xrpl.org/nftoken-authorized-minting.html#assigning-an-authorized-minter

You can't mint on behalf of others in this amendment, only on your own behalf. If you want elaborate and distributed minting rights then simply install a hook on the minting account that others can invoke to emit a mint transaction.

[shortthefomo]

So if someone comes to your 'mint factory' how do you make the initial transfer? This is what is happening today.

Currently this is a issue, where by a zero value offer is made and used. (As few actually understand they can use the above flag)

That initial transfer is also much cleaning in all the accounting as your not having to clean up zero value transaction out a transaction list.

Obv another route is signer lists, but that is a complicated setup.

Would be nice to see some further thoughts around this initial transfer. As it's an existing issue that this does not address.

[RichardAH]

We could add an optional destination field to URITokenMint if you think there's a real usecase for it. But the receiving party still has to accept the transfer. It'd be two transactions instead of three.

[realbrob]

Idea: Take XLS-20D and wrap XLS-35D feature sets around it. Interoperability between the two protocols is critical IMO, we should learn from these other chains and do the work to prevent fragmentation. Fragmentation are cracks in the foundation and community. Let's take what works and build upon it. Interoperability is what makes XRPL stronger and more attractive for future projects, we should consider this idea for the future of the ecosystem.

[bigcjat]

What is the reason for not having offers? It seems limiting not to be able to make a buy or counter offer. I understand you could do this on the platform end, but then the offer only exists there instead of ledger wide.

House is for sale, this much, take it or leave it.
Just doesn't seem right. Should be more like MLS than 12 realtors with different info.

[kennyzlei]

From a quick read on this, here are some of the benefits I perceive with this URIToken proposal:

• Ease for developers to integrate with first-class ledger objects
• Ease for developers to write hooks that take an action based on a specific non-fungible token id
• Simpler understanding of owner reserve requirements
• Smaller transaction data that is easier to understand

Are there other benefits we hope to gain from this implementation?

[ledhed2222]

I'm curious to clarify this too

[Silkjaer]

Ease for developers to integrate with first-class ledger objects

This is especially true for hooks, where I don't think it's actually possible (or at least extremely difficult/expensive) to parse NFTokenPages (trigger actions when an issued NFT is moved). So URIToken may be a better option for NFT an implementation on sidechains with Hooks enabled.

@RichardAH ?

[tequdev]

There is no explanation for the Flags specified in the URITokenCreateSellOffer transaction example.

Is it a Flag representing a Sell? In this case, I don't think it is necessary to specify the Flags field because URITokenCreateSellOffer itself represents a Sell.

[dangell7]

Hello group: per the new XLS Contributing process, it is my opinion that we have reach a "well-refined standard."

As such, I propose that we move this discussion to a file (via #110) 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.

(Note that per the Contributing guidelines, moving a spec into the DRAFT state does not mean any kind of endorsement, nor does it mean that this specification will become adopted. It is solely meant as a mechanism to enable better change tracking using PRs.)

[intelliot]

Closing this discussion in order to focus comments on PR #110 XLS-35d: URITokens — Lightweight first-class NFTs