input-output-hk · stevenj · Apr 7, 2025 · Feb 13, 2025 · Feb 13, 2025 · Feb 16, 2025
diff --git a/.config/dictionaries/project.dic b/.config/dictionaries/project.dic
@@ -51,6 +51,7 @@ crontabs
 crontagged
 csprng
 cstring
+cuelang
 dalek
 dashmap
 Datelike
@@ -123,6 +124,7 @@ jorm
 jormungandr
 Jörmungandr
 jsonschema
+Justfile
 kiduri
 lcov
 Leay
@@ -141,6 +143,7 @@ logcall
 lookaside
 maindbname
 mapref
+markdownlint
 mdlint
 mdns
 MEMMAP
@@ -200,6 +203,7 @@ pubkey
 publickey
 pubspec
 pwrite
+pytest
 qpsg
 quic
 rapidoc

diff --git a/.gitignore b/.gitignore
@@ -84,3 +84,7 @@ $RECYCLE.BIN/
 # Dart stuff
 /pubspec.lock
 /.dart_tool/**/*
+
+# Python stuff
+.pytest_cache
+__pycache__
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -10,7 +10,8 @@
   "ignores": [
     ".config/dictionaries/**",
     "**/target/**",
-    "**/.dart_tool/**"
+    "**/.dart_tool/**",
+    "**/.pytest_cache/**"
   ],
   // Set standard config options in `/.markdownlint.jsonc`
   "config": {

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -24,5 +24,8 @@
         "dtsvet.vscode-wasm",
         "terrastruct.d2",
         "fill-labs.dependi",
+        "nefrob.vscode-just-syntax",
+        "charliermarsh.ruff",
+        "ms-python.python",
     ]
 }
diff --git a/Justfile b/Justfile
@@ -15,6 +15,19 @@ check-spelling:
     earthly +check-spelling
 
 
+# Fix and Check Markdown files
+format-python-code:
+    ruff check --select I --fix .
+    ruff format .
+
+# Fix and Check Markdown files
+lint-python:
+    ruff check .
+
+# generates specifications data
+gen_specs:
+    just specs/pre-push
+
 # Pre Push Checks - intended to be run by a git pre-push hook.
-pre-push: check-markdown check-spelling
+pre-push: gen_specs check-markdown check-spelling format-python-code lint-python
     just rust/pre-push
diff --git a/docs/Earthfile b/docs/Earthfile
@@ -4,6 +4,7 @@ IMPORT github.com/input-output-hk/catalyst-ci/earthly/docs:v3.3.0 AS docs-ci
 
 
 IMPORT .. AS repo
+IMPORT ../specs AS specs
 
 # Copy all the source we need to build the docs
 src:
@@ -13,6 +14,9 @@ src:
     # Now copy into that any artifacts we pull from the builds.
     COPY --dir repo+repo-docs/repo /docs/includes
 
+    # Copy our generated Signed Document Specification data.
+    COPY specs+src/signed_doc.json /docs/includes
+
 
 # Build the docs here.
 docs:

diff --git a/docs/src/architecture/08_concepts/catalyst_docs/.pages b/docs/src/architecture/08_concepts/catalyst_docs/.pages
@@ -1,5 +1 @@
 title: Catalyst Documents
-arrange:
-- proposal.md
-- review.md
-- comment.md
diff --git a/docs/src/architecture/08_concepts/catalyst_docs/comment.md b/docs/src/architecture/08_concepts/catalyst_docs/comment.md
@@ -46,17 +46,17 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do
   "content-encoding" => "br"
   ```
 
-* [`ref`](./../signed_doc/meta.md#ref-document-reference).
+* [`ref`](./../signed_doc/metadata.md#ref-document-reference).
   Reference to a related [Proposal Document],
   which [`type`](./../signed_doc/spec.md#type) must be equal to
   [proposal document `type`][Proposal Document] field value.
 
-* [`template`](./../signed_doc/meta.md#ref-document-reference).
+* [`template`](./../signed_doc/metadata.md#ref-document-reference).
   A reference to the comment template document,
   which [`type`](./../signed_doc/spec.md#type) must be equal to
   [comment template `type`](#comment-template) field value.
 
-* [`reply`](./../signed_doc/meta.md#reply-reply-reference) (optional).
+* [`reply`](./../signed_doc/metadata.md#reply-reply-reference) (optional).
   A reference to another comment document,
   where the comment is in reply to the referenced comment.
   The [`type`](./../signed_doc/spec.md#type) of the replied document
@@ -65,7 +65,7 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do
   The referenced `comment` must be for the same proposal [`id`](./../signed_doc/spec.md#id),
   but can be for a different proposal [`ver`](./../signed_doc/spec.md#ver).
 
-* [`section`](./../signed_doc/meta.md#section-section-reference) (optional).
+* [`section`](./../signed_doc/metadata.md#section-section-reference) (optional).
   Used when the comment only applies to a specific section to the document being commented upon,
   and not the entire document.
 
@@ -106,7 +106,7 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do
   "content-encoding" => "br"
   ```
 
-* [`category_id`](./../signed_doc/meta.md#category_id) (optional).
+* [`category_id`](./../signed_doc/metadata.md#category_id) (optional).
   A reference to the category document,
   which [`type`](./../signed_doc/spec.md#type) must be equal to
   `48c20109-362a-4d32-9bba-e0a9cf8b45be` value.

diff --git a/docs/src/architecture/08_concepts/catalyst_docs/proposal.md b/docs/src/architecture/08_concepts/catalyst_docs/proposal.md
@@ -50,12 +50,12 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do
   "content-encoding" => "br"
   ```
 
-* [`template`](./../signed_doc/meta.md#ref-document-reference).
+* [`template`](./../signed_doc/metadata.md#ref-document-reference).
   A reference to the proposal template document,
   which [`type`](./../signed_doc/spec.md#type) must be equal to
   [proposal template `type`](#proposal-template) field value.
 
-* [`category_id`](./../signed_doc/meta.md#category_id) (optional).
+* [`category_id`](./../signed_doc/metadata.md#category_id) (optional).
   A reference to the category document,
   which [`type`](./../signed_doc/spec.md#type) must be equal to
   `48c20109-362a-4d32-9bba-e0a9cf8b45be` value.
@@ -112,7 +112,7 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do
   "content-encoding" => "br"
   ```
 
-* [`category_id`](./../signed_doc/meta.md#category_id) (optional).
+* [`category_id`](./../signed_doc/metadata.md#category_id) (optional).
   A reference to the category document,
   which [`type`](./../signed_doc/spec.md#type) must be equal to
   `48c20109-362a-4d32-9bba-e0a9cf8b45be` value.

diff --git a/docs/src/architecture/08_concepts/catalyst_docs/review.md b/docs/src/architecture/08_concepts/catalyst_docs/review.md
@@ -46,7 +46,7 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do
   "content-encoding" => "br"
   ```
 
-* [`template`](./../signed_doc/meta.md#ref-document-reference).
+* [`template`](./../signed_doc/metadata.md#ref-document-reference).
   A reference to the review template document,
   which [`type`](./../signed_doc/spec.md#type) must be equal to
   [review template `type`](#review-template) field value.

diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md
@@ -35,16 +35,16 @@ A list of used [Catalyst Signed Document protected header fields](./../signed_do
   "content-type" => "br"
   ```
 
-* [`brand_id`](./../signed_doc/meta.md#brand_id).
-* [`campaign_id`](./../signed_doc/meta.md#campaign_id).
-* [`election_id`](./../signed_doc/meta.md#election_id).
-* [`category_id`](./../signed_doc/meta.md#category_id).
+* [`brand_id`](./../signed_doc/metadata.md#brand_id).
+* [`campaign_id`](./../signed_doc/metadata.md#campaign_id).
+* [`election_id`](./../signed_doc/metadata.md#election_id).
+* [`category_id`](./../signed_doc/metadata.md#category_id).
 
 #### Public vote
 
-For the public vote [`type`](./../signed_doc/spec.md#type) value defined as follows:
+For the public vote [`type`](./../signed_doc/metadata.md#type) value defined as follows:
 
-* [`type`](./../signed_doc/spec.md#type): `8de5586c-e998-4b95-8742-7be3c8592803` [UUID] value.
+* [`type`](./../signed_doc/metadata.md#type): `8de5586c-e998-4b95-8742-7be3c8592803` [UUID] value.
 
   ```CDDL
   "type" => 37(h'8DE5586CE9984B9587427BE3C8592803')
@@ -66,9 +66,9 @@ Following that spec need to define a `choice`, `proof` and `prop-id`.
 
 #### Private vote
 
-For the private vote [`type`](./../signed_doc/spec.md#type) value defined as follows:
+For the private vote [`type`](./../signed_doc/metadata.md#type) value defined as follows:
 
-* [`type`](./../signed_doc/spec.md#type): `e78ee18d-f380-44c1-a852-80aa6ecb07fe` [UUID] value.
+* [`type`](./../signed_doc/metadata.md#type): `e78ee18d-f380-44c1-a852-80aa6ecb07fe` [UUID] value.
 
   ```CDDL
   "type" => 37(h'E78EE18DF38044C1A85280AA6ECB07FE')
@@ -112,7 +112,7 @@ the following properties are used:
 <!-- OPTIONAL SECTIONS: see CIP-0001 > Document > Structure table -->
 
 [Catalyst Signed Document]: ./../signed_doc/spec.md
-[Catalyst Signed Document content]: ./../signed_doc/spec.md#signed-object-content
+[Catalyst Signed Document content]: ./../signed_doc/spec.md#content-type
 [Generalized Vote Transaction Structure]: ./gen_vote_tx.md
 [BLAKE2b-512]: https://www.blake2.net/blake2.pdf
 [ristretto255]: https://ristretto.group

diff --git a/docs/src/architecture/08_concepts/immutable_ledger/ledger.md b/docs/src/architecture/08_concepts/immutable_ledger/ledger.md
@@ -77,39 +77,36 @@ so its fully follows the structure of the [Catalyst Signed Document] specificati
 
 ### Metadata Fields
 
-* [`id`](./../signed_doc/spec.md#id).
+* [`id`](./../signed_doc/metadata.md#id).
   Used as a unique identifier of the chain.
   So all blocks from the same chain must have the same
-  [`id`](./../signed_doc/spec.md#id) field value.
-* [`ver`](./../signed_doc/spec.md#ver).
+  [`id`](./../signed_doc/metadata.md#id) field value.
+* [`ver`](./../signed_doc/metadata.md#ver).
   Used as a unique identifier of the block itself.
   Also the block's creation `timestamp` value is determined from the
-  [`ver`](./../signed_doc/spec.md#ver) field.
+  [`ver`](./../signed_doc/metadata.md#ver) field.
 * [`content type`](./../signed_doc/spec.md#content-type): `application/cbor`.
   [Catalyst Signed Document content] must be a [CBOR] encoded.
 
   ```CDDL
   3 => 50
   ```
 
-* [`content encoding`](./../signed_doc/spec.md#content-encoding-optional):
+* [`content encoding`](./../signed_doc/spec.md#content-encoding):
   [Catalyst Signed Document content] must be [Brotli] compressed.
 
   ```CDDL
   "content-type" => "br"
   ```
 
-* [`type`](./../signed_doc/spec.md#type): `d9e7e6ce-2401-4d7d-9492-f4f7c64241c3` [UUID] value.
+* [`type`](./../signed_doc/metadata.md#type): `d9e7e6ce-2401-4d7d-9492-f4f7c64241c3` [UUID] value.
 
   ```CDDL
   "type" => 37(h'D9E7E6CE24014D7D9492F4F7C64241C3')
   ```
 
-* [`ref_hash`](./../signed_doc/meta.md#ref-hash-secured-document-reference).
-  Previous block reference.
-  A [`ref`](./../signed_doc/meta.md#ref-document-reference) part **must** be a pair of
-  [`id`](./../signed_doc/spec.md#id) and
-  [`ver`](./../signed_doc/spec.md#ver).
+* [`ref`](./../signed_doc/metadata.md#ref).
+  Previous block reference, including Hash of the previous block.
 
 ### Content format
 
@@ -144,32 +141,25 @@ Block:
 
 ### Block validation rules
 
-* [`id`](./../signed_doc/spec.md#id)
+* [`id`](./../signed_doc/metadata.md#id)
   **MUST** be the same as for the previous block (except for genesis).
 * `height` **MUST** be incremented by `1` from the previous block height value (except for genesis and final block).
   *Genesis* block **MUST** have `0` value.
   *Final* block **MUST** hash be incremented by `1` from the previous block height and changed the sign to negative.
   E.g. previous block height is `9` and the *Final* block height is `-10`.
 * *Final* block is the last one for the specific chain and any other block could not be referenced to the *Final* one.
 
-* [`ver`](./../signed_doc/spec.md#ver)
+* [`ver`](./../signed_doc/metadata.md#ver)
   timestamp value **MUST** be greater or equals than the corresponding `timestamp`
   of the previous block (except for genesis).
-* [`ref_hash`](./../signed_doc/meta.md#ref-hash-secured-document-reference)
+* [`ref`](./../signed_doc/metadata.md#ref)
   **MUST** be a reference to the previous block (except for genesis).
 * `ledger-type` **MUST** be the same as for the previous block if present (except for genesis).
   **MANDATORY** field for *Genesis* and *Final* blocks.
 * `purpose-id` **MUST** be the same as for the previous block if present (except for genesis).
   **MANDATORY** field for *Genesis* and *Final* blocks.
-* [`kid`](./../signed_doc/spec.md#cose-signature-protected-header) field
+* [`kid`](./../signed_doc/spec.md#kid) field
   **MUST** be the same as for the previous block (except for genesis).
-* [`ref_hash`](./../signed_doc/meta.md#ref-hash-secured-document-reference)'s
-  `hash-bytes` CBOR tag value and `bytes` size
-  **MUST** be the same as for the previous block (except for genesis).
-  Means that the hash function type and hash size itself must be the same.
-* [`ref_hash`](./../signed_doc/meta.md#ref-hash-secured-document-reference)
-  field for the *Genesis* block **MUST** be omitted.
-* `block-data` **MUST** be a [deterministically][CBOR-deterministically-encoded] encoded CBOR.
 
 ## Rationale
 
@@ -184,7 +174,6 @@ Block:
 <!-- OPTIONAL SECTIONS: see CIP-0001 > Document > Structure table -->
 
 [Catalyst Signed Document]: ./../signed_doc/spec.md
-[Catalyst Signed Document content]: ./../signed_doc/spec.md#signed-object-content
-[CBOR-deterministically-encoded]: https://datatracker.ietf.org/doc/html/rfc8949#name-deterministically-encoded-c
+[Catalyst Signed Document content]: ./../signed_doc/spec.md#content-type
 [Brotli]: https://datatracker.ietf.org/doc/html/rfc7932
 [CBOR]: https://datatracker.ietf.org/doc/rfc8949/
diff --git a/docs/src/architecture/08_concepts/signed_doc/.pages b/docs/src/architecture/08_concepts/signed_doc/.pages
@@ -1,5 +1,6 @@
 title: Catalyst Signed Document
 nav:
   - Specification: spec.md
-  - Metadata Fields: meta.md
+  - Metadata Fields: metadata.md
   - Document Types: types.md
+  - docs