input-output-hk · stevenj · May 15, 2025 · May 16, 2025 · May 20, 2025 · May 21, 2025
diff --git a/.vscode/settings.recommended.json b/.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": "*",

diff --git a/docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot b/docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot
@@ -1,4 +1,4 @@
-digraph "None" {
+digraph "All" {
     rankdir="LR"
     graph [fontname="helvetica", fontsize="32", fontcolor="#29235c", bgcolor="white"];
     node [penwidth="0", margin="0", fontname="helvetica", fontsize="32", fontcolor="#29235c"];

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters.md b/docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters.md
@@ -112,7 +112,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters.md b/docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters.md
@@ -130,7 +130,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/category_parameters.md b/docs/src/architecture/08_concepts/signed_doc/docs/category_parameters.md
@@ -130,7 +130,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/comment_moderation_action.md b/docs/src/architecture/08_concepts/signed_doc/docs/comment_moderation_action.md
@@ -153,7 +153,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/decision_parameters.md b/docs/src/architecture/08_concepts/signed_doc/docs/decision_parameters.md
@@ -132,7 +132,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal.md
@@ -226,7 +226,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment.md
@@ -261,7 +261,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/.../src/architecture/08_concepts/signed_doc/docs/proposal_comment_meta_template.md b/.../src/architecture/08_concepts/signed_doc/docs/proposal_comment_meta_template.md
@@ -141,7 +141,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment_template.md
@@ -154,7 +154,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_meta_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_meta_template.md
@@ -141,7 +141,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_moderation_action.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_moderation_action.md
@@ -153,7 +153,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_submission_action.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_submission_action.md
@@ -199,49 +199,106 @@ States:
       `hide` is only actioned if sent by the author,
          for a collaborator it identified that they do not wish to be listed as a `collaborator`.
 
-Schema :
-<!-- markdownlint-disable MD013 -->
-```json
-{
-  "$id": "https://raw.githubusercontent.com/input-output-hk/catalyst-libs/refs/heads/main/specs/signed_docs/docs/payload_schemas/proposal_submission_action.schema.json",
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": false,
-  "definitions": {
-    "action": {
-      "description": "The action being performed on the Proposal.",
-      "enum": [
-        "final",
-        "draft",
-        "hide"
+### Schema
+
+<!-- markdownlint-disable MD013 MD046 max-one-sentence-per-line -->
+??? abstract
+
+    The kind of action is controlled by this payload.
+    The Payload is a [JSON][RFC8259] Document, and must conform to this schema.
+
+    States:
+
+    * `final` : All collaborators must publish a `final` status for the proposal to be `final`.
+    * `draft` : Reverses the previous `final` state for a signer and accepts collaborator status to a document.
+    * `hide`  : Requests the proposal be hidden (not final, but a hidden draft).
+          `hide` is only actioned if sent by the author,
+             for a collaborator it identified that they do not wish to be listed as a `collaborator`.
+
+    ```json
+    {
+      "$id": "https://raw.githubusercontent.com/input-output-hk/catalyst-libs/refs/heads/main/specs/signed_docs/docs/payload_schemas/proposal_submission_action.schema.json",
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "additionalProperties": false,
+      "definitions": {
+        "action": {
+          "description": "The action being performed on the Proposal.",
+          "enum": [
+            "final",
+            "draft",
+            "hide"
+          ],
+          "type": "string"
+        }
+      },
+      "description": "Structure of the payload of a Proposal Submission Action.",
+      "maintainers": [
+        {
+          "name": "Catalyst Team",
+          "url": "https://projectcatalyst.io/"
+        }
       ],
-      "type": "string"
+      "properties": {
+        "action": {
+          "$ref": "#/definitions/action"
+        }
+      },
+      "required": [
+        "action"
+      ],
+      "title": "Proposal Submission Action Payload Schema",
+      "type": "object",
+      "x-changelog": {
+        "2025-03-01": [
+          "First Version Created."
+        ]
+      }
+    }
+    ```
+
+<!-- markdownlint-enable MD013 MD046 max-one-sentence-per-line -->
+
+### Examples
+<!-- markdownlint-disable MD013 MD046 max-one-sentence-per-line -->
+??? example "Example: Final Proposal Submission"
+
+    This document indicates the linked proposal is final and requested to proceed for further consideration.
+
+    ```json
+    {
+      "action": "final"
     }
-  },
-  "description": "Structure of the payload of a Proposal Submission Action.",
-  "maintainers": [
+    ```
+
+<!-- markdownlint-enable MD013 MD046 max-one-sentence-per-line -->
+<!-- markdownlint-disable MD013 MD046 max-one-sentence-per-line -->
+??? example "Example: Draft Proposal Submission"
+
+    This document indicates the linked proposal is no longer final and should not proceed for further consideration.
+    It is also used by collaborators to accept that they are a collaborator on a document.
+
+    ```json
     {
-      "name": "Catalyst Team",
-      "url": "https://projectcatalyst.io/"
+      "action": "draft"
     }
-  ],
-  "properties": {
-    "action": {
-      "$ref": "#/definitions/action"
+    ```
+
+<!-- markdownlint-enable MD013 MD046 max-one-sentence-per-line -->
+<!-- markdownlint-disable MD013 MD046 max-one-sentence-per-line -->
+??? example "Example: Hidden Proposal Submission"
+
+    If submitted by the proposal author the document is hidden, it is still public but not shown as
+    a proposal being drafted.
+    If submitted by a collaborator, that collaborator is declaring they do not wish to be listed as
+    a collaborator on the proposal.
+
+    ```json
+    {
+      "action": "hide"
     }
-  },
-  "required": [
-    "action"
-  ],
-  "title": "Proposal Submission Action Payload Schema",
-  "type": "object",
-  "x-changelog": {
-    "2025-03-01": [
-      "First Version Created."
-    ]
-  }
-}
-```
-<!-- markdownlint-enable MD013 -->
+    ```
+
+<!-- markdownlint-enable MD013 MD046 max-one-sentence-per-line -->
 
 ## Signers
 
@@ -260,7 +317,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_template.md
@@ -158,7 +158,7 @@ New versions of this document may be published by:
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/metadata.md b/docs/src/architecture/08_concepts/signed_doc/metadata.md
@@ -348,7 +348,7 @@ In addition to the validation performed for [Document Reference](metadata.md#doc
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/spec.md b/docs/src/architecture/08_concepts/signed_doc/spec.md
@@ -25,6 +25,40 @@ Catalyst Signed Documents are based on [COSE][RFC9052].
 Specifically, the [COSE Sign][RFC9052-CoseSign] format is used.
 This allows one or more signatures to be attached to the same document.
 
+While every Catalyst Signed Document is a valid [COSE Sign][RFC9052-CoseSign] format document,
+not every [COSE Sign][RFC9052-CoseSign] format document is a valid Catalyst Signed Document.
+The following restrictions apply:
+
+### Unprotected Headers are not permitted
+
+It is a requirement that any document that contains exactly the same data, must produce the same
+catalyst signed document.
+This means that unprotected headers, which do not form part of the data protected by
+the signature are not permitted.
+Any document which contains any unprotected headers is not a valid Catalyst Signed Document,
+even though it may be a valid [COSE Sign][RFC9052-CoseSign] formatted document.
+
+### Only defined metadata and [COSE][RFC9052] Headers are allowed
+
+Each document type, defines a set of metadata and the [COSE][RFC9052] Headers which are allowed in that document type.
+Even if the Catalyst Signed document metadata exists in this specification, IF it is not defined as
+a valid metadata or [COSE][RFC9052] Header field for that particular document it may not be present.
+Unexpected but otherwise valid Metadata or [COSE][RFC9052] Header fields invalidate the Catalyst Signed Document.
+
+### No undefined metadata or unused [COSE][RFC9052] Headers may be present
+
+[COSE][RFC9052] Header Fields which are defined by the [COSE][RFC9052] Specification, but are NOT defined as part of a
+Catalyst Signed Document may not be present.
+Any such [COSE][RFC9052] Header Fields present in the document render it an invalid Catalyst Signed Document.
+
+Any metadata field that is not defined in this specification may not be present in any protected header.
+Unrecognized metadata fields in a document render it an invalid Catalyst Signed Document.
+
+### [CBOR Deterministic Encoding][CBOR-LFD-ENCODING] MUST be used
+
+The Catalyst Signed Document **MUST** be encoded using [CBOR Deterministic Encoding][CBOR-LFD-ENCODING].
+The "length-first core deterministic encoding requirements" variant of deterministic encoding *MUST* be used.
+
 ### Signed Document [CDDL][RFC8610] Definition
 
 <!-- markdownlint-disable max-one-sentence-per-line -->
@@ -120,7 +154,7 @@ used to sign the protected portion of the document.
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |
 
@@ -138,6 +172,15 @@ used to sign the protected portion of the document.
 
 * Use generalized parameters.
 
+#### 0.04 (2025-05-30)
+
+* Improve and make document serialization more repeatable, and stricter.
+* TODO: Define Systems parameters
+* TODO: Define DReps documents.
+* TODO: Define Proposer Profiles.
+* TODO: Define Role 0 Profile.
+
+[CBOR-LFD-ENCODING]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.3
 [application/schema+json]: https://datatracker.ietf.org/doc/draft-bhutton-json-schema/
 [RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
 [application/cbor]: https://www.iana.org/assignments/media-types/application/cbor

diff --git a/docs/src/architecture/08_concepts/signed_doc/types.md b/docs/src/architecture/08_concepts/signed_doc/types.md
@@ -55,7 +55,7 @@ All Defined Document Types
 | --- | --- |
 | License | This document is licensed under [CC-BY-4.0] |
 | Created | 2024-12-27 |
-| Modified | 2025-05-05 |
+| Modified | 2025-05-30 |
 | Authors | Alex Pozhylenkov <[email protected]> |
 | | Steven Johnson <[email protected]> |