Add some documentation

Author: stanislav-tkach

rust/catalyst-contest/src/choices.rs

@@ -4,6 +4,21 @@ use cbork_utils::decode_helper::decode_array_len;
 use minicbor::{Decode, Decoder, Encode, Encoder, encode::Write};
 
 /// Voters Choices.
+///
+/// The CDDL schema:
+/// ```cddl
+/// choices = [ 0, clear-choices ] /
+/// [ 1, elgamal-ristretto255-encrypted-choices ]
+///
+/// clear-choices = ( +clear-choice )
+///
+/// clear-choice = int
+///
+/// elgamal-ristretto255-encrypted-choices = [
+///     [+ elgamal-ristretto255-encrypted-choice]
+///     ? row-proof
+/// ]
+/// ```
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub enum Choices {
     /// A universal unencrypted set of choices.
@@ -18,6 +33,16 @@ pub enum Choices {
 }
 
 /// An elgamal encrypted ciphertext `(c1, c2)`.
+///
+/// The CDDL schema:
+/// ```cddl
+/// elgamal-ristretto255-encrypted-choice = [
+///     c1: elgamal-ristretto255-group-element
+///     c2: elgamal-ristretto255-group-element
+/// ]
+///
+/// elgamal-ristretto255-group-element = bytes .size 32
+/// ```
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub struct ElgamalRistretto255Choice {
     /// An individual Elgamal group element that composes the elgamal cipher text.
@@ -27,9 +52,29 @@ pub struct ElgamalRistretto255Choice {
 }
 
 /// A universal encrypted row proof.
+///
+/// The CDDL schema:
+/// ```cddl
+/// row-proof = [0, zkproof-elgamal-ristretto255-unit-vector-with-single-selection ]
+///
+/// zkproof-elgamal-ristretto255-unit-vector-with-single-selection = [ +zkproof-elgamal-ristretto255-unit-vector-with-single-selection-item, zkproof-ed25519-scalar ]
+///
+/// zkproof-elgamal-ristretto255-unit-vector-with-single-selection-item = ( zkproof-elgamal-announcement, ~elgamal-ristretto255-encrypted-choice, zkproof-ed25519-r-response )
+///
+/// zkproof-elgamal-announcement = ( zkproof-elgamal-group-element, zkproof-elgamal-group-element, zkproof-elgamal-group-element )
+///
+/// zkproof-elgamal-group-element = bytes .size 32
+///
+/// zkproof-ed25519-r-response = ( zkproof-ed25519-scalar, zkproof-ed25519-scalar, zkproof-ed25519-scalar )
+///
+/// zkproof-ed25519-scalar = bytes .size 32
+/// ```
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub struct RowProof {
-    // TODO: FIXME:
+    /// A list of a single selection proofs.
+    selections: Vec<()>,
+    /// An individual Ed25519 scalar used in ZK proofs.
+    scalar: (),
 }
 
 impl Decode<'_, ()> for Choices {

rust/catalyst-contest/src/column_proof.rs

@@ -7,6 +7,11 @@ use minicbor::{Decode, Decoder, Encode, Encoder, encode::Write};
 const ARRAY_LEN: u64 = 2;
 
 /// A universal encrypted column proof.
+///
+/// The CDDL schema:
+/// ```cddl
+/// column-proof = [ uint, [ +undefined ] ]
+/// ```
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub struct ColumnProof(pub u64);
 

rust/catalyst-contest/src/contest_ballot.rs

@@ -8,6 +8,16 @@ use minicbor::{Decode, Decoder, Encode, Encoder, encode::Write};
 use crate::{Choices, ColumnProof, EncryptedChoices, MatrixProof};
 
 /// An individual Ballot cast in a Contest by a registered user.
+///
+/// The CDDL schema:
+/// ```cddl
+/// contest-ballot-payload = {
+///     + uint => choices
+///     ? "column-proof" : column-proof
+///     ? "matrix-proof" : matrix-proof
+///     ? "voter-choice" : voter-choice
+/// }
+/// ```
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub struct ContentBallot {
     /// A map of voters choices.

rust/catalyst-contest/src/encrypted_choices.rs

@@ -7,10 +7,22 @@ use minicbor::{Decode, Decoder, Encode, Encoder, encode::Write};
 const ENCRYPTED_BLOCK_ARRAY_LEN: u64 = 16;
 
 /// Encrypted voter choices.
+///
+/// The CDDL schema:
+/// ```cddl
+/// voter-choice = [ 0, aes-ctr-encrypted-choices ]
+///
+/// aes-ctr-encrypted-choices = +aes-ctr-encrypted-block
+/// ```
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub struct EncryptedChoices(pub Vec<EncryptedBlock>);
 
 /// An AES-CTR encrypted data block.
+///
+/// The CDDL schema:
+/// ```cddl
+/// aes-ctr-encrypted-block = bytes .size 16
+/// ```
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub struct EncryptedBlock(pub [u8; ENCRYPTED_BLOCK_ARRAY_LEN as usize]);
 
@@ -25,10 +37,10 @@ impl Decode<'_, ()> for EncryptedChoices {
                 "Unexpected encrypted choices array length: {len}, expected at least 2"
             )));
         }
-        let val = u64::decode(d, ctx)?;
-        if val != 0 {
+        let version = u64::decode(d, ctx)?;
+        if version != 0 {
             return Err(minicbor::decode::Error::message(format!(
-                "Unexpected encrypted choices array value: {val}, expected 0"
+                "Unexpected encrypted choices array value: {version}, expected 0"
             )));
         }
 

rust/catalyst-contest/src/matrix_proof.rs

@@ -7,6 +7,11 @@ use minicbor::{Decode, Decoder, Encode, Encoder, encode::Write};
 const ARRAY_LEN: u64 = 2;
 
 /// A universal encrypted matrix proof.
+///
+/// The CDDL schema:
+/// ```cddl
+/// matrix-proof = [ uint, undefined ]
+/// ```
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub struct MatrixProof(pub u64);