HIP-405: Fungible Token Metadata JSON Schema

Abstract

This specification provides a standard scheme for fungible token metadata on Hedera Token Service (HTS).

Fungible tokens minted to this specification will be able to be served by explorers, wallets and other applications, allowing those applications to display information about the token that is additional to that stored directly on-ledger in the token.

Motivation

Metadata is typically associated with non-fungible tokens (NFTs), for which metadata such as artwork is typically stored off-ledger to avoid typically relatively high on-ledger storage costs.

HIP-10 normalizes a metadata model for NFTs on Hedera where the HTS token points at a (possibly off-ledger) JSON file that itself carries information about the characteristics of the token and links to media.

As is the case for NFTs, it may be useful to provide information about a fungible token (FT) beyond that which is stored on-ledger. This specification follows the HIP-10 model to allow a fungible HTS token to point to a (possibly off-ledger) JSON file carrying that additional information. The key difference between this proposal and HIP-10 is that this specification defines a JSON schema specifically optimized for fungible tokens rather than NFTs.

While this specification follows the HIP-10 model, the current reality is that mechanism by which a token points to a JSON metadata file is different for an NFT than for a FT. NFTs have a metadata field for this pointer, while FTs do not (as of the time of this proposal). Consequently, FTs must leverage the more generic memo field on the token. It is expected that, in the future, this incongruity can and likely will be resolved so that the model is symmetrical across token types on HTS, providing FTs the purpose built metadatafield. When this is resolved in the future, we’d expect that field will point to a JSON object adhering to the schema specified here.

Rationale

This design is expected to

• Stay consistent with HIP-10 model for NFT metadata
• Provide sufficient flexibility on which JSON metadata parameters are required and which optional
• Not mandate a particular storage location for either the JSON or any media it points to, i.e. IPFS, HFS, or a web server.
• Avoid duplication or conflict with the on-ledger token attributes

User Stories

As a token creator, I want to provide more information about the token and corresponding project than afforded by the HTS token model.

As a wallet developer, network explorer, systems integrator, or exchange, I want to be able to query the metadata for different tokens, both fungible and non-fungible, in a consistent manner so that I can display that information to my users in a consistent & intuitive interface. This is far easier and ensure’s consistent metadata over an off-chain mechanism or existing alternative options.

Specification

Schema

The HTS token schema allows for the name and symbol for a fungible token to be carried on-ledger. To avoid redundancy & potential conflict, the JSON metadata does not include these two attributes. Instead, the JSON metadata holds additional attributes of the token that may be useful for its interpretation, evaluation, and display.

The JSON for a fungible token includes the following information

• description - human readable description of the token and corresponding project
• smallestUnitName - the name of the smallest unit of the token
• smallestUnitSymbol - the symbol of the smallest unit of the token
• creator - the entity that created the token
• creatorDID - the decentralized identifier of the creator
• admin - if the token has an admin key, the entity that manages that key
• lightLogo - a logo for the token designed for light backgrounds. svg is recommended.
• lightLogoType - if the lightLogo is specified, its mime type
• darkLogo - a logo for the token designed for dark backgrounds. svg is recommended.
• darkLogoType - if the darkLogo is specified, its mime type
• website address -the address at which additional information on the token or corresponding project
• chat/discord address - the address at which the project’s community holds discussion
• whitepaper address - the address at which the project’s whitepaper can be found
• properties - container for arbitrary token attributes not specifically listed above

Below is the human-readable schema

{
    "description": "description of token - RECOMMENDED - max. of 500 characters",
    "smallestUnitName" : "the name of the smallest denomination of these tokens, if the name exists - OPTIONAL",
    "smallestUnitSymbol" : "the nsymbol of the smallest denomination of these tokens, if the symbol exists - OPTIONAL",
    "creator": "creator(s) - RECOMMENDED",
    "creatorDID": "DID  - OPTIONAL ",
    "admin": "admin(s) - OPTIONAL",
    "lightLogo": "IPFS CID or path to the token's light background logo file - RECOMMENDED",
    "lightLogotype": "mime type - i.e. image/jpeg - CONDITIONALLY OPTIONAL ",
    "darkLogo": "IPFS CID or path to the token's dark background logo file - RECOMMENDED",
    "darkLogotype": "mime type - i.e. image/jpeg - CONDITIONALLY OPTIONAL ",
    "website": "link to website -  OPTIONAL", 
    "discussion": "link to discussion/discord -  OPTIONAL", 
    "whitepaper": "link to whitepaper -  OPTIONAL",
    "properties": "arbitrary additional data relevant to the token - OPTIONAL"
}

Formatting Notes

URI Formatting

URI’s shall follow the following format: protocol://resource_location

For resources that are on the world wide web, the standard http and https protocols are acceptable. Ie. http://www.example.org/image/file.jpg

For resources that are on IPFS, the protocol must be ipfs:// and the resource location must be the cid of the file. I.e. ipfs://bafkreibwci24bt2xtqi23g35gfx63wj555u77lwl2t55ajbfjqomgefxce

For resources that stored are on the hedera file service, the protocol is hedera:mainnet//0.0.123456

A more complete list of URI’s can be found here: https://en.wikipedia.org/wiki/List_of_URI_schemes

Mime Formatting

Mime formatting shall follow the following format: type/subtype

As a rule, mime types are all lower case. However apps should be programmed to accept any case for robustness.

A list of common mime types can be found here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types

Note that mime types for directories are not uniformly defined. Some IPFS CIDs point to directories rather than files, so this type is useful. This standard shall define it using the format: text/directory

Reference Implementation

Example JSON Document

This is an example of a basic JSON metadata file for a fungible token as described by this schema.

{
    "description": "Calaxy Tokens ($CLXY) act as gas powering The Creator’s Galaxy personal monetization ecosystem, in addition to
    providing verifiable, decentralized governance.",
    "smallestUnitName": "Myro", 
    “creator”: “The Creator's Galaxy Foundation”,
    "lightLogo": "ipfs://bafkreibwci24bt2xtqi23g35gfx63wj555u77lwl2t55ajbfjqomgefxce",
    "lightLogoType": “image/svg”,
    “website”: “www.creatorsgalaxy.com”,
    "whitepaper": "www.creatorsgalaxy.com/whitepaper.pdf"
}

Backwards Compatibility

This HIP is entirely opt-in, and does not break any existing functionality. It simply provides standards to facilitate integration for the display of metadata for fungible HTS tokens throughout the ecosystem.

Security Implications

Mutability of the metadata for a token will depend on a) whether or not the token itself has an admin key (and so the link to metadata via the memo can be changed to another different JSON metadata file and b) whether the storage location of the JSON metadata file guarantees immutability (e.g. IPFS of HFS), and c) whether the storage location of any media the JSON references guarantees immutability.

This dependence is represented below

-----------------            ---------------------           -------------------
|    Hedera      |          |    JSON storage    |           |   media storage  |
|                |          |                    |           |                  |
|  --------      |          |    --------        |           |                  |
|  | token |     |          |    | JSON  |       |           |                  |
|  | <memo>|-----|----------|--->|       |       |           |    -----------   |
|  |       |     |          |    | <logo>|-------|-----------|--->| logo file|  |
|   -------      |          |     -------        |           |    |__________|  |
|________________|          |____________________|           |__________________|  
   mutable?                      mutable?                         mutable?

How to Teach This

Wallet and token explorer implementations interrogate HTS tokens using this standard to display additional metadata for fungible tokens such as logos and descriptions.

Rejected Ideas

• It would have been possible to propose that HIP-10 be extended to support both NFTs and FTs.

Open Issues

• Should this specification reuse the HIP-10 schema model of using a generic properties container to contain the webpage, discussion, and whitepaper values? And so allow a wallet or market querying the JSON metadata for both NFTs and FTs to rely on a consistent schema?

• What is the appropriate maximum lenght for a token’s description? Wallets, exchanges, explorers, etc., will need to display these within their UI, and there needs to be some restrictions to ensure consistent display lengths.

References

[0] https://github.com/hashgraph/did-method/blob/master/did-method-specification.md

[1] https://w3c.github.io/did-core/

[4] https://docs.ipfs.io/how-to/best-practices-for-nft-data/#persistence-and-availability

[5] https://en.wikipedia.org/wiki/List_of_URI_schemes

[6] https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types

Copyright/license

This document is licensed under the Apache License, Version 2.0 – see LICENSE or (https://www.apache.org/licenses/LICENSE-2.0)

Citation

Please cite this document as: