CIP-0067, CIP-0068 | Add Clarification for Edits and Modification (#586)

* Bump CIP-0068 version for RFT Clarify the use of version, introduce changelog. Fixes #520. * Changes to CIP-67 and CIP-68 to inform how, when, and why changes should be made to either CIP-67 or CIP-68 * fix a few grammar errors in 1 sentence of original document * fixing error in my error fix / clarification * * Minor grammatical and feedback updates. * Inclusion of an "extension_boilerplate.md" file for reference in subsequent PRs. * Update headers to current CIP-0001 format * Update CIP-0068/README.md Co-authored-by: Ryan Williams <[email protected]> * Update CIP-0067/README.md Co-authored-by: Ryan Williams <[email protected]> * Update CIP-0067/README.md Co-authored-by: Ryan Williams <[email protected]> * Changes to CIP-67 and CIP-68 to inform how, when, and why changes should be made to either CIP-67 or CIP-68 * fix a few grammar errors in 1 sentence of original document * fixing error in my error fix / clarification * * Minor grammatical and feedback updates. * Inclusion of an "extension_boilerplate.md" file for reference in subsequent PRs. * Update headers to current CIP-0001 format * Update CIP-0068/README.md Co-authored-by: Ryan Williams <[email protected]> --------- Co-authored-by: KtorZ <[email protected]> Co-authored-by: Robert Phair <[email protected]> Co-authored-by: Ryan Williams <[email protected]>
cardano-foundation · Nov 14, 2023 · de76120 · de76120
1 parent d6c5ad3
commit de76120
Show file tree

Hide file tree

Showing 5 changed files with 419 additions and 105 deletions.
diff --git a/CIP-0067/README.md b/CIP-0067/README.md
@@ -1,9 +1,14 @@
 ---
 CIP: 67
 Title: Asset Name Label Registry
-Authors: Alessandro Konrad <[email protected]>, Thomas Vellekoop <[email protected]>
 Status: Proposed
-Type: Informational
+Category: Tokens
+Authors: 
+  - Alessandro Konrad <[email protected]>
+  - Thomas Vellekoop <[email protected]>
+Implementors:
+Discussions:
+ - https://github.com/cardano-foundation/CIPs/pull/586
 Created: 2022-07-13
 License: CC-BY-4.0
 ---
@@ -18,13 +23,13 @@ As more assets are minted and different standards emerge to query data for these
 
 ## Specification
 
-To give issuers, the option to classify assets the `asset_name` needs to be prefixed the following `4 bytes` binary encoding:
+To give issuers the option to classify assets, the `asset_name` MUST be prefixed with 4 bytes encoding the following binary value:
 ```
 [ 0000 | 16 bits label_num | 8 bits 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 left-padded with 0s.
+If `label_num` < 2 bytes, the remaining bits MUST be left-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
@@ -79,28 +84,37 @@ We have the following asset name: `0x000de140`
 
 These are the reserved `asset_name_label` values
 
-`asset_name_label`            | class | description              |
-----------------------------  | ----- |  ----------------------- |
-0 - 15                        | -     |  private use             |
+| `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.
+> The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
+> NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
+> "OPTIONAL" in this section are to be interpreted as described in
+> [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+Those wishing to propose an addition to this registry **MUST** draft a new CIP describing the standard for implementing
+the token. Once the CIP has achieved the `Under Review` status the proposer **SHALL** make the necessary edits to 
+[registry.json](./registry.json). These changes **SHOULD** be submitted under a separate pull request against the CIP
+repository and include a brief description of the standard and a link to the CIP Pull Request describing implementation
+details.
 
 ## Rationale
 
 Asset name labels make it easy to identify native assets and classify them in their asset class intended by the issuer. Since the identification of these native assets is done by third parties, the design is focused on the usability for them.
 
-First, The label should be quickly parsable with a first check. That is, an initial check on an asset name that is easy and will exclude a big subset of the available token names that do not follow standard. This is why the label starts and ends with `0000` in bits. Additionally, in its hex notation, this is differentiable by a human in its readable form, a more common representation.
+First, the label should be quickly parsable with a first check. That is, an initial check on an asset name that is easy and will exclude a big subset of the available token names that do not follow standard. This is why the label starts and ends with `0000` in bits. Additionally, in its hex notation, this is differentiable by a human in its readable form, a more common representation.
 
 Secondly, the remaining verification on whether a certain `asset_name_label` standard is followed should be a one shot calculation. Here we mean that the calculation of the check should be straightforward, the label should not be fitted via brute force by a third party. That's why the label contains the bit representation of the integer label it tries to follow.
 
 Another thing that is important to understand is that an oblivious token issuer might not be aware of this standard. This could lead to the unintentional misinterpretation by third parties and injection attacks. We can minimize this attack vector by making the label format obscure. That is why the label also contains a checksum derived from the `asset_name_label` to add characters that are deterministically derived but look like nonsense. Together with the above zero "brackets", and the fixed size binary encoding, it make it unlikely someone follows this standard accidentally. The CRC-8 checksum is chosen for it low-impact on resources and its readily available implementations in multiple languages.
 
 ## Path to Active
 
-- Get support for this CIP by wallets, explorers, minting platforms and other 3rd parties.
-- Get support by tools/libraries like Lucid, PlutusTx, cardano-cli, etc. to generate/verify labels.
+- [X] Get support for this CIP by wallets, explorers, minting platforms and other 3rd parties.
+- [X] Get support by tools/libraries like Lucid, PlutusTx, cardano-cli, etc. to generate/verify labels.
 
 ### Reference Implementation(s)
 
@@ -130,4 +144,4 @@ Keys represent labels in `decimal` numbers. Values represent the entire label, i
 
 ## Copyright
 
-This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
diff --git a/CIP-0067/registry.json b/CIP-0067/registry.json
@@ -2,27 +2,31 @@
   {
     "asset_name_label": 100,
     "class": "NFT",
-    "description": "CIP-0068 - Datum Metadata Standard (Reference NFT)"
+    "description": "CIP-0068 - Datum Metadata Standard (Reference NFT)",
+    "documentation": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0068"
   },
   {
     "asset_name_label": 222,
     "class": "NFT",
-    "description": "CIP-0068 - Datum Metadata Standard (222 sub standard)"
+    "description": "CIP-0068 - Datum Metadata Standard (222 sub standard)",
+    "documentation": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0068"
   },
   {
     "asset_name_label": 333,
     "class": "FT",
-    "description": "CIP-0068 - Datum Metadata Standard (333 sub standard)"
+    "description": "CIP-0068 - Datum Metadata Standard (333 sub standard)",
+    "documentation": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0068"
   },
   {
     "asset_name_label": 444,
     "class": "RFT",
-    "description": "CIP-0068 - Datum Metadata Standard (444 sub standard)"
+    "description": "CIP-0068 - Datum Metadata Standard (444 sub standard)",
+    "documentation": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0068"
   },
   {
     "asset_name_label": 500,
     "class": "NFT",
     "description": "CIP-0102 - Datum Metadata Standard (500 sub standard)",
     "documentation": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0102"
   }
-]
+]
diff --git a/CIP-0067/registry.schema.json b/CIP-0067/registry.schema.json
@@ -10,7 +10,8 @@
       {
         "asset_name_label": 222,
         "class": "NFT",
-        "description": "CIP-0068 - NFT Metadata Standard (222 sub standard)"
+        "description": "CIP-0068 - NFT Metadata Standard (222 sub standard)",
+        "documentation": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0068"
       }
     ]
   ],
@@ -53,6 +54,14 @@
             "title": "The asset name label description",
             "default": "",
             "examples": ["CIP-0068 - NFT Metadata Standard (222 sub standard)"]
+          },
+          "documentation": {
+            "$id": "#/items/anyOf/0/properties/documentation",
+            "type": "string",
+            "format": "url",
+            "title": "Documentation Link",
+            "default": "",
+            "examples": ["https://github.com/cardano-foundation/CIPs/blob/master/CIP-0068"]
           }
         },
         "additionalProperties": false