JSON Schema for Fungible Tokens

[paulatcalaxy]

Following the HIP-10 model of defining a JSON Schema for NFTs, we@calaxy would like to define the comparable for fungible tokens.

Premise is to link from the memo field on the HTS token to a JSON file that itself links to metadata like a logo, whitepaper, discord, etc. By normalizing the JSON schema we simplify for wallets , explorers, etc its display in a consistent manner

Metadata includes

• Description - human readable description of the token and corresponding project
• smallestDenom - the name of the smallest denomination of these
• Creator - the entity that created the token
• Creator DID - the decentralized identifier of the creator
• Admin - if the token has an admin key, the entity that manages that key
• Logo - the logo for the token
• Type - if the logo is included, 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

We've put together a rough first draft at https://github.com/paulatcalaxy/hedera-improvement-proposal/blob/master/HIP/hip-xxxx.md

Hoping for some review and broad stroke validation before creating a PR

paul (& cooper)

[rocketmay]

Description Length

No comment, 500 seems fine.

Smallest Denom

It should be noted in the schema that smallestDenom is the symbol which will be used by applications when displaying small denominations and is not necessarily the name. For example, for HBAR smallestDenom would be entered in the metadata as "ħ" not "Tinybar"

Logos

Logo and Alt Logo for the token - We should strongly recommend projects provide their logo as a .svg vector file, and recommend the logo be square.

I'm not sure what the distinction between Logo and Alt Logo is, but perhaps guidelines should be given? ie. Logo suitable for light backgrounds and Alt Logo suitable for dark?

Alt Logo should be included in the human-readable metadata (currently missing from the list).

Mutable Data

Although I understand the metadata including things such as website, whitepaper and discord address, I wonder about there being an issue where due to the immutable nature of the metadata, these fields cannot be updated if they were to change in the future. This would only be mutable if the token had an admin key, which may not be desirable as noted in the HIP.

This is a tricky question because even if the metadata is hosted somewhere mutable such as the project's website, what if that project website changes? A token without an admin key would have no recourse to update their metadata.

For a project to be required to set a token admin key purely to be able to update aesthetics seems a bit overkill.

If there was a way to change the metadata separately, with a 'metadata key', that would solve the problem fairly elegantly. However that just adds more bloat to the platform. Or perhaps the treasury could by default have permission to update the metadata and only the metadata. Not sure how feasible or reasonable that is either.

Properties Field

I concur with providing an optional "properties" field, much like HIP-10, for arbitrary data that a FT might want to include (for example, website/discord/whitepaper), if only to capture unknown, unanticipated future use cases and additional information a project might want to include.

Metadata field in FT's

I support this idea, it depends on Hedera to make the call regarding scalability of adding another field.

[bluemonad]

This looks great. It might be helpful to have an optional field for other metadata that the token creator might want to add (that aren't a textual description or a website). Also, perhaps it would be useful to allow an optional image property, similar to HIP-10.

If the intended meaning of smallestDenom is as the first reply states, then maybe a different name should be chosen? Intuitively, I would guess most people would think TinyBar is the smallestDenom of HBAR and not "ħ". Alternatively, another field could be added for the default textual representation of the denomination.

[paulatcalaxy]

thanks May, I will add the generic properties field to follow the HIP-10 model.

We have had preliminary discussions with Hedera on the value of a consistent mechanism across NFTS and FTs for pointing to metadata. I expect the original HTS API just didnt anticipate the value of FT metadata

[solubrew]

Why not use an IPFS type link to a place for mutable meta data?

[solubrew]

I see your points, the one reason I think that the NFT link needs to be in the sequence is that currently building any type of application that interacts with large quantities of fungible tokens becomes an effort of piecing together lists from various githubs and other services. Where if all FTs had a single collection contract which could have an NFT minted with base details for that FT protocol then applications could be built with a single source to access possible other protocols. Of course this single location can be created off-chain but not in decentralized permissionless way.

[Cooper-Kunz]

interacts with large quantities of fungible tokens becomes an effort of piecing together lists from various githubs and other services.

I believe that the attempt at standardizing the JSON schema, embedded on-chain & attached auto the token, is addressing this problem and sufficiently reduces the complexity required versus alternatives. The "single source of truth is the tokens themselves on-chain (and their potentially off-chain (but well defined and standardly structured) metadata).

If you (and the community) think that the standard needs to accommodate NFTs then we could potentially include an optional NFT reference in the schema - however I'd still argue that is an anti-pattern that should likely not be encouraged. e.g.

{
    "description": "description - RECOMMENDED - max. of 500 characters",
    "smallestDenom" : "how to refer to the smallest denomination of these tokens - OPTIONAL",
    "creator": "creator(s) - RECOMMENDED",
    "creatorDID": "DID  - OPTIONAL ",
    "admin": "admin(s) - OPTIONAL",
    "logo": "IPFS CID or path to the token's logo file - RECOMMENDED",
    "altLogo": "IPFS CID or path to the token's alternative logo file - OPTIONAL",
    "type": "mime type - i.e. image/jpeg - CONDITIONALLY OPTIONAL "
    "website": "link to website -  OPTIONAL", 
    "discussion": "link to discussion/discord -  OPTIONAL", 
    "whitepaper": "link to whitepaper -  OPTIONAL",
    "nftRef": "HTS NFT Token ID - OPTIONAL",
}

[bluemonad]

This usage of an NFT as a single source of truth sounds like a rather specific choice of developers. Should this be part of the schema? A general "other" field would allow people to choose if they would like to implement something like this (or something else).

[paulatcalaxy]

Ive updated the draft to

• add a properties container for arbitrary data
• cleaned up the smallest unit definition to distinguish between a name and a symbol
• cleaned up the definition of logo fields to make explicit the differentiation between light & dark logos

[paulatcalaxy]

#405

[rocketmay]

I was chatting with @sergmetelin and the topic of KYC came up - that if a FT has a KYC requirement, it's difficult to put that requirement into context without additional data. We could consider adding in a standardized optional field in properties for a KYC website/url so that tokens with KYC requirements can direct users to the appropriate information?

"Properties": {
"KYCAddress":"url to kyc information"
}

[paulatcalaxy]

@rocketmay I agree that it would be useful to have an optional KYCAddress but will propose it belongs as a peer of the other denominated fields versus a property. Thoughts?

[rocketmay]

my thought was that KYC is probably niche enough that it makes more sense to have be a property rather than store it in the root of the token, to keep the root clean. In my mind root is for fields which have broad applicability across many token types.

However, I also see the argument for keeping it in root, as it is indeed related to an intrinsic attribute of the token on the platform.

I don't have strong feelings either way.