사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/hedera-dev/hedera-skills --skill hts-system-contract시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Hedera Token Service (HTS) System Contract
HTS precompile at 0x167 enables Solidity contracts to create and manage Hedera-native tokens with built-in compliance controls (KYC, freeze, pause) and custom fees.
Quick Reference
Imports:
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";Safe variants (auto-revert on failure): SafeHTS.sol, SafeViewHTS.sol
Critical: HBAR Payment Required
Token creation requires explicit HBAR value payment (not just gas):
// ❌ WRONG - fails with INSUFFICIENT_TX_FEE
(int rc, address token) = createNonFungibleToken(token);
// ✅ CORRECT
(int rc, address token) = createNonFungibleToken{value: msg.value}(token);Call from TypeScript:
await contract.createToken(name, symbol, {
gasLimit: 350_000,
value: ethers.parseEther("15"), // ~$1-2 USD of HBAR
});Token Key System
Seven key types control token operations (bit positions for keyType field):
| Key | Bit | Value | Controls |
|---|---|---|---|
| ADMIN | 0 | 1 | Update token, keys, deletion |
| KYC | 1 | 2 | Grant/revoke KYC |
| FREEZE | 2 | 4 | Freeze/unfreeze accounts |
| WIPE | 3 | 8 | Wipe balances |
| SUPPLY | 4 | 16 | Mint/burn |
| FEE | 5 | 32 | Update fees |
| PAUSE | 6 | 64 | Pause all operations |
Use KeyHelper for key construction:
keys[0] = getSingleKey(KeyType.SUPPLY, KeyValueType.CONTRACT_ID, address(this));See references/keys.md for key value types and JSON tuple format.
Association Model
Accounts must associate with tokens before receiving them:
int rc = associateToken(accountAddress, tokenAddress);
require(
rc == HederaResponseCodes.SUCCESS ||
rc == HederaResponseCodes.TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT,
"Association failed"
);Common Patterns
Fungible Token Creation
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");
}Mintable NFT Collection
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-Enabled Token
Treasury must self-grant KYC after creation:
// After token creation with KYC key
int kycRc = grantTokenKyc(tokenAddress, address(this));
require(kycRc == HederaResponseCodes.SUCCESS, "Self-KYC failed");Response Code Handling
Always check response codes. SUCCESS = 22.
require(responseCode == HederaResponseCodes.SUCCESS, "Operation failed");Common codes: See references/response-codes.md
Additional References
- API Reference: references/api.md - All function signatures
- Custom Fees: references/fees.md - Fixed, fractional, royalty fees
- Compliance Controls: references/compliance.md - KYC, freeze, pause details
- Struct Definitions: references/structs.md - HederaToken, Expiry, etc.
- Troubleshooting: references/troubleshooting.md - Common errors and fixes

