How kaleababayneh/zkuni works
Project Type and Purpose
• zkUni is a privacy-preserving, single-page admissions system (a web-based full-stack app with most logic on the client) that uses a Noir ZK circuit to compute and prove a stable matching (Gale-Shapley) with ElGamal encrypted results.
• Key Use Case: Students and colleges submit hidden preference lists; the system computes an optimal matching inside a ZK circuit, encrypts matches per recipient, and generates a proof of correct matching/encryption without revealing any preferences.
File-Structure Analysis
• Top Level:
• package.json, bun.lock, package-lock.json, vite.config.js
→ Frontend build & dependency management (Vite + Node).
• index.html, index.js, stable.js, new.js, key-generate.js
→ Client entry-point, preference collection, key gen, proof invocation scripts.
• circuit/
• Nargo.toml
→ Noir circuit project config.
• src/elgamal.nr, src/main.nr
→ Noir code for ElGamal encryption & Gale-Shapley matching.
• target/circuit.json
→ Compiled circuit artifact consumed by JS prover/runtime.
README Insights
• Technologies: Noir for ZK logic, ElGamal for encryption, JavaScript/TypeScript for client logic, Vite for bundling.
• Architecture Intent: Purely trustless, zero-knowledge matching; proof ⇒ correctness of both matching algorithm and encryption steps.
Main Components & Relationships
a. Frontend Web Application
• index.html + JS modules (index.js, stable.js, new.js)
• Serves UI for preference entry, triggering cryptographic routines.
b. Key-Generation Module (key-generate.js)
• Generates ElGamal key pairs for students & colleges.
c. ZK Prover Runtime (noir-client + WASM)
• Loads circuit.json, takes inputs (prefs + keys), runs witness gen & proof.
d. Noir ZK Circuit (main.nr + elgamal.nr)
• Implements Gale-Shapley + ElGamal encryption inside the proof.
e. Proof Verifier (noir-client or embedded verifier)
• Verifies the proof without revealing any inputs.
f. Delivery & Decryption
• Encrypted match outputs are distributed; recipients use private keys to decrypt.
Architectural Patterns & Principles
• Separation of Concerns:
• UI vs. Cryptographic Logic vs. Circuit definition.
• Zero-Knowledge Pattern:
• Prover/Verifier roles clearly separated.
• Client-Heavy Compute:
• Moves both matching and proof generation to the browser/Node, avoids a trusted backend.