HIP-765: NFT Collection Token Metadata Field

Abstract

This HIP proposes the addition of the metadata field to Non-Fungible Token Class, taking after the individual Non-Fungible Token (NFT) metadata field which was added in HIP-17. While HIP-17 metadata is scoped to a single NFT, here we propose adding metadata scoped to an entire token class.

Motivation

Similar to NFT’s on the network, the fungible token implementation is largely functional. There is a need for a token creator to specify additional “metadata” about the token. The data and formatting is explored in HIP-YYY but there is no field suitable for storing the link to this metadata.

The most ‘logical’ field proposed to store this data is the existing ‘memo’ field, however a dedicated metadata field is more appropriate.

Rationale

The success of HIP-412 in standardizing the individual NFT space on Hedera demonstrates the potential of standardized metadata functionality for NFT Collections as well. Wallets, explorers and other applications can display relevant supplementary information about tokens to users in a decentralized fashion.

User stories

As a token creator, I want a platform-standardized method to host information about my NFT Collection in a decentralized fashion, allowing applications to query data such as token icon, featured image and website.

As a wallet or explorer, I want to query a mirror node to obtain the metadata for any NFT Collection token, similar to current individual non-fungible tokens. Mirror nodes currently return metadata for individual NFTs; but for an NFT Collection token genrally, we want to get Token-level (ie Collection-level) metadata.

As a developer, I want to store the metadata uri in a dedicated field, to avoid ambiguity of using an overloaded field such as ‘memo’.

Specification

HAPI Changes

======= This HIP proposes the addition of the metadata field to Non-Fungible Token Class, taking after the individual Non-Fungible Token (NFT) metadata field, which was added in HIP-17. While HIP-17 metadata is scoped to a single NFT, here we propose adding metadata scoped to an entire token class.

Motivation

Similar to NFTs on the network, the fungible token implementation is mainly functional. There is a need for a token creator to specify additional “metadata” about the token. The data and formatting are explored in HIP-766, but no field is suitable for storing the link to this metadata.

The most logical field proposed to store this data is the existing memo field, however, a dedicated metadata field is more appropriate.

Rationale

The success of HIP-412 in standardizing the individual NFT space on Hedera demonstrates the potential of standardized metadata functionality for NFT Collections as well. Wallets, explorers and other applications can display relevant supplementary information about tokens to users in a decentralized fashion.

User stories

• As a token creator, I want a platform-standardized method to host information about my NFT Collection in a decentralized fashion, allowing applications to query data such as token icon, featured image, and website.

• As a wallet or explorer, I want to query a mirror node to obtain the metadata for any NFT Collection token, similar to current individual non-fungible tokens. Mirror nodes currently return metadata for individual NFTs. However, for an NFT Collection token, we want to get token-level (ie Collection-level) metadata.

• As a developer, I want to store the metadata URI in a dedicated field, to avoid ambiguity of using an overloaded field such as the memo field.

Specification

HAPI Changes

   // Retrieves the metadata of a token
   rpc getTokenInfo (Query) returns (Response);

TokenCreateTransactionBody

Property metadata is updated at the token-type level for non-fungible collections (as opposed at the nft-id level which is already supported)

message TokenCreateTransactionBody {
   TokenID token = 1; // The token id for which to create tokens. If token does not exist, transaction results in INVALID_TOKEN_ID
   string metadata = 3; // The metadata that is being created. Maximum allowed size of metadata is 100 bytes
}

TokenUpdateTransactionBody

Property metadata is set at the token-type level for non-fungible tokenID.

message TokenUpdateTransactionBody {
    TokenID token = 1; // The token id for which to create tokens. If token does not exist, transaction results in INVALID_TOKEN_ID
    optional string metadata = 2; // The metadata string that is being created. Maximum allowed size of metadata is 100 bytes
}

For sdk implementation:

1. Add a new field to TokenCreateTransactionBody, ``` message TokenCreateTransactionBody { … /**
   • The token metadata, limited to a UTF-8 encoding of no more than 100 bytes;
   • will usually be a URI to a complete description (as NFT metadata generally
   • just links to a HIP-412 compliant JSON document) */ string metadata = 23; } ```
2. Permit updates by adding a new field to TokenUpdateTransactionBody,

Updating the metadata field should require a metadataKey (ie HIP-657)

message TokenUpdateTransactionBody {
    ...
    /**
     * If set, the token's new metadata (UTF-8 encoding max 100 bytes)
     */
    google.protobuf.StringValue metadata = 16;
}

1. Support getting the metadata directly from consensus nodes in the getTokenInfo response, ``` message TokenInfo { … /**
   • The token’s metadata, if any. */ string metadata = 27; } ```

Pricing considerations:

• The price for this metadata will be identical to the cost for storage of the memo.

Backwards Compatibility

This HIP adds functionality and does not affect other services.

Security Implications

There are no additional security implications for the addition of metadata to NFT Collections that are different from individual NFT metadata.

How to Teach This

The Hedera documentation should be updated to reflect the new field. Specific education on metadata contents and formatting is out of scope.

Reference Implementation

The reference implementation must be complete before any HIP is given the status of “Final”. The final implementation must include test code and documentation.

Rejected Ideas

Using the existing memo field to store metadata was a suggestion that would not require a HIP. This was rejected by the community in favour of a clearly defined, dedicated field.

Open Issues

Should EVM system precompile contracts for TokenCreate, TokenUpdate, and GetTokenInfo be updated with metadata support?

References

A collection of URLs used as references through the HIP.

• https://hips.hedera.com/hip/hip-17 - Non-Fungible Tokens
• https://hips.hedera.com/hip/hip-766 - NFT Collection Metadata JSON Schema
• https://hips.hedera.com/hip/hip-412 - NFT Token Metadata JSON Schema
• https://hips.hedera.com/hip/hip-646 - Fungible Token Metadata Field

Copyright/license

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

Acknowledgements

Big thanks to the author and working group of HIP-646 which was used extensively in both the content and formatting of this HIP.

Citation

Please cite this document as: