diff --git a/docs/src/architecture/08_concepts/catalyst_voting/.pages b/docs/src/architecture/08_concepts/catalyst_voting/.pages index b3e6a7370e..242ec1a0c8 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/.pages +++ b/docs/src/architecture/08_concepts/catalyst_voting/.pages @@ -1,4 +1,6 @@ title: Catalyst Voting arrange: - crypto.md - - transaction.md + - gen_vote_tx.md + - jorm.md + - cat_v2.md diff --git a/docs/src/architecture/08_concepts/catalyst_voting/tx_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/tx_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..7ae9c7ec46 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md @@ -0,0 +1,71 @@ +# Catalyst V2 + +--- + +Title: Catalyst V2 Voting Transaction + +Status: Proposed + +Authors: + - Alex Pozhylenkov + +Created: 2024-10-24 + +--- + +## Abstract + +This document describes a Catalyst V2 vote transaction structure. + +## Motivation + +## Specification + +It is a Catalyst v2 voting transaction +defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specification) structure. + +Following that spec need to define a 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`. + + + +??? 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-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 new file mode 100644 index 0000000000..92dd63f420 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl @@ -0,0 +1,31 @@ +gen-vote-tx = [ + tx-body, + signature +] + +tx-body = [ + vote-type + event, + votes, + voters-data, +] + +vote-type = UUID ; e.g. Public or Private vote +event = { * event-key => any } +event-key = int / text + +votes = [+ vote] +vote = [ + choices, + proof \ null, + prop-id \ null, +] +choices = [+ choice] +choice = encoded-cbor +proof = encoded-cbor +prop-id = 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/tx_v2_cose_payload.cddl b/docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl similarity index 70% rename from docs/src/architecture/08_concepts/catalyst_voting/tx_v2_cose_payload.cddl rename to 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/tx_v2_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 new file mode 100644 index 0000000000..d1645e5d8c --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl @@ -0,0 +1,29 @@ +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-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 + +;# 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 new file mode 100644 index 0000000000..1a2b70f6fd --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md @@ -0,0 +1,87 @@ +# General Voting Transaction + +--- + +Title: General Voting Transaction Structure + +Status: Proposed + +Authors: + - Alex Pozhylenkov + +Created: 2024-09-04 + +--- + +## Abstract + +This document defines a generalized view of the "Catalyst" voting transaction. + +## Motivation + +Project "Catalyst" requires a structure to keep people vote's data in the secure way, anonymous and verifiable way. + +## Specification + + +??? note "vote transaction definition: `gen_vote_tx.cddl`" + + ```CDDL + {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl', indent=4) }} + ``` + + +`event` - a set of different identifiers which is uniquely define a particular voting event. + +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`. + 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. + +### 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. +However, only `COSE Signed Data Object` or `COSE_Sign` type is used. + +The following header must be included in the [COSE] signature. + +`protected`: + +* `content type`: `application/cbor` + (this parameter is used to indicate the content type of the data in the payload or ciphertext fields). + +Any other headers as `alg`, `kid` etc. could be specified of any kind and not defined by this spec. + +#### 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/gen_vote_tx_cose_payload.cddl') }} +``` + + +## Rationale + +## Path to Active + +### Acceptance Criteria + + +### Implementation Plan + + + + +[BLAKE2b-256]: https://www.blake2.net/blake2.pdf +[COSE]: https://datatracker.ietf.org/doc/rfc9052/ +[CBOR]: https://datatracker.ietf.org/doc/rfc8949/ diff --git a/docs/src/architecture/08_concepts/catalyst_voting/transaction.md b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md similarity index 80% rename from docs/src/architecture/08_concepts/catalyst_voting/transaction.md rename to docs/src/architecture/08_concepts/catalyst_voting/jorm.md index 2ded6f5ca6..6dc3ba3575 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/transaction.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/jorm.md @@ -1,40 +1,37 @@ -# Transactions +# Jörmungandr --- -Title: Voting Transactions +Title: Jörmungandr Voting Transaction Status: Proposed Authors: - Alex Pozhylenkov -Created: 2024-09-04 +Created: 2024-10-24 --- ## 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 describes a definition of the original Jörmungandr `VoteCast` transaction. ## Motivation -Project "Catalyst" requires a structure to keep people vote's data in the secure way, anonymous and verifiable way. - ## Specification -### v1 (Jörmungandr) +An original Jörmungandr blockchain's `VoteCast` transaction structure. -??? note "V1 vote transaction definition: `tx_v1.abnf`" +??? note "V1 transaction definition: `jorm.abnf`" ```abnf - {{ include_file('src/architecture/08_concepts/catalyst_voting/tx_v1.abnf', indent=4) }} + {{ include_file('src/architecture/08_concepts/catalyst_voting/abnf/jorm.abnf', indent=4) }} ``` -#### Example +### Example V1 transaction representation in hex: @@ -78,18 +75,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): @@ -118,55 +115,6 @@ Expected witness (includes signature) ``` -### v2 - - -??? note "V2 vote transaction definition: `tx_v2.cddl`" - - ```CDDL - {{ include_file('src/architecture/08_concepts/catalyst_voting/tx_v2.cddl', indent=4) }} - ``` - - -`event` - a set of different identifiers which is uniquely define a particular voting event. - -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`. - 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. - -#### 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. -However, only `COSE Signed Data Object` or `COSE_Sign` type is used. - -The following header must be included in the [COSE] signature. - -`protected`: - -* `content type`: `application/cbor` - (this parameter is used to indicate the content type of the data in the payload or ciphertext fields). - -Any other headers as `alg`, `kid` etc. could be specified of any kind and not defined by this spec. - -##### 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/tx_v2_cose_payload.cddl') }} -``` - - ## Rationale ## Path to Active @@ -182,5 +130,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/ + + diff --git a/docs/src/architecture/08_concepts/catalyst_voting/tx_v2.cddl b/docs/src/architecture/08_concepts/catalyst_voting/tx_v2.cddl deleted file mode 100644 index 673586b6cd..0000000000 --- a/docs/src/architecture/08_concepts/catalyst_voting/tx_v2.cddl +++ /dev/null @@ -1,26 +0,0 @@ -vote_tx = [ - vote_tx_body, - signature -] - -vote_tx_body = [ - vote_type: UUID ; e.g. Public or Private vote - event, - votes, - voters_data: encoded_cbor -] - -event = { * event_key => any } -event_key = int / text - -votes = [+ vote] -vote = [ - choices: encoded-cbor, - proof: encoded-cbor / null, - prop_id: encoded-cbor / null, -] -choices = [+ choice] -choice = encoded-cbor - -UUID = #6.37(bytes) ; UUID type -signature = #6.98(COSE_Sign) ; COSE signature