0002 XAS-2d — Dynamic URITokens

[RichardAH]

XAS-2d — Dynamic URITokens

Background

URITokens are lightweight first-class NFT objects for the Xahau network (and other XRP Ledger Protocol networks if they want them.) At time of writing URITokens are immutable once minted. This is undesirable for several Hooks related use-cases, including but not limited to games wishing to store and modify game state information inside a URIToken.

Amendment

To rectify this an amendment featureDynamicURIToken is herein proposed which adds the following to the protocol:

• a lsfIssuerModifiable flag to the ltURI_TOKEN object,
• an optional sfBlob field to the ltURI_TOKEN object,
• a tfIssuerModifiable flag to URITokenMint transactor,
• an optional sfBlob field to the URITokenMint transactor, and
• a URITokenModify transactor, with the following schema:

{
	"TransactionType": "URITokenModify",
	"URITokenID": <id>,
	"URI": <optional url>,
	"Blob": <optional hex blob>,
	... other common fields
}

Constraints

When a URIToken is minted with the tfIssuerModifiable flag, it is implicitly also burnable by the Issuer. The Issuer also becomes a strong transactional stakeholder in all dealings with the token (except burning, in which they remain a weak TSH.) The flag is mutually exclusive with tfBurnable, to avoid ambiguity.

To ensure URIToken uniqueness, when an issuer-modifiable URIToken is created it is referenced twice in the ledger: once in the normal way (by the keylet created by the hash of its Issuer and URI... which changes when the URIToken is modified) and once by a new keylet type called MODIFIABLE_URI_TOKEN which is determined by the hash of the Mint transaction that originally created the modifiable token. This means that each URI may only be used once by a given Issuer and tecDUPLICATE is returned (as is normal) if a dynamic token is updated to have the same URI as another token issued by the same Issuer.

The sfBlob field is arbitrary additional data supplied during minting and/or modifying. The amendment provides that non-modifiable URITokens may also supply and use this field (although in this case it is not modifiable after minting). The purpose of this field is to allow Hooks to store information inside a URIToken as desired.

URITokenModify transactions must include at least one of sfURI and sfBlob, as well as sfURITokenID. Attempting to modify a non-modifiable URIToken results in tecNO_PERMISSION.

In an effort to conserve transactor numbers, URITokenModify will sit on the same HookOn bit as URITokenMint.

[MarvinSunday]

This is good @RichardAH
So I want to ask, the Modifiable URITokens can be automatically changed by the Hook mounted on the Issuer or is there going to be a separate provision for that?
I went through your earlier work on Brokerage Hooks and you cited mounting a hook on the Issuer to allow transfers of NFTs through the brokerage Hooks

[dangell7]

The issuer account would be the only account that can mutate the URIToken. Be that on a hook or just through the submission of a transaction.

[MarvinSunday]

Okay, I guess that would be awesome 😎
Thanks @dangell7 I totally appreciate the insights...

[TammyFYEO]

This is so good. Games wishing to store and modify game state information inside a URIToken is an epic use case. I'm really excited to see what people build on this once it's adopted.

[dangell7]

Optimization of URIToken Mutable Data:

Users wishing to use mutating URITokens should learn to optimize their data. Here is how I would use a mutable URIToken.

URI: immutable data stored in ipfs:

{
  "attributes": [
    {
      "trait_type": "name",
      "value": "my name"
    },
  ],
  "collection": {
    "family": "string",
    "issuer": "string",
    "name": "string",
    "taxon": "int"
  },
  "description": "string",
  "external_url": "string",
  "image": "ipfs://cid",
  "name": "string",
  "nftType": "xahau.v0",
  "schema": "ipfs://cid",
  "mutable_schema": {
    "field": "id",
    "type": "uint8",
  }
}

mutable_schema is a new field that stores the attribute field and type. This comes from the hooks-toolkit BinaryModels metadata() function but this can be written any number of ways.

Now in the sfBlob you only store the bytes of the value: 0A or 10. This allows you to store A LOT of mutable data.

Marketplaces should read both the immutable data from ipfs and the mutable data from the blob.

This is how I would optimize the use of a mutable URIToken.

Keep in mind the order of the mutable schema is very important. This is why using a binary-model is recommended imo.

[dangell7]

Furthermore, this is on Xahau and you might want to use the attributes in a hook, I would then store all values that you need to access in the mutable_schema.

So maybe your NFT has a speed attribute, you could then store the speed attribute hex in the sfBlob so that you could access the attribute inside the hook.

Storing the values in the sfBlob as straight binary hex makes it much easier to manipulate (read/write) the data in a hook.

So maybe instead of mutable_schema we change it to state_schema, state_abi or something similar.

[MarvinSunday]

Awesome 😎
This means a hook that changes the Mutable URIToken state can be added to the Issuer plus you now have the ability to manipulate the ### mutable_schema field in the Hook.
This is her so much, I imagine being able to alternate the look of a NFT per time 😊.