From 9aef4901de0a171cb5c1fc7dc52b595bed2c06ff Mon Sep 17 00:00:00 2001 From: Michael Kantor <6068672+kantorcodes@users.noreply.github.com> Date: Fri, 28 Jun 2024 12:33:17 -0400 Subject: [PATCH 1/5] feat: wip smart hashinals --- docs/standards/hcs-7.md | 157 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 docs/standards/hcs-7.md diff --git a/docs/standards/hcs-7.md b/docs/standards/hcs-7.md new file mode 100644 index 0000000..0b6342d --- /dev/null +++ b/docs/standards/hcs-7.md @@ -0,0 +1,157 @@ +# HCS-7 Standard: Smart Hashinals + +### Status: Draft + +### Table of Contents + +- [HCS-7 Standard: Smart Hashinals](#hcs-7-standard-smart-hashinals) + - [Status: Draft](#status-draft) + - [Table of Contents](#table-of-contents) + - [Authors](#authors) + - [Abstract](#abstract) + - [Motivation](#motivation) + - [Specification](#specification) + - [Creating an HCS-7 Topic ID](#creating-an-hcs-7-topic-id) + - [Metadata](#metadata) + - [Submitting Messages](#submitting-messages) + - [Validation](#validation) + - [Rendering](#rendering) + - [Examples](#examples) + - [Limitations](#limitations) + - [Conclusion](#conclusion) + +## Authors + +- Kantorcodes [https://twitter.com/kantorcodes]() + +## Abstract + +This standard is a sub-standard of [HCS-6](./hcs-6.md) which introduces a way to inscribe and tokenize **Hashinals** whose `metadata` can be updated at a whim by utilizing an indexed Topic ID whose current sequence number is determined by calling a public smart contract method. + +## Motivation + +HCS-6 introduced a novel way of updating metadata of a Hashinal dynamically by registering new sequence numbers. Some use-cases require switching between metadata rapidly or based on programmatic conditions. For example: + +- Time of day +- When experience points in-game drop increase to a certain point +- When price of an asset changes + +## Specification + +HCS-6 is largely built on top of [HCS-6](./hcs-6.md) which describes how Dynamic Hashinals work. Please read that document for further clarity. + +**Smart Hashinals** follow the same steps for tokenization. + +### Creating an HCS-7 Topic ID + +The `memo` field for Smart Hashinals must follow this format to be valid. + +``hcs-7:indexed:{ttl}` + +The only variable element in the memo would be the `ttl` field. We suggest a longer `ttl` as this is the time in seconds that gateways and clients will store the previous version of your `metadata` in their cache. In the future, gateways and clients may decide to prioritize Topics with longer `metadata` by imposing fees, introducing rate limits, etc. The minimum `ttl` must be `3600` (1 hour) to be valid, and the suggested minimum would be `86400` (1 day) + +### Metadata + +Smart **Hashinals** follow all of the same rules described in [HCS-5](./hcs-5.md), with one main exception being that they will utilize the `HCS-7` hcsStandard instead of `HCS-1`. The resulting [HRL](../definitions.md) minted onto a serial number includes the protocol number `7` + +The format of the `metadata` on a dynamic **Hashinal** is as follows: + +`hcs://7/{topicId}` + +`topicId` is a valid HCS-7 Registry Topic ID in which data for this NFT will be or is written to. + +### Submitting Messages + +Unlike HCS-6, HCS-7 messages are `indexed`, which means that the current metadata is not determined by the latest sequence number. This also affords some flexibility in ordering of messages, and the ability to update sequences if required in the future. + +A valid HCS-7 Topic Id, should have registered HCS-1 topics to choose from, and an initial registered configuration message with a memo of "config". + +Registering config follows this format: + +```json +{ + "p": "hcs-7", + "op": "register", + // the HCS-1 Topic ID + "c": { + "m": "run", + "abi": { + "constant": false, + "inputs": [ + { + "name": "accountId", + "type": "address" + } + ], + "name": "run", + "outputs": [ + { + "name": "result", + "type": "uint256" + } + ], + "outputs": [] + } + }, + "m": "config" +} +``` + +The smart contract function must be public, and not mutate state(nonpayable) or the Smart Hashinal will not render. To reduce message size, `payable`, `stateMutability`, and `type` fields should be excluded. This is to ensure that execution is free. + +These excluded fields are assumed to have the following defaults when calling the method: + +```json +{ "payable": false, "stateMutability": "nonpayable", "type": "function" } +``` + +| Field | Description | +| ------------------- | --------------------------------------------------------------- | +| `p` | Protocol identifier, here it is "hcs-7". | +| `op` | Operation type, here it is "register". | +| `c` | Configuration object containing method details. | +| `c.m` | Method name, here it is "run". | +| `c.abi` | ABI definition for the method. | +| `c.abi.constant` | Indicates if the method is constant. | +| `c.abi.inputs` | Array of input parameters for the method. | +| `c.abi.inputs.name` | Name of the input parameter, here it is "accountId". | +| `c.abi.inputs.type` | Type of the input parameter, here it is "address". | +| `c.abi.name` | Method name, here it is "run". | +| `c.abi.outputs` | Array of output parameters for the method (empty in this case). | +| `m` | Memo field for the message, here it is "config". | + +Registering valid HCS-1 Topics to choose from follows this format: + +```json +{ + "p": "hcs-7", + "op": "register", + // the HCS-1 Topic ID + "t_id": "0.0.12345", + "m": "Version 1" +} +``` + +### Validation + +Dynamic **Hashinals** are only valid when + +- Their HCS-7 Topic ID is `indexed` +- Valid [HCS-1 Topic IDs](./hcs-1.md) are registered with a `t_id` field +- They specify a `ttl` that is at least `3600` (1 hour) +- It is created after `TBD` nanosecond timestamp + +### Rendering + +Unlike HCS-6, the latest Sequence Number does not determine which metadata to display. Instead, the output of calling the ABI described in the `configuration` message would return an Integer that maps to a sequence number to choose from. + +### Examples + TBD example smart contract implementations + +### Limitations + +Smart Hashinals must utilize smart contracts with a public, nonpayable method that other platforms can call to determine the current sequence number for execution. Calls that require payment will not be valid. + +### Conclusion + +TBD From 97d3a3a6ab9eef739454ec818bc4018dc72b1dcb Mon Sep 17 00:00:00 2001 From: Michael Kantor <6068672+kantorcodes@users.noreply.github.com> Date: Fri, 28 Jun 2024 12:33:50 -0400 Subject: [PATCH 2/5] feat: wip smart hashinals --- docs/standards/hcs-7.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/standards/hcs-7.md b/docs/standards/hcs-7.md index 0b6342d..43323d4 100644 --- a/docs/standards/hcs-7.md +++ b/docs/standards/hcs-7.md @@ -72,7 +72,6 @@ Registering config follows this format: { "p": "hcs-7", "op": "register", - // the HCS-1 Topic ID "c": { "m": "run", "abi": { From 02fb6675815fd95ed10efcea396db14e3d58cab2 Mon Sep 17 00:00:00 2001 From: Michael Kantor <6068672+kantorcodes@users.noreply.github.com> Date: Fri, 28 Jun 2024 12:39:01 -0400 Subject: [PATCH 3/5] feat: wip smart hashinals --- docs/standards/hcs-7.md | 36 +++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/standards/hcs-7.md b/docs/standards/hcs-7.md index 43323d4..ab5eaf7 100644 --- a/docs/standards/hcs-7.md +++ b/docs/standards/hcs-7.md @@ -14,6 +14,7 @@ - [Creating an HCS-7 Topic ID](#creating-an-hcs-7-topic-id) - [Metadata](#metadata) - [Submitting Messages](#submitting-messages) + - [Configuration Message](#configuration-message) - [Validation](#validation) - [Rendering](#rendering) - [Examples](#examples) @@ -96,9 +97,25 @@ Registering config follows this format: } ``` -The smart contract function must be public, and not mutate state(nonpayable) or the Smart Hashinal will not render. To reduce message size, `payable`, `stateMutability`, and `type` fields should be excluded. This is to ensure that execution is free. +Registering valid HCS-1 Topics to choose from follows this format: + +```json +{ + "p": "hcs-7", + "op": "register", + // the HCS-1 Topic ID + "t_id": "0.0.12345", + "m": "Version 1" +} +``` + +### Configuration Message + +The ABI provided to the configuration must be public, and not mutate state(nonpayable) or the Smart Hashinal will not render. + +To reduce message size, `payable`, `stateMutability`, and `type` fields should be excluded from the JSON. -These excluded fields are assumed to have the following defaults when calling the method: +To ensure execution is free, these excluded fields are assumed to have the following defaults when calling the method. ```json { "payable": false, "stateMutability": "nonpayable", "type": "function" } @@ -119,18 +136,6 @@ These excluded fields are assumed to have the following defaults when calling th | `c.abi.outputs` | Array of output parameters for the method (empty in this case). | | `m` | Memo field for the message, here it is "config". | -Registering valid HCS-1 Topics to choose from follows this format: - -```json -{ - "p": "hcs-7", - "op": "register", - // the HCS-1 Topic ID - "t_id": "0.0.12345", - "m": "Version 1" -} -``` - ### Validation Dynamic **Hashinals** are only valid when @@ -145,7 +150,8 @@ Dynamic **Hashinals** are only valid when Unlike HCS-6, the latest Sequence Number does not determine which metadata to display. Instead, the output of calling the ABI described in the `configuration` message would return an Integer that maps to a sequence number to choose from. ### Examples - TBD example smart contract implementations + +TBD example smart contract implementations ### Limitations From fbe556f19e8ea0b19d4290bf534de3fb3d92d551 Mon Sep 17 00:00:00 2001 From: Michael Kantor <6068672+kantorcodes@users.noreply.github.com> Date: Fri, 28 Jun 2024 12:42:49 -0400 Subject: [PATCH 4/5] feat: wip smart hashinals --- docs/standards/hcs-7.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/standards/hcs-7.md b/docs/standards/hcs-7.md index ab5eaf7..cff1ac1 100644 --- a/docs/standards/hcs-7.md +++ b/docs/standards/hcs-7.md @@ -37,9 +37,11 @@ HCS-6 introduced a novel way of updating metadata of a Hashinal dynamically by r - When experience points in-game drop increase to a certain point - When price of an asset changes +These kinds of use cases, while possible with HCS-6, would require submitting many messages to the Topic Id. HCS-7, through trustless, programmatic, verifiable execution solves for this. + ## Specification -HCS-6 is largely built on top of [HCS-6](./hcs-6.md) which describes how Dynamic Hashinals work. Please read that document for further clarity. +HCS-7 is largely built on top of [HCS-6](./hcs-6.md) which describes how Dynamic Hashinals work. Please read that document for further clarity. **Smart Hashinals** follow the same steps for tokenization. From 92711da682ed051481ab797922c6b8c3756f242e Mon Sep 17 00:00:00 2001 From: Michael Kantor <6068672+kantorcodes@users.noreply.github.com> Date: Fri, 28 Jun 2024 14:14:16 -0400 Subject: [PATCH 5/5] feat: wip smart hashinals --- docs/standards/hcs-7.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/standards/hcs-7.md b/docs/standards/hcs-7.md index cff1ac1..6a94fab 100644 --- a/docs/standards/hcs-7.md +++ b/docs/standards/hcs-7.md @@ -76,7 +76,6 @@ Registering config follows this format: "p": "hcs-7", "op": "register", "c": { - "m": "run", "abi": { "constant": false, "inputs": [ @@ -127,8 +126,7 @@ To ensure execution is free, these excluded fields are assumed to have the follo | ------------------- | --------------------------------------------------------------- | | `p` | Protocol identifier, here it is "hcs-7". | | `op` | Operation type, here it is "register". | -| `c` | Configuration object containing method details. | -| `c.m` | Method name, here it is "run". | +| `c` | Configuration object containing method details. | `c.abi` | ABI definition for the method. | | `c.abi.constant` | Indicates if the method is constant. | | `c.abi.inputs` | Array of input parameters for the method. | @@ -136,11 +134,11 @@ To ensure execution is free, these excluded fields are assumed to have the follo | `c.abi.inputs.type` | Type of the input parameter, here it is "address". | | `c.abi.name` | Method name, here it is "run". | | `c.abi.outputs` | Array of output parameters for the method (empty in this case). | -| `m` | Memo field for the message, here it is "config". | +| `m` | Should always be "config" | ### Validation -Dynamic **Hashinals** are only valid when +Smart **Hashinals** are only valid when - Their HCS-7 Topic ID is `indexed` - Valid [HCS-1 Topic IDs](./hcs-1.md) are registered with a `t_id` field