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 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.

Related HIPs

• HIP-646 will add metadata for fungible tokens, which will introduce the same fields as this HIP.
• HIP-657 introduces mutable metadata for NFTs. The METADATA key defined in HIP-657 will also allow updating the metadata field specified in this HIP.

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

1. Add a new field to 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 {
    ...
   
    /**
     * Metadata of the created token definition.
     */
    bytes metadata = 23;
   }
   

TokenUpdateTransactionBody

1. Permit updates by adding a new field to TokenUpdateTransactionBody, Property metadata is set at the token-type level for non-fungible tokenID.

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

message TokenUpdateTransactionBody {
    ...
    
    /**
     * If set, the metadata of the updated token definition
     */
    google.protobuf.BytesValue metadata = 16;
}

GetTokenInfo

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

Pricing considerations:

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

Mirror Node Changes

Currently, only for individual NFTs does the Mirror Node REST API return the metadata field. This will be extended to an entire token type for both fungible (HIP-646) and non-fungible token collections (this HIP).

/api/v1/tokens

For the list tokens endpoint, the token level metadata field will be returned as a base64 encoded value.

{
    "links": {
        "next": null
    },
    "tokens": [
        {
            "admin_key": {
                "_type": "ED25519",
                "key": "0aa8e21064c61eab86e2a9c164565b4e7a9a4146106e0a6cd03a8c395a110e92"
            },
            "metadata": "Ag==",
            "symbol": "fungible",
            "token_id": "0.0.1032",
            "type": "FUNGIBLE_COMMON"
        },
        {
            "admin_key": {
                "_type": "ED25519",
                "key": "0aa8e21064c61eab86e2a9c164565b4e7a9a4146106e0a6cd03a8c395a110e92"
            },
            "metadata": "VEVTVF9tZXRhZGF0YQ==",
            "symbol": "non_fungible",
            "token_id": "0.0.1036",
            "type": "NON_FUNGIBLE_UNIQUE"
        }
    ]
}

/api/v1/tokens/{tokenId}

For a given token ID, in addition to the metadata field, the new metadata_key (HIP-657) will also be returned in the standard key format.

{
    "admin_key": {
        "_type": "ED25519",
        "key": "0aa8e21064c61eab86e2a9c164565b4e7a9a4146106e0a6cd03a8c395a110e92"
    },
    "auto_renew_account": "0.0.1020",
    "auto_renew_period": 6999999,
    "created_timestamp": "1706556543.894559367",
    "custom_fees": {
        "created_timestamp": "1706556543.894559367",
        "fixed_fees": [],
        "royalty_fees": []
    },
    "decimals": "0",
    "deleted": true,
    "expiry_timestamp": 1713556542894559367,
    "fee_schedule_key": {
        "_type": "ED25519",
        "key": "0aa8e21064c61eab86e2a9c164565b4e7a9a4146106e0a6cd03a8c395a110e92"
    },
    "freeze_default": false,
    "freeze_key": null,
    "initial_supply": "0",
    "kyc_key": null,
    "max_supply": "0",
    "memo": "Mirror Node acceptance test: 2024-01-29T19:29:03.525656Z Create token",
    "metadata": "VEVTVF9tZXRhZGF0YQ==",
    "metadata_key": {
        "_type": "ED25519",
        "key": "0aa8e21064c61eab86e2a9c164565b4e7a9a4146106e0a6cd03a8c395a110e92"
    },
    "modified_timestamp": "1706556543.894559367",
    "name": "non_fungible_name",
    "pause_key": {
        "_type": "ED25519",
        "key": "0aa8e21064c61eab86e2a9c164565b4e7a9a4146106e0a6cd03a8c395a110e92"
    },
    "pause_status": "UNPAUSED",
    "supply_key": {
        "_type": "ED25519",
        "key": "0aa8e21064c61eab86e2a9c164565b4e7a9a4146106e0a6cd03a8c395a110e92"
    },
    "supply_type": "INFINITE",
    "symbol": "non_fungible",
    "token_id": "0.0.1036",
    "total_supply": "0",
    "treasury_account_id": "0.0.1020",
    "type": "NON_FUNGIBLE_UNIQUE",
    "wipe_key": {
        "_type": "ED25519",
        "key": "0aa8e21064c61eab86e2a9c164565b4e7a9a4146106e0a6cd03a8c395a110e92"
    }
}

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: