Immutability & Persistence of Token Metadata

Hedera Improvement Proposals (HIP) and normalize a model by which an (non-fungible and fungible respectively) Hedera Token Service (HTS) token can link to metadata that is supplemental & complementary to the token information already stored on-ledger. Using this model, the token links to a JavaScript Object Notation (JSON) file with standardized information, and possibly additional links to media like PNGs, videos, or icons.

It should be noted that the fundamental aspects of the token, i.e. its supply and ownership, is maintained on Hedera. Metadata is, by nature, secondary to this. Nevertheless, it could be helpful to have additional metadata stored and maintained on a public network like Hedera, or a content addressable peer-to-peer network like InterPlanetary File System (IPFS).

The immutability of a token’s metadata will depend on all of the immutability characteristics of:

  • The HTS token itself
  • The storage location of the JSON
  • The storage location of any media

For a fungible token, this relationship is represented below.

Note: The principle is the same for an NFT, but for such tokens it is the custom metadata field on the token that links to the JSON file. These discrepancies in the interfaces provided by the Hedera network could change in the future.

The metadata for the token will only be guaranteed to be immutable if none of the above are mutable.

Another consideration for the long term immutability & persistence of token metadata is the cost of storage of both the token and linked metadata. Even if the token or its metadata is uneditable, it may nevertheless disappear if its storage is not paid for.

We discuss below different options for the mutability and persistence of Hedera token metadata.

Token Mutability & Persistence

If a token on Hedera has an admin key, then the memo/metadata linking to the JSON file can be modified to point at a different JSON file, with potentially different information & links within. If there is no admin key on the token then the link cannot be modified. The implication is that if an HTS token is created with no admin key then the token is immutable, and whatever the initial value of the memo or metadata fields are they will never change. On the other hand, if a token does have an admin key, then it is possible that the link to the JSON file could change in the future.

An HTS token must pay for its storage on the network. A token has an autoRenewAccount, from which the fee for storage will be deducted on a specified schedule. If the balance of that account ever reaches zero, then the token will be deleted from state — whether or not it has an admin key.

Storage Mutability & Persistence

If the JSON file is located in mutable storage, then the JSON file can be edited to have different information, and to possibly link to different media. If the JSON file is located in immutable storage, then it will be impossible to either modify the JSON file or replace it with a different file.

Similarly, If the media is located in mutable storage, then the media linked to by the JSON file can be swapped out for different PNGs or logos. If the media is located in immutable storage, then it will be impossible to replace that media with different files.

IPFS uses content addressing to identify content by what’s in it rather than by where it’s located. An IPFS content identifier (CID) for a given piece of content is the hash of that content. Because a hash is unique, changing the content changes the hash, and so the identifier. Consequently, if a link to content stored in IPFS uses the CID for that content, then that link is immutable, i.e. it would be impossible to swap in different content without changing the CID.

IPFS does not have a built-in mechanism to incentivize people to run nodes and store content for others. Consequently, while it may be free to store your content on IPFS, there is no guarantee of its ongoing persistence, which often results in trusting paid services such as to ensure availability of your IPFS data. Filecoin, however, adds an economic layer on top of the IPFS protocol that attempts to solve this problem, providing a marketplace where nodes with large storage capacity can rent their storage to users.

The Hedera File Service (HFS) is, unlike IPFS, not intrinsically immutable. Like for Hedera tokens, a file stored in HFS can be either mutable or immutable, depending on whether it has its own administrative key that can modify it. If a file is created with no admin key then henceforth no changes can be made to the file. As an example, if a token’s JSON file were stored as a file on Hedera, and if that file had an associated key, then the contents of the file could be changed with a FileUpdate transaction — with different content and links to different media. If the JSON file had no key, then no such update would be possible, making the contents of that file immutable.

As for tokens, a file must pay for its storage in the Hedera state. Unlike for tokens however, there is no concept of auto renewal and a file’s storage must be explicitly paid for with a FileUpdate transaction extending its lifetime (and paying the corresponding fee). A key implication of this is that if a file has no key, then it will be impossible to update its expiration time and will necessarily eventually be deleted from state — though this could be far in the future if the storage fee is prepaid.

Calaxy continues to explore the best options within the above design space for the tokens minted on the Creators Galaxy, including:

  • Fungible $CLXY
  • Fungible creator tokens
  • Non-fungible collectibles

Our current expectation is that these tokens will be fully immutable- specifically that

  1. The tokens will have no admin keys
  2. The JSON file (whether conforming to HIP-412 or HIP-405) and any media will be stored on immutable storage, either HFS or (more likely) IPFS

Notwithstanding the above, we do see possible value in granular mutability in some situations. For instance, it might be useful for a Creator to be able to change their username or profile picture on their Creator token. It might be possible to address this sort of requirement by differentiating between mutable metadata and immutable metadata on the token. Stay tuned for possible future HIPs.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store