feat(docs): signed doc spec 0.04 (#341)

* fix(docs): correct python type annotations in documentation generator (#325)

* feat(docs): Consolidate all parameters types into a single parameters reference.

* fix(docs): Fix linked references

* feat(docs): Start of adding capability to cluster like documents to simplify relationship diagrams.

* fix(docs): wip fix of clustered documents

* feat(docs): Add document clusters to help with autogenerated diagrams.

* fix(docs): fix spelling

* fix(Python): fix type

* fix(docs): Inter doc links in diagrams

* fix(docs): Neils Eyesight Soother

* fix(docs): Rename Election Parameters to Decision parameters

* fix(docs): python types

* fix(docs): add missing doc generator type definitions

* fix(general): Updater recommended vscode settings

* docs(docs): Better define the document encoding restrictions. (#326)

* feat(docs): Add examples for predefined document schemas (#342)

* format the blueprint.cue

* fix(docs): Update module to latest cue version

* feat(docs): WIP formalized definitions of field definitions for json schema templates

* feat(docs): WIP

* fix(docs): simplify schema with cue format

* feat(docs): WIP template defs dictionary

* fix(docs): update python files we don't want in git

* refactor(docs): reorganize the cue files for better modularity

* refactor(docs): Move spec python model for better modularity

* docs(docs): Add base of new spec python workspace and modules

* fix(docs): remove lin to root ruff.toml which was impacting import sorting

* refactor(docs): Reorganize the doc generator into the new module structure

* refactor(docs): Cleanup document specification data structure and methods

* refactor(docs): Remove last remnants of direct dict accesses.

* refactor(docs): remove code obsoleted by refactor

* refactor(docs): large cue refactor to stuff that should be common

* docs(docs): Add chain metadata to support chained document references.

* fix(docs): lint issues

* fix(docs): lint issues

* fix(docs): CI build issues

* docs(docs): wip

* docs(docs): Add fully generalized, templated parameters documents to the specification.

* fix(docs): form templates do not have templates

* fix(docs): remove the parameters from templates on the parameters documents themselves (redundant).

* fix(docs): use common parameters definition

* feat(docs): Add Representative Profiles and Nomination Forms

* feat(docs): Add Rep Profiles, Nominations and Delegations documents

* Update contest_delegation.cue

Break line with multiple sentences

* fix excess lines in null payload description

* fix(docs): contest delegation spacing

* fix(docs): contest structure fix

* fix(docs): structure quick fix

* fix(docs): fixed indentation in contest md

* fix(docs): contest cue file fix

* fix(docs): quick fix on indentation

* fix(docs): markdown indentation fix

* fix(docs): minor character and structure fix

* fix(docs): contest cue file fix

* fix(docs): additional indentation fix

---------

Co-authored-by: Nathan Bogale <[email protected]>

Author: stevenj

.config/dictionaries/project.dic

@@ -4,12 +4,14 @@ ABNF
 addrr
 addrs
 adminer
+admon
 anypolicy
 apskhem
 Arissara
 asyncio
 Attributes
 auditability
+Auliffe
 auxdata
 babystep
 backpressure
@@ -21,6 +23,7 @@ blockdiag
 blockfetch
 blosc
 bmac
+Bogale
 bootstrapper
 BROTLI
 Cabe
@@ -80,6 +83,7 @@ elgamal
 encryptor
 Errno
 Eternl
+evalv
 excalidraw
 explicitely
 extn
@@ -160,6 +164,8 @@ ltail
 maindbname
 mapref
 markdownlint
+mdformat
+mdit
 mdlint
 mdns
 MEMMAP
@@ -175,6 +181,7 @@ mitigations
 mkcron
 mkdelay
 mkdirat
+mkdocs
 Mmap
 moderations
 moka
@@ -230,6 +237,7 @@ pypackages
 pytest
 pytype
 qpsg
+qrcode
 quic
 rankdir
 rapidoc

.gitignore

@@ -1,3 +1,5 @@
+new
+
 ## Secrets
 **/.secret
 
@@ -87,4 +89,10 @@ $RECYCLE.BIN/
 
 # Python stuff
 .pytest_cache
-__pycache__
+__pycache__
+py.typed
+*.egg-info
+.venv
+.ruff_cache
+dist
+*.pyi

.markdownlint-cli2.jsonc

@@ -11,7 +11,8 @@
     ".config/dictionaries/**",
     "**/target/**",
     "**/.dart_tool/**",
-    "**/.pytest_cache/**"
+    "**/.pytest_cache/**",
+    "**/.venv"
   ],
   // Set standard config options in `/.markdownlint.jsonc`
   "config": {

.vscode/settings.recommended.json

@@ -1,5 +1,5 @@
 {
-  // Recommended `settings.json` configuration
+  "$comment": "Recommended `settings.json` configuration",
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": {
     "source.organizeImports": true,
@@ -37,12 +37,20 @@
     "rust",
     "rust/c509-certificate",
     "rust/cardano-chain-follower",
+    "rust/catalyst-types",
     "rust/catalyst-voting",
+    "rust/immutable-ledger",
+    "rust/vote-tx-v1",
+    "rust/vote-tx-v2",
+    "rust/signed-doc",
     "rust/cbork",
     "rust/hermes-ipfs",
+    "rust/rbac-registration",
+    "rust/cardano-blockchain-types",
     "dart",
     "docs",
-    "general"
+    "general",
+    "deps"
   ],
   "conventionalCommits.gitmoji": false,
   "markdown.extension.toc.unorderedList.marker": "*",

blueprint.cue

@@ -12,9 +12,9 @@ global: {
 		]
 		providers: {
 			aws: {
-				region:   "eu-central-1"
+				region: "eu-central-1"
 				ecr: registry: "332405224602.dkr.ecr.eu-central-1.amazonaws.com"
-				role:     "arn:aws:iam::332405224602:role/ci"
+				role: "arn:aws:iam::332405224602:role/ci"
 			}
 
 			docker: credentials: {

docs/src/architecture/08_concepts/signed_doc/.pages

@@ -3,4 +3,5 @@ nav:
   - Specification: spec.md
   - Metadata Fields: metadata.md
   - Document Types: types.md
+  - Document Templates: templates.md
   - docs

docs/src/architecture/08_concepts/signed_doc/cddl/chain.cddl

@@ -0,0 +1,50 @@
+; chain
+
+
+; Reference to the previous Signed Document in a sequence.
+; * `height` is of the CURRENT block.
+; * `document_ref` is *ONLY* omitted in the very first document in a sequence.
+chain = [height, ? document_ref]
+
+; The consecutive sequence number of the current document
+; in the chain.
+; The very first document in a sequence is numbered `0` and it
+; *MUST ONLY* increment by one for each successive document in
+; the sequence.
+;
+; The FINAL sequence number is encoded with the current height
+; sequence value, negated.
+;
+; For example the following values for height define a chain
+; that has 5 documents in the sequence 0-4, the final height
+; is negated to indicate the end of the chain:
+; `0, 1, 2, 3, -4`
+;
+; No subsequent document can be chained to a sequence that has
+; a final chain height.
+height = int
+
+; Reference to a single Signed Document
+document_ref = [
+  document_id,
+  document_ver,
+  document_locator
+]
+
+; Document ID
+document_id = uuid_v7
+
+; UUIDv7
+uuid_v7 = #6.37(bytes .size 16)
+
+; Document Version
+document_ver = uuid_v7
+
+; Where a document can be located, must be a unique identifier.
+document_locator = {
+  "cid" => cid
+}
+
+; IPLD content identifier
+; TODO: add size limits if possible
+cid = #6.42(bytes)

docs/src/architecture/08_concepts/signed_doc/cddl/document_ref.cddl

@@ -1,12 +1,12 @@
 ; document_ref
 
 
-; Reference to another Signed Document
-document_ref = [ 1* [
+; Reference to a single Signed Document
+document_ref = [
   document_id,
   document_ver,
   document_locator
-] ]
+]
 
 ; Document ID
 document_id = uuid_v7

docs/src/architecture/08_concepts/signed_doc/cddl/document_refs.cddl

@@ -0,0 +1,30 @@
+; document_refs
+
+
+; Reference to one or more Signed Documents
+document_refs = [ 1* document_ref ]
+
+; Reference to a single Signed Document
+document_ref = [
+  document_id,
+  document_ver,
+  document_locator
+]
+
+; Document ID
+document_id = uuid_v7
+
+; UUIDv7
+uuid_v7 = #6.37(bytes .size 16)
+
+; Document Version
+document_ver = uuid_v7
+
+; Where a document can be located, must be a unique identifier.
+document_locator = {
+  "cid" => cid
+}
+
+; IPLD content identifier
+; TODO: add size limits if possible
+cid = #6.42(bytes)

docs/src/architecture/08_concepts/signed_doc/cddl/signed_document.cddl

@@ -37,14 +37,23 @@ COSE_Document_Standard_Headers = (
 )
 
 ; Supported Content Media Types.
-; If uint is used, only CoAP Content Formats that match the string format are allowed.
+; If the Media Type is supported by COAP, then the `uint` CoAP encoded
+; version of the media type must be used, in preference to the string.
 media_type = (
-    (uint .eq (50 / 60)) /
+    (uint .eq (0 / 50 / 60 / 20000)) /
     (tstr .eq (
+        "application/cbor" /
+        "application/cddl" /
         "application/json" /
         "application/schema+json" /
-        "application/cbor" /
-        "application/cddl"
+        "text/css; charset=utf-8" /
+        "text/css; charset=utf-8; template=handlebars" /
+        "text/html; charset=utf-8" /
+        "text/html; charset=utf-8; template=handlebars" /
+        "text/markdown; charset=utf-8" /
+        "text/markdown; charset=utf-8; template=handlebars" /
+        "text/plain; charset=utf-8" /
+        "text/plain; charset=utf-8; template=handlebars"
     ))
 )
 
@@ -56,13 +65,14 @@ Signed_Document_Metadata_Headers = (
   "type" => document_type
   "id" => document_id
   "ver" => document_ver
-  ?"ref" => document_ref
-  ?"template" => document_ref
-  ?"reply" => document_ref
+  ?"ref" => document_refs
+  ?"template" => document_refs
+  ?"reply" => document_refs
   ?"section" => section_ref
   ?"collaborators" => collaborators
   ?"revocations" => revocations
-  ?"parameters" => document_ref
+  ?"parameters" => document_refs
+  ?"chain" => chain
 )
 
 ; Document Type
@@ -80,12 +90,15 @@ uuid_v7 = #6.37(bytes .size 16)
 ; Document Version
 document_ver = uuid_v7
 
-; Reference to another Signed Document
-document_ref = [ 1* [
+; Reference to one or more Signed Documents
+document_refs = [ 1* document_ref ]
+
+; Reference to a single Signed Document
+document_ref = [
   document_id,
   document_ver,
   document_locator
-] ]
+]
 
 ; Where a document can be located, must be a unique identifier.
 document_locator = {
@@ -111,6 +124,29 @@ catalyst_id_kid = bytes
 ; List of revoked versions of this document.
 revocations = [ * document_ver ] / true
 
+; Reference to the previous Signed Document in a sequence.
+; * `height` is of the CURRENT block.
+; * `document_ref` is *ONLY* omitted in the very first document in a sequence.
+chain = [height, ? document_ref]
+
+; The consecutive sequence number of the current document
+; in the chain.
+; The very first document in a sequence is numbered `0` and it
+; *MUST ONLY* increment by one for each successive document in
+; the sequence.
+;
+; The FINAL sequence number is encoded with the current height
+; sequence value, negated.
+;
+; For example the following values for height define a chain
+; that has 5 documents in the sequence 0-4, the final height
+; is negated to indicate the end of the chain:
+; `0, 1, 2, 3, -4`
+;
+; No subsequent document can be chained to a sequence that has
+; a final chain height.
+height = int
+
 ; Generic Header definition
 COSE_Generic_Headers = ( * COSE_label => COSE_values )