HIP-358: Allow Token Create Through Hedera Token Service Precompiled Contract Source

AuthorStoyan Panayotov
Discussions-Tohttps://github.com/hashgraph/hedera-improvement-proposal/discussions/375
StatusFinal
Needs Council ApprovalYes
Review period endsWed, 30 Mar 2022 07:00:00 +0000
TypeStandards Track
CategoryService
Created2022-02-09
Updated2022-04-01, 2022-04-11, 2022-05-25

Abstract

Describe the integration of Hedera Token Service (HTS) with the Hedera Smart Contract Service (HSCS), allowing contracts to create HTS tokens programmatically.

Motivation

Allow smart contract developers on Hedera to create HTS fungible and non-fungible tokens through the HTS precompiled contract giving smart contracts developers on Hedera to ability to leverage Hedera native token functionality.

Rationale

HIP-206 already allows token mint, burn, associate, dissociate and transfer through the HTS precompiled contract. Allowing creation of tokens via smart contracts is a natural extension of the precompiled contract and would enable smart contract developers to rely solely on contract code for token management.

User stories

As a smart contract developer, I want to be able to create a native HTS fungible token through a solidity contract call.

As a smart contract developer, I want to be able to create a native HTS fungible token with custom fees through a solidity contract call.

As a smart contract developer, I want to be able to create a native HTS non-fungible token through a solidity contract call.

As a smart contract developer, I want to be able to create a native HTS non-fungible token with custom fees through a solidity contract call.

Specification

EVM Precompile extension

The Solidity file for development is updated with new types and function signatures that the precompile will respond to. It is included in this HIP by reference.

Solidity Function Signatures

The following structs are defined to simplify the interface between solidity and the HTS precompile:

Name Definition
KeyValue (bool, address, bytes, bytes, address)
Expiry (uint, address, uint)
TokenKey (uint, KeyValue)
HederaToken (string, string, address, string, bool, uint32, bool, TokenKey[], Expiry)
FixedFee (uint32, address, bool, bool, address)
FractionalFee (uint32, uint32, uint32, uint32, bool, address)
RoyaltyFee (uint32, uint32, uint32, address, bool, address)

Two functions are defined for creating fungible and non-fungible tokens each. One is a simple version with just the required fields and the other a full version supporting custom fees as well. The ABI signature and hashes for each call are as follows:

hash effective signature return
7812a04b createFungibleToken(HederaToken, uint, uint) (int, addess)
4c381ae7 createFungibleTokenWithCustomFees(HederaToken, uint, uint, FixedFee[], FractionalFee[]) (int, addess)
9dc711e0 createNonFungibleToken(HederaToken) (int, addess)
5bc7c0e6 createNonFungibleTokenWithCustomFees(HederaToken, FixedFee[], RoyaltyFee[]) (int, addess)

Precompile Gas Costs

In order to allow creation of token through the precompiled contract, a new mechanism for payment is introduced - precompile calls are partially payed by Hbar value transfers. There is a base cost of 100,000 Gas for each call to the create functions. Additional Hbar cost is required to be transferred as value to the precompile call. The Hbar price will be calculated using the following formula:

The total cost of HTS Token create through the precompile is equal to the cost of a HAPI Create Token Transaction with similar arguments at that instance plus a 20% premium. The Hbars required to be transferred as value in the precompile call will be equal to the total cost required minus the Hbar cost for the base 100,000 gas cost at that instance.

The gas cost is always charged to the HAPI payer. The Hbars transferred as value to the precompile will be charged to the msg.sender for the message frame. Contracts performing a direct call to the precompile will be required to hold Hbar.

Exchange rates might change and consequently Hbar cost for token create might change. The demo contract provided has means to adjust how much Hbar is transferred as value to the precompile call.

Minimum Gas Charge

The gas limit in ethereum fulfills an essential role in limiting processing throughput, it also serves in Ethereum Mainnet as a long-term storage cost. This HIP only separates the long-term storage costs but needs to keep the throughput limiting. Hence some of the precompile cost must be paid in gas.

Only accepting the exact amount

When a user transfers in via value hbar only the amount needed to pay the transaction is deducted, even if there is excess. This will simplify accounting in smart contacts that want to maximize hbar payment ability and not needing to program in tracking fluctuating exchange rates.

Precompile Transaction Records

Child records for Token Create will be created for each precompile call.

Backwards Compatibility

There are no changes to the protobufs. The changes in the existing HTS precompile only add new features and capabilities and should not impact existing behaviour.

Security Implications

This HIP does not change the implementation of HTS token create, nor does it add new features. What is being added is a new way to call existing functionality. The security posture of the system is expected to remain unchanged.

How to Teach This

The IHederaTokenService.sol interface is well documented and example client code is provided with TokenCreateContract.sol.

Reference Implementation

Rejected Ideas

Support for Complex Keys

This HIP only supports simple 1 of 1 and contract keys for authorization, and does not support threshold or other complex key structures. There are multiple reasons. First, solidity does not allow for recursive structure definitions like protobufs do. This recursive definition is essential to the complex key structures supported by the protobuf APIs. Second, allowing even one level of threshold signatures increases the size of the ABI significantly for a feature that would burden uses of the API that do not use threshold key arrangements. It is possible that HTS update calls may be added to the HTS precompile, and it would partially address this shortcoming. In the interim the protbuf API provides full access to complex keys.

Open Issues

References

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: