Skip to content

README.md

Latest commit

 

History

History
102 lines (82 loc) · 5.15 KB

README.md

File metadata and controls

102 lines (82 loc) · 5.15 KB

🔐 IDHard: Zero-Knowledge Identity for Web3

Stop Sharing Your Data. Start Proving Your Truth.

IDHard is a programmable, privacy-preserving identity vault built for the Web3 era. It completely re-engineers the KYC process by allowing users to verify their identity exactly once with an anchoring institution, and subsequently prove their credentials across the internet using Zero-Knowledge Proofs (ZKPs) and Selective Disclosure JWTs (SD-JWT)—without ever exposing their physical documents or raw Personally Identifiable Information (PII) again.

🌟 The Problem We Solve

  • For Businesses / Banks: Eliminates multi-billion dollar "Data Liability" by removing the need to store honeypots of redundant PII. Drastically reduces the $2-$10 cost per repeated KYC check per user.
  • For Users: Complete data sovereignty. Documents live inside the local device Secure Enclave. Users mathematically prove attributes (e.g., Age > 18 or Country = 'India') without disclosing the underlying raw values.

🏗 System Architecture

The ecosystem consists of four interconnected repositories/services:

1. The IDHard Issuance Portal (frontend_bank)

The primary anchoring entry point where users initiate their KYC process.

  • Tech Stack: Next.js, TailwindCSS, React.
  • Features:
    • Beautiful, animated Web3 Neobank interface.
    • Real-time Government API integrators (e.g., DigiLocker modal).
    • Web3 Wallet connection to link Ethereum Addresses (EIP-5192) to verified human identities.

2. Zero-Knowledge Cryptography Backend (bank_backend)

The core Node.js application responsible for cryptographic operations, verifying ZK-proofs, and interacting with the ledger.

  • Tech Stack: Node.js, Express, Ethers.js, Veramo Core, MerkleTreeJS.
  • Features:
    • Groq Multimodal AI: Uses meta-llama/llama-4-scout-17b-16e-instruct to OCR extract identity documents intelligently and privately.
    • SD-JWT Issuance: Transforms planar KYC data into highly-salted Merkle leaves, returning a VC containing only hashes (/api/issue-sd-jwt).
    • Soulbound NFT Minting: Anchors the root hash of the user's Merkle tree to the Polygon Amoy testnet.
    • ZKP Verification Node: Receives encrypted intercept packets from the mobile wallet, validates predicates against on-chain roots via Merkle inclusion proofs, and serves the state to third parties (/api/verify-proof).

3. The Verifying Party / Portal B (bank-b-frontend)

A mock "DeFi Exchange" or secondary financial institution that wants to verify a user natively without doing the KYC themselves.

  • Tech Stack: Next.js, TailwindCSS.
  • Features:
    • Interactive Cryptographic Explorer: Real-time polling to verify session challenges seamlessly via QR codes.
    • Dynamically parses intercept data to distinguish between:
      • ZKP Range Proofs: (e.g. Predicate Age >= 18 mathematically verified, no data disclosed).
      • Selective Disclosure: (e.g. User explicitly shares text 123 Tech Park alongside its verified Leaf Hash).
      • Hidden Anchor Nodes: Prove that undisclosed attributes remain strictly hashed and encrypted under user consensus.
    • Demo Simulator: Built-in network-simulator button to auto-verify ZKP packets for demonstration purposes without requiring a physical camera.

4. Mobile Identity Wallet (Android/React Native)

The pocket-sized Secure Enclave vault (external repository/module).

  • Scans session QR codes.
  • Unlocks SD-JWT from local storage using biometrics.
  • Compiles Circom / Groth16 WASM proof circuits directly on the edge.
  • Sends mathematical predicates to the respective verifier endpoints via HTTP.

🚀 Quick Start / Local Development

Prerequisites

  • Node.js (v18+)
  • npm or yarn
  • Free Ngrok Account (for mobile app tunnel)

1. Run the Cryptography Backend

cd bank_backend
npm install
# Ensure you copy .env.example to .env and input your Polygon RPC and Groq API keys
npm run start

Runs on http://localhost:3001

2. Run the Main Anchor Bank (IDHard)

cd frontend_bank
npm install
npm run dev

Runs on http://localhost:3000

3. Run the Verifier Institution (Bank B)

cd bank-b-frontend
npm install
npm run dev

Runs on http://localhost:3002 (Auto-increments if port is busy).

4. Demoing the Zero-Knowledge Verify Flow

  1. Open Bank B (http://localhost:3002).
  2. Type in your Ngrok URL (or localhost tunnel) and click Initialize Verification.
  3. If you do not have the physical Android app on hand: Click Auto-Simulate Mobile Scan (Demo Mode).
  4. Watch the Network Observer Activity terminal automatically forge the cryptographic chain, construct the local Merkle Tree, query Amoy, and pop the Verified lock!

🛠 Tech Stack Details

  • Frontend: React, Next.js 14, TailwindCSS, Framer Motion
  • Cryptography: snarkjs, circom, merkletreejs, keccak256
  • Agent & JWT: @veramo/core, W3C Verifiable Credentials
  • AI/Edge: Groq Cloud LPU SDK (Llama 4 Instruct)
  • Blockchain: Polygon Amoy Testnet, OpenZeppelin, Hardhat, Ethers.js v6

Built with ☕️ and 🧠 during Hackfest 2026. Empowering users with digital dignity.