Resources
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."
https://www.github.com/InterWorkAlliance/TokenTaxonomyFramework/tree/main/token-taxonomy.md
Token ID
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…..
Appendix
Hedera documentation
https://docs.hedera.com/guides/docs/sdks/tokens
IWA token taxonomy
https://www.github.com/InterWorkAlliance/TokenTaxonomyFramework/tree/main/token-taxonomy.md
Discord discussions
Token class vs instance
https://discord.com/channels/373889138199494658/768621337865486347/811900888733712416
What is an NFT?
https://discord.com/channels/373889138199494658/768621337865486347/827119136617791528
