# Standard Details ### Idea 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. #### Private [✅ ](https://emojipedia.org/check-mark-button)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. #### Public [❌](https://emojipedia.org/cross-mark) 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:**\ [0.0.4350190](https://hashscan.io/mainnet/topic/0.0.4350190) #### Operations * **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. #### State Calculation 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 Implementation 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. #### How to Use HCS-20 1. **Deploying a Point Contract**: \ Optionally create your own point asset by inscribing a deploy operation. 2. **Minting Points**: \ Mint new points by inscribing the mint operation with the specified amount and recipient. 3. **Transferring Points**: \ Transfer points by inscribing the transfer operation with the relevant details. ### Validity of Transactions * 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** ## JSON Structure **Common Attributes:** * `p`: Protocol identifier (required). * `op`: Operation type (required). * `tick`: Unique identifier for the point (required). * `m`: Memo field for additional information (optional). ### Deploy Points ```json { "p": "hcs-20", "op": "deploy", "name": "point_name", "tick": "unique_point_identifier", "max": "max_supply", "lim": "optional_limit_of_mint_per_transaction", "metadata": "optional_metadata", "m": "optional_memo" } ``` **Attributes Table:** | Key | Required | Description | | ---------- | -------- | ----------------------------------------------------------------- | | `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 | ### Mint Points ```json { "p": "hcs-20", "op": "mint", "tick": "unique_point_identifier", "amt": "number_of_points", "to": "recipient_hedera_address", "m": "optional_memo" } ``` **Attributes Table:** | Key | Required | Description | | ------ | -------- | ---------------------------------------------------- | | `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 | ### Burn Points ```json { "p": "hcs-20", "op": "burn", "tick": "unique_point_identifier", "amt": "number_of_points", "from": "holder_hedera_address", "m": "optional_memo" } ``` **Attributes Table:** | Key | Required | Description | | ------ | -------- | ------------------------------------------------------- | | `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 | ### Transfer Points ```json { "p": "hcs-20", "op": "transfer", "tick": "unique_point_identifier", "amt": "number_of_points", "from": "sender_hedera_address", "to": "recipient_hedera_address", "m": "optional_memo" } ``` **Attributes Table:**
KeyRequiredDescription
pYesProtocol identifier, specifies HCS-20
opYesOperation type, here it's 'transfer'
tickYesUnique identifier of the point to be transferred
amtYesAmount of points to transfer
fromYesAddress of the sender
toYesAddress of the recipient
mNoOptional additional memo related to the operation
## **Field validation** 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: #### Common Fields Validation (For All Messages) 1. **Protocol Identifier (p)** * Type: String * Requirement: Required * Validation: Must be 'hcs-20', case insensitive. 2. **Operation Type (op)** * Type: String * Requirement: Required * Validation: Must be one of the following: 'deploy', 'mint', 'burn', 'transfer', 'register', case insensitive. 3. **Memo (memo)** * Type: String * Requirement: Optional * Validation: Any string value is accepted. #### Number Field (Used in Various Operations) * **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 (Used in Various Operations) * **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. #### Register Operation * **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. #### Burn Operation * **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. #### Deploy Operation * **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. #### Mint Operation * **Ticker Symbol (tick)** * Same validation as in Burn Operation. * **Amount** * Uses `numberFieldSchema` for validation. * **To Address** * Uses `accountFieldSchema` for validation. #### Transfer Operation * **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. #### Important Notes * 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. ## HCS-20 Tool - Open Sourced 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.
#### WARNING #### THIS IS IN ALPHA 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.* #### Github Link: {% embed url="" %} ## HCS-20 Tool Downloads **v0.0.2** ### Mac {% embed url="" %} ### Windows X64 {% embed url="" %} ### Linux {% embed url="" %}