diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/collaborators.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/collaborators.cddl
index 9aab4024c2..200bd91542 100644
--- a/docs/src/architecture/08_concepts/signed_doc/cddl/collaborators.cddl
+++ b/docs/src/architecture/08_concepts/signed_doc/cddl/collaborators.cddl
@@ -2,6 +2,9 @@
; Allowed Collaborators on the next subsequent version of a document.
+; Sorting for each array element follows the same sort order as specified for Map Keys,
+; as defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering),
+; and all array elements are unique.
collaborators = [ + catalyst_id_kid ]
; UTF8 Catalyst ID URI encoded as a bytes string.
diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/contest_ballot_payload.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/contest_ballot_payload.cddl
index 85f84af64a..e6cf0116e8 100644
--- a/docs/src/architecture/08_concepts/signed_doc/cddl/contest_ballot_payload.cddl
+++ b/docs/src/architecture/08_concepts/signed_doc/cddl/contest_ballot_payload.cddl
@@ -5,47 +5,12 @@
; Catalyst Vote Payload data object.
contest-ballot-payload = {
- + document_ref => choices
+ + uint => choices
? "column-proof" : column-proof
? "matrix-proof" : matrix-proof
? "voter-choice" : voter-choice
}
-; 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.
-; Currently limited to SHA2-256 based CIDs.
-cid = #6.42(bytes .abnfb ("cid" .det cbor-cid ))
-
-; CIDv1 ABNF Constrained for SHA2-256
-cbor-cid = '
- cid = cidv1 codec-cbor sha2-256 digest-32 digest
- cidv1 = %x00 %x01
- codec-cbor = %x51
- sha2-256 = %x12
- digest-32 = %x20
- digest = 32(%x00-FF)
-'
-
; Voters Choices.
choices = [ 0, clear-choices ] /
[ 1, elgamal-ristretto255-encrypted-choices ]
diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/document_refs.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/document_refs.cddl
index d590dbcd9d..6f156e0ada 100644
--- a/docs/src/architecture/08_concepts/signed_doc/cddl/document_refs.cddl
+++ b/docs/src/architecture/08_concepts/signed_doc/cddl/document_refs.cddl
@@ -1,8 +1,11 @@
; document_refs
-; Reference to one or more Signed Documents
-document_refs = [ 1* document_ref ]
+; Reference to one or more Signed Documents.
+; Sorting for each array element follows the same sort order as specified for Map Keys,
+; as defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering),
+; and all array elements are unique.
+document_refs = [ + document_ref ]
; Reference to a single Signed Document
document_ref = [
diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/document_type.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/document_type.cddl
index f7be1d480b..d1a4de1e91 100644
--- a/docs/src/architecture/08_concepts/signed_doc/cddl/document_type.cddl
+++ b/docs/src/architecture/08_concepts/signed_doc/cddl/document_type.cddl
@@ -2,7 +2,7 @@
; Document Type
-document_type = [ 1* uuid_v4 ]
+document_type = uuid_v4
; UUIDv4
uuid_v4 = #6.37(bytes .size 16)
diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/signed_document.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/signed_document.cddl
index 1e5834cf36..f38336b0f1 100644
--- a/docs/src/architecture/08_concepts/signed_doc/cddl/signed_document.cddl
+++ b/docs/src/architecture/08_concepts/signed_doc/cddl/signed_document.cddl
@@ -76,7 +76,7 @@ Signed_Document_Metadata_Headers = (
)
; Document Type
-document_type = [ 1* uuid_v4 ]
+document_type = uuid_v4
; UUIDv4
uuid_v4 = #6.37(bytes .size 16)
@@ -90,8 +90,11 @@ uuid_v7 = #6.37(bytes .size 16)
; Document Version
document_ver = uuid_v7
-; Reference to one or more Signed Documents
-document_refs = [ 1* document_ref ]
+; Reference to one or more Signed Documents.
+; Sorting for each array element follows the same sort order as specified for Map Keys,
+; as defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering),
+; and all array elements are unique.
+document_refs = [ + document_ref ]
; Reference to a single Signed Document
document_ref = [
@@ -127,6 +130,9 @@ section_ref = json_pointer
json_pointer = text
; Allowed Collaborators on the next subsequent version of a document.
+; Sorting for each array element follows the same sort order as specified for Map Keys,
+; as defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering),
+; and all array elements are unique.
collaborators = [ + catalyst_id_kid ]
; UTF8 Catalyst ID URI encoded as a bytes string.
diff --git a/docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot b/docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot
index 2f6a89b85c..7b30594324 100644
--- a/docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot
+++ b/docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot
@@ -377,6 +377,101 @@ digraph "All" {
];
+ "Proposal" [
+ id="Proposal";
+ label=<
+
+ >
+ ];
+
+
"Proposal Comment" [
id="Proposal Comment";
label=<
@@ -221,6 +236,7 @@ Relationships"
"Proposal":"template":e -> "Proposal Form Template":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
"Proposal":"parameters":e -> "Brand Parameters" [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*", lhead="cluster_system_parameters"]
+ "Contest Ballot":"title":e -> "Proposal":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
"Proposal Comment":"title":e -> "Proposal":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
"Proposal Moderation Action":"title":e -> "Proposal":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
"Proposal Submission Action":"title":e -> "Proposal":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
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
index ff6cd9a882..db1bc68e18 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters.md
@@ -210,7 +210,7 @@ of the previous submitted document's version.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters_form_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters_form_template.md
index 55d779c514..d718fcd259 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters_form_template.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters_form_template.md
@@ -131,7 +131,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
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
index 000367d455..8a38a0315c 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters.md
@@ -239,7 +239,7 @@ of the previous submitted document's version.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters_form_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters_form_template.md
index d6f93043cb..6d1c5b4c16 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters_form_template.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters_form_template.md
@@ -159,7 +159,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
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
index bb61287fb9..88e9d37f3c 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/category_parameters.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/category_parameters.md
@@ -239,7 +239,7 @@ of the previous submitted document's version.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/category_parameters_form_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/category_parameters_form_template.md
index 1fe27ac3f8..4d19b3bf7d 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/category_parameters_form_template.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/category_parameters_form_template.md
@@ -159,7 +159,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
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
index 8ba7f61a7b..a4a8683923 100644
--- 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
@@ -163,7 +163,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/contest_ballot.md b/docs/src/architecture/08_concepts/signed_doc/docs/contest_ballot.md
index a02b128552..c7bb3b9cff 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/contest_ballot.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/contest_ballot.md
@@ -108,6 +108,52 @@ The first version of the document must set [`ver`](../metadata.md#ver) == [`id`]
The document version must always be >= the document ID.
+### [`ref`](../metadata.md#ref)
+
+
+| Parameter | Value |
+| --- | --- |
+| Required | yes |
+| Format | [Document Reference](../metadata.md#document-reference) |
+| Multiple References | True |
+| Valid References | [Proposal](proposal.md) |
+
+Reference to a Linked Document or Documents.
+This is the primary hierarchical reference to a related document.
+
+If a reference is defined as required, there must be at least 1 reference specified.
+Some documents allow multiple references, and they are documented as required.
+
+The document reference serves two purposes:
+
+1. It ensures that the document referenced by an ID/Version is not substituted.
+ In other words, that the document intended to be referenced, is actually referenced.
+2. It Allows the document to be unambiguously located in decentralized storage systems.
+
+There can be any number of Document Locations in any reference.
+The currently defined locations are:
+
+* `cid` : A [CBOR Encoded IPLD Content Identifier][CBOR-TAG-42] ( AKA an [IPFS CID][IPFS-CID] ).
+* Others may be added when further storage mechanisms are defined.
+
+The document location does not guarantee that the document is actually stored.
+It only defines that if it were stored, this is the identifier
+that is required to retrieve it.
+Therefore it is required that Document References
+are unique and reproducible, given a documents contents.
+
+#### [`ref`](../metadata.md#ref) Validation
+
+The following must be true for a valid reference:
+
+* The Referenced Document **MUST** Exist
+* Every value in the `document_locator` must consistently reference the exact same document.
+* The `document_id` and `document_ver` **MUST** match the values in the referenced document.
+* In the event there are **MULTIPLE** [`ref`](../metadata.md#ref) listed, they **MUST** be sorted.
+
+Sorting for each element of [`ref`](../metadata.md#ref) follows the same sort order as specified for Map Keys,
+as defined by [CBOR Deterministic Encoding][CBOR-LFD-ENCODING] (4.3.2 Length-First Map Key Ordering).
+
### [`revocations`](../metadata.md#revocations)
@@ -144,6 +190,7 @@ Such documents may never be submitted.
| Required | yes |
| Format | [Document Reference](../metadata.md#document-reference) |
| Valid References | [Contest Parameters](contest_parameters.md) |
+| Linked Reference Metadata | [`ref`](#ref) |
A reference to the Parameters Document this document lies under.
@@ -164,15 +211,20 @@ The profile template, or proposal templates could be defined at any of these
levels, and as long as they all refer to the same chain of parameters in the
hierarchy they are all valid.
+* The Document referenced by [`ref`](../metadata.md#ref)
+ * MUST contain [`parameters`](../metadata.md#parameters) metadata; AND
+ * MUST match the referencing documents [`parameters`](../metadata.md#parameters) value.
+
## Payload
The Payload is a [CBOR][RFC8949] document that must conform to the `contest-ballot-payload` [CDDL][RFC8610].
Contents
-* `document_ref => choices`
- * The payload is a map keyed by a proposal `document_ref`.
- * Each key identifies one specific proposal via `[document_id, document_ver, document_locator]`.
+* `uint => choices`
+ * The payload is a map keyed by a `uint` index to the array element from [`ref`](../metadata.md#ref) metadata field,
+ which is a proposal `document_ref`.
+ * Each identifies one specific proposal via `[document_id, document_ver, document_locator]`.
* The value for each key is that voter’s `choices` for that proposal.
* There is exactly one set of `choices` per referenced proposal (no duplicates).
@@ -215,76 +267,6 @@ Notes
#### Sub-schemas
-
-??? note "Required Definition: document_ref"
-
- * [document_ref.cddl](../cddl/document_ref.cddl)
-
- ``` cddl
- {{ include_file('./../cddl/document_ref.cddl', indent=4) }}
- ```
-
-
-
-??? note "Required Definition: document_id"
-
- * [document_id.cddl](../cddl/document_id.cddl)
-
- ``` cddl
- {{ include_file('./../cddl/document_id.cddl', indent=4) }}
- ```
-
-
-
-??? note "Required Definition: uuid_v7"
-
- * [uuid_v7.cddl](../cddl/uuid_v7.cddl)
-
- ``` cddl
- {{ include_file('./../cddl/uuid_v7.cddl', indent=4) }}
- ```
-
-
-
-??? note "Required Definition: document_ver"
-
- * [document_ver.cddl](../cddl/document_ver.cddl)
-
- ``` cddl
- {{ include_file('./../cddl/document_ver.cddl', indent=4) }}
- ```
-
-
-
-??? note "Required Definition: document_locator"
-
- * [document_locator.cddl](../cddl/document_locator.cddl)
-
- ``` cddl
- {{ include_file('./../cddl/document_locator.cddl', indent=4) }}
- ```
-
-
-
-??? note "Required Definition: cid"
-
- * [cid.cddl](../cddl/cid.cddl)
-
- ``` cddl
- {{ include_file('./../cddl/cid.cddl', indent=4) }}
- ```
-
-
-
-??? note "Required Definition: cbor-cid"
-
- * [cbor_cid.cddl](../cddl/cbor_cid.cddl)
-
- ``` cddl
- {{ include_file('./../cddl/cbor_cid.cddl', indent=4) }}
- ```
-
-
??? note "Required Definition: choices"
@@ -479,7 +461,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
@@ -491,8 +473,16 @@ Only the original author can update and sign a new version of documents.
* Add Voting Ballots and Ballot Checkpoint Documents
+#### 0.2.1 (2025-12-02)
+
+* Added missing [`ref`](../metadata.md#ref) metadata field definition.
+* Improved `payload` [cddl][RFC8610] definition, replaced `document_ref` to the `uint` as a map keys to the `choices`.
+
+[CBOR-TAG-42]: https://github.com/ipld/cid-cbor/
+[CBOR-LFD-ENCODING]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.3
[RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
[CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
+[IPFS-CID]: https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid
[RFC9562-V7]: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7
[RFC8949]: https://www.rfc-editor.org/rfc/rfc8949.html
[RFC8610]: https://www.rfc-editor.org/rfc/rfc8610
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/contest_ballot_checkpoint.md b/docs/src/architecture/08_concepts/signed_doc/docs/contest_ballot_checkpoint.md
index de3638a503..242dbb7b9b 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/contest_ballot_checkpoint.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/contest_ballot_checkpoint.md
@@ -516,7 +516,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/contest_delegation.md b/docs/src/architecture/08_concepts/signed_doc/docs/contest_delegation.md
index b86caa7a90..46a6c7f345 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/contest_delegation.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/contest_delegation.md
@@ -359,7 +359,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/contest_parameters.md b/docs/src/architecture/08_concepts/signed_doc/docs/contest_parameters.md
index 3499f8f677..9e29c4003f 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/contest_parameters.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/contest_parameters.md
@@ -241,7 +241,7 @@ of the previous submitted document's version.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/contest_parameters_form_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/contest_parameters_form_template.md
index ea1a291fa1..bea92b3d25 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/contest_parameters_form_template.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/contest_parameters_form_template.md
@@ -161,7 +161,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/presentation_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/presentation_template.md
index 6def7261a0..fd71576e91 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/presentation_template.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/presentation_template.md
@@ -251,7 +251,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal.md
index b623b3059a..c308fdf2d4 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/proposal.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/proposal.md
@@ -278,7 +278,7 @@ of the previous submitted document's version.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
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
index f55f5e9600..b4fff6ee5d 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment.md
@@ -278,7 +278,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment_form_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment_form_template.md
index 2f9fe0a7dc..7c7d3a6ddb 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment_form_template.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment_form_template.md
@@ -161,7 +161,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_form_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_form_template.md
index 8a6f993e11..c72dac9eaf 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_form_template.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_form_template.md
@@ -161,7 +161,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
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
index 46b19fa857..aa85cab653 100644
--- 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
@@ -163,7 +163,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
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
index 9ed5c8bf70..03c25f0a12 100644
--- 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
@@ -373,7 +373,7 @@ of the referenced document specified by the 'ref' metadata field.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/rep_nomination.md b/docs/src/architecture/08_concepts/signed_doc/docs/rep_nomination.md
index d0b5081731..5e1cddcd0c 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/rep_nomination.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/rep_nomination.md
@@ -284,7 +284,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/rep_nomination_form_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/rep_nomination_form_template.md
index 36d9954ae2..d954836ee9 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/rep_nomination_form_template.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/rep_nomination_form_template.md
@@ -159,7 +159,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/rep_profile.md b/docs/src/architecture/08_concepts/signed_doc/docs/rep_profile.md
index a17a7e8db8..8845927b21 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/rep_profile.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/rep_profile.md
@@ -195,7 +195,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/rep_profile_form_template.md b/docs/src/architecture/08_concepts/signed_doc/docs/rep_profile_form_template.md
index 60d79a6239..76f0faf479 100644
--- a/docs/src/architecture/08_concepts/signed_doc/docs/rep_profile_form_template.md
+++ b/docs/src/architecture/08_concepts/signed_doc/docs/rep_profile_form_template.md
@@ -159,7 +159,7 @@ Only the original author can update and sign a new version of documents.
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/metadata.md b/docs/src/architecture/08_concepts/signed_doc/metadata.md
index 41604a26ff..5f81ee8c47 100644
--- a/docs/src/architecture/08_concepts/signed_doc/metadata.md
+++ b/docs/src/architecture/08_concepts/signed_doc/metadata.md
@@ -639,7 +639,7 @@ classDiagram
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/docs/src/architecture/08_concepts/signed_doc/spec.md b/docs/src/architecture/08_concepts/signed_doc/spec.md
index fb81d51087..9cf44ad4e1 100644
--- a/docs/src/architecture/08_concepts/signed_doc/spec.md
+++ b/docs/src/architecture/08_concepts/signed_doc/spec.md
@@ -565,7 +565,7 @@ Catalyst ID URI iden
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
@@ -640,6 +640,11 @@ Catalyst ID URI iden
* 'content encoding' metadata field become non optional for all document types where it was an optional field.
* Added new 'payload.schema' type - [CDDL][RFC8610] schema, defined as string.
+#### 0.2.1 (2025-12-02)
+
+* Added missing [`ref`](metadata.md#ref) metadata field definition.
+* Improved `payload` [cddl][RFC8610] definition, replaced `document_ref` to the `uint` as a map keys to the `choices`.
+
[CBOR-LFD-ENCODING]: https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.3
[RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
[JSON Schema-2020-12]: https://json-schema.org/draft/2020-12
diff --git a/docs/src/architecture/08_concepts/signed_doc/types.md b/docs/src/architecture/08_concepts/signed_doc/types.md
index 3004b8d1b2..aeefad96f9 100644
--- a/docs/src/architecture/08_concepts/signed_doc/types.md
+++ b/docs/src/architecture/08_concepts/signed_doc/types.md
@@ -42,7 +42,7 @@ All Defined Document Types
| --- | --- |
| License | This document is licensed under [CC-BY-4.0] |
| Created | 2024-12-27 |
-| Modified | 2025-11-10 |
+| Modified | 2025-12-02 |
| Authors | Alex Pozhylenkov |
| | Nathan Bogale |
| | Neil McAuliffe |
diff --git a/rust/catalyst-signed-doc-spec/Cargo.toml b/rust/catalyst-signed-doc-spec/Cargo.toml
index 04e7928e44..01808175bb 100644
--- a/rust/catalyst-signed-doc-spec/Cargo.toml
+++ b/rust/catalyst-signed-doc-spec/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "catalyst-signed-doc-spec"
-version = "0.2.0"
+version = "0.2.1"
edition.workspace = true
authors.workspace = true
homepage.workspace = true
diff --git a/specs/definitions/cddl/contest_ballot_payload.cue b/specs/definitions/cddl/contest_ballot_payload.cue
index 29b85913bc..9d624903cb 100644
--- a/specs/definitions/cddl/contest_ballot_payload.cue
+++ b/specs/definitions/cddl/contest_ballot_payload.cue
@@ -8,7 +8,6 @@ package cddl
cddlDefinitions: {
"contest-ballot-payload": {
requires: [
- "document_ref",
"choices",
"column-proof",
"matrix-proof",
@@ -16,10 +15,10 @@ cddlDefinitions: {
]
def: """
{
- + \(requires[0]) => \(requires[1])
+ + uint => \(requires[0])
+ ? "\(requires[1])" : \(requires[1])
? "\(requires[2])" : \(requires[2])
? "\(requires[3])" : \(requires[3])
- ? "\(requires[4])" : \(requires[4])
}
"""
description: """
diff --git a/specs/definitions/cddl/signed_doc.cue b/specs/definitions/cddl/signed_doc.cue
index 584ec0ab8a..bd7e0ed6a2 100644
--- a/specs/definitions/cddl/signed_doc.cue
+++ b/specs/definitions/cddl/signed_doc.cue
@@ -5,7 +5,7 @@ package cddl
cddlDefinitions: #cddlDefinitions & {
document_type: {
- def: "[ 1* \(requires[0]) ]"
+ def: "\(requires[0])"
requires: ["uuid_v4"]
description: "Unique Document Type Identifier"
comment: "Document Type"
@@ -32,11 +32,16 @@ cddlDefinitions: #cddlDefinitions & {
comment: "Where a document can be located, must be a unique identifier."
}
document_refs: {
- def: "[ 1* \(requires[0]) ]"
+ def: "[ + \(requires[0]) ]"
requires: [
"document_ref",
]
- comment: "Reference to one or more Signed Documents"
+ comment: """
+ Reference to one or more Signed Documents.
+ Sorting for each array element follows the same sort order as specified for Map Keys,
+ as defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering),
+ and all array elements are unique.
+ """
}
document_ref: {
def: """
@@ -61,7 +66,12 @@ cddlDefinitions: #cddlDefinitions & {
collaborators: {
def: "[ + \(requires[0]) ]"
requires: ["catalyst_id_kid"]
- comment: "Allowed Collaborators on the next subsequent version of a document."
+ comment: """
+ Allowed Collaborators on the next subsequent version of a document.
+ Sorting for each array element follows the same sort order as specified for Map Keys,
+ as defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering),
+ and all array elements are unique.
+ """
}
revocations: {
def: "[ * \(requires[0]) ] / true "
diff --git a/specs/definitions/signed_docs/authors_copyright.cue b/specs/definitions/signed_docs/authors_copyright.cue
index bb7032941c..a5b6b1fa79 100644
--- a/specs/definitions/signed_docs/authors_copyright.cue
+++ b/specs/definitions/signed_docs/authors_copyright.cue
@@ -141,5 +141,13 @@ copyright: #copyrightNotice & {
* Added new 'payload.schema' type - CDDL schema, defined as string.
"""
},
+ {
+ version: "0.2.1"
+ modified: "2025-12-02"
+ changes: """
+ * Added missing `ref` metadata field definition.
+ * Improved `payload` cddl definition, replaced `document_ref` to the `uint` as a map keys to the `choices`.
+ """
+ },
]
}
diff --git a/specs/definitions/signed_docs/docs/contest_ballot.cue b/specs/definitions/signed_docs/docs/contest_ballot.cue
index 409d39bf98..f0b88e3ac4 100644
--- a/specs/definitions/signed_docs/docs/contest_ballot.cue
+++ b/specs/definitions/signed_docs/docs/contest_ballot.cue
@@ -48,9 +48,17 @@ docs: "Contest Ballot": {
}
metadata: {
+ ref: {
+ required: "yes"
+ type: "Proposal"
+ multiple: true
+ }
parameters: {
required: "yes"
type: "Contest Parameters"
+ linked_refs: [
+ "ref",
+ ]
}
revocations: required: "optional"
}
@@ -63,9 +71,10 @@ docs: "Contest Ballot": {
Contents
- * `document_ref => choices`
- * The payload is a map keyed by a proposal `document_ref`.
- * Each key identifies one specific proposal via `[document_id, document_ver, document_locator]`.
+ * `uint => choices`
+ * The payload is a map keyed by a `uint` index to the array element from `ref` metadata field,
+ which is a proposal `document_ref`.
+ * Each identifies one specific proposal via `[document_id, document_ver, document_locator]`.
* The value for each key is that voter’s `choices` for that proposal.
* There is exactly one set of `choices` per referenced proposal (no duplicates).
@@ -111,5 +120,13 @@ docs: "Contest Ballot": {
* Add Voting Ballots and Ballot Checkpoint Documents
"""
},
+ {
+ version: "0.2.1"
+ modified: "2025-12-02"
+ changes: """
+ * Added missing `ref` metadata field definition.
+ * Improved `payload` cddl definition, replaced `document_ref` to the `uint` as a map keys to the `choices`.
+ """
+ },
]
}
diff --git a/specs/signed_doc.json b/specs/signed_doc.json
index 6f79570867..2e8ede0766 100644
--- a/specs/signed_doc.json
+++ b/specs/signed_doc.json
@@ -177,7 +177,7 @@
]
},
"collaborators": {
- "comment": "Allowed Collaborators on the next subsequent version of a document.",
+ "comment": "Allowed Collaborators on the next subsequent version of a document.\nSorting for each array element follows the same sort order as specified for Map Keys,\nas defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering),\nand all array elements are unique.",
"def": "[ + catalyst_id_kid ]",
"requires": [
"catalyst_id_kid"
@@ -222,7 +222,7 @@
},
"contest-ballot-payload": {
"comment": "Catalyst Vote Payload data object.",
- "def": "{\n\t+ document_ref => choices\n\t? \"column-proof\" : column-proof\n\t? \"matrix-proof\" : matrix-proof\n\t? \"voter-choice\" : voter-choice\n}",
+ "def": "{\n\t+ uint => choices\n\t? \"column-proof\" : column-proof\n\t? \"matrix-proof\" : matrix-proof\n\t? \"voter-choice\" : voter-choice\n}",
"description": "Catalyst Vote Payload data object.\n\nA vote payload that can hold both encrypted or unencrypted votes.",
"examples": [
{
@@ -237,7 +237,6 @@
}
],
"requires": [
- "document_ref",
"choices",
"column-proof",
"matrix-proof",
@@ -269,15 +268,15 @@
]
},
"document_refs": {
- "comment": "Reference to one or more Signed Documents",
- "def": "[ 1* document_ref ]",
+ "comment": "Reference to one or more Signed Documents.\nSorting for each array element follows the same sort order as specified for Map Keys,\nas defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering),\nand all array elements are unique.",
+ "def": "[ + document_ref ]",
"requires": [
"document_ref"
]
},
"document_type": {
"comment": "Document Type",
- "def": "[ 1* uuid_v4 ]",
+ "def": "uuid_v4",
"description": "Unique Document Type Identifier",
"requires": [
"uuid_v4"
@@ -618,6 +617,11 @@
"changes": "* Added a new 'Contest Ballot' and 'Contest Ballot Checkpoint' document types.\n* Improved the specification for 'Contest Delegation' document type.\n* 'content encoding' metadata field become non optional for all document types where it was an optional field.\n* Added new 'payload.schema' type - CDDL schema, defined as string.",
"modified": "2025-11-10",
"version": "0.2.0"
+ },
+ {
+ "changes": "* Added missing `ref` metadata field definition.\n* Improved `payload` cddl definition, replaced `document_ref` to the `uint` as a map keys to the `choices`.",
+ "modified": "2025-12-02",
+ "version": "0.2.1"
}
]
},
@@ -1638,7 +1642,9 @@
"parameters": {
"description": "A reference to the Parameters Document this document lies under.",
"format": "Document Reference",
- "linked_refs": null,
+ "linked_refs": [
+ "ref"
+ ],
"multiple": false,
"required": "yes",
"type": "Contest Parameters",
@@ -1647,7 +1653,10 @@
"ref": {
"description": "Reference to a Linked Document or Documents. \nThis is the primary hierarchical reference to a related document.\t\t\t\n\nIf a reference is defined as required, there must be at least 1 reference specified.\nSome documents allow multiple references, and they are documented as required.\n\nThe document reference serves two purposes:\n \n1. It ensures that the document referenced by an ID/Version is not substituted.\n\tIn other words, that the document intended to be referenced, is actually referenced.\n2. It Allows the document to be unambiguously located in decentralized storage systems.\n\nThere can be any number of Document Locations in any reference.\nThe currently defined locations are:\n\n* `cid` : A CBOR Encoded IPLD Content Identifier ( AKA an IPFS CID ).\n* Others may be added when further storage mechanisms are defined.\n\nThe document location does not guarantee that the document is actually stored.\nIt only defines that if it were stored, this is the identifier\nthat is required to retrieve it.\nTherefore it is required that Document References\nare unique and reproducible, given a documents contents.",
"format": "Document Reference",
- "required": "excluded",
+ "linked_refs": null,
+ "multiple": true,
+ "required": "yes",
+ "type": "Proposal",
"validation": "The following must be true for a valid reference:\n\n* The Referenced Document **MUST** Exist\n* Every value in the `document_locator` must consistently reference the exact same document.\n* The `document_id` and `document_ver` **MUST** match the values in the referenced document.\n* In the event there are **MULTIPLE** `ref` listed, they **MUST** be sorted.\n\nSorting for each element of `ref` follows the same sort order as specified for Map Keys, \nas defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering)."
},
"reply": {
@@ -1689,7 +1698,7 @@
},
"notes": [],
"payload": {
- "description": "The Payload is a CBOR document that must conform to the `contest-ballot-payload` CDDL.\n\nContents\n\n* `document_ref => choices`\n\t* The payload is a map keyed by a proposal `document_ref`.\n\t* Each key identifies one specific proposal via `[document_id, document_ver, document_locator]`.\n\t* The value for each key is that voter’s `choices` for that proposal.\n\t* There is exactly one set of `choices` per referenced proposal (no duplicates).\n\n* `choices`\n\t* Discriminated union of unencrypted or encrypted choices.\n\n* `row-proof` (optional, inside encrypted choices)\n \t* Proves, without revealing contents, that the encrypted row encodes a unit vector with exactly one selection.\n\n* `column-proof` (optional, top-level)\n\t* Placeholder for future column-level proofs across proposals.\n\t* Not defined at present; omit in implementations.\n\n* `matrix-proof` (optional, top-level)\n\t* Placeholder for future matrix-wide proofs across all proposals and positions.\n\t* Not defined at present; omit in implementations.\n\n* `voter-choice` (optional, top-level)\n\t* This is ONLY Not included when the vote is unencrypted.\n\t* Allows a voter to read back their ballot selections without decrypting the entire ballot.\n\nNotes\n\n* `document_locator` uses a CBOR Tag 42 `cid` to locate the referenced proposal in content-addressed storage.\n Implementations should constrain the CID to SHA2-256 multihash; the multicodec SHOULD be `cbor (0x51)` to\n reflect an unwrapped COSE_Sign CBOR block.\n* The application defines the permissible range and semantics of `clear-choice` integers.\n* All CBOR must use core-deterministic encoding so that content addressing remains stable.",
+ "description": "The Payload is a CBOR document that must conform to the `contest-ballot-payload` CDDL.\n\nContents\n\n* `uint => choices`\n\t* The payload is a map keyed by a `uint` index to the array element from `ref` metadata field,\n\t which is a proposal `document_ref`.\n\t* Each identifies one specific proposal via `[document_id, document_ver, document_locator]`.\n\t* The value for each key is that voter’s `choices` for that proposal.\n\t* There is exactly one set of `choices` per referenced proposal (no duplicates).\n\n* `choices`\n\t* Discriminated union of unencrypted or encrypted choices.\n\n* `row-proof` (optional, inside encrypted choices)\n \t* Proves, without revealing contents, that the encrypted row encodes a unit vector with exactly one selection.\n\n* `column-proof` (optional, top-level)\n\t* Placeholder for future column-level proofs across proposals.\n\t* Not defined at present; omit in implementations.\n\n* `matrix-proof` (optional, top-level)\n\t* Placeholder for future matrix-wide proofs across all proposals and positions.\n\t* Not defined at present; omit in implementations.\n\n* `voter-choice` (optional, top-level)\n\t* This is ONLY Not included when the vote is unencrypted.\n\t* Allows a voter to read back their ballot selections without decrypting the entire ballot.\n\nNotes\n\n* `document_locator` uses a CBOR Tag 42 `cid` to locate the referenced proposal in content-addressed storage.\n Implementations should constrain the CID to SHA2-256 multihash; the multicodec SHOULD be `cbor (0x51)` to\n reflect an unwrapped COSE_Sign CBOR block.\n* The application defines the permissible range and semantics of `clear-choice` integers.\n* All CBOR must use core-deterministic encoding so that content addressing remains stable.",
"examples": [
{
"description": "Example Shows:\n\n* Three Proposals\n* Two Encrypted Choices\n* Row Proofs for each proposal.\n* `aes-ctr-encrypted-choices` which reflects the choices.\n\nThe Contest Private Key was: 0x1234562343....\nThe Contest Public Key was: 0x1324354235...\nThe AES encryption key for the `aes-ctr-encrypted-choices` is 0x123456789...",
@@ -1723,6 +1732,11 @@
"changes": "* Add Voting Ballots and Ballot Checkpoint Documents",
"modified": "2025-11-03",
"version": "0.1.5"
+ },
+ {
+ "changes": "* Added missing `ref` metadata field definition.\n* Improved `payload` cddl definition, replaced `document_ref` to the `uint` as a map keys to the `choices`.",
+ "modified": "2025-12-02",
+ "version": "0.2.1"
}
]
},