From 657289af10e1ae8da43f87db15ef6754af5421ba Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Thu, 24 Oct 2024 13:16:03 +0300 Subject: [PATCH 01/14] refactor docs --- .../08_concepts/catalyst_voting/{ => abnf}/tx_v1.abnf | 0 .../08_concepts/catalyst_voting/{ => cddl}/tx_v2.cddl | 0 .../catalyst_voting/{ => cddl}/tx_v2_cose_payload.cddl | 0 .../architecture/08_concepts/catalyst_voting/transaction.md | 6 +++--- 4 files changed, 3 insertions(+), 3 deletions(-) rename docs/src/architecture/08_concepts/catalyst_voting/{ => abnf}/tx_v1.abnf (100%) rename docs/src/architecture/08_concepts/catalyst_voting/{ => cddl}/tx_v2.cddl (100%) rename docs/src/architecture/08_concepts/catalyst_voting/{ => cddl}/tx_v2_cose_payload.cddl (100%) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/tx_v1.abnf b/docs/src/architecture/08_concepts/catalyst_voting/abnf/tx_v1.abnf similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/tx_v1.abnf rename to docs/src/architecture/08_concepts/catalyst_voting/abnf/tx_v1.abnf diff --git a/docs/src/architecture/08_concepts/catalyst_voting/tx_v2.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_v2.cddl similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/tx_v2.cddl rename to docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_v2.cddl diff --git a/docs/src/architecture/08_concepts/catalyst_voting/tx_v2_cose_payload.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_v2_cose_payload.cddl similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/tx_v2_cose_payload.cddl rename to docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_v2_cose_payload.cddl diff --git a/docs/src/architecture/08_concepts/catalyst_voting/transaction.md b/docs/src/architecture/08_concepts/catalyst_voting/transaction.md index 2ded6f5ca6..cb1fefc372 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/transaction.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/transaction.md @@ -30,7 +30,7 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure ??? note "V1 vote transaction definition: `tx_v1.abnf`" ```abnf - {{ include_file('src/architecture/08_concepts/catalyst_voting/tx_v1.abnf', indent=4) }} + {{ include_file('src/architecture/08_concepts/catalyst_voting/abnf/tx_v1.abnf', indent=4) }} ``` @@ -124,7 +124,7 @@ Expected witness (includes signature) ??? note "V2 vote transaction definition: `tx_v2.cddl`" ```CDDL - {{ include_file('src/architecture/08_concepts/catalyst_voting/tx_v2.cddl', indent=4) }} + {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/tx_v2.cddl', indent=4) }} ``` @@ -163,7 +163,7 @@ In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes: ```CDDL -{{ include_file('src/architecture/08_concepts/catalyst_voting/tx_v2_cose_payload.cddl') }} +{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/tx_v2_cose_payload.cddl') }} ``` From b9f54ae7ffc7aeb7910d9ba2b1cd8ebf82264f8c Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Thu, 24 Oct 2024 14:36:46 +0300 Subject: [PATCH 02/14] split into different docs --- .../08_concepts/catalyst_voting/.pages | 1 + .../abnf/{tx_v1.abnf => jorm_v1.abnf} | 0 .../cddl/{tx_v2.cddl => tx.cddl} | 0 ...cose_payload.cddl => tx_cose_payload.cddl} | 0 .../08_concepts/catalyst_voting/jorm.md | 138 ++++++++++++++++++ .../catalyst_voting/transaction.md | 115 +-------------- 6 files changed, 147 insertions(+), 107 deletions(-) rename docs/src/architecture/08_concepts/catalyst_voting/abnf/{tx_v1.abnf => jorm_v1.abnf} (100%) rename docs/src/architecture/08_concepts/catalyst_voting/cddl/{tx_v2.cddl => tx.cddl} (100%) rename docs/src/architecture/08_concepts/catalyst_voting/cddl/{tx_v2_cose_payload.cddl => tx_cose_payload.cddl} (100%) create mode 100644 docs/src/architecture/08_concepts/catalyst_voting/jorm.md diff --git a/docs/src/architecture/08_concepts/catalyst_voting/.pages b/docs/src/architecture/08_concepts/catalyst_voting/.pages index b3e6a7370e..34142e0a26 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/.pages +++ b/docs/src/architecture/08_concepts/catalyst_voting/.pages @@ -2,3 +2,4 @@ title: Catalyst Voting arrange: - crypto.md - transaction.md + - jorm.md diff --git a/docs/src/architecture/08_concepts/catalyst_voting/abnf/tx_v1.abnf b/docs/src/architecture/08_concepts/catalyst_voting/abnf/jorm_v1.abnf similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/abnf/tx_v1.abnf rename to docs/src/architecture/08_concepts/catalyst_voting/abnf/jorm_v1.abnf diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_v2.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_v2.cddl rename to docs/src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_v2_cose_payload.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_cose_payload.cddl similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_v2_cose_payload.cddl rename to docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_cose_payload.cddl diff --git a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md new file mode 100644 index 0000000000..a89cc1a752 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md @@ -0,0 +1,138 @@ +# Jörmungandr + +--- + +Title: Jörmungandr Voting Transactions + +Status: Proposed + +Authors: + - Alex Pozhylenkov + +Created: 2024-10-24 + +--- + +## Abstract + +This document decribes a different definitions of the Jörmungandr based transactions. + +## Motivation + +## Specification + +### v1 (Jörmungandr blockchain) + +An original Jörmungandr blockchain's transaction structure. + + +??? note "V1 vote transaction definition: `jorm_v1.abnf`" + + ```abnf + {{ include_file('src/architecture/08_concepts/catalyst_voting/abnf/jorm_v1.abnf', indent=4) }} + ``` + + +#### Example + +V1 transaction representation in hex: + + +```hex +0000037e000b36ad42885189a0ac3438cdb57bc8ac7f6542e05a59d1f2e4d1d38194c9d4ac7b000203f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fc8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846021c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c702edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f96644067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0aac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f480cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb5570af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d882228e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be29546152902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee40353453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc0859718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0cbc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40ccbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e00000000000000000100ff00000000000000036d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed909155870200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d +``` + + + +1. Transaction size (u32): `0000037e` +2. Jörmungandr specific tag (u8): `00` +3. Jörmungandr specific tag (u8): `0b` +4. Vote plan id (32 byte hash): `36ad42885189a0ac3438cdb57bc8ac7f6542e05a59d1f2e4d1d38194c9d4ac7b` +5. Proposal index (u8): `00` +6. Payload type tag (u8): `02` +7. Encrypted vote: +`03|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|c8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846` + * size (u8): `03` + * ciphertext (group element (32 byte), group element (32 byte)): `f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|c8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846` +8. Proof: `02|1c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a|06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c70|2edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f9664|4067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0a|ac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f48|0cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb557|0af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d88222|8e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be295461|52902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356|ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455|d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d|3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a|85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee403|53453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc08|59718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0c|bc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40c|cbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e` + * size (u8): `02` + * announcements (group element (32 byte), group element (32 byte), group element (32 byte)): `1c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a|06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c70|2edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f9664|4067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0a|ac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f48|0cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb557` + * ciphertext (group element (32 byte), group element (32 byte)): `0af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d88222|8e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be295461|52902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356|ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455` + * response randomness (scalar (32 byte), scalar (32 byte), scalar (32 byte)): `d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d|3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a|85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee403|53453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc08|59718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0c|bc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40c` + * scalar (32 byte): `cbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e` +9. `IOW` stand for Inputs-Outputs-Witnesses: `00000000000000000100ff00000000000000036d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed909155870200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d` + * Jörmungandr specific block date (epoch (u32), slot (u32)) + (*could be anything, not processed anymore*): `00000000|00000000` + * number of inputs and witnesses (u8) (**always** `1`): `01` + * number of outputs (u8) (**always** `0`): `00` + * Inputs + 1. + * Jörmungandr specific tag: `ff` + * Jörmungandr specific value (u64) (*could be anything, not processed anymore*): `0000000000000003` + * input pointer (32 byte): `6d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed90915587` + * Witnesses + 1. + * Jörmungandr specific tag (u8): `02` + * Jörmungandr specific nonce (u32) (*could be anything, not processed anymore*): `00000000` + * legacy signature (64 byte): `e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d` + + +#### Transaction vote generation + +To generate a cryptographically secured `ENCRYPTED-VOTE` and `PROOF-VOTE` 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. +2. [ristretto255] as a backend cryptographic group. +3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the "Vote plan id" bytes. + +#### Transaction signing (witness generation) + +Signature generated from the [BLAKE2b-256] hashed `VOTE-PAYLOAD` bytes except of the `WITNESS` part +(the last part from the bytes array): + +1. `CAST-CERT` bytes +2. `BLOCK-DATE` bytes +3. `%x01` +4. `%x00` +5. `INPUT` bytes + +Based on the on the transaction example, data to sign: + + +```hex +36ad42885189a0ac3438cdb57bc8ac7f6542e05a59d1f2e4d1d38194c9d4ac7b000203f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fc8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846021c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c702edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f96644067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0aac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f480cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb5570af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d882228e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be29546152902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee40353453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc0859718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0cbc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40ccbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e00000000000000000100ff00000000000000036d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed90915587 +``` + + +[BLAKE2b-256] hash of the transaction data to sign equals to `f51473df863be3e0383ce5a8da79c7ff51b3d98dadbbefbf9f042e8601901269` + +Expected witness (includes signature) + + +```hex +0200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d +``` + + +### v2 + +## Rationale + +## Path to Active + +### Acceptance Criteria + + +### Implementation Plan + + + + +[BLAKE2b-256]: https://www.blake2.net/blake2.pdf +[BLAKE2b-512]: https://www.blake2.net/blake2.pdf +[ristretto255]: https://ristretto.group + + diff --git a/docs/src/architecture/08_concepts/catalyst_voting/transaction.md b/docs/src/architecture/08_concepts/catalyst_voting/transaction.md index cb1fefc372..3d5b31fce9 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/transaction.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/transaction.md @@ -1,8 +1,8 @@ -# Transactions +# General Voting Transaction --- -Title: Voting Transactions +Title: General Voting Transaction Structure Status: Proposed @@ -15,8 +15,7 @@ Created: 2024-09-04 ## Abstract -This document describes a specification of the different versions "Catalyst" voting transaction structure. -From the old one (Jörmungandr) to the newest. +This document defines a generilized view of the "Catalyst" voting transaction. ## Motivation @@ -24,107 +23,11 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure ## Specification -### v1 (Jörmungandr) - - -??? note "V1 vote transaction definition: `tx_v1.abnf`" - - ```abnf - {{ include_file('src/architecture/08_concepts/catalyst_voting/abnf/tx_v1.abnf', indent=4) }} - ``` - - -#### Example - -V1 transaction representation in hex: - - -```hex -0000037e000b36ad42885189a0ac3438cdb57bc8ac7f6542e05a59d1f2e4d1d38194c9d4ac7b000203f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fc8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846021c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c702edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f96644067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0aac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f480cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb5570af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d882228e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be29546152902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee40353453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc0859718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0cbc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40ccbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e00000000000000000100ff00000000000000036d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed909155870200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d -``` - - - -1. Transaction size (u32): `0000037e` -2. Jörmungandr specific tag (u8): `00` -3. Jörmungandr specific tag (u8): `0b` -4. Vote plan id (32 byte hash): `36ad42885189a0ac3438cdb57bc8ac7f6542e05a59d1f2e4d1d38194c9d4ac7b` -5. Proposal index (u8): `00` -6. Payload type tag (u8): `02` -7. Encrypted vote: -`03|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|c8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846` - * size (u8): `03` - * ciphertext (group element (32 byte), group element (32 byte)): `f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|c8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846` -8. Proof: `02|1c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a|06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c70|2edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f9664|4067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0a|ac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f48|0cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb557|0af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d88222|8e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be295461|52902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356|ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455|d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d|3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a|85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee403|53453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc08|59718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0c|bc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40c|cbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e` - * size (u8): `02` - * announcements (group element (32 byte), group element (32 byte), group element (32 byte)): `1c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a|06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c70|2edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f9664|4067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0a|ac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f48|0cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb557` - * ciphertext (group element (32 byte), group element (32 byte)): `0af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d88222|8e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be295461|52902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356|ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455` - * response randomness (scalar (32 byte), scalar (32 byte), scalar (32 byte)): `d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d|3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a|85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee403|53453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc08|59718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0c|bc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40c` - * scalar (32 byte): `cbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e` -9. `IOW` stand for Inputs-Outputs-Witnesses: `00000000000000000100ff00000000000000036d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed909155870200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d` - * Jörmungandr specific block date (epoch (u32), slot (u32)) - (*could be anything, not processed anymore*): `00000000|00000000` - * number of inputs and witnesses (u8) (**always** `1`): `01` - * number of outputs (u8) (**always** `0`): `00` - * Inputs - 1. - * Jörmungandr specific tag: `ff` - * Jörmungandr specific value (u64) (*could be anything, not processed anymore*): `0000000000000003` - * input pointer (32 byte): `6d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed90915587` - * Witnesses - 1. - * Jörmungandr specific tag (u8): `02` - * Jörmungandr specific nonce (u32) (*could be anything, not processed anymore*): `00000000` - * legacy signature (64 byte): `e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d` - - -#### Transaction vote generation - -To generate a cryptographically secured `ENCRYPTED-VOTE` and `PROOF-VOTE` 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. -2. [ristretto255] as a backend cryptographic group. -3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the "Vote plan id" bytes. - -#### Transaction signing (witness generation) - -Signature generated from the [BLAKE2b-256] hashed `VOTE-PAYLOAD` bytes except of the `WITNESS` part -(the last part from the bytes array): - -1. `CAST-CERT` bytes -2. `BLOCK-DATE` bytes -3. `%x01` -4. `%x00` -5. `INPUT` bytes - -Based on the on the transaction example, data to sign: - - -```hex -36ad42885189a0ac3438cdb57bc8ac7f6542e05a59d1f2e4d1d38194c9d4ac7b000203f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fc8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846021c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c702edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f96644067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0aac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f480cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb5570af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d882228e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be29546152902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee40353453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc0859718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0cbc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40ccbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e00000000000000000100ff00000000000000036d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed90915587 -``` - - -[BLAKE2b-256] hash of the transaction data to sign equals to `f51473df863be3e0383ce5a8da79c7ff51b3d98dadbbefbf9f042e8601901269` - -Expected witness (includes signature) - - -```hex -0200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d -``` - - -### v2 - -??? note "V2 vote transaction definition: `tx_v2.cddl`" +??? note "vote transaction definition: `tx.cddl`" ```CDDL - {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/tx_v2.cddl', indent=4) }} + {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl', indent=4) }} ``` @@ -141,7 +44,7 @@ Vote: `voters_data` - an any additional voter's specific data. -#### Transaction signing +### Transaction signing [COSE] is used to define a transaction's signature structure. [COSE] is a flexible security protocol that supports various types of security messages. @@ -156,14 +59,14 @@ The following header must be included in the [COSE] signature. Any other headers as `alg`, `kid` etc. could be specified of any kind and not defined by this spec. -##### Signature payload +#### Signature payload As mentioned earlier, the content type of the [COSE] signature payload is `application/cbor`. In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes: ```CDDL -{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/tx_v2_cose_payload.cddl') }} +{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/tx_cose_payload.cddl') }} ``` @@ -180,7 +83,5 @@ In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes: [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/ From fc1cd66d6294e38c29fde9ee1a8aa56f5641c4d6 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Thu, 24 Oct 2024 14:37:10 +0300 Subject: [PATCH 03/14] rename file --- docs/src/architecture/08_concepts/catalyst_voting/.pages | 2 +- .../catalyst_voting/{transaction.md => gen_vote_tx.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/src/architecture/08_concepts/catalyst_voting/{transaction.md => gen_vote_tx.md} (100%) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/.pages b/docs/src/architecture/08_concepts/catalyst_voting/.pages index 34142e0a26..1a94f3c447 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/.pages +++ b/docs/src/architecture/08_concepts/catalyst_voting/.pages @@ -1,5 +1,5 @@ title: Catalyst Voting arrange: - crypto.md - - transaction.md + - gen_vote_tx.md - jorm.md diff --git a/docs/src/architecture/08_concepts/catalyst_voting/transaction.md b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/transaction.md rename to docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md From 6a6f39eda3bfc6b82fcbb9dc22e7bbec1c7f989e Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Thu, 24 Oct 2024 15:16:32 +0300 Subject: [PATCH 04/14] add cddl specs --- .../catalyst_voting/cddl/jorm_v2/choice.cddl | 7 +++++ .../catalyst_voting/cddl/jorm_v2/proof.cddl | 8 +++++ .../catalyst_voting/cddl/jorm_v2/prop_id.cddl | 4 +++ .../08_concepts/catalyst_voting/jorm.md | 31 ++++++++++++++++++- 4 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl create mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl create mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl new file mode 100644 index 0000000000..1369d94ea4 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl @@ -0,0 +1,7 @@ +choice = public_choice / private_choice + +public_choice = uint +private_choice = ciphertext + +ciphertext = [group_element, group_element] +group_element = bytes .size 32 \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl new file mode 100644 index 0000000000..b622be8e63 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl @@ -0,0 +1,8 @@ +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 +group_element = bytes .size 32 \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl new file mode 100644 index 0000000000..f219047182 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl @@ -0,0 +1,4 @@ +prop_id = [vote_plan_id, proposal_index] + +vote_plan_id = bytes .size 32 +proposal_index = uint .size 1 ; 1-byte unsigned integer \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md index a89cc1a752..fffc8c6019 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md @@ -26,7 +26,7 @@ This document decribes a different definitions of the Jörmungandr based transac An original Jörmungandr blockchain's transaction structure. -??? note "V1 vote transaction definition: `jorm_v1.abnf`" +??? note "V1 transaction definition: `jorm_v1.abnf`" ```abnf {{ include_file('src/architecture/08_concepts/catalyst_voting/abnf/jorm_v1.abnf', indent=4) }} @@ -119,6 +119,35 @@ Expected witness (includes signature) ### v2 +It is a Jörmungandr based transaction +defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specification) structure. + +Following that spec we need define a format of `choice`, `proof` and `prop_id`. + +`jorm_v2/choice.cddl`: + + +```abnf +{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl') }} +``` + + +`jorm_v2/proof.cddl`: + + +```abnf +{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl') }} +``` + + +`jorm_v2/prop_id.cddl`: + + +```abnf +{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl') }} +``` + + ## Rationale ## Path to Active From 60eff8312b4e8815a69d216034f512debeaf6188 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Thu, 24 Oct 2024 15:39:34 +0300 Subject: [PATCH 05/14] wip --- .../08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl | 4 +++- .../architecture/08_concepts/catalyst_voting/cddl/tx.cddl | 4 ++-- docs/src/architecture/08_concepts/catalyst_voting/jorm.md | 8 +++++--- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl index b622be8e63..d2c1db39f6 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl @@ -1,4 +1,6 @@ -proof = [ [+ (announcement, ciphertext, r-response)], scalar] +proof = zk_proof \ null + +zk_proof = [ [+ (announcement, ciphertext, r-response)], scalar] announcement = (group_element, group_element, group_element) ciphertext = (group_element, group_element) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl index 673586b6cd..33b74ae616 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl @@ -16,8 +16,8 @@ event_key = int / text votes = [+ vote] vote = [ choices: encoded-cbor, - proof: encoded-cbor / null, - prop_id: encoded-cbor / null, + proof: encoded-cbor, + prop_id: encoded-cbor, ] choices = [+ choice] choice = encoded-cbor diff --git a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md index fffc8c6019..ae80357b5f 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md @@ -124,10 +124,12 @@ defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specificati Following that spec we need define a format of `choice`, `proof` and `prop_id`. +If `choice` is a public one, `proof` **must** be `null`. + `jorm_v2/choice.cddl`: -```abnf +```cddl {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl') }} ``` @@ -135,7 +137,7 @@ Following that spec we need define a format of `choice`, `proof` and `prop_id`. `jorm_v2/proof.cddl`: -```abnf +```cddl {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl') }} ``` @@ -143,7 +145,7 @@ Following that spec we need define a format of `choice`, `proof` and `prop_id`. `jorm_v2/prop_id.cddl`: -```abnf +```cddl {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl') }} ``` From 825807d2ae840a45c227300386d86c47fe08d18d Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Thu, 24 Oct 2024 15:46:41 +0300 Subject: [PATCH 06/14] wip --- .../catalyst_voting/cddl/jorm_v2/proof.cddl | 2 +- .../08_concepts/catalyst_voting/jorm.md | 20 +++++++++++++++---- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl index d2c1db39f6..ada26f261a 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl @@ -1,6 +1,6 @@ proof = zk_proof \ null -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) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md index ae80357b5f..a457d980fd 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md @@ -77,18 +77,18 @@ V1 transaction representation in hex: * legacy signature (64 byte): `e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d` -#### Transaction vote generation +#### Vote generation To generate a cryptographically secured `ENCRYPTED-VOTE` and `PROOF-VOTE` 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 `VOTE-PLAN-ID` and `PROPOSAL-INDEX`, 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 `VOTE-PLAN-ID` bytes. -#### Transaction signing (witness generation) +#### Signing (witness generation) Signature generated from the [BLAKE2b-256] hashed `VOTE-PAYLOAD` bytes except of the `WITNESS` part (the last part from the bytes array): @@ -150,6 +150,18 @@ If `choice` is a public one, `proof` **must** be `null`. ``` +#### Vote generation + +To generate a cryptographically secured `private_choice` 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. +2. [ristretto255] as a backend cryptographic group. +3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the `vote_plan_id` bytes. + ## Rationale ## Path to Active From 9e2d86e498a9b562a2148c4bfca9ae2abe40c732 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Thu, 24 Oct 2024 15:52:34 +0300 Subject: [PATCH 07/14] wip --- docs/src/architecture/08_concepts/catalyst_voting/jorm.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md index a457d980fd..7c195f806d 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md @@ -124,8 +124,6 @@ defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specificati Following that spec we need define a format of `choice`, `proof` and `prop_id`. -If `choice` is a public one, `proof` **must** be `null`. - `jorm_v2/choice.cddl`: @@ -150,6 +148,10 @@ If `choice` is a public one, `proof` **must** be `null`. ``` +!!! note + + If `choice` is a public one, `proof` **must** be `null`. + #### Vote generation To generate a cryptographically secured `private_choice` and `zk_proof` parts you can follow this [spec](./crypto.md#vote). From 98b274d4565950bd733e9a54ad0afad2435fccb2 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Thu, 24 Oct 2024 19:21:33 +0300 Subject: [PATCH 08/14] wip --- .../cddl/{tx.cddl => gen_vote_tx.cddl} | 15 ++++++--- ...oad.cddl => gen_vote_tx_cose_payload.cddl} | 0 .../catalyst_voting/cddl/jorm_v2/choice.cddl | 7 ---- .../catalyst_voting/cddl/jorm_v2/proof.cddl | 10 ------ .../catalyst_voting/cddl/jorm_v2/prop_id.cddl | 4 --- .../catalyst_voting/cddl/vote_tx_v2.cddl | 26 +++++++++++++++ .../catalyst_voting/gen_vote_tx.md | 6 ++-- .../08_concepts/catalyst_voting/jorm.md | 32 +++++-------------- 8 files changed, 47 insertions(+), 53 deletions(-) rename docs/src/architecture/08_concepts/catalyst_voting/cddl/{tx.cddl => gen_vote_tx.cddl} (59%) rename docs/src/architecture/08_concepts/catalyst_voting/cddl/{tx_cose_payload.cddl => gen_vote_tx_cose_payload.cddl} (100%) delete mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl delete mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl delete mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl create mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl similarity index 59% rename from docs/src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl rename to docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl index 33b74ae616..31103a6067 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl @@ -4,23 +4,28 @@ vote_tx = [ ] vote_tx_body = [ - vote_type: UUID ; e.g. Public or Private vote + vote_type event, votes, - voters_data: encoded_cbor + voters_data, ] +vote_type = UUID ; e.g. Public or Private vote event = { * event_key => any } event_key = int / text votes = [+ vote] vote = [ - choices: encoded-cbor, - proof: encoded-cbor, - prop_id: encoded-cbor, + choices, + proof, + prop_id, ] choices = [+ choice] choice = encoded-cbor +proof = encoded-cbor \ null +prop_id = encoded-cbor \ null + +voters_data = encoded-cbor UUID = #6.37(bytes) ; UUID type signature = #6.98(COSE_Sign) ; COSE signature diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_cose_payload.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/cddl/tx_cose_payload.cddl rename to docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl deleted file mode 100644 index 1369d94ea4..0000000000 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl +++ /dev/null @@ -1,7 +0,0 @@ -choice = public_choice / private_choice - -public_choice = uint -private_choice = ciphertext - -ciphertext = [group_element, group_element] -group_element = bytes .size 32 \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl deleted file mode 100644 index ada26f261a..0000000000 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl +++ /dev/null @@ -1,10 +0,0 @@ -proof = zk_proof \ null - -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 -group_element = bytes .size 32 \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl deleted file mode 100644 index f219047182..0000000000 --- a/docs/src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl +++ /dev/null @@ -1,4 +0,0 @@ -prop_id = [vote_plan_id, proposal_index] - -vote_plan_id = bytes .size 32 -proposal_index = uint .size 1 ; 1-byte unsigned integer \ No newline at end of file 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 new file mode 100644 index 0000000000..2d1360c55e --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl @@ -0,0 +1,26 @@ +choice = #6.24(bstr(choice_data)) +proof = #6.24(bstr(proof_data)) \ null +prop_id = #6.24(bstr(proposal)) \ null + + +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) +ciphertext = (group_element, group_element) +r-response = (scalar, scalar, scalar) + +scalar = bytes .size 32 +group_element = bytes .size 32 + diff --git a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md index 3d5b31fce9..f46c914626 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md @@ -24,10 +24,10 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure ## Specification -??? note "vote transaction definition: `tx.cddl`" +??? note "vote transaction definition: `gen_vote_tx.cddl`" ```CDDL - {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/tx.cddl', indent=4) }} + {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl', indent=4) }} ``` @@ -66,7 +66,7 @@ In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes: ```CDDL -{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/tx_cose_payload.cddl') }} +{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/get_vote_tx_cose_payload.cddl') }} ``` diff --git a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md index 7c195f806d..9981073432 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md @@ -124,34 +124,18 @@ defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specificati Following that spec we need define a format of `choice`, `proof` and `prop_id`. -`jorm_v2/choice.cddl`: - - -```cddl -{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/choice.cddl') }} -``` - - -`jorm_v2/proof.cddl`: - - -```cddl -{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/proof.cddl') }} -``` - - -`jorm_v2/prop_id.cddl`: - - -```cddl -{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/jorm_v2/prop_id.cddl') }} -``` - - !!! note If `choice` is a public one, `proof` **must** be `null`. + +??? note "vote transaction v2 definition: `vote_tx_v2.cddl`" + + ```CDDL + {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl', indent=4) }} + ``` + + #### Vote generation To generate a cryptographically secured `private_choice` and `zk_proof` parts you can follow this [spec](./crypto.md#vote). From aa69938af6ccd78cc0cb8c07719dbea67bc5b2e0 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 28 Oct 2024 10:16:13 +0200 Subject: [PATCH 09/14] wip --- .../08_concepts/catalyst_voting/.pages | 1 + .../abnf/{jorm_v1.abnf => jorm.abnf} | 0 .../08_concepts/catalyst_voting/cat_v2.md | 69 +++++++++++++++++++ .../catalyst_voting/cddl/gen_vote_tx.cddl | 8 +-- .../08_concepts/catalyst_voting/jorm.md | 49 +++---------- 5 files changed, 82 insertions(+), 45 deletions(-) rename docs/src/architecture/08_concepts/catalyst_voting/abnf/{jorm_v1.abnf => jorm.abnf} (100%) create mode 100644 docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md diff --git a/docs/src/architecture/08_concepts/catalyst_voting/.pages b/docs/src/architecture/08_concepts/catalyst_voting/.pages index 1a94f3c447..242ec1a0c8 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/.pages +++ b/docs/src/architecture/08_concepts/catalyst_voting/.pages @@ -3,3 +3,4 @@ arrange: - crypto.md - gen_vote_tx.md - jorm.md + - cat_v2.md diff --git a/docs/src/architecture/08_concepts/catalyst_voting/abnf/jorm_v1.abnf b/docs/src/architecture/08_concepts/catalyst_voting/abnf/jorm.abnf similarity index 100% rename from docs/src/architecture/08_concepts/catalyst_voting/abnf/jorm_v1.abnf rename to docs/src/architecture/08_concepts/catalyst_voting/abnf/jorm.abnf diff --git a/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md b/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md new file mode 100644 index 0000000000..d0d2c06fe3 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md @@ -0,0 +1,69 @@ +# Catalyst V2 + +--- + +Title: Catalyst V2 Voting Transaction + +Status: Proposed + +Authors: + - Alex Pozhylenkov + +Created: 2024-10-24 + +--- + +## Abstract + +This document decribes 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 we need define a format of `choice`, `proof` and `prop_id`. + +!!! note + + If `choice` is a public one, `proof` **must** be `null`. + + +??? note "vote transaction v2 definition: `vote_tx_v2.cddl`" + + ```CDDL + {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.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, +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. +2. [ristretto255] as a backend cryptographic group. +3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the `vote_plan_id` bytes. + +## Rationale + +## Path to Active + +### Acceptance Criteria + + +### Implementation Plan + + + + +[BLAKE2b-256]: https://www.blake2.net/blake2.pdf +[BLAKE2b-512]: https://www.blake2.net/blake2.pdf +[ristretto255]: https://ristretto.group + + 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 31103a6067..74cd5f0fb3 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 @@ -17,13 +17,13 @@ event_key = int / text votes = [+ vote] vote = [ choices, - proof, - prop_id, + proof \ null, + prop_id \ null, ] choices = [+ choice] choice = encoded-cbor -proof = encoded-cbor \ null -prop_id = encoded-cbor \ null +proof = encoded-cbor +prop_id = encoded-cbor voters_data = encoded-cbor diff --git a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md index 9981073432..5e01258f9e 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md @@ -2,7 +2,7 @@ --- -Title: Jörmungandr Voting Transactions +Title: Jörmungandr Voting Transaction Status: Proposed @@ -15,25 +15,23 @@ Created: 2024-10-24 ## Abstract -This document decribes a different definitions of the Jörmungandr based transactions. +This document decribes a definition of the original Jörmungandr `VoteCast` transaction. ## Motivation ## Specification -### v1 (Jörmungandr blockchain) - -An original Jörmungandr blockchain's transaction structure. +An original Jörmungandr blockchain's `VoteCast` transaction structure. -??? note "V1 transaction definition: `jorm_v1.abnf`" +??? note "V1 transaction definition: `jorm.abnf`" ```abnf - {{ include_file('src/architecture/08_concepts/catalyst_voting/abnf/jorm_v1.abnf', indent=4) }} + {{ include_file('src/architecture/08_concepts/catalyst_voting/abnf/jorm.abnf', indent=4) }} ``` -#### Example +### Example V1 transaction representation in hex: @@ -77,7 +75,7 @@ V1 transaction representation in hex: * legacy signature (64 byte): `e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d` -#### Vote generation +### Vote generation To generate a cryptographically secured `ENCRYPTED-VOTE` and `PROOF-VOTE` parts you can follow this [spec](./crypto.md#vote). Important to note, @@ -88,7 +86,7 @@ the following properties are used: 2. [ristretto255] as a backend cryptographic group. 3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the `VOTE-PLAN-ID` bytes. -#### Signing (witness generation) +### Signing (witness generation) Signature generated from the [BLAKE2b-256] hashed `VOTE-PAYLOAD` bytes except of the `WITNESS` part (the last part from the bytes array): @@ -117,37 +115,6 @@ Expected witness (includes signature) ``` -### v2 - -It is a Jörmungandr based transaction -defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specification) structure. - -Following that spec we need define a format of `choice`, `proof` and `prop_id`. - -!!! note - - If `choice` is a public one, `proof` **must** be `null`. - - -??? note "vote transaction v2 definition: `vote_tx_v2.cddl`" - - ```CDDL - {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.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, -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. -2. [ristretto255] as a backend cryptographic group. -3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the `vote_plan_id` bytes. - ## Rationale ## Path to Active From d3c6d3c731c56f10a9760f4cc7a0b65b7d60c157 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 28 Oct 2024 10:33:05 +0200 Subject: [PATCH 10/14] update vote_tx_v2 --- .../08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 2d1360c55e..af8239e88a 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,7 +1,8 @@ -choice = #6.24(bstr(choice_data)) -proof = #6.24(bstr(proof_data)) \ null -prop_id = #6.24(bstr(proposal)) \ null +vote_tx_v2 = vote_tx +choice = #6.24(bstr(choice_data)) +proof = #6.24(bstr(proof_data)) +prop_id = #6.24(bstr(proposal)) choice_data = public_choice / private_choice @@ -24,3 +25,5 @@ r-response = (scalar, scalar, scalar) scalar = bytes .size 32 group_element = bytes .size 32 +;# include gen_vote_tx + From b67bab7a20396b50bdbc05ab9c911b89dc8329a8 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 28 Oct 2024 10:37:48 +0200 Subject: [PATCH 11/14] update --- .../catalyst_voting/cddl/gen_vote_tx.cddl | 22 +++++++-------- .../cddl/gen_vote_tx_cose_payload.cddl | 2 +- .../catalyst_voting/cddl/vote_tx_v2.cddl | 28 +++++++++---------- .../catalyst_voting/gen_vote_tx.md | 4 +-- 4 files changed, 28 insertions(+), 28 deletions(-) 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 74cd5f0fb3..6ce2f6d506 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,31 +1,31 @@ -vote_tx = [ - vote_tx_body, +vote-tx = [ + vote-tx-body, signature ] -vote_tx_body = [ - vote_type +vote-tx-body = [ + vote-type event, votes, - voters_data, + voters-data, ] -vote_type = UUID ; e.g. Public or Private vote -event = { * event_key => any } -event_key = int / text +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, + prop-id \ null, ] choices = [+ choice] choice = encoded-cbor proof = encoded-cbor -prop_id = encoded-cbor +prop-id = encoded-cbor -voters_data = encoded-cbor +voters-data = encoded-cbor UUID = #6.37(bytes) ; UUID type signature = #6.98(COSE_Sign) ; COSE signature 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 e91264e8e4..dd7cac02d5 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 +cose-payload = blake2b-256 blake2b-256 = #6.32782(bytes .size 32) ; Blake2b-256 hash bytes \ No newline at end of file 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 af8239e88a..d1645e5d8c 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,29 +1,29 @@ -vote_tx_v2 = vote_tx +vote-tx-v2 = gen-vote-tx -choice = #6.24(bstr(choice_data)) -proof = #6.24(bstr(proof_data)) -prop_id = #6.24(bstr(proposal)) +choice = #6.24(bstr(choice-data)) +proof = #6.24(bstr(proof-data)) +prop-id = #6.24(bstr(proposal)) -choice_data = public_choice / private_choice +choice-data = public-choice / private-choice -public_choice = uint -private_choice = ciphertext +public-choice = uint +private-choice = ciphertext -ciphertext = [group_element, group_element] -group_element = bytes .size 32 +ciphertext = [group-element, group-element] +group-element = bytes .size 32 proposal = UUID -proof_data = zk_proof +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) +announcement = (group-element, group-element, group-element) +ciphertext = (group-element, group-element) r-response = (scalar, scalar, scalar) scalar = bytes .size 32 -group_element = bytes .size 32 +group-element = bytes .size 32 ;# include gen_vote_tx diff --git a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md index f46c914626..4591901d25 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md @@ -37,12 +37,12 @@ Vote: * `choices` - a collection of voter choices for the proposal. * `proof` - a voter proof, could be `null`. -* `prop_id` - a proposal id for which `choice` is made, could be `null`. +* `prop-id` - a proposal id for which `choice` is made, could be `null`. For that case where for the `event` defined only **one** proposal, so it's redundant to provide an additional identifier for the proposal, so it could be placed `null`. -`voters_data` - an any additional voter's specific data. +`voters-data` - an any additional voter's specific data. ### Transaction signing From a917bd07e3b81ce03d5f6c7e6e2077e3eaae4291 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 28 Oct 2024 10:51:28 +0200 Subject: [PATCH 12/14] wip --- docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md | 3 ++- .../08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl | 6 +++--- 2 files changed, 5 insertions(+), 4 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 d0d2c06fe3..e27bb2970c 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md @@ -28,7 +28,8 @@ Following that spec we need define a format of `choice`, `proof` and `prop_id`. !!! note - If `choice` is a public one, `proof` **must** be `null`. + - If `choice` is a *public* one, `proof` **must** be `null`. + - If `choice` is *private* one, `proof` **must** be **not** `null`. ??? note "vote transaction v2 definition: `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 6ce2f6d506..92dd63f420 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,9 +1,9 @@ -vote-tx = [ - vote-tx-body, +gen-vote-tx = [ + tx-body, signature ] -vote-tx-body = [ +tx-body = [ vote-type event, votes, From ac437a14e396cf95aa43c04193d4e5cf13f8f898 Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Mon, 28 Oct 2024 11:21:17 +0200 Subject: [PATCH 13/14] fix md and spelling --- docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md | 5 +++-- .../architecture/08_concepts/catalyst_voting/gen_vote_tx.md | 2 +- docs/src/architecture/08_concepts/catalyst_voting/jorm.md | 2 +- 3 files changed, 5 insertions(+), 4 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 e27bb2970c..b1d4106fa0 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md @@ -15,7 +15,7 @@ Created: 2024-10-24 ## Abstract -This document decribes a Catalyst V2 vote transaction structure. +This document describes a Catalyst V2 vote transaction structure. ## Motivation @@ -26,10 +26,12 @@ defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specificati Following that spec we need define a format of `choice`, `proof` and `prop_id`. + !!! note - If `choice` is a *public* one, `proof` **must** be `null`. - If `choice` is *private* one, `proof` **must** be **not** `null`. + ??? note "vote transaction v2 definition: `vote_tx_v2.cddl`" @@ -63,7 +65,6 @@ the following properties are used: -[BLAKE2b-256]: https://www.blake2.net/blake2.pdf [BLAKE2b-512]: https://www.blake2.net/blake2.pdf [ristretto255]: https://ristretto.group diff --git a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md index 4591901d25..c4c686283a 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md @@ -15,7 +15,7 @@ Created: 2024-09-04 ## Abstract -This document defines a generilized view of the "Catalyst" voting transaction. +This document defines a generalized view of the "Catalyst" voting transaction. ## Motivation diff --git a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md index 5e01258f9e..6dc3ba3575 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/jorm.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md @@ -15,7 +15,7 @@ Created: 2024-10-24 ## Abstract -This document decribes a definition of the original Jörmungandr `VoteCast` transaction. +This document describes a definition of the original Jörmungandr `VoteCast` transaction. ## Motivation From d5d481e2b1332c0227cb869eb2e45d5408a9b19e Mon Sep 17 00:00:00 2001 From: Mr-Leshiy Date: Tue, 29 Oct 2024 09:59:20 +0200 Subject: [PATCH 14/14] fix comments --- docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md | 4 ++-- .../architecture/08_concepts/catalyst_voting/gen_vote_tx.md | 2 +- 2 files changed, 3 insertions(+), 3 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 b1d4106fa0..7ae9c7ec46 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md @@ -24,12 +24,12 @@ 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 we need define a format of `choice`, `proof` and `prop_id`. +Following that spec need to define a format of `choice`, `proof` and `prop_id`. !!! note - - If `choice` is a *public* one, `proof` **must** be `null`. + - If `choice` is *public* one, `proof` **must** be `null`. - If `choice` is *private* one, `proof` **must** be **not** `null`. diff --git a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md index c4c686283a..1a2b70f6fd 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md @@ -66,7 +66,7 @@ In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes: ```CDDL -{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/get_vote_tx_cose_payload.cddl') }} +{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl') }} ```