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.

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 method names will be preserved, with the introduction of new structs to support the metadata field and metadata key.
• Information retrieval methods: Method names will be updated to include V2 to distinguish them from the old methods, as the return types will change.
• 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

To achieve this, the Hedera Token Service (HTS) system contract will be updated to expose the required features.
The existing system contract functions will be extended and new functions will be added to the IHederaTokenService
to support the new metadata field and metadata key.

New Solidity Types

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

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

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

struct FungibleTokenInfoV2 {
    // The new struct with metadata
    TokenInfoV2 token;
    int32 decimals;
}

struct NonFungibleTokenInfoV2 {
    // The new struct with metadata
    TokenInfoV2 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 and the new methods.

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: