HIP-1028: Metadata management via SmartContracts

Abstract

HIP-646/657/765 introduced a new metadata field for Fungible Tokens (FT), Non-Fungible Tokens (NFT) and METADATA key
for updating metadata. However, these features are not supported by smart contracts.
This proposal aims to enhance the Hedera Smart Contract Service (HSCS) by exposing HIP-646/657/765 features in the Hedera Token Service system contract.

Motivation

A user may need to create, update and get info for token metadata and the metadata key for Fungible Tokens (FT) and Non-Fungible Tokens (NFT)
from a smart contract.
The current version of Hedera Smart Contract Service (HSCS) does not cover these use cases.

Rationale

The HAPI calls for creating tokens and updating token information were modified to include the new metadata and metadata key.
This proposal extends the Hedera Token Service (HTS) system contract by introducing new functions to expose these capabilities.

• Create and update methods: Existing structs will be modified to support the metadata field and metadata key at a new system contract address (0x16c).
• New functionality: A new function for TokenUpdateNfts HAPI operation will be added.

User stories

1. As an EOA I would like to initiate a smart contract transaction that creates a fungible token with metadata.
2. As an EOA I would like to initiate a smart contract transaction that creates a non-fungible token collection with metadata.
3. As an EOA I would like to initiate a smart contract transaction that updates a fungible token with metadata.
4. As an EOA I would like to initiate a smart contract transaction that updates a non-fungible token collection with metadata.
5. As an EOA I would like to initiate a smart contract transaction that creates a fungible token with a metadata key.
6. As an EOA I would like to initiate a smart contract transaction that creates a non-fungible token collection with metadata key.
7. As an EOA I would like to initiate a smart contract transaction that updates a fungible token with metadata key.
8. As an EOA I would like to initiate a smart contract transaction that updates a non-fungible token collection with metadata key.
9. As an EOA I would like to initiate a smart contract transaction that creates a fungible token with metadata and metadata key.
10. As an EOA I would like to initiate a smart contract transaction that creates a non-fungible token collection with metadata and metadata key.
11. As an EOA I would like to initiate a smart contract transaction that updates the metadata of unique instances of an NFT(s).

Specification

New System HTS System Contract Version - 0x16c

Since the modifications required to implement this HIP require breaking changes to structs within the HTS system contract, a new system contract address (0x16c) will be introduced to support the new functionality. All existing HTS functions not mentioned in this HIP will continue to behave as they do today at the new system contract address. Furthermore, the existing HTS system contract at address 0x167 will remain unchanged to ensure backwards compatibility for existing contracts that reference the HTS system contract at that address.

Minting Tokens

The token minting processes remain unchanged by this HIP. NFT metadata during minting continues to function as before. However, this HIP introduces two new features: metadata capabilities at the token class level and the ability to modify individual NFT metadata using a metadata key.

Metadata Key

The newly introduced metadata key enables modification of metadata for individual NFTs. All supported key types on Hedera can be used to define this key, including Contract Key. This means that the contract ID of the contract calling the functions in this HIP can also serve as the metadata key.

New Solidity Types

The following structs have been modified to support metadata and metadata key

struct HederaToken {
    String name;
    String symbol;
    // other fields identical to the existing HederaToken struct
    ...
    // The new field for metadata
    bytes metadata;
}

The following three structs, TokenInfo, FungibleTokenInfo and NonFungibleTokenInfo, are mentioned as they have cascading modifications because of the inclusion of the HederaToken struct.

struct TokenInfo {
    // The new struct with metadata
    HederaToken token;
    // other fields identical to the existing TokenInfo struct
    ...
}

struct FungibleTokenInfo {
    // The new struct with metadata
    TokenInfo token;
    int32 decimals;
}

struct NonFungibleTokenInfo {
    // The new struct with metadata
    TokenInfo token;
    // other fields identical to the existing NonFungibleTokenInfo struct
    ...
}

Adding a comment to the TokenKey struct to clarify that the 7th bit is designated for the metadata key.
However, existing methods that use HederaToken with the TokenKey struct will continue to ignore the metadataKey bit.

struct TokenKey {
    // bit field representing the key type. Keys of all types that have corresponding bits set to 1
    // will be created for the token.
    // 0th bit: adminKey
    // 1st bit: kycKey
    // 2nd bit: freezeKey
    // 3rd bit: wipeKey
    // 4th bit: supplyKey
    // 5th bit: feeScheduleKey
    // 6th bit: pauseKey
    
    // the 7th bit will be metadata key
    // 7th bit: metadataKey
    uint keyType;
    
    // the value that will be set to the key type
    KeyValue key
}

Solidity Function Signatures

The new structs will change the signature of the functions. However the old versions of the functions will continue working.

Backwards Compatibility

Backwards compatibility is ensured by the consensus node supporting both the existing HTS system contract at address 0x167 and the introduction of the new contract at address 0x16c for the new functionality described above.

Security Implications

The HIP provides exposure to existing HTS functionality. Fundamentally security is still governed by the ledger security logic
in combination with the EVM. As such, there should be no new security implications.

References

• HIP-646
• HIP-657
• HIP-765

Copyright/license

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

Citation

Please cite this document as: