Skip to content

feat(docs): Contest Ballot payload improvement #674

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Dec 4, 2025
+1,294 −1,209
Merged

feat(docs): Contest Ballot payload improvement #674

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
70fc1f0
contest ballot payload update
Mr-Leshiy Dec 2, 2025
2121896
regenerate
Mr-Leshiy Dec 2, 2025
8491a09
fix CI
Mr-Leshiy Dec 2, 2025
c69695e
fix catalyst-signed-doc-spec build
Mr-Leshiy Dec 2, 2025
3c659ee
Merge branch 'main' into feat/contest-ballot-payload-update
Mr-Leshiy Dec 2, 2025
1a1faeb
wip
Mr-Leshiy Dec 3, 2025
ba7dbe8
wip
Mr-Leshiy Dec 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/src/architecture/08_concepts/signed_doc/cddl/collaborators.cddl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
37 changes: 1 addition & 36 deletions docs/src/architecture/08_concepts/signed_doc/cddl/contest_ballot_payload.cddl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 ]
Expand Down
7 changes: 5 additions & 2 deletions docs/src/architecture/08_concepts/signed_doc/cddl/document_refs.cddl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 = [
Expand Down
2 changes: 1 addition & 1 deletion docs/src/architecture/08_concepts/signed_doc/cddl/document_type.cddl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@


; Document Type
document_type = [ 1* uuid_v4 ]
document_type = uuid_v4

; UUIDv4
uuid_v4 = #6.37(bytes .size 16)
12 changes: 9 additions & 3 deletions docs/src/architecture/08_concepts/signed_doc/cddl/signed_document.cddl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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 = [
Expand Down Expand Up @@ -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.
Expand Down
205 changes: 108 additions & 97 deletions docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -377,6 +377,101 @@ digraph "All" {
];


"Proposal" [
id="Proposal";
label=<
<TABLE BORDER="2" COLOR="#29235c" CELLBORDER="1" CELLSPACING="0" CELLPADDING="10">
<TR>
<TD PORT="title" BGCOLOR="#1d71b8" HREF="./docs/proposal/">
<FONT COLOR="#ffffff"><B> Proposal </B></FONT>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="content type" BGCOLOR="#e7e2dd">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">content type</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>application/json</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="type" BGCOLOR="#b8b5b0">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">type</FONT></TD>
<TD ALIGN="RIGHT"><FONT FACE="Courier" COLOR="#7706E5"><B><I>7808d2ba-d511-40af-84e8-c0d1625fdfdc</I></B></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="id" BGCOLOR="#e7e2dd">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">id</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Document Id</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="ver" BGCOLOR="#b8b5b0">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">ver</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Document Ver</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="template" BGCOLOR="#e7e2dd">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">template</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Proposal Form Template</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="collaborators" BGCOLOR="#b8b5b0">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">collaborators</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Collaborators Reference List</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="revocations" BGCOLOR="#e7e2dd">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">revocations</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Version Revocations</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="parameters" BGCOLOR="#b8b5b0">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">parameters</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Brand Parameters<BR />Campaign Parameters<BR />Category Parameters</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>

</TABLE>
>
];


"Contest Parameters" [
id="Contest Parameters";
label=<
Expand Down Expand Up @@ -522,7 +617,17 @@ digraph "All" {
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="revocations" BGCOLOR="#e7e2dd">
<TD ALIGN="LEFT" PORT="ref" BGCOLOR="#e7e2dd">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">ref</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Proposal</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="revocations" BGCOLOR="#b8b5b0">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">revocations</FONT></TD>
Expand All @@ -532,7 +637,7 @@ digraph "All" {
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="parameters" BGCOLOR="#b8b5b0">
<TD ALIGN="LEFT" PORT="parameters" BGCOLOR="#e7e2dd">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">parameters</FONT></TD>
Expand Down Expand Up @@ -1007,101 +1112,6 @@ digraph "All" {
];


"Proposal" [
id="Proposal";
label=<
<TABLE BORDER="2" COLOR="#29235c" CELLBORDER="1" CELLSPACING="0" CELLPADDING="10">
<TR>
<TD PORT="title" BGCOLOR="#1d71b8" HREF="./docs/proposal/">
<FONT COLOR="#ffffff"><B> Proposal </B></FONT>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="content type" BGCOLOR="#e7e2dd">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">content type</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>application/json</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="type" BGCOLOR="#b8b5b0">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">type</FONT></TD>
<TD ALIGN="RIGHT"><FONT FACE="Courier" COLOR="#7706E5"><B><I>7808d2ba-d511-40af-84e8-c0d1625fdfdc</I></B></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="id" BGCOLOR="#e7e2dd">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">id</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Document Id</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="ver" BGCOLOR="#b8b5b0">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">ver</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Document Ver</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="template" BGCOLOR="#e7e2dd">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">template</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Proposal Form Template</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="collaborators" BGCOLOR="#b8b5b0">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">collaborators</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Collaborators Reference List</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="revocations" BGCOLOR="#e7e2dd">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">revocations</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Version Revocations</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>
<TR>
<TD ALIGN="LEFT" PORT="parameters" BGCOLOR="#b8b5b0">
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">parameters</FONT></TD>
<TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Brand Parameters<BR />Campaign Parameters<BR />Category Parameters</I></FONT></TD>
</TR>
</TABLE>
</TD>
</TR>

</TABLE>
>
];


"Proposal Comment Form Template" [
id="Proposal Comment Form Template";
label=<
Expand Down Expand Up @@ -1811,6 +1821,7 @@ digraph "All" {
"Category Parameters":"parameters":e -> "Campaign Parameters":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
"Category Parameters Form Template":"parameters":e -> "Campaign Parameters" [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*", lhead="cluster_system_parameters"]
"Comment Moderation Action":"ref":e -> "Proposal Comment":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
"Contest Ballot":"ref":e -> "Proposal":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
"Contest Ballot":"parameters":e -> "Contest Parameters":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
"Contest Ballot Checkpoint":"ref":e -> "Contest Ballot":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
"Contest Ballot Checkpoint":"parameters":e -> "Contest Parameters":"title":w [dir=forward, penwidth=6, color="#29235c", headlabel="1", taillabel="*"]
Expand Down
Loading