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

Solidity Structure Updates

Due to recursion issues with KeyList definitions, the following structure modifications are required:

// IHederaTokenService.sol modifications
struct ThresholdKey {
    uint256 threshold;  // Must be 1 for this implementation
    Key[] keys;         // Limited to non-nested keys only
}

struct Key {
    KeyType keyType;
    bytes publicKey;
    address contractId;
    address delegatableContractId;
    ThresholdKey thresholdKey;  // New field
}

KeyHelper.sol requires updates to validate threshold keys:

• Ensure threshold equals 1
• Prevent nested threshold keys
• Validate all keys within the threshold structure
• Return appropriate error codes for invalid configurations

Threshold Limitations

This implementation enforces the following limitations:

1. Threshold Value: Only threshold=1 is supported (any one of the specified keys can perform operations)
2. Nesting Restriction: Threshold keys cannot contain other threshold keys
3. Maximum Keys: A threshold key can contain a maximum of 10 keys to prevent gas limit issues
4. Key Types: Only ECDSA_SECP256K1 and CONTRACT_ID key types are allowed within threshold keys

New response codes for validation failures:

• INVALID_THRESHOLD_VALUE (350): Threshold value must be 1
• NESTED_THRESHOLD_NOT_SUPPORTED (351): Nested thresholds not allowed
• THRESHOLD_KEY_LIST_TOO_LARGE (352): Too many keys in threshold
• INVALID_KEY_TYPE_IN_THRESHOLD (353): Invalid key type within threshold

Transaction Signing Specification

For threshold keys with threshold=1, transaction signing follows these rules:

1. Key Selection: Any one of the keys specified in the threshold key list can sign the transaction
2. Signature Verification: The system verifies that at least one valid signature from the threshold key list is present
3. Key Types and Signing:
   • ECDSA_SECP256K1: Standard ECDSA signature verification
   • CONTRACT_ID: The contract specified must be the msg.sender or have explicit authorization

The signing specification aligns with existing Hedera SDK behavior for threshold keys, ensuring consistency across different interfaces.

System Contract Address

This feature will be exposed through the Hedera Token Service system contract at:

• Address: 0x0000000000000000000000000000000000000167
• Availability: Starting from System Contract Version 0.52.0 (or the version when this HIP is implemented)

Smart contracts can detect support for threshold keys through version checking of the system contract.

Updated Token Creation Function

function createToken(
    IHederaTokenService.HederaToken memory token
) internal returns (int64 responseCode, address tokenAddress)

The function will validate threshold keys according to the specified limitations before token creation.

Updated updateTokenKeys Function

function updateTokenKeys(
    address token,
    IHederaTokenService.TokenKey[] memory keys
) internal returns (int64 responseCode)

The function will validate threshold keys according to the specified limitations before updating token keys.

Backwards Compatibility

This enhancement maintains full backwards compatibility. Existing token creation and key update functions continue to work unchanged. The new functionality is opt-in and only activated when threshold keys are explicitly specified.

Security Implications

Potential Concerns

• Multiple administrators increase the attack surface
• CONTRACT_ID usage in threshold keys requires careful access control
• Large threshold key lists could hit gas limits

Mitigation

• Strict validation at creation and update time
• Enforcing threshold=1 and preventing nested thresholds
• Limiting keys per threshold to 10
• Following protobuf definitions for additional validation

How to Teach This

Documentation should include:

• Step-by-step guide for implementing threshold keys in HTS precompiles
• Explanation of threshold=1 limitation and rationale
• Security best practices for multi-administrator setups
• Examples of common use cases (cross-chain bridges, DAOs)

Reference Implementation

The reference implementation should follow the Hedera SDK’s existing threshold key implementation while adapting it for EVM constraints. Key components include protobuf alignment, validation logic in KeyHelper.sol, and comprehensive test coverage.

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 > 1: Due to Ethereum’s lack of native multi-signature transaction support, implementing thresholds greater than 1 was deemed technically infeasible
3. Nested Threshold Keys: Would create excessive complexity and potential security issues
4. Unlimited Key Lists: Could lead to gas limit issues

Open Issues

1. Gas cost analysis for threshold key operations
2. Security audit scope and requirements
3. Performance impact benchmarking
4. Comprehensive error handling strategy

Citation

Please cite this document as: