HTS System Contract Skill

Hedera Token Service（HTS）系统合约

0x167 处的 HTS 预编译合约支持 Solidity 合约创建和管理 Hedera 原生代币，并内置合规控制（KYC、冻结、暂停）和自定义费用。

快速参考

导入：

import {HederaTokenService} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-token-service/HederaTokenService.sol";
import {KeyHelper} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-token-service/KeyHelper.sol";
import {ExpiryHelper} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-token-service/ExpiryHelper.sol";
import {HederaResponseCodes} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-token-service/HederaResponseCodes.sol";

安全变体（失败时自动回滚）：SafeHTS.sol、SafeViewHTS.sol

重要：需要支付 HBAR

创建代币需要显式支付 HBAR（不仅仅是 Gas）：

// ❌ WRONG - fails with INSUFFICIENT_TX_FEE
(int rc, address token) = createNonFungibleToken(token);

// ✅ CORRECT
(int rc, address token) = createNonFungibleToken{value: msg.value}(token);

从 TypeScript 调用：

await contract.createToken(name, symbol, {
  gasLimit: 350_000,
  value: ethers.parseEther("15"), // ~$1-2 USD of HBAR
});

代币密钥系统

七种密钥类型用于控制代币操作（keyType 字段的位位置）：

密钥	位	值	控制操作
ADMIN	0	1	更新代币、密钥和删除代币
KYC	1	2	授予/撤销 KYC
FREEZE	2	4	冻结/解冻账户
WIPE	3	8	清除余额
SUPPLY	4	16	铸造/销毁
FEE	5	32	更新费用
PAUSE	6	64	暂停所有操作

使用 KeyHelper 构造密钥：

keys[0] = getSingleKey(KeyType.SUPPLY, KeyValueType.CONTRACT_ID, address(this));

有关密钥值类型和 JSON 元组格式，请参阅 references/keys.md。

关联模型

账户必须先与代币关联，才能接收代币：

int rc = associateToken(accountAddress, tokenAddress);
require(
    rc == HederaResponseCodes.SUCCESS ||
    rc == HederaResponseCodes.TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT,
    "Association failed"
);

常见模式

创建可替代代币

function createToken() external payable {
    IHederaTokenService.HederaToken memory token;
    token.name = "My Token";
    token.symbol = "MTK";
    token.treasury = address(this);
    token.expiry = createAutoRenewExpiry(address(this), 7776000); // 90 days

    (int rc, address created) = createFungibleToken{value: msg.value}(
        token, 1000000, 18  // initialSupply, decimals
    );
    require(rc == HederaResponseCodes.SUCCESS, "Create failed");
}

可铸造的 NFT 系列

function createNFT() external payable {
    IHederaTokenService.HederaToken memory token;
    token.name = "My NFT";
    token.symbol = "MNFT";
    token.treasury = address(this);
    token.tokenSupplyType = true;  // FINITE
    token.maxSupply = 10000;

    IHederaTokenService.TokenKey[] memory keys = new IHederaTokenService.TokenKey[](1);
    keys[0] = getSingleKey(KeyType.SUPPLY, KeyValueType.CONTRACT_ID, address(this));
    token.tokenKeys = keys;
    token.expiry = createAutoRenewExpiry(address(this), 7776000);

    (int rc, address created) = createNonFungibleToken{value: msg.value}(token);
    require(rc == HederaResponseCodes.SUCCESS, "Create failed");
}

function mintNFT(bytes memory metadata) external {
    bytes[] memory metas = new bytes[](1);
    metas[0] = metadata;
    (int rc, , int64[] memory serials) = mintToken(tokenAddress, 0, metas);
    require(rc == HederaResponseCodes.SUCCESS, "Mint failed");
}

启用 KYC 的代币

创建后，财库账户必须自行授予 KYC：

// After token creation with KYC key
int kycRc = grantTokenKyc(tokenAddress, address(this));
require(kycRc == HederaResponseCodes.SUCCESS, "Self-KYC failed");

响应代码处理

始终检查响应代码。SUCCESS = 22。

require(responseCode == HederaResponseCodes.SUCCESS, "Operation failed");

常见代码：请参阅 references/response-codes.md

更多参考资料

• API 参考：references/api.md - 所有函数签名
• 自定义费用：references/fees.md - 固定费用、分数费用、版税费用
• 合规控制：references/compliance.md - KYC、冻结、暂停详情
• 结构体定义：references/structs.md - HederaToken、Expiry 等
• 故障排除：references/troubleshooting.md - 常见错误及解决方法