HIP-657: Mutable metadata fields for dynamic NFTs Source

AuthorPatches Punks
Working GroupJason Fabritz <@bugbytesinc>, Sean Cuscus <@seancuscus>, Cooper Kunz <@Cooper-Kunz>, May Chan <@rocketmay>, Burstall Stowerling <@Burstall>, Ian Holsman <@web3-nomad>, Ashe Oro <@Ashe-Oro>, Michael Garber <@mgarbs>, Paul Sullivan <@paulgs9988>
Needs Council ApprovalYes
Review period endsTue, 28 Feb 2023 07:00:00 +0000
TypeStandards Track
Updated2023-01-21, 2023-01-24, 2023-02-03, 2023-02-15, 2023-02-23, 2023-03-01, 2023-03-07


Currently, there is no native way to update the metadata of a non-fungible token (NFT) on the Hedera network. This HIP proposes the creation of a new key called the METADATA key, which will allow updating NFT metadata. This will provide the Hedera network with functional parity with other networks and enable developers to create dynamic NFTs with new interactions.


Dynamic NFTs are a valuable addition to the world of non-fungible tokens because they allow for more interactive and immersive experiences. With the ability to update the metadata of an NFT, developers can create game pieces that gain new equipment and stats, legal agreements that reflect changing parameters, or even NFTs that update their images based on the time of day. Dynamic NFTs also open up the possibility for NFTs to be used in a wider range of industries and applications, such as supply chain tracking, real estate, among others. The potential for dynamic NFTs is numerous, and their introduction will greatly enhance the capabilities of the NFT ecosystem.


To address this issue, the proposed solution is to create a new key called the METADATA key. This key will allow NFTs in a collection to update their metadata.

The use of the METADATA key to update NFT metadata will not affect the functionality of existing NFTs on the Hedera Network. It will be available for new and existing NFTs.

User stories

  • As a collector of NFTs, I want to be able to update the metadata of an NFT in my collection so that I can add new information or make changes to the existing metadata.

  • As a creator of NFTs, I want to be able to update the metadata of an NFT while leaving an auditable on-chain history of when the update happened and which key was used to sign for the update action so that I can retain as much transparency as possible.

  • As a creator of NFTs, I want to use IPFS to manage my dynamic NFT’s metadata so that I don’t have to use a centralized file storage solution to enable the ability to edit.

  • As a developer building applications on top of the Hedera Network, I want the ability to update the metadata of NFTs so that I can create dynamic NFTs and build more advanced use cases.


The METADATA key will be a new key that allows for updating the metadata of an NFT in a new NftMetadataUpdate transaction.

The NftMetadataUpdate transaction should accept the following parameters: - identifier (string): the 0.0..

  • the new NFT metadata: the new metadata for the NFT

The NftMetadataUpdate transaction should have a new token type field called “dynamic_metadata” of type bool, which is valid only for non-fungible tokens. By default, this field is set to false (meaning the metadata for this token type is immutable). If set to true, owners of this token type can change their NFT’s metadata via the NftMetadataUpdate transaction.

Example transaction:



message NftMetadataUpdateTransactionBody {
     * The Token to be updated
    TokenID token = 1;

     * The metadata key of the Token. If Token is immutable, transaction will resolve to
     Key metadataKey = 2;

     * Represents the unique metadata of the NFT
    bytes metadata = 3;

TokenCreate and TokenUpdate should be updated to add this new metadata key

message TokenCreateTransactionBody {
     * The key which can change the supply of a token. The key is used to sign Token NFT Metadata Update
     * operations
    Key metadataKey = 11;

message TokenUpdateTransactionBody {
     * The key which can change the metadata of an NFT. The key is used to sign Token NFT Metadata Update
     * operations
    Key metadataKey = 11;

Requirements: The NFT must exist on the Hedera network and should only be allowed to execute if it is signed by the new METADATAKEY. The new metadata must be a valid byte array limited to 100 bytes. The update must be made atomically and be recorded on the Hedera network.

Backwards Compatibility

The addition of the METADATA key will not affect the functionality of existing NFTs on the Hedera Network because it will be available for use on new NFTs.

Security Implications

The use of the METADATA key and creation of a NftMetadataUpdate transaction will not introduce any new security concerns.

How to Teach This


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

Open Issues

There are currently no open issues with this proposal.




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


Please cite this document as: