HIP-1069: Enable Threshold Key Support in HTS Token Creation and Update Operations

Abstract

This HIP proposes an enhancement to the Hedera Token Service (HTS) precompile functions to support Threshold Keys in both token creation and key updates. Although Threshold Keys are supported within the SDK, they cannot currently be set through the HTS precompiles, which limits their usability in smart contracts for token management. Enabling Threshold Key support (with threshold=1) within the HTS precompiles would allow token keys managed by multiple administrators to be set during creation and updated on-chain, adding significant flexibility for contract-based token operations.

Motivation

The Hedera SDK allows setting Threshold Keys for token keys, which is a useful feature for administrative setups where multiple potential administrators need equal permissions. However, the HTS precompile functions do not currently support Threshold Keys, making it impossible to create or update token keys with multiple potential administrators directly on-chain. This limitation creates a gap in functionality, especially for projects that require flexible administrative control within contract environments, such as Axelar’s cross-chain integrations.

Rationale

Supporting Threshold Keys (threshold=1) directly within the token creation and update precompiles aligns with Hedera’s goal of providing flexible, decentralized token management. By allowing contract-based applications to set Threshold Keys during token creation and subsequent updates, developers can implement multiple administrator scenarios where any one of the specified administrators can perform operations. This simplifies administrative control without needing to rely on external SDK calls or workarounds. Due to Ethereum’s lack of native multi-signature transaction support, this implementation focuses on threshold=1 scenarios, which covers the primary use case of allowing multiple potential administrators with equal permissions.

User Stories

1. As a developer managing a cross-chain bridge, I want to create tokens with Threshold Keys and update token keys through HTS precompiles, allowing multiple potential administrators to authorize operations.
2. As a DApp creator, I want to create tokens with a Threshold Key as the supply key and update it as needed, enabling multiple administrators to have equal permission to adjust supply.
3. As a DAO member, I want to both create and update token keys on-chain using a Threshold Key to allow any approved administrator to manage key operations.
4. As a protocol developer, I want to initialize tokens with Threshold Keys during creation to establish flexible administrative controls from the start, where any designated administrator can perform operations.

Specification

The following updates are proposed to the HTS precompile functions to support Threshold Keys with threshold=1:

Updated Token Creation Function

Add support for Threshold Key types within the token creation parameters:

    /// Operation to create a token with Threshold Key support
    /// @param token The token creation parameters, including Threshold Keys for multi-admin support
    /// @return responseCode The response code for the status of the request. SUCCESS is 22.
    /// @return tokenAddress The created token's address
    function createToken(
        IHederaTokenService.HederaToken memory token
    ) internal returns (int64 responseCode, address tokenAddress) {
        (bool success, bytes memory result) = precompileAddress.call(
            abi.encodeWithSelector(
                IHederaTokenService.createToken.selector,
                token
            )
        );
        (responseCode, tokenAddress) = success
            ? abi.decode(result, (int32, address))
            : (HederaResponseCodes.UNKNOWN, address(0));
    }   

Updated updateTokenKeys Precompile Function

Add support for Threshold Key types within IHederaTokenService.TokenKey[] in the updateTokenKeys function:

    /// Operation to update token keys with Threshold Key support
    /// @param token The token address
    /// @param keys The token keys, including Threshold Keys for multi-admin support
    /// @return responseCode The response code for the status of the request. SUCCESS is 22.
    function updateTokenKeys(
        address token,
        IHederaTokenService.TokenKey[] memory keys
    ) internal returns (int64 responseCode) {
        (bool success, bytes memory result) = precompileAddress.call(
            abi.encodeWithSelector(
                IHederaTokenService.updateTokenKeys.selector,
                token,
                keys
            )
        );
        (responseCode) = success
            ? abi.decode(result, (int32))
            : HederaResponseCodes.UNKNOWN;
    }

Example Usage for both operations:

    // Threshold Key definition (threshold=1)
    IHederaTokenService.TokenKey memory key = IHederaTokenService.TokenKey({
        keyType: KeyType.SUPPLY,
        key: ThresholdKey({
            keys: [
                Key(KeyType.ECDSA_SECP256K1, ecdsaPublicKey1),
                Key(KeyType.CONTRACT_ID, contractId2)
            ],
            threshold: 1  // Any one administrator can perform operations
        })
    });

    // Creation with Threshold Key
    IHederaTokenService.HederaToken memory tokenParams = IHederaTokenService.HederaToken({
        name: "Example Token",
        symbol: "EXT",
        treasury: msg.sender,
        keys: [key],
        // ... other parameters
    });

    (int responseCode, address tokenAddress) = IHederaTokenService.createToken(tokenParams);

    // Updating with Threshold Key
    IHederaTokenService.updateTokenKeys(tokenAddress, [key]);

Backwards Compatibility

No foreseen issues

Security Implications

TBD

How to Teach This

This enhancement should be documented in the Hedera developer documentation, with examples on how to set Threshold Keys (threshold=1) for token keys during both creation and updates using the HTS precompiles, emphasizing the use case of enabling multiple potential administrators with equal permissions.

Reference Implementation

A reference implementation should mirror the specification given within the Hedera SDK to allow developers to use Threshold Keys within HTS precompiles for both token creation and updates, ensuring compatibility with both contract-based and SDK token operations.

Rejected Ideas

1. External SDK Workarounds: Using SDK calls outside of the smart contract was considered but found impractical for fully on-chain applications.
2. Support for Threshold Keys with threshold > 1: Due to Ethereum’s lack of native multi-signature transaction support, implementing thresholds greater than 1 was deemed technically infeasible.

Open Issues

1. 2.

Citation

Please cite this document as: