Standard Details
Last updated
Last updated
The HCS-20 standard is designed to leverage the Hedera Consensus Service (HCS) for creating, managing, and transferring auditable ownership of points. It utilizes topic IDs on the Hedera network to record JSON-encoded transactions, providing a framework for a auditable pointing system.
There are two major ways to use this standard.
Submit Key
A topic ID with a submit key allows control of all data posted to that topic. This is great for most use cases like gaming, leaderboard points, loyalty points, etc.
Valid transaction indexing note:
Indexers of topic Ids with submit keys shouldn't require the payer account id to be the same as the one moving balances. Since the submit key requirement implies only authorized parties should have write access to move funds, all transfer transactions written are authorized.
No Submit Key
A topic ID with no submit key allows anyone to sign and write transaction openly to the public topic Id. Creators can make their own topic ids, or can use the proposed main topic id.
Benefits of using the main public topic Id is to give access to a central location of all inscriptions for HCS-20 public points where indexers don't need to index multiple topic Ids for balances.
Valid transaction indexing note:
Indexing valid balances also includes checking if the payer account id is the same as the transfer of balance out of an account. If payer account is different than the account having points removed, it's indexed as a failed transaction.
Proposed main public topic Id:
Deploy Point Contract: Initialize a new point asset on the network.
Mint Point: Create new points and assign them to a recipient.
Burn Point: Permanently remove a specified number of points from circulation.
Transfer Point: Move points from one account to another.
The state (such as balances) of HCS-20 points is determined by aggregating the activities of deploy, mint, and transfer operations inscribed onto the HCS topic IDs.
Deployments initialize the point contract without directly affecting state.
Mints add to the balance of the first owner specified in the mint operation.
Transfers adjust balances by deducting from the sender and crediting for the receiver.
Frontend applications can interact with the HCS-20 standard by submitting the JSON operations to specified topic IDs on the Hedera network and reading the state from these topics.
Deploying a Point Contract: Optionally create your own point asset by inscribing a deploy operation.
Minting Points: Mint new points by inscribing the mint operation with the specified amount and recipient.
Transferring Points: Transfer points by inscribing the transfer operation with the relevant details.
A transfer is valid if the amount does not exceed the available balance at the time of inscription.
A mint is valid if the amount does not exceed the max supply of the asset at the time of inscription & that the amount minted is less than or equal to lim set on the deploy operation.
The order of transactions is by consensus timestamp for determining validity.
Payer account id has to be the same as the account having points removed from it's balance if the topic ID has no submit key
Common Attributes:
p: Protocol identifier (required).
op: Operation type (required).
tick: Unique identifier for the point (required).
m: Memo field for additional information (optional).
Attributes Table:
p
Yes
Protocol identifier, specifies HCS-20
op
Yes
Operation type, here it's 'deploy'
name
Yes
Name of the point, describes the asset being created
tick
Yes
Unique identifier for the point, akin to a ticker symbol
max
Yes
Maximum supply of the point, sets the upper limit
lim
No
Limit per transaction for minting, optional
metadata
No
Optional additional data related to the points (HIP-412 standard)
m
No
Optional additional memo related to the operation
Attributes Table:
p
Yes
Protocol identifier, specifies HCS-20
op
Yes
Operation type, here it's 'mint'
tick
Yes
Unique identifier of the point to be minted
amt
Yes
Amount of points to mint
to
Yes
Address of the recipient receiving the minted points
m
No
Optional additional memo related to the operation
Attributes Table:
p
Yes
Protocol identifier, specifies HCS-20
op
Yes
Operation type, here it's 'burn'
tick
Yes
Unique identifier of the point to be burned
amt
Yes
Amount of points to burn
from
Yes
Address of the holder from whom points are being burned
m
No
Optional additional memo related to the operation
Attributes Table:
p
Yes
Protocol identifier, specifies HCS-20
op
Yes
Operation type, here it's 'transfer'
tick
Yes
Unique identifier of the point to be transferred
amt
Yes
Amount of points to transfer
from
Yes
Address of the sender
to
Yes
Address of the recipient
m
No
Optional additional memo related to the operation
For the field validation section of the HCS-20 standard documentation, it's essential to clearly define the structure and rules that each field must adhere to. Based on the provided Zod schemas, here's a breakdown of the validation for each field in the context of different operation types:
Protocol Identifier (p)
Type: String
Requirement: Required
Validation: Must be 'hcs-20', case insensitive.
Operation Type (op)
Type: String
Requirement: Required
Validation: Must be one of the following: 'deploy', 'mint', 'burn', 'transfer', 'register', case insensitive.
Memo (memo)
Type: String
Requirement: Optional
Validation: Any string value is accepted.
Number Field (amount, max, lim)
Type: String representing a number
Requirement: Depends on the context
Validation: Must be a valid number. The string length must be less than or equal to 18 characters. If conversion to a number fails, it defaults to 0.
Account Field (toAddress, fromAddress, topicId)
Type: String
Requirement: Depends on the context
Validation: Must match the regex pattern ^(0|(?:[1-9]\d*))\.(0|(?:[1-9]\d*))\.(0|(?:[1-9]\d*))(?:-([a-z]{5}))?$. If the field includes a hyphen (-), only the part before the hyphen is considered.
Name
Type: String
Requirement: Required
Validation: Must be between 1 and 100 characters in length.
Topic ID
Uses accountFieldSchema for validation.
Metadata
Type: String
Requirement: Optional
Validation: Any string value is accepted.
Ticker Symbol (tick)
Type: String
Requirement: Required
Validation: Must be a string, converted to lowercase, and whitespace trimmed.
Amount
Uses numberFieldSchema for validation.
From Address
Uses accountFieldSchema for validation.
Ticker Symbol (tick)
Same validation as in Burn Operation.
Name
Same validation as in Register Operation.
Maximum Supply (max)
Uses numberFieldSchema for validation but defaults to Infinity if not provided.
Limit per Mint (lim)
Uses numberFieldSchema for validation but defaults to Infinity if not provided.
Metadata
Same validation as in Register Operation.
Ticker Symbol (tick)
Same validation as in Burn Operation.
Amount
Uses numberFieldSchema for validation.
To Address
Uses accountFieldSchema for validation.
Ticker Symbol (tick)
Same validation as in Burn Operation.
Amount
Uses numberFieldSchema for validation.
To Address
Uses accountFieldSchema for validation.
From Address
Uses accountFieldSchema for validation.
Ensure that these field validation rules are communicated clearly in your documentation to prevent invalid transactions and ensure smooth operation of the HCS-20 standard.
You must use Hedera-compatible wallets to pay to inscribe currently.
The mint and transfer operations are the only ones that cause a change in balance.
Turtle Moon wants to help build the future of innovation on Hedera so we've created these tools for our own project and are open sourcing them to the community to help expedite the growth and speed of HCS-20's on Hedera.
This codebase is in ALPHA, meaning there are a lot of bugs that are still needing to be fixed and enhancements to be integrated. USE AT YOUR OWN RISK. This software is provided as is and Turtle Moon is not responsible for any issues using the software.
The Indexer will be updated periodically and the way transactions are calculated may change as the standard matures.
No points are intended to have any value.
v0.0.2
