Hedera Token Service (HTS)
DRAFT Notes - please feel free to comment / suggest edits
Token class vs instance
The term "token" can be confusing as it has at least 2 possible meanings depending on the context:
to "create" a new token means to create a new token class eg "Citi USD Stablecoin" backed 1:1 with USD held by Citi in a fiat bank account
to "mint" a new token is like minting coins, eg an actual $1 that you can trade with. This is called a Token instance in IWA token taxonomy
"A token instance is an owned token of a particular class. Depending on the platform how this notion is actually implemented will vary. Instances of a token that you may own, or have in your digital wallet, represent your account balance of that token class."
The token ID is the unique identifier for a token class.
It uses the same format as any Hedera entity (account, file, topic, contract)
eg 0.0.12345 (shard.realm.account)
Create a token [class]
A token [class] comprises a number of attributes:
Admin key if assigned, allows almost all attributes to be updated
Name and symbol (each upto 100 chars) this might be used to reference externally stored meta-data
Memo a short publicly visible memo about the token
decimals how much can the token be divided (this can't be updated)
Treasury account, holds the supply of token instances
Supply key if assigned, allows treasury tokens to be minted or burned
Initial supply (optional) how many token instances to mint initially
KYC key if assigned, controls the KYC status of accounts
Freeze key if assigned, controls the freeze status of accounts
Default freeze status - if set to 'frozen' then accounts must be unfrozen before they can transaction with the token.
Wipe key If assigned, can remove any number of token instances from any accounts.
HIP-17 NFT (released September 2021)
Token Type - Fungible Common (each instance is identical) or Non Fungible Unique (each instance is uniquely identified by a serial number)
Note: a token can be "Fungible Common" but still have uniquely identifiable instances defined by a layer 2 solution, such as GoMint launch May 2021
Max Supply - maximum number of instances that can be minted
Supply Type - fixed or infinite
HIP-18 custom fees (released September 2021)
Fee Schedule Key If assigned, allows the holder to update any custom fees assigned to the token
Custom fees - rules or fixed, fractional, or royalty fees can optionally be attached and are applied automatically when a token is transferred
Other - released September 2021
Pause key - similar to Freeze, except it applies to all token instances, wherever they are
As for all Hedera entities, there is the cost of maintaining the token on the Hedera network. This is managed with 3 attributes:
Expiration time - when the token will last until
Renewal account - the account that will pay for renewal
Renewal frequency - how often the renewal charge will be taken
Update a token [class]
If a token does not have an admin key then the token is immutable, both in terms of attributes and supply. Otherwise, apart from decimals, all attributes can be updated.
Associate token [class] to an account
By default, no account can receive any token unless the account owner has approved this. The account owner does this by signing a transaction that associates a token to their account. They can also reverse this (dissociate).
This prevents Air drops and helps accounts holders in meeting any regulatory requirements.
Transfer token [instances]
Transfer tokens between accounts. This can be a simple transfer of one token, or a multi-token, multi-party atomic swap.
eg Alice has 30 apples, Bob has 30 bananas, Carol has 30 carrots. They can agree to swap their tokens to end up with 10 each of each type of fruit or veg, all in one transaction. If any party does not sign then the whole agreement is voided.
Mint & Burn
If the token class has a 'supply key' then new token instances can be minted into the treasury account, or removed (burnt)
Freeze & KYC [token class]
Both of these features are optional and only apply if Freeze or KYC keys are assigned, respectively. An account which is frozen or does not have KYC (for the given token class) cannot send or receive tokens. Technically the functions are similar but are managed via separate keys, so for example KYC might be delegated to a 3rd party
A combination of these attributes, along with Hedera multi-sig capability, creates some interesting possibilities…..
IWA token taxonomy
Token class vs instance
What is an NFT?