ADR - Token metadata

[mamorales1]

Context

In order to empower the tokens created by the accelerator to increase not only the functionality they could achieve, but also the information of each token created, it is important to give users the ability to add metadata to their tokens.

Hedera already provides a way to add metadata to non-fungible tokens, since is mandatory for this kind of tokens, but they don’t yet for fungible tokens, although there are a couple of HIPs, HIP-405 and HIP-646 (the first one in active status while the other one still in accepted status), to define a fungible token metadata JSON schema and create a metadata field also for fungible tokens.

Once above HIP-646 is complete, we could integrate this standard way of including metadata into fungible tokens in the accelerator, but, meanwhile, we would like to manage metadata into the accelerator tokens so that when we have to change the way to do it, it's as easy as possible.

HIP-646 aims to create a new token field that allows the token to point to the JSON file where metadata is stored. HTS tokens already have a memo field, but this field has a more generic purpose and we are also being using it to store information about the smart contract proxy address that manages the stable coin. We could add the information we are currently storing in the memo field into the metadata JSON file, but this would force us not only to create but also to store this metadata JSON file and, later on, to access this file to get this necessary information, and this is something that we are not considering, at least, for the moment. Therefore, we are not going to use the memo field for this purpose.

Proposal

Our proposal is to allow the user to optionally add a metadata URI to the stable coin is being created and, once this is created, the user could change this metadata URI, remove it or add it in the case the user didn’t do it when creating the stable coin.

Since metadata information is inherent to the token, and since, currently, the token does not have a field for such a purpose, our proposal is to create a variable in the stable coin smart contract in order to store the metadata URI, so this metadata URI will be part of optional information required to the user when creating the stable coin. Subsequently, if the user is the token administrator, it will be able to change this URI in any way. This way, it wouldn’t be any change, regarding the user permissions, when the metadata URI is stored in the new metadata token field: the token administrator will be the only one who will be able to add metadata information to the token, now and later on.

Let’s see how this affects to different accelerator’s modules.

Smart contracts

As commented above, a new variable to store the metadata URI must be added to the stable coin contract. We are going to use metadata as the variable name since is the name that will have the new token field according to the the HIP-646.

The stable coin contract consists of several contracts that modularizes the functionality. In this case, the field will be added to the HederaTokenManager contract, and public functions to get and set this variable must be also added to the contract:

// HTS token metadata
string private _metadata;

/**
 * @dev Checks that an string is not longer than 100 characters
 *
 * @param str The string whose length is going to be checked
 */
modifier lessThan100(string calldata str){
  if (bytes(str).length > 100) revert("Longer than 100 characters");
  _;
}

/**
 * @dev Emitted when a new metadata was set
 *
 * @param metadata The metadata that was set
 */
event MetadataSet(string metadata);

/**
 * @dev Gets the metadata
 *
 */
function _getMetadata() external view returns (string memory) {
  return _metadata;
}

/**
 * @dev Sets the metadata
 *
 * @param metadata The metadata to set
 */
function setMetadata(string calldata metadata) 
  external 
  lessThan100(metadata) 
{
  _metadata = metadata;
  
  emit MetadataSet(metadata);
}

HIP-646, which is still in accepted status, establishes that the maximum allowed size for the new metadata token field will be of 100 bytes, so it would important to set the same limit in the smart contract variable. Therefore, to control this limit we will use the above lessThan100 modifier.

As the user will be able to set the metadata URI when deploying or when updating the stable coin, these two functions in the smart contracts to deploy and update the stable coin will also change.

It is important to note that when HIP-646 is implemented and HTS fungible tokens have a metadata property, the above variable will be removed. We are currently using a gap variable in the smart contract (uint256[50] private __gap) which is an empty reserved space in order to add storage variables in future versions of the smart contract. So, when adding this new variable, this array of gaps will be decreased in one positon, and, in the same way, when the metadata variable is removed, the array of gaps will have the 50 positions again, but just before doing this increase, the value of the metadata must be set to 0 for future new storage variables will not have the URI as a value.

Another aspect to take into account when the new metadata token field is available will be that the new version of HederaTokenManager, which will not have the metadata variable, must have an initialize function that allows the users who migrates, from the latests version of the contrat to the new one, to copy the value of the variable to the new metadata token field.

Let’s start with the deploy function in the StableCoinFactory smart contract.

Deploying the stable coin

The function definition is the following:

function deployStableCoin(
    TokenStruct calldata requestedToken,
    address stableCoinContractAddress
)

Most of the data is passed to the function through the TokenStruct parameter type. Now, the user will pass another data, the metadata, so this struct, that is defined in the above contract interface, IStableCoinFactory, must be change to add the new property at the end:

struct TokenStruct {
        string tokenName;
        string tokenSymbol;
        bool freeze;
        bool supplyType;
        int64 tokenMaxSupply;
        int64 tokenInitialSupply;
        int32 tokenDecimals;
        address reserveAddress;
        int256 reserveInitialAmount;
        bool createReserve;
        KeysLib.KeysStruct[] keys;
        IHederaTokenManager.RolesStruct[] roles;
        IHederaTokenManager.CashinRoleStruct cashinRole;
        string metadata;
    }

To create the token, the above mentioned deployStableCoin function, in the StableCoinFactory contract, invokes the initialize function of the HederaTokenManager contract, which is the function that creates the token.

function initialize(
        InitializeStruct calldata init
)

So, the initializeStruct must be also changed to add the property.

struct InitializeStruct {
        IHederaTokenService.HederaToken token;
        int64 initialTotalSupply;
        int32 tokenDecimals;
        address originalSender;
        address reserveAddress;
        RolesStruct[] roles;
        CashinRoleStruct cashinRole;
        string tokenMetadataURI;
}

And in the deployStableCoin function must fill this new property.

// Initialize Proxy
IHederaTokenManager.InitializeStruct
    memory initInfo = IHederaTokenManager.InitializeStruct(
        token,
        requestedToken.tokenInitialSupply,
        requestedToken.tokenDecimals,
        msg.sender,
        reserveAddress,
        requestedToken.roles,
        requestedToken.cashinRole,
        requestedToken.tokenMetadataURI
    );

address tokenAddress = HederaTokenManager(address(stableCoinProxy))
    .initialize{value: msg.value}(initInfo);

Finally, the metadata must be set in the initialize function of HederaTokenManager contract:

...
set(requestedToken.tokenMetadataURI);
...

The following diagram illustrates the flow.

Updating the stable coin

In the case of updating the token, the operation is very similar, but easier, since the function to update the token is defined in the HederaTokenManager smart contract, so the StableCoinFactory contract is not involved.

function updateToken(
    UpdateTokenStruct calldata updatedToken
)

So the struct to modify will be only UpdateTokenStruct, defined in the IHederaTokenManager interface.

struct UpdateTokenStruct {
        string tokenName;
        string tokenSymbol;
        KeysLib.KeysStruct[] keys;
        int64 second;
        int64 autoRenewPeriod;
        string tokenMetadataURI;
}

This struct contains those properties that can be updated from both the CLI and the UI. Since we are going to give the oportunity to users to also update the metadata, this property must be added to the struct as shown above.

In the updateToken function the metadata will be set in this easy way:

...
set(requestedToken.tokenMetadataURI);
...

So the diagram is less complex than in the case of the deploy.

SDK

Once the variable which aims to store the token metadata URI was added to the stable coin smart contract and the deployStableCoin and updatetoken functions were also modified to consider the metadata URI property to set the variable, the SDK must also change both the deploy stable coin and the update token functionalities in order to pass the token metadata URI to be stored in the HederaTokenManager smart contract.

This is the only modification to the SDK, so the deploy functionality looks like the following diagram.

While the update looks like this other one.

The SDK’s deploy and update flows will not be modified when HTS fungible tokens have a metadata property, since the value of the metadata URI will continue to be provided in the same way and the contract calls will be also the same, and it will be the smart contract which stores this metadata URI in the token instead of in the smart contract.

Besides the stable coin deployment and the token update, the SDK must provide a function to get the token metadata URI, since both in the CLI and the UI this URI will be shown when the user displays the details of the token. This operation will be performed through the RPCQueryAdapter because is a query operation to the smart contract. When HIP-646 is implemented, and the HTS token has its own metadata field, this information will be obtained through the mirror node as in the case of other token properties.

Therefore, for the user to get the token metadata along with other stable coin information in the details menu option, both in the CLI and the UI, the SDK getInfo operation of the StableCoin input port must be modified. In the flow of this operation, the GetStableCoinQueryHandler class gets the token information through the mirror node and the PoR information through a query to the PoR smart contract. Therefore, another query, in this case to the HederaTokenManager smart contract, where the getMetadata function is located, through the RPCTransactionAdapter, will be made. So we have to implement the getTokenMetadataURI function in the RPCTransactionAdapter and call to this function in the GetStableCoinQueryHandler. This function will not be necessary when HTS fungible tokens have their own metadata property, since this value will be part of the data obtained through the mirror node.

The operation diagram would be the following:

The StableCoinViewModel class, which is the object type returned by the getInfo function of the StableCoin input port, must be also modified in order to add the property to be provided to the CLI and the UI.

export default interface StableCoinViewModel extends QueryResponse {
    tokenId?: HederaId;
    name?: string;
    symbol?: string;
    decimals?: number;
    totalSupply?: BigDecimal;
    maxSupply?: BigDecimal;
    initialSupply?: BigDecimal;
    treasury?: HederaId;
    proxyAddress?: ContractId;
    proxyAdminAddress?: ContractId;
    evmProxyAddress?: EvmAddress;
    evmProxyAdminAddress?: EvmAddress;
    expirationTime?: string;
    freezeDefault?: boolean;
    autoRenewAccount?: HederaId;
    autoRenewPeriod?: number;
    expirationTimestamp?: number;
    paused?: boolean;
    deleted?: boolean;
    adminKey?: ContractId | PublicKey | undefined;
    kycKey?: ContractId | PublicKey | undefined;
    freezeKey?: ContractId | PublicKey | undefined;
    wipeKey?: ContractId | PublicKey | undefined;
    supplyKey?: ContractId | PublicKey | undefined;
    pauseKey?: ContractId | PublicKey | undefined;
    feeScheduleKey?: PublicKey | undefined;
    reserveAddress?: ContractId;
    reserveAmount?: BigDecimal;
    customFees?: RequestCustomFee[];
    metadata?: string;
}

CLI

In the CLI, the create stable coin and the update functionalities will also be affected.

During the stable coin deployment, in the flow that requests the user to provide required information, the question "Do you want to configure the initial supply, max supply or decimals? " will be change by "Do you want to configure the initial supply, max supply, decimals or add some metadata?”. In the case that the user answers affirmatively to this question, besides the data is already requested to the user, the token metadata URI will be also requested, and the data provided by the user will populate the metadata property of the UpdateRequest object.

On the other hand, when the user wants to update the token through the token configuration menu option, besides the name, the symbol, the expiration time, the autorenew period and the keys, the user will also be able to provide a new metadata URI (it doesn’t mind if this URI didn’t exist before) or remove the existing one. It is important to remember that only the token administrator, the account who owns the the token admin key, will be able to update the token, so this will not change when HTS fungible tokens have a metadata property.

In the case of the details menu option, where the token metadata URI must be displayed, it will only be necessary to write this new data since the SDK operation would already return this property along with the other properties.

UI

Regarding the UI, the state is very similar to that the CLI. The user will be able to provide a token metadata URI when creating the stable coin and update a new URI through the stable coin details menu option where the current metadata URI will be always displayed.

When creating the stable coin, the token metadata URI will be requested to the user in the optional details step, along with the initial supply, the supply type and the decimals number.

The stable coin details menu option will display the metadata URI and also will allow the user to update this URI in the same way as it does with the name, the symbol, the autorenew period, the expiration time and the keys. As in the case of the CLI, only the token administrator will be able to update this property.

Out of scope

It's not the purpose of this document to define metadata schema, which is well defined for fungible tokens in the active HIP-405, nor to state where this metadata should be stored, since the functionality described above regarding the metadata does not include the creation of the JSON metadata file nor the storage of it, but, simply, adding existing metadata to the token.

Decision

After the above study we have reached the following conclusions:

• We are not going to use the already existing memo field to store the metadata URI.

• A new variable to store the token metadata URI and accessing functions will be added in the stable coin smart contract.

• The user will be able to provide a token metadata URI, both through the CLI and the UI, during the stable coin creation process.

• The token metadata URI will be part of the token information displayed both in the CLI and the UI.

• The user will be able to update the token metadata URI both from the CLI and the UI.

• The user will be able to remove the token metadata URI both from the CLI and the UI.

• The user will be able to provide a token metadata URI to an existing token that doesn’t have it.