CIP-0067 | Asset Name Label Registry

CIP-0067/README.md

@@ -0,0 +1,128 @@
+---
+CIP: 67
+Title: Asset Name Label Registry
+Authors: Alessandro Konrad <alessandro.konrad@live.de>, Thomas Vellekoop <thomas.vellekoop@iohk.io>
+Status: Draft
+Type: Informational
+Created: 2022-07-13
+License: CC-BY-4.0
+---
+
+## Abstract
+
+This proposal defines a standard to classify Cardano native assets by the asset name.
+
+## Motivation
+
+As more assets are minted and different standards emerge to query data for these assets, it's getting harder for 3rd parties to determine the asset type and how to proceed with it. This standard is similar to [CIP-0010](../CIP-0010), but focuses on the asset name of an asset.
+
+
+## Specification
+
+To classify assets the `asset_name` needs to be prefixed the following `4 bytes` binary encoding:
+```
+[ 0000 | 2 bytes label_num | 1 byte checksum | 0000 ]
+```
+- The leading and ending four 0s are brackets
+- `label_num` has a fixed size of 2 bytes (`Label range in decimal: [0, 65535]`). 
+If `label_num` < 2 bytes the remaining bits need to be padded with 0s.
+- `checksum` has a fixed size of 1 byte. The checksum is calculated by applying the [CRC-8](#CRC-8) algorithm on the `label_num (including the padded 0s)`. 
+
+### CRC-8
+
+- Check: `0xF4`
+- Poly: `0x07`
+- Init: `0x00`
+- RefIn: `false`
+- RefOut: `false`
+- XorOut: `0x00`
+- Lookup table:
+```
+[
+  0x00, 0x07, 0x0e, 0x09, 0x1c, 0x1b, 0x12, 0x15, 0x38, 0x3f, 0x36, 0x31, 0x24,
+  0x23, 0x2a, 0x2d, 0x70, 0x77, 0x7e, 0x79, 0x6c, 0x6b, 0x62, 0x65, 0x48, 0x4f,
+  0x46, 0x41, 0x54, 0x53, 0x5a, 0x5d, 0xe0, 0xe7, 0xee, 0xe9, 0xfc, 0xfb, 0xf2,
+  0xf5, 0xd8, 0xdf, 0xd6, 0xd1, 0xc4, 0xc3, 0xca, 0xcd, 0x90, 0x97, 0x9e, 0x99,
+  0x8c, 0x8b, 0x82, 0x85, 0xa8, 0xaf, 0xa6, 0xa1, 0xb4, 0xb3, 0xba, 0xbd, 0xc7,
+  0xc0, 0xc9, 0xce, 0xdb, 0xdc, 0xd5, 0xd2, 0xff, 0xf8, 0xf1, 0xf6, 0xe3, 0xe4,
+  0xed, 0xea, 0xb7, 0xb0, 0xb9, 0xbe, 0xab, 0xac, 0xa5, 0xa2, 0x8f, 0x88, 0x81,
+  0x86, 0x93, 0x94, 0x9d, 0x9a, 0x27, 0x20, 0x29, 0x2e, 0x3b, 0x3c, 0x35, 0x32,
+  0x1f, 0x18, 0x11, 0x16, 0x03, 0x04, 0x0d, 0x0a, 0x57, 0x50, 0x59, 0x5e, 0x4b,
+  0x4c, 0x45, 0x42, 0x6f, 0x68, 0x61, 0x66, 0x73, 0x74, 0x7d, 0x7a, 0x89, 0x8e,
+  0x87, 0x80, 0x95, 0x92, 0x9b, 0x9c, 0xb1, 0xb6, 0xbf, 0xb8, 0xad, 0xaa, 0xa3,
+  0xa4, 0xf9, 0xfe, 0xf7, 0xf0, 0xe5, 0xe2, 0xeb, 0xec, 0xc1, 0xc6, 0xcf, 0xc8,
+  0xdd, 0xda, 0xd3, 0xd4, 0x69, 0x6e, 0x67, 0x60, 0x75, 0x72, 0x7b, 0x7c, 0x51,
+  0x56, 0x5f, 0x58, 0x4d, 0x4a, 0x43, 0x44, 0x19, 0x1e, 0x17, 0x10, 0x05, 0x02,
+  0x0b, 0x0c, 0x21, 0x26, 0x2f, 0x28, 0x3d, 0x3a, 0x33, 0x34, 0x4e, 0x49, 0x40,
+  0x47, 0x52, 0x55, 0x5c, 0x5b, 0x76, 0x71, 0x78, 0x7f, 0x6a, 0x6d, 0x64, 0x63,
+  0x3e, 0x39, 0x30, 0x37, 0x22, 0x25, 0x2c, 0x2b, 0x06, 0x01, 0x08, 0x0f, 0x1a,
+  0x1d, 0x14, 0x13, 0xae, 0xa9, 0xa0, 0xa7, 0xb2, 0xb5, 0xbc, 0xbb, 0x96, 0x91,
+  0x98, 0x9f, 0x8a, 0x8d, 0x84, 0x83, 0xde, 0xd9, 0xd0, 0xd7, 0xc2, 0xc5, 0xcc,
+  0xcb, 0xe6, 0xe1, 0xe8, 0xef, 0xfa, 0xfd, 0xf4, 0xf3,
+]
+```
+
+
+### Example:
+
+#### Construct a label
+We want to use the decimal label `222` for an asset name:
+
+1. Convert to hex and pad with missing 0s => `0x00de`
+2. Calculate CRC-8 checksum => `0x14`
+3. Add brackes and combine label => `0x000de140`
+
+#### Verify a label
+We have the following asset name: `0x000de140`
+
+1. Slice off the first 4 bytes of the asset name => `0x000de140`
+2. Check if first 4 bits and last 4 bits are `0b0000` (`0x0`)
+3. Slice of the 2 `label_num` bytes and apply them to the CRC-8 algorithm. If the result matches with the `checksum` byte a `valid` label was found and it can be returned. => `0x00de`
+4. Convert to decimal => `222`
+
+
+### Reserved labels
+
+These are the reserved `asset_name_label` values
+
+`asset_name_label`            | class | description              |
+----------------------------  | ----- |  ----------------------- |
+0 - 15                        | -     |  private use             |
+
+### Adding an entry to the registry
+
+To propose an addition to the registry edit the [registry.json](./registry.json) with your details, open a pull request against the CIPs repository and give a brief description of your project and how you intend to use the label for assets.
+
+## Rationale
+
+Asset name labels make it easy to classify assets. It's important to understand that an oblivious token issuer might use the prefix X for all kinds of things, leading to misinterpretation by clients that follow this standard. We can minimize this attack vector by making the label format obscure. Brackets, checksum and fixed size binary encoding make it unlikely someone follows this standard by accident.
+
+## Reference Implementation(s)
+
+- [Lucid TypeScript implementation of toLabel/fromLabel](https://github.com/spacebudz/lucid/blob/39cd2129101bd11b03b624f80bb5fe3da2537fec/src/utils/utils.ts#L500-L522)
+- [Lucid TypeScript implementation of CRC-8](https://github.com/spacebudz/lucid/blob/main/src/misc/crc8.ts)
+
+## Test Vectors
+
+Keys represent labels in `decimal` numbers. Values represent the entire label including brackets and checksum in `hex`:
+
+```yaml
+0     : 00000000
+1     : 00001070
+23    : 00017650
+99    : 000632e0
+533   : 00215410
+2000  : 007d0550
+4567  : 011d7690
+11111 : 02b670b0
+49328 : 0c0b0f40
+65535 : 0ffff240
+```
+
+## References
+
+- CIP-0010: https://github.com/cardano-foundation/CIPs/blob/master/CIP-0010
+
+## Copyright
+
+This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).

CIP-0067/registry.json

@@ -0,0 +1,12 @@
+[
+  {
+    "asset_name_label": 222,
+    "class": "NFT",
+    "description": "CIP-0068 - NFT Metadata Standard (222 sub standard)"
+  },
+  {
+    "asset_name_label": 333,
+    "class": "FT",
+    "description": "CIP-0068 - NFT Metadata Standard (333 sub standard)"
+  }
+]

CIP-0067/registry.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "https://cips.cardano.org/cips/cip67/registry.schema.json",
+  "type": "array",
+  "title": "Asset Name Label Registry",
+  "description": "JSON schema for asset name label registry",
+  "default": [],
+  "examples": [
+    [
+      {
+        "asset_name_label": 222,
+        "class": "NFT",
+        "description": "CIP-0068 - NFT Metadata Standard (222 sub standard)"
+      }
+    ]
+  ],
+  "additionalItems": false,
+  "items": {
+    "$id": "#/items",
+    "anyOf": [
+      {
+        "$id": "#/items/anyOf/0",
+        "type": "object",
+        "title": "The first anyOf schema",
+        "description": "An entry in the asset name label registry",
+        "default": {},
+        "examples": [
+          {
+            "asset_name_label": 222,
+            "class": "NFT",
+            "description": "CIP-0068 - NFT Metadata Standard (222 sub standard)"
+          }
+        ],
+        "required": ["asset_name_label", "class", "description"],
+        "properties": {
+          "asset_name_label": {
+            "$id": "#/items/anyOf/0/properties/asset_name_label",
+            "type": "integer",
+            "title": "The asset_name_label number",
+            "default": 0,
+            "examples": [222]
+          },
+          "class": {
+            "$id": "#/items/anyOf/0/properties/class",
+            "type": "string",
+            "title": "The asset class",
+            "default": "",
+            "examples": ["NFT", "FT", "SFT"]
+          },
+          "description": {
+            "$id": "#/items/anyOf/0/properties/description",
+            "type": "string",
+            "title": "The asset name label description",
+            "default": "",
+            "examples": ["CIP-0068 - NFT Metadata Standard (222 sub standard)"]
+          }
+        },
+        "additionalProperties": false
+      }
+    ]
+  }
+}