feat(rust): Encoding/decoding for the ContestBallotPayload type

rust/catalyst-contest/Cargo.toml

@@ -15,7 +15,14 @@ workspace = true
 [dependencies]
 anyhow = "1.0.100"
 async-trait = "0.1.89"
-catalyst-signed-doc = { version = "0.0.10", path = "../signed_doc" }
 futures = "0.3.31"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.145"
+minicbor = { version = "0.25.1", features = ["alloc", "derive", "half"] }
+proptest = { version = "1.6.0", features = ["attr-macro"] }
+proptest-derive = "0.5.1"
+
+cbork-utils = { version = "0.0.2", git = "https://github.com/input-output-hk/catalyst-libs.git", tag = "cbork-utils-v0.0.2" }
+# TODO: Use tag instead of path.
+catalyst-signed-doc = { version = "0.0.10", path = "../signed_doc" }
+catalyst-voting = { version = "0.0.2", git = "https://github.com/input-output-hk/catalyst-libs.git", tag = "catalyst-voting/v0.0.2" }

rust/catalyst-contest/src/contest_ballot/ballot.rs

@@ -0,0 +1,159 @@
+//! An individual Ballot cast in a Contest by a registered user.
+
+use std::collections::BTreeMap;
+
+use cbork_utils::decode_helper::decode_map_len;
+use minicbor::{Decode, Decoder, Encode, Encoder, encode::Write};
+
+use crate::{Choices, EncryptedChoices};
+
+/// 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 ContentBallotPayload {
+    /// A map of voters choices.
+    pub choices: BTreeMap<u64, Choices>,
+    /// A universal encrypted column proof.
+    ///
+    /// This is a placeholder for now and should always be `None`.
+    pub column_proof: Option<()>,
+    /// A universal encrypted matrix proof.
+    ///
+    /// This is a placeholder for now and should always be `None`.
+    pub matrix_proof: Option<()>,
+    /// An encrypted voter choice payload.
+    pub voter_choices: Option<EncryptedChoices>,
+}
+
+impl Decode<'_, ()> for ContentBallotPayload {
+    fn decode(
+        d: &mut Decoder<'_>,
+        ctx: &mut (),
+    ) -> Result<Self, minicbor::decode::Error> {
+        use minicbor::data::Type;
+
+        let len = decode_map_len(d, "content ballot payload")?;
+
+        let mut choices = BTreeMap::new();
+        let column_proof = None;
+        let matrix_proof = None;
+        let mut voter_choices = None;
+        for _ in 0..len {
+            match d.datatype()? {
+                Type::U8 | Type::U16 | Type::U32 | Type::U64 => {
+                    let key = d.u64()?;
+                    let val = Choices::decode(d, ctx)?;
+                    choices.insert(key, val);
+                },
+                Type::String => {
+                    match d.str()? {
+                        "column-proof" => {
+                            return Err(minicbor::decode::Error::message(
+                                "column-proof is a placeholder and shouldn't be used",
+                            ));
+                        },
+                        "matrix-proof" => {
+                            return Err(minicbor::decode::Error::message(
+                                "matrix-proof is a placeholder and shouldn't be used",
+                            ));
+                        },
+                        "voter-choices" => voter_choices = Some(EncryptedChoices::decode(d, ctx)?),
+                        key => {
+                            return Err(minicbor::decode::Error::message(format!(
+                                "Unexpected content ballot payload key value: {key:?}"
+                            )));
+                        },
+                    }
+                },
+                t => {
+                    return Err(minicbor::decode::Error::message(format!(
+                        "Unexpected content ballot payload key type: {t:?}"
+                    )));
+                },
+            }
+        }
+
+        Ok(Self {
+            choices,
+            column_proof,
+            matrix_proof,
+            voter_choices,
+        })
+    }
+}
+
+impl Encode<()> for ContentBallotPayload {
+    fn encode<W: Write>(
+        &self,
+        e: &mut Encoder<W>,
+        _ctx: &mut (),
+    ) -> Result<(), minicbor::encode::Error<W::Error>> {
+        let len = u64::try_from(self.choices.len())
+            .map_err(minicbor::encode::Error::message)?
+            .checked_add(u64::from(self.column_proof.is_some()))
+            .and_then(|v| v.checked_add(u64::from(self.matrix_proof.is_some())))
+            .and_then(|v| v.checked_add(u64::from(self.voter_choices.is_some())))
+            .ok_or_else(|| {
+                minicbor::encode::Error::message("contest ballot payload map length overflow")
+            })?;
+        e.map(len)?;
+
+        for (&key, val) in &self.choices {
+            e.u64(key)?.encode(val)?;
+        }
+        if let Some(column_proof) = self.column_proof.as_ref() {
+            e.str("column-proof")?.encode(column_proof)?;
+        }
+        if let Some(matrix_proof) = self.matrix_proof.as_ref() {
+            e.str("matrix-proof")?.encode(matrix_proof)?;
+        }
+        if let Some(voter_choices) = self.voter_choices.as_ref() {
+            e.str("voter-choices")?.encode(voter_choices)?;
+        }
+
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use catalyst_voting::crypto::elgamal::Ciphertext;
+
+    use super::*;
+    use crate::contest_ballot::encrypted_block::EncryptedBlock;
+
+    #[test]
+    fn roundtrip() {
+        let original = ContentBallotPayload {
+            choices: [
+                (1, Choices::Clear(vec![1, 2, 3, 4, 5])),
+                (2, Choices::Encrypted {
+                    choices: vec![Ciphertext::zero()],
+                    row_proof: None,
+                }),
+            ]
+            .into(),
+            column_proof: None,
+            matrix_proof: None,
+            voter_choices: Some(EncryptedChoices(vec![
+                EncryptedBlock([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]),
+                EncryptedBlock([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]),
+            ])),
+        };
+        let mut buffer = Vec::new();
+        original
+            .encode(&mut Encoder::new(&mut buffer), &mut ())
+            .unwrap();
+        let decoded = ContentBallotPayload::decode(&mut Decoder::new(&buffer), &mut ()).unwrap();
+        assert_eq!(original, decoded);
+    }
+}

rust/catalyst-contest/src/contest_ballot/choices.rs

@@ -0,0 +1,157 @@
+//! Voters Choices.
+
+use catalyst_voting::crypto::{elgamal::Ciphertext, zk_unit_vector::UnitVectorProof};
+use cbork_utils::decode_helper::decode_array_len;
+use minicbor::{Decode, Decoder, Encode, Encoder, encode::Write};
+
+/// A clear choice indicator. See the `Choices` CBOR schema for the details.
+const CLEAR_CHOICE: u8 = 0;
+
+/// An encrypted choice indicator. See the `Choices` CBOR schema for the details.
+const ENCRYPTED_CHOICE: u8 = 1;
+
+/// Voters Choices.
+///
+/// The CDDL schema:
+/// ```cddl
+/// choices = [ 0, clear-choices ] /
+/// [ 1, elgamal-ristretto255-encrypted-choices ]
+///
+/// clear-choices = ( +clear-choice )
+///
+/// clear-choice = uint
+///
+/// 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.
+    Clear(Vec<u64>),
+    /// ElGamal/Ristretto255 encrypted choices.
+    Encrypted {
+        /// A list of ElGamal/Ristretto255 encrypted choices.
+        choices: Vec<Ciphertext>,
+        /// A universal encrypted row proof.
+        row_proof: Option<UnitVectorProof>,
+    },
+}
+
+impl Decode<'_, ()> for Choices {
+    fn decode(
+        d: &mut Decoder<'_>,
+        ctx: &mut (),
+    ) -> Result<Self, minicbor::decode::Error> {
+        let len = decode_array_len(d, "choices")?;
+        if len < 2 {
+            return Err(minicbor::decode::Error::message(format!(
+                "Unexpected choices array length {len}, expected at least 2"
+            )));
+        }
+        match u8::decode(d, ctx)? {
+            CLEAR_CHOICE => {
+                let mut values = Vec::with_capacity(
+                    len.checked_sub(1)
+                        .ok_or_else(|| {
+                            minicbor::decode::Error::message("Choices array length underflow")
+                        })?
+                        .try_into()
+                        .map_err(minicbor::decode::Error::message)?,
+                );
+                for _ in 1..len {
+                    values.push(u64::decode(d, ctx)?);
+                }
+                Ok(Self::Clear(values))
+            },
+            ENCRYPTED_CHOICE => {
+                if len > 2 {
+                    return Err(minicbor::decode::Error::message(format!(
+                        "Unexpected encrypted choices array length {len}, expected 2"
+                    )));
+                }
+
+                let len = decode_array_len(d, "elgamal-ristretto255-encrypted-choices")?;
+                if !(1..=2).contains(&len) {
+                    return Err(minicbor::decode::Error::message(format!(
+                        "Unexpected elgamal-ristretto255-encrypted-choices array length {len}, expected 1 or 2"
+                    )));
+                }
+                let choices = <Vec<Ciphertext>>::decode(d, ctx)?;
+                let mut row_proof = None;
+                if len == 2 {
+                    row_proof = Some(UnitVectorProof::decode(d, ctx)?);
+                }
+                Ok(Self::Encrypted { choices, row_proof })
+            },
+            val => {
+                Err(minicbor::decode::Error::message(format!(
+                    "Unexpected choices value: {val}"
+                )))
+            },
+        }
+    }
+}
+
+impl Encode<()> for Choices {
+    fn encode<W: Write>(
+        &self,
+        e: &mut Encoder<W>,
+        ctx: &mut (),
+    ) -> Result<(), minicbor::encode::Error<W::Error>> {
+        match self {
+            Choices::Clear(choices) => {
+                e.array((choices.len() as u64).checked_add(1).ok_or_else(|| {
+                    minicbor::encode::Error::message("Clear choices array length overflow")
+                })?)?;
+                0.encode(e, ctx)?;
+                for choice in choices {
+                    choice.encode(e, ctx)?;
+                }
+            },
+            Choices::Encrypted { choices, row_proof } => {
+                e.array(2)?;
+                1.encode(e, ctx)?;
+                // Allowed because 1 + 1 will never result in overflow.
+                #[allow(clippy::arithmetic_side_effects)]
+                e.array(1 + u64::from(row_proof.is_some()))?;
+                choices.encode(e, ctx)?;
+                if let Some(row_proof) = row_proof {
+                    row_proof.encode(e, ctx)?;
+                }
+            },
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn clear_roundtrip() {
+        let original = Choices::Clear(vec![1, 2, 3]);
+        let mut buffer = Vec::new();
+        original
+            .encode(&mut Encoder::new(&mut buffer), &mut ())
+            .unwrap();
+        let decoded = Choices::decode(&mut Decoder::new(&buffer), &mut ()).unwrap();
+        assert_eq!(original, decoded);
+    }
+
+    #[test]
+    fn encrypted_roundtrip() {
+        let original = Choices::Encrypted {
+            choices: vec![Ciphertext::zero(), Ciphertext::zero()],
+            row_proof: None,
+        };
+        let mut buffer = Vec::new();
+        original
+            .encode(&mut Encoder::new(&mut buffer), &mut ())
+            .unwrap();
+        let decoded = Choices::decode(&mut Decoder::new(&buffer), &mut ()).unwrap();
+        assert_eq!(original, decoded);
+    }
+}

rust/catalyst-contest/src/contest_ballot/encrypted_block.rs

@@ -0,0 +1,52 @@
+//! An AES-CTR encrypted data block.
+
+use minicbor::{Decode, Decoder, Encode, Encoder, encode::Write};
+
+/// A length of the encrypted block byte array.
+const ENCRYPTED_BLOCK_LEN: usize = 16;
+
+/// An AES-CTR encrypted data block.
+///
+/// The CDDL schema:
+/// ```cddl
+/// aes-ctr-encrypted-block = bytes .size 16
+/// ```
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+#[cfg_attr(test, derive(proptest_derive::Arbitrary))]
+pub struct EncryptedBlock(pub [u8; ENCRYPTED_BLOCK_LEN]);
+
+impl Decode<'_, ()> for EncryptedBlock {
+    fn decode(
+        d: &mut Decoder<'_>,
+        ctx: &mut (),
+    ) -> Result<Self, minicbor::decode::Error> {
+        <[u8; ENCRYPTED_BLOCK_LEN]>::decode(d, ctx).map(Self)
+    }
+}
+
+impl Encode<()> for EncryptedBlock {
+    fn encode<W: Write>(
+        &self,
+        e: &mut Encoder<W>,
+        ctx: &mut (),
+    ) -> Result<(), minicbor::encode::Error<W::Error>> {
+        self.0.encode(e, ctx)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use proptest::property_test;
+
+    use super::*;
+
+    #[property_test]
+    fn roundtrip(original: EncryptedBlock) {
+        let mut buffer = Vec::new();
+        original
+            .encode(&mut Encoder::new(&mut buffer), &mut ())
+            .unwrap();
+        let decoded = EncryptedBlock::decode(&mut Decoder::new(&buffer), &mut ()).unwrap();
+        assert_eq!(original, decoded);
+    }
+}