Add more docs

Author: tcerqueira

README.md

@@ -1,23 +1,108 @@
 # Zanzibar
 
-Worldcoin re-mixing system.
+Distributed cryptographic protocol.
 
 ## Overview
 
 ## Run
 
-To run the tests
-```
+To run the tests:
+```bash
 cargo test
 ```
 
-To run the benchmarks
-```
+To run the benchmarks:
+```bash
 cargo bench
 ```
 
-To generate documentation
+To generate documentation:
+```bash
+cargo doc --open
 ```
-cargo doc
+
+## Demo
+
+To run a demo we need:
+- A shared key
+- 3 mix nodes
+- 1 client
+
+There's a key already configured in `mix-node/config/crypto.json`. However, the `secret_key` will be different for each node, this will be overriden with environment variables later.
+
+### Keys
+- Participant 0: `secret_key = "D7W4K_1QPjuoEQNsTeyWT92yHSPp67-sApmGksw9EQo"`
+- Participant 1: `secret_key = "XGaup1prWoijF91au13Qv2OgqGjo-uE74szhzGbXUgw"`
+- Participant 2: `secret_key = "qRekI7iFdtWeHbdJKc8JMOqNM67nCQTLwQA9BwFxlA4"`
+
+<!-- If you want to generate keys yourself, you can run:
+```bash
+# 3 participants with 2 minimum threshold
+cargo run --bin gen_keys -- 2 3
 ```
-You can find the generated docs on /target/doc/remix/index.hmtl
+And then copy the `key_set` into the `crypto.json` config file. -->
+
+<details>
+<summary>If you want to generate keys yourself (optional)</summary>
+
+To generate a new set of keys:
+```bash
+# 3 participants with 2 minimum threshold
+cargo run --bin gen_keys -- 2 3
+```
+Copy the resulting `key_set` into the `crypto.json` config file.
+</details>
+
+### Running Mix Nodes
+
+We can spin up the 3 mix nodes like so:
+```bash
+# For more detailed logs, run these before starting the servers:
+# export RUST_LOG=info,mix_node=trace,tower_http=debug
+
+# Participant 0
+APP_CRYPTO__SECRET_KEY="D7W4K_1QPjuoEQNsTeyWT92yHSPp67-sApmGksw9EQo" \
+APP_CRYPTO__WHOAMI="0" \
+APP_APPLICATION__PORT="6000" \
+cargo run --bin rest --release
+
+# Participant 1
+APP_CRYPTO__SECRET_KEY="XGaup1prWoijF91au13Qv2OgqGjo-uE74szhzGbXUgw" \
+APP_CRYPTO__WHOAMI="1" \
+APP_APPLICATION__PORT="6001" \
+cargo run --bin rest --release
+
+# Participant 2
+APP_CRYPTO__SECRET_KEY="qRekI7iFdtWeHbdJKc8JMOqNM67nCQTLwQA9BwFxlA4" \
+APP_CRYPTO__WHOAMI="2" \
+APP_APPLICATION__PORT="6002" \
+cargo run --bin rest --release
+```
+
+### Running the Client
+
+Now that the network of mix-nodes is up and running, we can run the client that will request a comparison:
+```bash
+# two codes of length 10
+cargo run --example demo -- 10
+
+# two codes of length 12800
+cargo run --example demo -- 12800
+```
+**Note:** Because the servers are running on the same machine and the operations are very CPU heavy, the performance is not truly representative of a real-world deployment.
+
+### How it Works
+
+The client:
+1. Requests the public key to encrypt the codes (instead of hardcoding it)
+2. Generates a random code with the given length and clones it (both codes will be identical)
+3. Encrypts both codes and sends a request to "http://localhost:6000/hamming"
+4. Since the codes are identical, the expected hamming distance is 0
+
+### Testing Threshold Decryption
+
+To test threshold decryption:
+1. Shutdown the mix-node on port `6002` and run the client again - it should still compute the hamming distance
+2. Shutdown another mix-node (port `6001`) - the network can no longer compute the hamming distance because the number of nodes is below the threshold, returning an error
+
+The code for the client can be found at `mix-node/examples/demo`.

mix-node/examples/demo/main.rs

@@ -15,7 +15,8 @@ async fn main() -> anyhow::Result<()> {
         .nth(1)
         .expect("cli arg 'n_bits' missing")
         .parse::<usize>()
-        .expect("cli arg is not a number");
+        .expect("cli arg is not a number")
+        * 2;
     let port = 6000;
     // Request public key
     let client = reqwest::Client::new();

mix-node/src/crypto.rs

@@ -1,3 +1,52 @@
+//! Secure cryptographic primitives for threshold ElGamal encryption.
+//!
+//! This module provides a set of tools for encrypted communication with threshold
+//! decryption capabilities using the ElGamal cryptosystem over the Ristretto curve.
+//! The implementation supports distributed key generation, encryption, remixing,
+//! threshold decryption, and verification of decryption shares.
+//!
+//! # Key Features
+//!
+//! * Secure threshold encryption using ElGamal over Ristretto
+//! * Efficient parallel processing with Rayon
+//! * Verifiable decryption shares
+//! * Support for mixing and remixing of ciphertexts
+//! * Hamming distance calculation between bit vectors
+//!
+//! # Examples
+//!
+//! ```
+//! # use anyhow::Result;
+//! # use elastic_elgamal::sharing::{Dealer, Params, PublicKeySet, ActiveParticipant};
+//! # use elastic_elgamal::group::Ristretto;
+//! # use bitvec::prelude::*;
+//! # use mix_node::crypto::*;
+//! # fn main() -> Result<()> {
+//! # let mut rng = rand::thread_rng();
+//! # let params = Params::new(3, 2);
+//! # let dealer = Dealer::<Ristretto>::new(params, &mut rng);
+//! # let (public_poly, poly_proof) = dealer.public_info();
+//! # let key_set = PublicKeySet::new(params, public_poly, poly_proof)?;
+//! # let participants: Vec<_> = (0..3)
+//! #    .map(|i| ActiveParticipant::new(key_set.clone(), i,
+//! #         dealer.secret_share_for_participant(i)).unwrap())
+//! #    .collect();
+//! # let bits = bitvec![1, 0, 1, 0];
+//! // Encrypt data
+//! let encrypted = encrypt(key_set.shared_key(), &bits);
+//!
+//! // Generate decryption shares
+//! let shares = vec![
+//!     decryption_share_for(&participants[0], &encrypted),
+//!     decryption_share_for(&participants[1], &encrypted),
+//! ];
+//!
+//! // Combine shares and decrypt
+//! let decrypted = decrypt_shares(&key_set, &encrypted, &shares)?;
+//! # Ok(())
+//! # }
+//! ```
+
 use anyhow::Context;
 use elastic_elgamal::{
     group::Ristretto,
@@ -9,16 +58,33 @@ use serde::{Deserialize, Serialize};
 use std::sync::LazyLock;
 use thiserror::Error;
 
+/// An ElGamal ciphertext over the Ristretto curve.
 pub type Ciphertext = elastic_elgamal::Ciphertext<Ristretto>;
+
+/// A bit vector used for storing binary data.
 pub type Bits = bitvec::vec::BitVec;
 
+/// A decryption share from a participant in the threshold encryption scheme.
+///
+/// Contains the participant's index and their decryption shares
+/// for a set of ciphertexts, along with proofs of correctness.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct DecryptionShare {
     index: usize,
     share: Vec<(VerifiableDecryption<Ristretto>, LogEqualityProof<Ristretto>)>,
 }
 
 impl DecryptionShare {
+    /// Creates a new decryption share with the given participant index and shares.
+    ///
+    /// # Arguments
+    ///
+    /// * `index` - The participant's index
+    /// * `share` - A vector of verifiable decryptions with their proofs
+    ///
+    /// # Returns
+    ///
+    /// A new `DecryptionShare` instance
     pub fn new(
         index: usize,
         share: Vec<(VerifiableDecryption<Ristretto>, LogEqualityProof<Ristretto>)>,
@@ -27,15 +93,24 @@ impl DecryptionShare {
     }
 }
 
+/// Discrete logarithm lookup table optimized for binary values.
+///
+/// This static table is used for efficient decryption of binary values (0 or 1).
 pub static LOOKUP_TABLE: LazyLock<DiscreteLogTable<Ristretto>> =
     LazyLock::new(|| DiscreteLogTable::<Ristretto>::new(0..=1));
 
+/// Errors that can occur during cryptographic operations.
 #[derive(Debug, Error)]
 pub enum CryptoError {
+    /// Error indicating invalid or mismatched lengths in cryptographic operations.
     #[error("InvalidLength: {0}")]
     InvalidLength(String),
 }
 
+/// Remixes two ciphertext vectors using ElGamal homomorphic properties.
+///
+/// This function performs remixing operations on two encrypted code vectors.
+/// Both vectors must have the same length, and the length must be even.
 pub fn remix(
     x_code: &mut [Ciphertext],
     y_code: &mut [Ciphertext],
@@ -51,6 +126,10 @@ pub fn remix(
     Ok(())
 }
 
+/// Encrypts a bit vector using the provided public key.
+///
+/// This function encrypts each bit in the input bit vector in parallel
+/// using the ElGamal encryption scheme.
 pub fn encrypt(pub_key: &PublicKey<Ristretto>, bits: &Bits) -> Vec<Ciphertext> {
     bits.as_raw_slice()
         .into_par_iter()
@@ -71,6 +150,10 @@ pub fn encrypt(pub_key: &PublicKey<Ristretto>, bits: &Bits) -> Vec<Ciphertext> {
         .collect::<Vec<_>>()
 }
 
+/// Generates decryption shares for a set of ciphertexts.
+///
+/// This function allows a participant to generate their decryption share
+/// for each ciphertext in the provided array.
 pub fn decryption_share_for(
     active_participant: &ActiveParticipant<Ristretto>,
     ciphertext: &[Ciphertext],
@@ -85,6 +168,10 @@ pub fn decryption_share_for(
     DecryptionShare::new(active_participant.index(), share)
 }
 
+/// Combines decryption shares to recover the original plaintext.
+///
+/// This function verifies and combines decryption shares from multiple
+/// participants to decrypt the original message.
 pub fn decrypt_shares(
     key_set: &PublicKeySet<Ristretto>,
     enc: &[Ciphertext],
@@ -124,6 +211,10 @@ pub fn decrypt_shares(
         .map(Bits::from_iter)
 }
 
+/// Calculates the Hamming distance between two bit vectors.
+///
+/// The Hamming distance is the number of positions at which the corresponding
+/// bits are different.
 pub fn hamming_distance(x_code: Bits, y_code: Bits) -> usize {
     // Q: What if x and y are different sizes?
     (x_code ^ y_code).count_ones()

mix-node/src/lib.rs

@@ -2,7 +2,7 @@ pub mod config;
 pub mod crypto;
 pub mod db;
 pub mod rest;
-pub(crate) mod rokio;
+pub mod rokio;
 pub mod test_helpers;
 
 use config::CryptoConfig;

mix-node/src/rest/error.rs

@@ -1,3 +1,8 @@
+//! Error types for the application.
+//!
+//! This module defines the error types used throughout the application,
+//! particularly for handling HTTP responses and crypto-related errors.
+
 use axum::{
     http::StatusCode,
     response::{IntoResponse, Response},
@@ -6,14 +11,25 @@ use thiserror::Error;
 
 use crate::crypto::CryptoError;
 
+/// Application-wide error types.
 #[derive(Debug, Error)]
 pub enum Error {
+    /// Error indicating an invalid length was provided
     #[error("InvalidLength: {0}")]
     InvalidLength(String),
+
+    /// Unexpected errors that don't fit other categories
     #[error(transparent)]
     Unexpected(#[from] anyhow::Error),
 }
 
+/// Implementation of `IntoResponse` for the application's error types.
+///
+/// Converts application errors into HTTP responses with appropriate status codes:
+/// - `InvalidLength` errors return `400 Bad Request`
+/// - `Unexpected` errors return `500 Internal Server Error`
+///
+/// The response body contains the error message as a string.
 impl IntoResponse for Error {
     fn into_response(self) -> Response {
         let status_code = match &self {