🗒️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

✅ 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

❌ 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

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

{
  "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

{
  "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

{
  "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

{
  "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:

Key	Required	Description
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

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:

https://github.com/HGraph-Punks/hcs-20-toolkitgithub.com

HCS-20 Tool Downloads

v0.0.2

Mac

Turtle Moon HCS Toolkit-0.0.2.dmgGoogle Docs

Windows X64

Turtle Moon HCS Toolkit Setup 0.0.2.exeGoogle Docs

Linux

Turtle Moon HCS Toolkit-0.0.2.AppImageGoogle Docs