diff --git a/docs/src/architecture/08_concepts/catalyst_voting/crypto.md b/docs/src/architecture/08_concepts/catalyst_voting/crypto.md index 04c6f5d8d4..8a7d22c8b9 100644 --- a/docs/src/architecture/08_concepts/catalyst_voting/crypto.md +++ b/docs/src/architecture/08_concepts/catalyst_voting/crypto.md @@ -65,7 +65,6 @@ Before any voting will start an initial setup procedure should be performed. * As most of the crypto algorithms are group dependent (more about this you can read in [appendix A](#a-group-definition)), it is needed to specifically define which cryptographically secure group would be used. -* Define a hash function which will be used by the underlying crypto algorithms. * Define a commitment key $ck$, which will be used during the voter proof generation and verification procedures. @@ -502,7 +501,7 @@ To compute it, prover needs to perform the next steps: * $A_l = g^{i_l * \beta_l} \circ ck^{\delta_l}, A_l \in \mathbb{G}$. 5. Calculate a first verifier challenge $ch_1 = H(ck, pk, \{c_j\}, \{I_l\}, \{B_l\}, \{A_l\})$, - where $H$ is a hash function, + where $H$ is [BLAKE2b-512] hash function, $j \in [0, \ldots, N-1]$ and $l \in [0, \ldots, log_2(N)-1]$. 6. For $j \in [0, \ldots, N-1]$ calculate polynomials @@ -518,7 +517,7 @@ To compute it, prover needs to perform the next steps: and $p_{j,l}$ - corresponding coefficients of the polynomial $p_j(x)$ calculated on step `7`. 9. Calculate a second verifier challenge $ch_2 = H(ch_1, \{D_l\})$, - where $H$ is a hash function + where $H$ is [BLAKE2b-512] hash function and $l \in [0, \ldots, log_2(N)-1]$. 10. For $l \in [0, \ldots, log_2(N)-1]$ calculate: * $z_l = i_l * ch_2 + \beta_l, z_l \in \mathbb{Z}_q$. @@ -558,12 +557,12 @@ verifier needs to perform the next steps: So the resulted $\mathbf{c} = (c_1, \ldots, c_M, \{c_j\})$. 2. Calculate the first verifier challenge $ch_1 = H(ck, pk, \{c_j\}, \{I_l\}, \{B_l\}, \{A_l\})$, - where $H$ is a hash function, + where $H$ is [BLAKE2b-512] hash function, $j \in [0, \ldots, N-1]$ and $l \in [0, \ldots, log_2(N)-1]$. 3. Calculate a second verifier challenge $ch_2 = H(ch_1, \{D_l\})$, - where $H$ is a hash function + where $H$ is [BLAKE2b-512] hash function and $l \in [0, \ldots, log_2(N)-1]$. 4. For $l \in [0, \ldots, log_2(N)-1]$ verify that the following statements are `true`, where $g$ is the group generator: @@ -683,3 +682,4 @@ If step `6` returns `true` so the final result is `true` otherwise return `false [treasury_system_paper]: https://eprint.iacr.org/2018/435.pdf [treasury_system_spec]: https://github.com/input-output-hk/treasury-crypto/blob/master/docs/voting_protocol_spec/Treasury_voting_protocol_spec.pdf [crypto_book]: https://gnanavelrec.wordpress.com/wp-content/uploads/2019/06/2.understanding-cryptography-by-christof-paar-.pdf +[BLAKE2b-512]: https://www.blake2.net/blake2.pdf diff --git a/docs/src/architecture/08_concepts/catalyst_voting/transaction.md b/docs/src/architecture/08_concepts/catalyst_voting/transaction.md index fa60732db1..2ded6f5ca6 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 @@ -# Transaction +# Transactions --- -Title: Voting Transaction +Title: Voting Transactions Status: Proposed @@ -46,7 +46,7 @@ V1 transaction representation in hex: 1. Transaction size (u32): `0000037e` -2. `00` +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` @@ -87,8 +87,7 @@ 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. [BLAKE2b-512] hash function. -4. 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) @@ -115,7 +114,56 @@ Expected witness (includes signature) ```hex - 0200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d +0200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d +``` + + +### 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') }} ``` @@ -131,6 +179,8 @@ Expected witness (includes signature) -[BLAKE2b-256]: https://www.blake2.net/blake2.pdf\ -[BLAKE2b-512]: https://www.blake2.net/blake2.pdf\ +[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 new file mode 100644 index 0000000000..673586b6cd --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/tx_v2.cddl @@ -0,0 +1,26 @@ +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 diff --git a/docs/src/architecture/08_concepts/catalyst_voting/tx_v2_cose_payload.cddl b/docs/src/architecture/08_concepts/catalyst_voting/tx_v2_cose_payload.cddl new file mode 100644 index 0000000000..e91264e8e4 --- /dev/null +++ b/docs/src/architecture/08_concepts/catalyst_voting/tx_v2_cose_payload.cddl @@ -0,0 +1,2 @@ +cose_payload = blake2b-256 +blake2b-256 = #6.32782(bytes .size 32) ; Blake2b-256 hash bytes \ No newline at end of file