-
Notifications
You must be signed in to change notification settings - Fork 140
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Ashe Oro <[email protected]>
- Loading branch information
Showing
1 changed file
with
144 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,144 @@ | ||
| --- | ||
| hip: | ||
| title: NFT Collection Token Metadata Field | ||
| author: Ashe Oro (@Ashe-Oro) | ||
| working-group: | ||
| type: Standards Track | ||
| category: Service | ||
| needs-council-approval: Yes | ||
| status: Active | ||
| created: 2023-06-30 | ||
| discussions-to: | ||
| updated: 2023-06-30 | ||
| --- | ||
|
|
||
| ## Abstract | ||
|
|
||
| This HIP proposes the addition of the metadata field to Non-Fungible TokenID, 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 type. | ||
|
|
||
| ## 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 | ||
|
|
||
| ``` | ||
| // 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`](https://github.com/hashgraph/hedera-protobufs/blob/main/services/token_create.proto), | ||
| ``` | ||
| 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`](https://github.com/hashgraph/hedera-protobufs/blob/main/services/token_update.proto), | ||
|
|
||
| **should ADMIN key be able to update this metadata field, or should it require the metadataKey (ie HIP-657 - https://github.com/hashgraph/hedera-improvement-proposal/blob/main/HIP/hip-657.md) | ||
| ``` | ||
| message TokenUpdateTransactionBody { | ||
| ... | ||
| /** | ||
| * If set, the token's new metadata (UTF-8 encoding max 100 bytes) | ||
| */ | ||
| google.protobuf.StringValue metadata = 16; | ||
| } | ||
| ``` | ||
|
|
||
| 3. Support getting the metadata directly from consensus nodes in the [`getTokenInfo` response](https://github.com/hashgraph/hedera-protobufs/blob/main/services/token_get_info.proto), | ||
| ``` | ||
| 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 collections of URLs used as references through the HIP. | ||
|
|
||
| https://hips.hedera.com/hip/hip-17 - Non-Fungible Tokens | ||
| https://hips.hedera.com/hip/hip-xxx - 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](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0) | ||
|
|
||
| ## Acknoledgements | ||
| Big thanks to the author and working group of HIP-646 which was used extensively in both the content and formatting of this HIP. |