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

The Hedera Token Service (HTS) will implement these features through a new system contract address (0x16c). This approach ensures backward compatibility - existing contracts using current functions and structs will continue to work without disruption when using HTS at address 0x167. The new system contract will maintain support for all existing functions that haven’t been redefined below.

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: