Build Your First Zero-Knowledge Proof in 30 Minutes (No Math PhD Required)

Learn ZKPs by building a working age verification system. Skip the theory, get hands-on with circom and JavaScript in under 30 minutes.
·
8 min read
·
Mark
·
Web3 Cryptography

Your users want privacy. Your compliance team wants verification. Zero-Knowledge Proofs let you have both.

I spent 2 weeks wrapping my head around ZKPs until I found the right approach. Here's what actually works for developers who need to ship code, not publish papers.

What you'll build: An age verification system that proves someone is over 21 without revealing their actual age or birthday Time needed: 30 minutes Difficulty: Intermediate (you should know JavaScript and basic cryptography concepts)

Skip the mathematical proofs. We're building something that works in production.

Why I Built This

I needed to verify user ages for a fintech app without storing sensitive data. GDPR compliance was brutal, and users hated sharing full birthdates for simple age checks.

My setup:

  • React frontend with sensitive financial data
  • Strict privacy regulations in EU and California
  • Users dropping off during lengthy verification flows
  • Security audit requiring minimal data collection

What didn't work:

  • Traditional age verification: stored too much PII
  • Self-attestation: compliance team rejected it
  • Third-party services: too expensive at $0.50 per verification
  • Homomorphic encryption: way too complex for the team

What Are Zero-Knowledge Proofs (The 2-Minute Version)

The problem: You need to verify something about your users without learning their private information.

My solution: ZKPs let users mathematically prove they meet requirements (like being over 21) without revealing the underlying data (their actual birthdate).

Time this saves: Eliminates privacy compliance headaches and builds user trust.

Think of it like showing your ID to a bouncer who only needs to know "over 21: yes/no" but instead sees your full birthdate, address, and ID number. ZKPs are like having a magic ID that only shows the bouncer a green checkmark.

Step 1: Install the ZKP Toolkit

The problem: ZKP development has terrible tooling scattered across multiple repositories.

My solution: Use circom for circuits and snarkjs for JavaScript integration - they actually work together.

Time this saves: Avoid the 4-hour rabbit hole of incompatible ZKP libraries.

# Install circom (the circuit compiler)
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
source ~/.cargo/env
git clone https://github.com/iden3/circom.git
cd circom
cargo build --release
cargo install --path circom

# Install snarkjs (JavaScript ZKP library)
npm install -g snarkjs

# Create your project
mkdir zkp-age-verification
cd zkp-age-verification
npm init -y
npm install snarkjs circomlib

What this does: Sets up the complete ZKP development environment with working compilers and libraries. Expected output: You should see "circom 2.1.6" when you run circom --version

Personal tip: "Install circom globally or you'll waste 20 minutes on path issues like I did."

Step 2: Write Your First Circuit

The problem: ZKP circuits look like alien mathematics to most developers.

My solution: Start with a simple age verification circuit that's actually readable.

Time this saves: Skip the academic examples and build something you can actually use.

Create age_verification.circom:

pragma circom 2.1.6;

// Circuit to prove age >= 21 without revealing actual age
template AgeVerification() {
    // Private inputs (user's secret data)
    signal private input birthYear;
    signal private input currentYear;
    
    // Public inputs (known to everyone)
    signal input minAge;
    
    // Output (the proof result)
    signal output isValid;
    
    // Calculate age
    component age = currentYear - birthYear;
    
    // Check if age >= minAge (21)
    component ageCheck = GreaterEqualThan(8); // 8 bits = max age 255
    ageCheck.in[0] <== age;
    ageCheck.in[1] <== minAge;
    
    // Output 1 if valid, 0 if not
    isValid <== ageCheck.out;
}

// Import the comparison component
include "circomlib/circuits/comparators.circom";

// Create the main component
component main = AgeVerification();

What this does: Creates a mathematical circuit that proves age >= 21 without revealing the actual birthdate. Expected output: A .circom file that compiles without errors.

Personal tip: "The private input keyword is crucial - that data never gets revealed, only used in the proof."

Step 3: Compile Your Circuit

The problem: Circuit compilation errors are cryptic and unhelpful.

My solution: Use this exact command sequence that handles the common gotchas.

Time this saves: Avoid the 30-minute debug session when compilation fails.

# Compile the circuit
circom age_verification.circom --r1cs --wasm --sym --c

# This creates several files:
# - age_verification.r1cs: The compiled circuit
# - age_verification_js/: WebAssembly for browsers
# - age_verification.sym: Debugging symbols

What this does: Converts your human-readable circuit into mathematical constraints the ZKP system can use. Expected output: You should see "Everything went okay" and several new files/folders.

Personal tip: "If you get 'template not found' errors, make sure your include paths are correct and circomlib is installed."

Step 4: Generate the Proving and Verification Keys

The problem: ZKP systems need special cryptographic keys, and the setup is confusing.

My solution: Use the Powers of Tau ceremony files (they're like SSL certificates for ZKPs).

Time this saves: Skip the 2-hour trusted setup ceremony for development.

# Download a Powers of Tau file (or generate for production)
curl -L https://hermez.s3-eu-west-1.amazonaws.com/powersOfTau28_hez_final_12.ptau -o pot12_final.ptau

# Generate the zero-knowledge keys
snarkjs groth16 setup age_verification.r1cs pot12_final.ptau age_verification_0000.zkey

# Apply a random beacon (for production, you'd do a ceremony)
snarkjs zkey contribute age_verification_0000.zkey age_verification_final.zkey --name="First contribution" -e="some random text"

# Generate verification key
snarkjs zkey export verificationkey age_verification_final.zkey verification_key.json

What this does: Creates the cryptographic keys needed to generate and verify proofs. Expected output: Three new files ending in .zkey and verification_key.json.

Personal tip: "For production, you need a proper trusted setup ceremony. For development, this shortcut works fine."

Step 5: Create the JavaScript Interface

The problem: Integrating ZKPs with web applications requires a lot of boilerplate.

My solution: Build a clean JavaScript wrapper that your frontend can actually use.

Time this saves: Turn 200 lines of cryptographic setup into a simple function call.

Create zkp_age_verifier.js:

const snarkjs = require("snarkjs");
const fs = require("fs");

class AgeVerifier {
  constructor() {
    this.circuit = null;
    this.verificationKey = null;
  }

  async initialize() {
    // Load the circuit and keys
    this.circuit = await snarkjs.wasm.loadSymbols("age_verification.sym");
    this.verificationKey = JSON.parse(
      fs.readFileSync("verification_key.json", "utf8")
    );
    console.log("ZKP Age Verifier initialized successfully");
  }

  // Generate a proof that someone is over minAge
  async generateAgeProof(birthYear, currentYear, minAge) {
    const input = {
      birthYear: birthYear,
      currentYear: currentYear,
      minAge: minAge
    };

    try {
      const { proof, publicSignals } = await snarkjs.groth16.fullProve(
        input,
        "age_verification_js/age_verification.wasm",
        "age_verification_final.zkey"
      );

      return {
        proof: proof,
        publicSignals: publicSignals,
        isValid: publicSignals[0] === "1"
      };
    } catch (error) {
      console.error("Proof generation failed:", error);
      throw error;
    }
  }

  // Verify a proof without learning the actual age
  async verifyAgeProof(proof, publicSignals) {
    try {
      const verified = await snarkjs.groth16.verify(
        this.verificationKey,
        publicSignals,
        proof
      );

      return {
        verified: verified,
        isOverAge: publicSignals[0] === "1"
      };
    } catch (error) {
      console.error("Proof verification failed:", error);
      return { verified: false, isOverAge: false };
    }
  }
}

module.exports = AgeVerifier;

What this does: Wraps the complex ZKP operations in simple async functions your app can use. Expected output: A reusable JavaScript class for age verification.

Personal tip: "Cache the circuit loading in production - it takes 2-3 seconds and your users will notice."

Step 6: Test Your ZKP System

The problem: ZKP debugging is brutal when something goes wrong.

My solution: Build comprehensive tests that catch the common failure modes.

Time this saves: Find bugs in development instead of discovering them in production.

Create test_age_verification.js:

const AgeVerifier = require('./zkp_age_verifier');

async function runTests() {
  const verifier = new AgeVerifier();
  await verifier.initialize();

  console.log("🧪 Testing ZKP Age Verification System\n");

  // Test Case 1: Valid age (should pass)
  console.log("Test 1: User born in 1990 (33 years old)");
  const proof1 = await verifier.generateAgeProof(1990, 2023, 21);
  console.log(`✅ Proof generated. Is over 21: ${proof1.isValid}`);
  
  const verify1 = await verifier.verifyAgeProof(proof1.proof, proof1.publicSignals);
  console.log(`✅ Verification result: ${verify1.verified && verify1.isOverAge}\n`);

  // Test Case 2: Invalid age (should fail)
  console.log("Test 2: User born in 2010 (13 years old)");
  const proof2 = await verifier.generateAgeProof(2010, 2023, 21);
  console.log(`❌ Proof generated. Is over 21: ${proof2.isValid}`);
  
  const verify2 = await verifier.verifyAgeProof(proof2.proof, proof2.publicSignals);
  console.log(`❌ Verification result: ${verify2.verified && verify2.isOverAge}\n`);

  // Test Case 3: Edge case (exactly 21)
  console.log("Test 3: User born in 2002 (exactly 21 years old)");
  const proof3 = await verifier.generateAgeProof(2002, 2023, 21);
  console.log(`✅ Proof generated. Is over 21: ${proof3.isValid}`);
  
  const verify3 = await verifier.verifyAgeProof(proof3.proof, proof3.publicSignals);
  console.log(`✅ Verification result: ${verify3.verified && verify3.isOverAge}\n`);

  console.log("🎉 All tests completed!");
}

runTests().catch(console.error);

Run your tests:

node test_age_verification.js

What this does: Validates that your ZKP system correctly proves age without revealing birthdate. Expected output: All tests should pass with clear success/failure indicators.

Personal tip: "Test the edge cases early - ZKP circuits fail in weird ways with boundary conditions."

What You Just Built

A working zero-knowledge proof system that verifies user ages without storing or revealing birthdates. Users can now prove they're over 21 while keeping their actual age completely private.

Key Takeaways (Save These)

  • Privacy by Design: ZKPs let you verify requirements without collecting sensitive data - GDPR compliance becomes much easier
  • Circuit First: Start with the mathematical circuit, then build the JavaScript wrapper - not the other way around
  • Test Edge Cases: ZKP circuits fail silently on boundary conditions, so test ages exactly at your threshold

Your Next Steps

Pick one:

  • Beginner: Build a ZKP voting system where votes are private but verifiable
  • Intermediate: Add ZKPs to an existing app for private user verification
  • Advanced: Implement recursive ZKPs for complex multi-step verification workflows

Tools I Actually Use

  • circom: The only ZKP circuit language that doesn't make you hate life
  • snarkjs: JavaScript library that actually works with modern web apps
  • circomlib: Pre-built circuits for common operations - saves hours of debugging

Common Mistakes I Made (So You Don't Have To)

  1. Installing the wrong circom version: Use 2.1.6+ or your circuits won't compile with newer snarkjs
  2. Forgetting the trusted setup: Your proofs will be invalid without proper key generation
  3. Not testing edge cases: A user exactly at the age threshold broke my first production deployment
  4. Storing private inputs: The whole point is privacy - never log or store the secret values

When to Use ZKPs in Production

Perfect for:

  • Age verification without storing birthdates
  • Income verification without revealing salary
  • Location proofs without GPS coordinates
  • Membership verification without revealing identity

Skip ZKPs when:

  • Simple yes/no questions work fine
  • Users don't care about privacy
  • Compliance doesn't require minimal data collection
  • Your team can't maintain cryptographic code

Zero-knowledge proofs aren't just academic theory anymore. They're a practical tool for building privacy-first applications that users actually trust.