feat(docs): Update voting docs, add cddl validation

.config/dictionaries/project.dic

@@ -27,6 +27,7 @@ cardano
 carryforward
 CBOR
 cbork
+cddlc
 cdylib
 CEST
 chacha

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

@@ -2,5 +2,5 @@ title: Catalyst Voting
 arrange:
     - crypto.md
     - gen_vote_tx.md
-    - jorm.md
-    - cat_v2.md
+    - v1.md
+    - v2.md

docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile

@@ -0,0 +1,19 @@
+VERSION 0.8
+
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.2.23 AS cddl-ci
+
+check-cddl:
+    FROM cddl-ci+cddl-base
+
+    WORKDIR /cddl
+
+    COPY ./gen_vote_tx.cddl \
+         ./vote_tx_v2_public.cddl \
+         ./vote_tx_v2_private.cddl \
+         ./gen_vote_tx_cose_payload.cddl \
+        .
+
+    RUN cddlc -2 gen_vote_tx_cose_payload.cddl
+    RUN cddlc -2 gen_vote_tx.cddl
+    RUN cddlc -2 vote_tx_v2_public.cddl
+    RUN cddlc -2 vote_tx_v2_private.cddl

docs/src/architecture/08_concepts/catalyst_voting/cddl/blueprint.cue

@@ -0,0 +1,2 @@
+version: "1.0.0"
+project: name: "docs-catalyst-voting-cddl"

docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl

@@ -1,31 +1,33 @@
-gen-vote-tx = [
-    tx-body,
+gen-vote-tx<choice-t, proof-t, prop-id-t> = [
+    tx-body<choice-t, proof-t, prop-id-t>,
     signature
 ]
 
-tx-body = [
+tx-body<choice-t, proof-t, prop-id-t> = [
     vote-type
     event,
-    votes,
+    votes<choice-t, proof-t, prop-id-t>,
     voters-data,
 ]
 
 vote-type = UUID ; e.g. Public or Private vote
 event = { * event-key => any }
 event-key = int / text
 
-votes = [+ vote]
-vote = [
-    choices,
-    proof \ null,
-    prop-id \ null,
+votes<choice-t, proof-t, prop-id-t> = [+ vote<choice-t, proof-t, prop-id-t>]
+vote<choice-t, proof-t, prop-id-t>  = [
+    choices<choice-t>,
+    proof<proof-t>,
+    prop-id<prop-id-t>,
 ]
-choices = [+ choice]
-choice = encoded-cbor
-proof = encoded-cbor
-prop-id = encoded-cbor
+choices<choice-t> = [+ choice<choice-t>]
+choice<choice-t> = #6.24(bytes .cbor choice-t) ; encoded-cbor
+proof<proof-t> = #6.24(bytes .cbor proof-t) ; encoded-cbor
+prop-id<prop-id-t> = #6.24(bytes .cbor prop-id-t) ; encoded-cbor
 
 voters-data = encoded-cbor
 
 UUID = #6.37(bytes) ; UUID type
-signature = #6.98(COSE_Sign) ; COSE signature
+signature = #6.98(cose.COSE_Sign) ; COSE signature
+
+;# import rfc9052 as cose

docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl

@@ -1,2 +1,2 @@
 cose-payload = blake2b-256
-blake2b-256 = #6.32782(bytes .size 32) ; Blake2b-256 hash bytes
+blake2b-256 = #6.32782(bytes .size 32) ; Blake2b-256 hash bytes

docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl

@@ -0,0 +1,19 @@
+vote-tx-v2 = gen-vote-tx<choice-data, proof-data, proposal>
+
+choice-data = ciphertext
+ciphertext = [group-element, group-element]
+
+proposal = UUID
+
+proof-data = zk-proof
+
+zk-proof = [[+ (announcement, ~ciphertext, r-response)], scalar]
+
+announcement = (group-element, group-element, group-element)
+r-response = (scalar, scalar, scalar)
+
+scalar = bytes .size 32
+group-element = bytes .size 32
+
+;# include gen_vote_tx
+

docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl

@@ -0,0 +1,8 @@
+vote-tx-v2-public = gen-vote-tx<choice-data, proof-data, proposal>
+
+choice-data = uint
+proof-data = undefined
+proposal = UUID
+
+;# include gen_vote_tx
+

docs/src/architecture/08_concepts/catalyst_voting/jorm.md → docs/src/architecture/08_concepts/catalyst_voting/v1.md

@@ -1,4 +1,4 @@
-# Jörmungandr
+# V1 (Jörmungandr)
 
 ---
 
@@ -16,6 +16,8 @@ Created: 2024-10-24
 ## Abstract
 
 This document describes a definition of the original Jörmungandr `VoteCast` transaction.
+It's not based on the ["General Voting Transaction"](./gen_vote_tx.md) specification
+and just represents an original transaction structure from the Jörmungandr blockchain.
 
 ## Motivation
 
@@ -130,5 +132,3 @@ Expected witness (includes signature)
 [BLAKE2b-256]: https://www.blake2.net/blake2.pdf
 [BLAKE2b-512]: https://www.blake2.net/blake2.pdf
 [ristretto255]: https://ristretto.group
-<!-- [COSE]: https://datatracker.ietf.org/doc/rfc9052/ -->
-<!-- [CBOR]: https://datatracker.ietf.org/doc/rfc8949/ -->

docs/src/architecture/08_concepts/catalyst_voting/v2.md

@@ -0,0 +1,108 @@
+# V2
+
+---
+
+Title: Catalyst V2 Voting Transaction
+
+Status: Proposed
+
+Authors:
+    - Alex Pozhylenkov <[email protected]>
+
+Created: 2024-10-24
+
+---
+
+## Abstract
+
+This document describes a Catalyst V2 vote transaction structure.
+
+## Motivation
+
+## Specification
+
+It is a Catalyst v2 voting transaction
+defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specification) structure.
+
+Following that spec need to define a `choice`, `proof` and `prop-id`.
+
+Also needed to define an `event` field,
+so for both public and private transaction it must be the following:
+
+```CDDL
+event = {
+    "brand_id": UUID,
+    "campaign_id": UUID,
+    "election_id": UUID,
+    "category_id": UUID,
+}
+```
+
+* `brand_id` - a unique identifier which represents a "brand" who is running the voting,
+    e.g. Catalyst, Midnight.
+* `campaign_id` - a unique identifier which defines a "campaign" of voting,
+    e.g. "treasury campaign".
+* `election_id` - a unique identifier which defines an election,
+    e.g. "Catalyst Fund 1", "Catalyst Fund 2".
+* `category_id` - a unique identifier which defines a voting category as a collection of proposals,
+    e.g. "Development & Infrastructure", "Products & Integrations".
+
+### Public vote
+
+<!-- markdownlint-disable max-one-sentence-per-line code-block-style -->
+??? note "Public vote transaction v2 definition: `vote_tx_v2_public.cddl`"
+
+    ```CDDL
+    {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl', indent=4) }}
+    ```
+<!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
+
+For the public vote `vote-type` value defined as follows:
+
+```CDDL
+vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742-7be3c8592803
+```
+
+### Private vote
+
+<!-- markdownlint-disable max-one-sentence-per-line code-block-style -->
+??? note "Private vote transaction v2 definition: `vote_tx_v2_private.cddl`"
+
+    ```CDDL
+    {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl', indent=4) }}
+    ```
+<!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
+
+For the private vote `vote-type` value defined as follows:
+
+```CDDL
+vote-type = #6.37(h'E78EE18DF38044C1A85280AA6ECB07FE') ; e78ee18d-f380-44c1-a852-80aa6ecb07fe
+```
+
+#### Vote and Proof generation
+
+To generate a cryptographically secured `choice-data` and `zk_proof` parts you can follow this [spec](./crypto.md#vote).
+Important to note,
+that as part of [*initial setup*](./crypto.md#initial-setup) of the voting procedure,
+the following properties are used:
+
+1. Each proposal, defined by the `proposal` field, defines a number of possible options.
+2. [ristretto255] as a backend cryptographic group.
+3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the `proposal` bytes.
+
+## Rationale
+
+## Path to Active
+
+### Acceptance Criteria
+<!-- Describes what are the acceptance criteria whereby a proposal becomes 'Active' -->
+
+### Implementation Plan
+<!-- A plan to meet those criteria or `N/A` if an implementation plan is not applicable. -->
+
+<!-- OPTIONAL SECTIONS: see CIP-0001 > Document > Structure table -->
+
+[BLAKE2b-512]: https://www.blake2.net/blake2.pdf
+[ristretto255]: https://ristretto.group
+<!-- [COSE]: https://datatracker.ietf.org/doc/rfc9052/ -->
+<!-- [CBOR]: https://datatracker.ietf.org/doc/rfc8949/ -->

docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile

@@ -0,0 +1,14 @@
+VERSION 0.8
+
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.2.23 AS cddl-ci
+
+check-cddl:
+    FROM cddl-ci+cddl-base
+
+    WORKDIR /cddl
+
+    COPY ./block.cddl ./genesis_to_prev_hash.cddl ./hash.cddl .
+
+    RUN cddlc -2 hash.cddl
+    RUN cddlc -2 block.cddl
+    RUN cddlc -2 genesis_to_prev_hash.cddl