CIP-0100 | Add test vector file (#782)

* recanonicalize examples * add test vector file and supporting files to explain the example * refactor test vectors
cardano-foundation · Apr 21, 2024 · 85cab04 · 85cab04
1 parent 65e163d
commit 85cab04
Show file tree

Hide file tree

Showing 6 changed files with 179 additions and 22 deletions.
diff --git a/CIP-0100/README.md b/CIP-0100/README.md
@@ -213,11 +213,7 @@ The following alternatives were considered, and rejected:
 
 ### Test Vectors
 
-An example document with an inline context is provided in [this](./example.json) example JSON file.
-
-Canonicalization should produce the following blak2b-256 hash:
-
-`6ea05c0e97b1b7316d48b5587a9e60d47c0c44993c8609c9544d88c111814819`
+See [test-vector.md](./test-vector.md) for example.
 
 ## Path to Active
 

diff --git a/CIP-0100/example.body.json b/CIP-0100/example.body.json
@@ -0,0 +1,54 @@
+{
+    "@context": {
+        "@language": "en-us",
+        "hashAlgorithm": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#hashAlgorithm",
+        "body": {
+            "@id": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#body",
+            "@context": {
+                "references": {
+                    "@id": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#references",
+                    "@container": "@set",
+                    "@context": {
+                        "governanceMetadata": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#GovernanceMetadataReference",
+                        "other": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#OtherReference",
+                        "label": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#reference-label",
+                        "uri": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#reference-uri"
+                    }
+                },
+                "comment": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#comment",
+                "externalUpdates": {
+                    "@id": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#externalUpdates",
+                    "@context": {
+                        "title": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#update-title",
+                        "uri": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#update-uri"
+                    }
+                }
+            }
+        },
+        "authors": {
+            "@id": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#authors",
+            "@container": "@set",
+            "@context": {
+                "did": "@id",
+                "name": "http://xmlns.com/foaf/0.1/name",
+                "witness": {
+                    "@id": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#witness",
+                    "@context": {
+                        "witnessAlgorithm": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#witnessAlgorithm",
+                        "publicKey": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#publicKey",
+                        "signature": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#signature"
+                    }
+                }
+            }
+        }
+    },
+    "body": {
+      "references": [
+        { "@type": "other", "label": "CIP-100", "uri": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md" }
+      ],
+      "comment": "This is a test vector for CIP-100",
+      "externalUpdates": [
+        { "title": "Blog", "uri": "https://314pool.com" }
+      ]
+    }
+  }
diff --git a/CIP-0100/example.body.canonical → CIP-0100/example.body.nq b/CIP-0100/example.body.canonical → CIP-0100/example.body.nq
@@ -1,9 +1,9 @@
-_:c14n0 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#update-title> "Blog"@en-us .
-_:c14n0 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#update-uri> "https://314pool.com"@en-us .
-_:c14n2 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#body> _:c14n5 .
-_:c14n3 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#OtherReference> .
-_:c14n3 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#reference-label> "CIP-100"@en-us .
-_:c14n3 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#reference-uri> "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md"@en-us .
-_:c14n5 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#comment> "This is a test vector for CIP-100"@en-us .
-_:c14n5 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#externalUpdates> _:c14n0 .
-_:c14n5 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#references> _:c14n3 .
+_:c14n0 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#body> _:c14n1 .
+_:c14n1 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#comment> "This is a test vector for CIP-100"@en-us .
+_:c14n1 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#externalUpdates> _:c14n3 .
+_:c14n1 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#references> _:c14n2 .
+_:c14n2 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#OtherReference> .
+_:c14n2 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#reference-label> "CIP-100"@en-us .
+_:c14n2 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#reference-uri> "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md"@en-us .
+_:c14n3 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#update-title> "Blog"@en-us .
+_:c14n3 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#update-uri> "https://314pool.com"@en-us .
diff --git a/CIP-0100/example.json b/CIP-0100/example.json
@@ -44,7 +44,7 @@
     },
     "hashAlgorithm": "blake2b-256",
     "authors": [
-      { "name": "Pi Lanningham", "witness": { "witnessAlgorithm": "ed25519", "publicKey": "46e4db7f87497ba232977ccd591b3d040316b155e8c60e3ea49176c03fa269de", "signature": "abcd"}}
+      { "name": "Pi Lanningham", "witness": { "witnessAlgorithm": "ed25519", "publicKey": "7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a", "signature": "340c2ef8d6abda96769844ab9dca2634ae21ef97ddbfad1f8843bea1058e40d656455a2962143adc603d063bbbe27b54b88d002d23d1dff1cd0e05017cd4f506"}}
     ],
     "body": {
       "references": [

diff --git a/CIP-0100/example.canonical → CIP-0100/example.nq b/CIP-0100/example.canonical → CIP-0100/example.nq
@@ -1,10 +1,16 @@
-_:c14n0 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#update-title> "Blog"@en-us .
-_:c14n0 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#update-uri> "https://314pool.com"@en-us .
-_:c14n2 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#body> _:c14n5 .
+_:c14n0 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#publicKey> "7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a"@en-us .
+_:c14n0 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#signature> "340c2ef8d6abda96769844ab9dca2634ae21ef97ddbfad1f8843bea1058e40d656455a2962143adc603d063bbbe27b54b88d002d23d1dff1cd0e05017cd4f506"@en-us .
+_:c14n0 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#witnessAlgorithm> "ed25519"@en-us .
+_:c14n1 <http://xmlns.com/foaf/0.1/name> "Pi Lanningham"@en-us .
+_:c14n1 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#witness> _:c14n0 .
+_:c14n2 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#comment> "This is a test vector for CIP-100"@en-us .
+_:c14n2 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#externalUpdates> _:c14n4 .
+_:c14n2 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#references> _:c14n3 .
 _:c14n3 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#OtherReference> .
 _:c14n3 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#reference-label> "CIP-100"@en-us .
 _:c14n3 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#reference-uri> "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md"@en-us .
-_:c14n4 <http://xmlns.com/foaf/0.1/name> "Pi Lanningham"@en-us .
-_:c14n5 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#comment> "This is a test vector for CIP-100"@en-us .
-_:c14n5 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#externalUpdates> _:c14n0 .
-_:c14n5 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#references> _:c14n3 .
+_:c14n4 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#update-title> "Blog"@en-us .
+_:c14n4 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#update-uri> "https://314pool.com"@en-us .
+_:c14n5 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#authors> _:c14n1 .
+_:c14n5 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#body> _:c14n2 .
+_:c14n5 <https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#hashAlgorithm> "blake2b-256"@en-us .
diff --git a/CIP-0100/test-vector.md b/CIP-0100/test-vector.md
@@ -0,0 +1,101 @@
+# Test Vector for CIP-0100
+
+Here we give some supporting files, give an example and explain how the [example.json](./example.json) was created.
+
+## Common Context
+
+### Common Fields
+
+The context fields which could be added to CIP-100 compliant jsonld metadata.
+See [cip-0100.common.jsonld](./cip-0100.common.jsonld).
+
+### Common Fields Schema
+
+A json schema for the common context fields.
+See [cip-0100.common.schema.json](./cip-0100.common.schema.json).
+
+## Example
+
+CIP-100 off-chain metadata json example: [example.json](./example.json)
+
+Blake2b-256 hash of the canonicalize example (to go on-chain): `cf704961a066ba770afdd810cc98e0834206df7c0febe70405e0a5f79dece3ec`
+
+### Intermediate files
+
+Files produced to articulate process, these are not necessary in implementations.
+
+Body files, used to correctly generate author's witness:
+- [example.body.json](./example.body.json)
+- [example.body.nq](./example.body.nq)
+
+Blake2b-256 hash digest of canonicalized body: `cc4ab8ead604ddb498ed4b2916af7b454c65ac783b5d836fddf388e72a40eccb`
+
+Whole document canonical representation, used to generate final hash:
+
+- [example.nq](./example.nq)
+
+### How-to Recreate
+
+This tutorial creates additional intermediate files, these are not required in implementations but are shown here to articulate the process.
+
+#### Author
+
+Private extended signing key (hex):
+`105d2ef2192150655a926bca9cccf5e2f6e496efa9580508192e1f4a790e6f53de06529129511d1cacb0664bcf04853fdc0055a47cc6d2c6d205127020760652`
+Public verification key (hex):
+`7ea09a34aebb13c9841c71397b1cabfec5ddf950405293dee496cac2f437480a`
+
+#### 1. Create the example.json's `body`
+
+Create the `example.json` file adding in all available values.
+Then remove from this document any top-level field that is not `@context` or `body`.
+
+This creates a intermediate file of [example.body.json](./example.body.json).
+
+#### 2. Canonicalize the `body`
+
+Using a tool which complies with the [RDF Dataset Canonicalization](https://w3c-ccg.github.io/rdf-dataset-canonicalization/spec/), create a canonicalized representation of [example.body.json](./example.body.json).
+One such tool is the [JSON-LD Playground](https://json-ld.org/playground/).
+Ensure the result ends in a newline.
+
+This creates a intermediate file of [example.body.nq](./example.body.nq).
+
+#### 3. Hash the canonicalized `body`
+
+Using a tool create a Blake2b-256 hash of the canonicalized [example.body.nq](./example.body.nq).
+One such tool is the [ToolKit Bay](https://toolkitbay.com/tkb/tool/BLAKE2b_256).
+
+For our example this will result in: `cc4ab8ead604ddb498ed4b2916af7b454c65ac783b5d836fddf388e72a40eccb`.
+
+#### 4. Authors witness over the hash of canonicalized `body`
+
+Use the hash produced in [3.](#3-hash-the-canonicalized-body) as the payload for the witness as described in [Hashing and Signatures](./README.md#hashing-and-signatures) for the chosen `witnessAlgorithm`.
+
+For the provided [example.json](./example.json), we use the keys described in [Author](#author) resulting in a `signature` of: `340c2ef8d6abda96769844ab9dca2634ae21ef97ddbfad1f8843bea1058e40d656455a2962143adc603d063bbbe27b54b88d002d23d1dff1cd0e05017cd4f506`
+
+#### 5. Add `authors` and `hashAlgorithm` to example.json
+
+We can go back to our [example.body.json](./example.body.json) and now add in properties from outside of `body`.
+- Adding the `hashAlgorithm` of `blake2b-256`.
+- Adding the `authors`, including information of our `witness` produced via [4.](#4-authors-witness-over-the-hash-of-canonicalized-body).
+
+By adding this information we create our [example.json](example.json).
+
+#### 6. Canonicalize example.json
+
+To be able to create a final metadata hash which can be attached on-chain we must first canonicalize the [example.json](example.json).
+Ensure the results ends in a newline.
+
+This creates [example.nq](./example.nq).
+
+#### 7. Hash the canonicalized example.json
+
+We then use the specified `hashAlgorithm` on [example.nq](./example.nq).
+
+This results in: `cf704961a066ba770afdd810cc98e0834206df7c0febe70405e0a5f79dece3ec`.
+
+#### 8. Submit to chain
+
+We can then host [example.json](./example.json) somewhere easily accessible following [Best Practices](./README.md#best-practices).
+
+Then at submission time of the governance metadata anchor we can provide the on-chain transaction both the URI to the hosted [example.json](./example.json) but also the hash generated via [7.](#7-hash-the-canonicalized-examplejson).