From bf625f932c2764d73c13974f67d98576d9487bf8 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Sun, 3 Nov 2024 10:36:37 +0200 Subject: [PATCH 01/17] fix gen_vote_tx structure --- Earthfile | 14 ++++++++++++++ .../catalyst_voting/cddl/gen_vote_tx.cddl | 16 ++++++++-------- .../catalyst_voting/cddl/vote_tx_v2.cddl | 9 ++------- 3 files changed, 24 insertions(+), 15 deletions(-) diff --git a/Earthfile b/Earthfile index a224708f32..5f69ecd003 100644 --- a/Earthfile +++ b/Earthfile @@ -41,3 +41,17 @@ repo-docs: COPY --dir *.md LICENSE-APACHE LICENSE-MIT . SAVE ARTIFACT /repo repo + +cddlc: + FROM ruby:3.3.0-alpine + + WORKDIR /cddl + + RUN gem install cddlc + + COPY ./docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl . + COPY ./docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl . + + RUN cddlc -u2tcddl vote_tx_v2.cddl + + diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl index 92dd63f420..42aa7720a3 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl @@ -15,15 +15,15 @@ event = { * event-key => any } event-key = int / text votes = [+ vote] -vote = [ - choices, - proof \ null, - prop-id \ null, +vote = [ + choices, + proof / null, + prop-id / null, ] -choices = [+ choice] -choice = encoded-cbor -proof = encoded-cbor -prop-id = encoded-cbor +choices = [+ choice] +choice = #6.24(bytes .cbor choice-t) ; encoded-cbor +proof = #6.24(bytes .cbor proof-t) ; encoded-cbor +prop-id = #6.24(bytes .cbor prop-id-t) ; encoded-cbor voters-data = encoded-cbor diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl index d1645e5d8c..73fa9da1a9 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl @@ -1,8 +1,4 @@ -vote-tx-v2 = gen-vote-tx - -choice = #6.24(bstr(choice-data)) -proof = #6.24(bstr(proof-data)) -prop-id = #6.24(bstr(proposal)) +vote-tx-v2 = gen-vote-tx choice-data = public-choice / private-choice @@ -16,10 +12,9 @@ proposal = UUID proof-data = zk-proof -zk-proof = [[+ (announcement, ciphertext, r-response)], scalar] +zk-proof = [[+ (announcement, ~ciphertext, r-response)], scalar] announcement = (group-element, group-element, group-element) -ciphertext = (group-element, group-element) r-response = (scalar, scalar, scalar) scalar = bytes .size 32 From ec1464103779c40fd74470fc50e63b328943f6b5 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 08:58:46 +0200 Subject: [PATCH 02/17] add cose import --- .../08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl index 42aa7720a3..6794a6443d 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl @@ -28,4 +28,6 @@ prop-id = #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 From b915d2212ab938df9b4fa9082806d46acd01a6b5 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 13:41:27 +0200 Subject: [PATCH 03/17] cleanup Earthfiles, add cddl-check target --- Earthfile | 14 -------------- .../08_concepts/catalyst_voting/cddl/Earthfile | 13 +++++++++++++ 2 files changed, 13 insertions(+), 14 deletions(-) create mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile diff --git a/Earthfile b/Earthfile index 5f69ecd003..a224708f32 100644 --- a/Earthfile +++ b/Earthfile @@ -41,17 +41,3 @@ repo-docs: COPY --dir *.md LICENSE-APACHE LICENSE-MIT . SAVE ARTIFACT /repo repo - -cddlc: - FROM ruby:3.3.0-alpine - - WORKDIR /cddl - - RUN gem install cddlc - - COPY ./docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl . - COPY ./docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl . - - RUN cddlc -u2tcddl vote_tx_v2.cddl - - diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile new file mode 100644 index 0000000000..f7d57151e7 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile @@ -0,0 +1,13 @@ +VERSION 0.8 + +IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:feat/cddl AS cddl-ci + +check-cddl: + FROM cddl-ci+cddl-base + + WORKDIR /cddl + + COPY ./docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl . + COPY ./docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl . + + RUN --no-cache cddlc -2tcddl vote_tx_v2.cddl \ No newline at end of file From 9e65f5c77655413d46a777acad65786d7e0e9708 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 13:45:37 +0200 Subject: [PATCH 04/17] update jorm spec --- docs/src/architecture/08_concepts/catalyst_voting/jorm.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md index 6dc3ba3575..e5dad981d9 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/jorm.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 - - From 27671148e3f0de249e2e4a24583a89c2d994f234 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 13:55:04 +0200 Subject: [PATCH 05/17] wip --- .../08_concepts/catalyst_voting/cat_v2.md | 2 +- .../catalyst_voting/cddl/gen_vote_tx.cddl | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md b/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md index 7ae9c7ec46..a6b9511539 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md @@ -1,4 +1,4 @@ -# Catalyst V2 +# V2 --- diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl index 6794a6443d..67635a0b20 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl @@ -1,12 +1,12 @@ -gen-vote-tx = [ - tx-body, +gen-vote-tx = [ + tx-body, signature ] -tx-body = [ +tx-body = [ vote-type event, - votes, + votes, voters-data, ] @@ -14,11 +14,11 @@ vote-type = UUID ; e.g. Public or Private vote event = { * event-key => any } event-key = int / text -votes = [+ vote] +votes = [+ vote] vote = [ choices, - proof / null, - prop-id / null, + proof, + prop-id, ] choices = [+ choice] choice = #6.24(bytes .cbor choice-t) ; encoded-cbor From a49638ab4ad258f26930771441dbee87c6464069 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 14:38:35 +0200 Subject: [PATCH 06/17] add cddl validation --- .../08_concepts/catalyst_voting/cddl/Earthfile | 7 ++++--- .../catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile index f7d57151e7..993d20b2b3 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile @@ -7,7 +7,8 @@ check-cddl: WORKDIR /cddl - COPY ./docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl . - COPY ./docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl . + COPY ./gen_vote_tx.cddl ./vote_tx_v2.cddl ./gen_vote_tx_cose_payload.cddl . - RUN --no-cache cddlc -2tcddl vote_tx_v2.cddl \ No newline at end of file + RUN cddlc -2 gen_vote_tx_cose_payload.cddl + RUN cddlc -2 gen_vote_tx.cddl + RUN cddlc -2 vote_tx_v2.cddl \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl index dd7cac02d5..f432c57404 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl +++ b/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 \ No newline at end of file +blake2b-256 = #6.32782(bytes .size 32) ; Blake2b-256 hash bytes From db89b974ecb8c0fabc778b017dccaef3e45ac9d4 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 14:41:59 +0200 Subject: [PATCH 07/17] add cddl validation for immutable_ledger specs --- .../08_concepts/catalyst_voting/cddl/Earthfile | 2 +- .../08_concepts/immutable_ledger/cddl/Earthfile | 13 +++++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile index 993d20b2b3..78089b8279 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile @@ -11,4 +11,4 @@ check-cddl: RUN cddlc -2 gen_vote_tx_cose_payload.cddl RUN cddlc -2 gen_vote_tx.cddl - RUN cddlc -2 vote_tx_v2.cddl \ No newline at end of file + RUN cddlc -2 vote_tx_v2.cddl diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile b/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile new file mode 100644 index 0000000000..1b863ba5f8 --- /dev/null +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile @@ -0,0 +1,13 @@ +VERSION 0.8 + +IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:feat/cddl AS cddl-ci + +check-cddl: + FROM cddl-ci+cddl-base + + WORKDIR /cddl + + COPY ./block.cddl ./genesis_to_prev_hash.cddl . + + RUN cddlc -2 block.cddl + RUN cddlc -2 genesis_to_prev_hash.cddl From 9db5ddbc2e7922265953ee1973c95c2047835f57 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 14:48:06 +0200 Subject: [PATCH 08/17] fix spelling --- .config/dictionaries/project.dic | 1 + 1 file changed, 1 insertion(+) diff --git a/.config/dictionaries/project.dic b/.config/dictionaries/project.dic index 02052bab53..9fc7fdc6f6 100644 --- a/.config/dictionaries/project.dic +++ b/.config/dictionaries/project.dic @@ -27,6 +27,7 @@ cardano carryforward CBOR cbork +cddlc cdylib CEST chacha From 93ccfed54151a21286117c988c5b7a75f2c0ce77 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 14:57:40 +0200 Subject: [PATCH 09/17] add missing blueprint.cue files --- .../architecture/08_concepts/catalyst_voting/cddl/blueprint.cue | 2 ++ .../08_concepts/immutable_ledger/cddl/blueprint.cue | 2 ++ 2 files changed, 4 insertions(+) create mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/blueprint.cue create mode 100644 docs/src/architecture/08_concepts/immutable_ledger/cddl/blueprint.cue diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/blueprint.cue b/docs/src/architecture/08_concepts/catalyst_voting/cddl/blueprint.cue new file mode 100644 index 0000000000..9e3d3a823a --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/blueprint.cue @@ -0,0 +1,2 @@ +version: "1.0.0" +project: name: "docs-catalyst-voting-cddl" diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/blueprint.cue b/docs/src/architecture/08_concepts/immutable_ledger/cddl/blueprint.cue new file mode 100644 index 0000000000..52eb1fb7b8 --- /dev/null +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/blueprint.cue @@ -0,0 +1,2 @@ +version: "1.0.0" +project: name: "docs-immutable-ledger-cddl" From ed6da6794df3945772e928c6fd227d60a550c749 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 19:29:16 +0200 Subject: [PATCH 10/17] fix --- .../immutable_ledger/cddl/block.cddl | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl b/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl index 5b9b832c8b..048d653534 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl @@ -1,26 +1,28 @@ block = [ block_header, - block_data: ~encoded-cbor, ; deterministically encoded CBOR - validator_signature, + block-data, + validator-signature, ] block_header = [ - chain_id: ULID, + chain-id: ULID, height: int, - timestamp: ~#6.1(uint .ge 1722470400), ; Epoch-based date/time - prev_block_id: hash_bytes, ; hash of the previous block - ?ledger_type: UUID, - ?purpose_id: ULID / UUID, + timestamp: #6.1(uint .ge 1722470400), ; Epoch-based date/time + prev-block-id: hash_bytes, ; hash of the previous block + ?ledger-type: UUID, + ?purpose-id: ULID / UUID, ?validator, ~metadata, ] +block-data = encoded-cbor + UUID = #6.37(bytes) ; UUID type ULID = #6.32780(bytes) ; ULID type hash_bytes = ( - #6.32781(bytes) \ ; Blake3 hash - #6.32782(bytes) \ ; Blake2b hash + #6.32781(bytes) / ; Blake3 hash + #6.32782(bytes) / ; Blake2b hash #6.32783(bytes) ; Blake2s hash ) kid = hash_bytes ; hash of the x509/c509 certificate @@ -28,4 +30,4 @@ kid = hash_bytes ; hash of the x509/c509 certificate validator = (kid / [2* kid]) metadata = [ *any ] -validator_signature = (bytes / [2* bytes]) +validator-signature = (bytes / [2* bytes]) From 165a2ee807bd276d0019937666208f9168793165 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 19:34:29 +0200 Subject: [PATCH 11/17] fix immutable ledger cddl definitions --- .../immutable_ledger/cddl/Earthfile | 3 +- .../immutable_ledger/cddl/block.cddl | 15 +++--- .../cddl/genesis_to_prev_hash.cddl | 19 ++++---- .../immutable_ledger/cddl/hash.cddl | 5 ++ .../08_concepts/immutable_ledger/ledger.md | 46 +++++++++---------- 5 files changed, 44 insertions(+), 44 deletions(-) create mode 100644 docs/src/architecture/08_concepts/immutable_ledger/cddl/hash.cddl diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile b/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile index 1b863ba5f8..c9c7ac1145 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile @@ -7,7 +7,8 @@ check-cddl: WORKDIR /cddl - COPY ./block.cddl ./genesis_to_prev_hash.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 diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl b/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl index 048d653534..d65f0fc78a 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/block.cddl @@ -1,14 +1,14 @@ block = [ - block_header, + block-header, block-data, validator-signature, ] -block_header = [ +block-header = [ chain-id: ULID, height: int, timestamp: #6.1(uint .ge 1722470400), ; Epoch-based date/time - prev-block-id: hash_bytes, ; hash of the previous block + prev-block-id: hash-bytes, ; hash of the previous block ?ledger-type: UUID, ?purpose-id: ULID / UUID, ?validator, @@ -20,14 +20,11 @@ block-data = encoded-cbor UUID = #6.37(bytes) ; UUID type ULID = #6.32780(bytes) ; ULID type -hash_bytes = ( - #6.32781(bytes) / ; Blake3 hash - #6.32782(bytes) / ; Blake2b hash - #6.32783(bytes) ; Blake2s hash -) -kid = hash_bytes ; hash of the x509/c509 certificate +kid = hash-bytes ; hash of the x509/c509 certificate validator = (kid / [2* kid]) metadata = [ *any ] validator-signature = (bytes / [2* bytes]) + +;# include hash diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl b/docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl index f6b22766eb..c30ecbf995 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl @@ -1,8 +1,8 @@ -genesis_to_prev_hash = [ - chain_id: ULID, - timestamp: ~#6.1(uint .ge 1722470400), ; Epoch-based date/time - ledger_type: UUID, - purpose_id: ULID / UUID, +genesis-to-prev-hash = [ + chain-id: ULID, + timestamp: #6.1(uint .ge 1722470400), ; Epoch-based date/time + ledger-type: UUID, + purpose-id: ULID / UUID, validator, ] @@ -10,9 +10,6 @@ UUID = #6.37(bytes) ; UUID type ULID = #6.32780(bytes) ; ULID type validator = (kid / [2* kid]) -kid = hash_bytes ; hash of the x509/c509 certificate -hash_bytes = ( - #6.32781(bytes) \ ; Blake3 hash - #6.32782(bytes) \ ; Blake2b hash - #6.32783(bytes) ; Blake2s hash -) \ No newline at end of file +kid = hash-bytes ; hash of the x509/c509 certificate + +;# include hash diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/hash.cddl b/docs/src/architecture/08_concepts/immutable_ledger/cddl/hash.cddl new file mode 100644 index 0000000000..32ca39ae72 --- /dev/null +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/hash.cddl @@ -0,0 +1,5 @@ +hash-bytes = ( + #6.32781(bytes) / ; Blake3 hash + #6.32782(bytes) / ; Blake2b hash + #6.32783(bytes) ; Blake2s hash +) diff --git a/docs/src/architecture/08_concepts/immutable_ledger/ledger.md b/docs/src/architecture/08_concepts/immutable_ledger/ledger.md index b2a5396679..af4cb2c95b 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/ledger.md +++ b/docs/src/architecture/08_concepts/immutable_ledger/ledger.md @@ -82,17 +82,17 @@ Which is well suited where it comes to process some temporary event e.g. voting. Header: -* `chain_id` - unique identifier of the chain. +* `chain-id` - unique identifier of the chain. * `height` - block's height. Also is used to identify the block type: *genesis*, *regular*, *final* (in more details described in [validation section](#block-validation-rules)). * `timestamp` - block's timestamp. -* `prev_block_id` - previous block hash. -* `ledger_type` - unique identifier of the ledger type. - In general, this is the way to strictly bound and specify `block_data` of the ledger for the specific `ledger_type`. +* `prev-block-id` - previous block hash. +* `ledger-type` - unique identifier of the ledger type. + In general, this is the way to strictly bound and specify `block-data` of the ledger for the specific `ledger-type`. But such rules will be a part of the specific ledger type definition, and not specified by this document. -* `purpose_id` - unique identifier of the purpose. +* `purpose-id` - unique identifier of the purpose. As it was stated before, each Ledger instance will have a strict time boundaries, so each of them will run for different purposes. @@ -102,13 +102,13 @@ Header: Block: -* `block_header` - block header described above, -* `block_data` - an array of some CBOR encoded data -* `validator_signature` - a signature or signatures of the validator's. +* `block-header` - block header described above, +* `block-data` - an array of some CBOR encoded data +* `validator-signature` - a signature or signatures of the validator's. ### Block validation rules -* `chain_id` **MUST** be the same as for the previous block (except for genesis). +* `chain-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. @@ -116,25 +116,25 @@ Block: * *Final* block is the last one for the specific chain and any other block could not be referenced to the *Final* one. * `timestamp` **MUST** be greater or equals than the `timestamp` of the previous block (except for genesis). -* `prev_block_id` **MUST** be a hash of the previous block bytes (except for genesis). +* `prev-block-id` **MUST** be a hash of the previous block bytes (except for genesis). -* `ledger_type` **MUST** be the same as for the previous block if present (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). +* `purpose-id` **MUST** be the same as for the previous block if present (except for genesis). **MANDATORY** field for *Genesis* and *Final* blocks. * `validator` **MUST** be the same as for the previous block if present (except for genesis). **MANDATORY** field for *Genesis* and *Final* blocks. -* `prev_block_id`'s CBOR tag value and `bstr` size **MUST** be the same as for the previous block (except for genesis). +* `prev-block-id`'s CBOR tag value and `bstr` 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. -* `prev_block_id` and `validator_signature` **MUST** use the same hash function, defined with the - `hash_bytes`. +* `prev-block-id` and `validator-signature` **MUST** use the same hash function, defined with the + `hash-bytes`. -* `prev_block_id` for the *Genesis* block **MUST** be a hash of the `genesis_to_prev_hash` bytes. +* `prev-block-id` for the *Genesis* block **MUST** be a hash of the `genesis-to-prev-hash` bytes. -* `block_data` **MUST** be a [deterministically][CBOR-deterministically-encoded] encoded CBOR. +* `block-data` **MUST** be a [deterministically][CBOR-deterministically-encoded] encoded CBOR. -??? note "Genesis to previous block hash CDDL definition: `genesis_to_prev_hash.cddl`" +??? note "Genesis to previous block hash CDDL definition: `genesis-to-prev-hash.cddl`" ```CDDL {{ include_file('src/architecture/08_concepts/immutable_ledger/cddl/genesis_to_prev_hash.cddl',indent=4) }} @@ -143,16 +143,16 @@ Block: #### Signature rules -`validator_signature` -**MUST** be a signature of the hashed `block_header` bytes and the `block_data` bytes +`validator-signature` +**MUST** be a signature of the hashed `block-header` bytes and the `block-data` bytes (with the order the same as defined for `block`). Signed by the validator's keys defined in the corresponding certificates referenced by the `validator`. Signature algorithm is defined by the certificate. The format and size of this field **MUST** be totally the same as `validator` field: -* if `validator` is only one id => `validator_signature` contains only 1 signature; -* if `validator` is array => `validator_signature` contains an array with the same length; -* order of signatures from the `validator_signature`'s array corresponds to the validators order of `validator`'s array. +* if `validator` is only one id => `validator-signature` contains only 1 signature; +* if `validator` is array => `validator-signature` contains an array with the same length; +* order of signatures from the `validator-signature`'s array corresponds to the validators order of `validator`'s array. ## Rationale From e0b78154cd8dc592e0a823041a94548ee7006f74 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 19:42:32 +0200 Subject: [PATCH 12/17] wip --- .../08_concepts/catalyst_voting/.pages | 4 ++-- ...ote_tx_v2.cddl => vote_tx_v2_private.cddl} | 0 .../cddl/vote_tx_v2_public.cddl | 24 +++++++++++++++++++ .../catalyst_voting/{jorm.md => v1.md} | 0 .../catalyst_voting/{cat_v2.md => v2.md} | 4 ++-- 5 files changed, 28 insertions(+), 4 deletions(-) rename docs/src/architecture/08_concepts/catalyst_voting/cddl/{vote_tx_v2.cddl => vote_tx_v2_private.cddl} (100%) create mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl rename docs/src/architecture/08_concepts/catalyst_voting/{jorm.md => v1.md} (100%) rename docs/src/architecture/08_concepts/catalyst_voting/{cat_v2.md => v2.md} (94%) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/.pages b/docs/src/architecture/08_concepts/catalyst_voting/.pages index 242ec1a0c8..02851bef17 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/.pages +++ b/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 diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl rename to docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl new file mode 100644 index 0000000000..73fa9da1a9 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl @@ -0,0 +1,24 @@ +vote-tx-v2 = gen-vote-tx + +choice-data = public-choice / private-choice + +public-choice = uint +private-choice = ciphertext + +ciphertext = [group-element, group-element] +group-element = bytes .size 32 + +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 + diff --git a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md b/docs/src/architecture/08_concepts/catalyst_voting/v1.md similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/jorm.md rename to docs/src/architecture/08_concepts/catalyst_voting/v1.md diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md similarity index 94% rename from docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md rename to docs/src/architecture/08_concepts/catalyst_voting/v2.md index a6b9511539..4b861d71db 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -34,10 +34,10 @@ Following that spec need to define a format of `choice`, `proof` and `prop_id`. -??? note "vote transaction v2 definition: `vote_tx_v2.cddl`" +??? note "vote transaction v2 definition: `vote_tx_v2_public.cddl`" ```CDDL - {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl', indent=4) }} + {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl', indent=4) }} ``` From 7f0639e8883a40672dd02e13e042d8707d2962e2 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 19:50:42 +0200 Subject: [PATCH 13/17] wip --- .../catalyst_voting/cddl/Earthfile | 9 ++++++-- .../cddl/vote_tx_v2_private.cddl | 7 +----- .../cddl/vote_tx_v2_public.cddl | 22 +++---------------- .../08_concepts/catalyst_voting/v2.md | 21 +++++++++++------- 4 files changed, 24 insertions(+), 35 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile index 78089b8279..b92aca8d21 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile @@ -7,8 +7,13 @@ check-cddl: WORKDIR /cddl - COPY ./gen_vote_tx.cddl ./vote_tx_v2.cddl ./gen_vote_tx_cose_payload.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.cddl + RUN cddlc -2 vote_tx_v2_public.cddl + RUN cddlc -2 vote_tx_v2_private.cddl diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl index 73fa9da1a9..23c4d5ea9f 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl @@ -1,12 +1,7 @@ vote-tx-v2 = gen-vote-tx -choice-data = public-choice / private-choice - -public-choice = uint -private-choice = ciphertext - +choice-data = ciphertext ciphertext = [group-element, group-element] -group-element = bytes .size 32 proposal = UUID diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl index 73fa9da1a9..de273ef4f0 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl @@ -1,24 +1,8 @@ -vote-tx-v2 = gen-vote-tx - -choice-data = public-choice / private-choice - -public-choice = uint -private-choice = ciphertext - -ciphertext = [group-element, group-element] -group-element = bytes .size 32 +vote-tx-v2-public = gen-vote-tx +choice-data = uint +proof-data = undefined 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 diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 4b861d71db..1a98045779 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -26,22 +26,27 @@ defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specificati Following that spec need to define a format of `choice`, `proof` and `prop_id`. - -!!! note - - - If `choice` is *public* one, `proof` **must** be `null`. - - If `choice` is *private* one, `proof` **must** be **not** `null`. - +### Public vote -??? note "vote transaction v2 definition: `vote_tx_v2_public.cddl`" +??? 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) }} ``` -### Vote generation +### Private vote + + +??? 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) }} + ``` + + +#### Vote generation To generate a cryptographically secured `private_choice` and `zk_proof` parts you can follow this [spec](./crypto.md#vote). Important to note, From dda76b7a1fa4e2fe7d76de4d7852112a410364de Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 20:20:02 +0200 Subject: [PATCH 14/17] wip --- .../08_concepts/catalyst_voting/v2.md | 41 ++++++++++++++++--- 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 1a98045779..270a59714d 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -24,7 +24,28 @@ This document describes a Catalyst V2 vote transaction structure. 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 format of `choice`, `proof` and `prop_id`. +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 @@ -36,6 +57,11 @@ Following that spec need to define a format of `choice`, `proof` and `prop_id`. ``` + +```CDDL +vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742-7be3c8592803 +``` + ### Private vote @@ -46,17 +72,20 @@ Following that spec need to define a format of `choice`, `proof` and `prop_id`. ``` -#### Vote generation +```CDDL +vote-type = #6.37(h'E78EE18DF38044C1A85280AA6ECB07FE') ; e78ee18d-f380-44c1-a852-80aa6ecb07fe +``` + +#### Vote and Proof generation -To generate a cryptographically secured `private_choice` and `zk_proof` parts you can follow this [spec](./crypto.md#vote). +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 `vote_plan_id` and `proposal_index`, defines a number of possible options. +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 `vote_plan_id` bytes. +3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the `proposal` bytes. ## Rationale From 886dd493c8d528997407b6094335e071bd1ffe9f Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 20:20:53 +0200 Subject: [PATCH 15/17] fix --- docs/src/architecture/08_concepts/catalyst_voting/v2.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 270a59714d..4716fcc5c6 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -57,6 +57,7 @@ event = { ``` +For the public vote `vote-type` value defined as follows: ```CDDL vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742-7be3c8592803 @@ -72,6 +73,8 @@ vote-type = #6.37(h'8DE5586CE9984B9587427BE3C8592803') ; 8de5586c-e998-4b95-8742 ``` +For the private vote `vote-type` value defined as follows: + ```CDDL vote-type = #6.37(h'E78EE18DF38044C1A85280AA6ECB07FE') ; e78ee18d-f380-44c1-a852-80aa6ecb07fe ``` From 00f866925ab4831cd4a396fff9036184bb02fc71 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 4 Nov 2024 20:29:46 +0200 Subject: [PATCH 16/17] fix CI --- docs/src/architecture/08_concepts/catalyst_voting/v2.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/v2.md b/docs/src/architecture/08_concepts/catalyst_voting/v2.md index 4716fcc5c6..53a583d45c 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/v2.md @@ -38,13 +38,13 @@ event = { } ``` - * `brand_id` - a unique identifier which represents a "brand" who is running the voting, +* `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, +* `campaign_id` - a unique identifier which defines a "campaign" of voting, e.g. "treasury campaign". - * `election_id` - a unique identifier which defines an election, +* `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, +* `category_id` - a unique identifier which defines a voting category as a collection of proposals, e.g. "Development & Infrastructure", "Products & Integrations". ### Public vote From aae492e4ceea97cb66784ea143739246ad2a3855 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Tue, 5 Nov 2024 13:12:36 +0200 Subject: [PATCH 17/17] fix cat-ci version --- .../src/architecture/08_concepts/catalyst_voting/cddl/Earthfile | 2 +- .../architecture/08_concepts/immutable_ledger/cddl/Earthfile | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile index b92aca8d21..0fe8c1b435 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile @@ -1,6 +1,6 @@ VERSION 0.8 -IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:feat/cddl AS cddl-ci +IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.2.23 AS cddl-ci check-cddl: FROM cddl-ci+cddl-base diff --git a/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile b/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile index c9c7ac1145..60e24f1584 100644 --- a/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile +++ b/docs/src/architecture/08_concepts/immutable_ledger/cddl/Earthfile @@ -1,6 +1,6 @@ VERSION 0.8 -IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:feat/cddl AS cddl-ci +IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.2.23 AS cddl-ci check-cddl: FROM cddl-ci+cddl-base