DOCUMENTATION

Everything you need to know about BitVeil

Overview

BitVeil is a privacy-preserving zero-knowledge proof demonstration for Hamming distance calculations. Built with Halo2 ZK-SNARKs and WebAssembly, it enables you to prove the similarity between two binary vectors without revealing the vectors themselves.

All cryptographic operations run locally in your browser. No data is ever sent to any server, ensuring complete privacy and security for sensitive comparisons.

Use Cases

  • Biometric matching (fingerprints, iris scans) without exposing biometric data
  • Secure similarity comparisons for encrypted databases
  • Private set intersection protocols
  • Decentralized identity verification systems
  • Privacy-preserving machine learning model comparisons

Features

Zero Knowledge

Prove Hamming distance without revealing input vectors. Complete privacy guaranteed.

Browser-Based

All operations run locally in your browser. No server communication required.

WASM-Powered

High-performance Rust circuits compiled to WebAssembly for speed.

Halo2 ZK-SNARKs

Industry-standard zero-knowledge proof system with Pasta curves.

Getting Started

Installation

git clone https://github.com/kunalsinghdadhwal/bitveil.git
cd bitveil
pnpm install

Development

pnpm dev

Open http://localhost:3000 to view the application.

Building Circuits (Optional)

If you modify the Rust circuits, rebuild the WASM module:

cd circuits
wasm-pack build --target bundler
cp -r pkg/* ../src/lib/wasm/

How It Works

What is Hamming Distance?

Hamming distance measures the number of positions at which two binary vectors differ. For example, comparing 1010 and 0011 gives a Hamming distance of 3 (three positions differ).

Vector A: 1 0 1 0
Vector B: 0 0 1 1
XOR: 1 0 0 1
Distance: 2 (bits differ)

Zero-Knowledge Proof Process

1

Setup Parameters

Generate or load cryptographic parameters (k=8 by default, meaning 256 circuit rows). Cached in browser for reuse.

2

Input Vectors

Enter two 32-bit binary vectors. Validation ensures only 0s and 1s are accepted.

3

Circuit Creation

The WASM module creates a Halo2 circuit with binary constraints, XOR gates, and accumulation logic.

4

Proof Generation

Generate proving and verifying keys, then create a zero-knowledge proof. This takes 2-5 seconds depending on your browser.

5

Verification

Verify the proof against the claimed Hamming distance. Verification takes under 1 second.

Architecture

BitVeil consists of two main components: a Rust-based ZK circuit library and a Next.js web application.

Technology Stack

Frontend

  • Next.js 15
  • React 19
  • TypeScript
  • Tailwind CSS
  • Radix UI

Backend

  • Rust (circuits)
  • Halo2 (ZK proofs)
  • Pasta Curves
  • WebAssembly
  • wasm-pack

Usage Guide

Browser Demo

  1. 1.Navigate to the demo page and wait for WASM circuits to load (indicated by a success toast)
  2. 2.Enter two 32-bit binary vectors (comma or space separated) or use quick examples
  3. 3.Click "Generate ZK Proof" to create a proof (takes 2-5 seconds)
  4. 4.View the Hamming distance and generated proof (Base64 encoded)
  5. 5.Click "Verify Proof" to confirm the proof is valid (takes under 1 second)
  6. 6.Test with different distances using the "Proof Tester" card to see failures

Example Vectors

Identical Vectors (Distance: 0)

A: 1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0
B: 1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0

Similar Vectors (Distance: 4)

A: 1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0
B: 0,0,1,0,0,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,0,0,1,0

Opposite Vectors (Distance: 32)

A: 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1
B: 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

CLI Reference

BitVeil includes a command-line interface for native proof generation and verification.

Building the CLI

cd circuits
cargo build --release --bin cli

Binary location: ./target/x86_64-unknown-linux-gnu/release/cli

Circuit Details

Circuit Architecture

The BitVeil circuit is built using the Halo2 proving system with three main components:

BitVeilChip

Main chip implementing circuit logic with binary verification, XOR computation, and accumulation.

BitVeilConfig

Configuration defining circuit structure: 3 advice columns and 1 instance column.

BitVeilCircuit

Complete circuit implementation with vector inputs and Hamming distance output.

Circuit Operations

  1. 1

    Binary Verification

    Validates that all input values are binary using the constraint: value * (1 - value) = 0

  2. 2

    XOR Computation

    Performs bitwise XOR using the constraint: a + b - 2ab - out = 0

  3. 3

    Accumulation

    Sums all XOR results to compute the final Hamming distance

  4. 4

    Public Output

    Exposes only the Hamming distance as a public value (vectors remain private)

Cryptographic Details

Proof System

Halo2 with Pasta curves

Field

Pallas base field (Fp)

Vector Length

32 bits

Transcript

Blake2b hash function

Performance

Performance metrics for browser-based proof generation and verification:

2-5s
Proof Generation
Browser-dependent
<1s
Verification
Consistently fast
2MB
WASM Size
First load only

Optimization Features

  • Setup parameters cached in localStorage (avoid regeneration)
  • WASM module loaded once per session and cached by browser
  • Proofs stored in localStorage for testing different distances
  • Optimized Rust compilation with release profile

Technical Specifications

Frontend

  • Next.js 15 (App Router)
  • React 19
  • TypeScript 5
  • Tailwind CSS 4
  • Radix UI Components
  • Framer Motion
  • Sonner (Toast notifications)

Cryptography

  • Halo2 Proving System
  • Pasta Curves (Pallas/Vesta)
  • Blake2b Transcript Hash
  • Plonkish Arithmetization
  • IPA Polynomial Commitment

Build Tools

  • Rust 1.70+
  • Cargo (Rust package manager)
  • wasm-pack 0.12+
  • pnpm 9
  • Node.js 18+

Dependencies

  • halo2_proofs 0.3
  • pasta_curves 0.5
  • wasm-bindgen 0.2
  • clap 4 (CLI)
  • anyhow (Error handling)