ZK Self-KYC Platform

A privacy-first, self-sovereign identity solution that enables users to prove they meet specific real-world requirements (age, location, humanity) without revealing personal data. Users sign their own attestations with their crypto wallet and generate zero-knowledge proofs that can be verified by services without exposing the underlying data.

🌟 Features

• Self-Sovereign Identity: Create identity claims using your crypto wallet without relying on third-party KYC providers
• Zero-Knowledge Proofs: Generate cryptographic proofs that validate requirements without revealing personal data
• Reusable Proof System: Generate multiple proof types from the same signed claim without re-signing
• Proof Templates: Common verification scenarios with pre-configured templates
• Proof Caching: Intelligent caching system to avoid regenerating identical proofs
• Privacy-First: All data stored locally in browser, no backend infrastructure required
• Modern UI: Built with shadcn/ui components and Tailwind CSS for a clean, responsive interface

🚀 Technology Stack

• Frontend: React 18 + TypeScript + Vite
• UI Components: shadcn/ui with Tailwind CSS
• Wallet Integration: wagmi + viem for Ethereum wallet connectivity
• Zero-Knowledge Proofs: snarkjs for ZK proof generation and verification
• State Management: Zustand for lightweight state management
• Local Storage: IndexedDB via Dexie.js for persistent data storage
• Testing: Vitest + React Testing Library

📋 Prerequisites

Before running this project, make sure you have:

• Node.js (version 18 or higher)
• npm or yarn package manager
• Web3 Wallet (MetaMask, WalletConnect, etc.) for testing wallet functionality

🛠️ Installation & Setup

1. Clone the repository

   git clone <repository-url>
   cd zk-self-kyc

2. Install dependencies

   npm install
   # or
   yarn install

3. Start the development server

   npm run dev
   # or
   yarn dev

4. Open your browser Navigate to http://localhost:5173 to view the application

🎯 Available Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build the project for production
• npm run preview - Preview the production build locally
• npm run lint - Run ESLint for code quality checks
• npm run test - Run tests in watch mode
• npm run test:run - Run tests once
• npm run test:ui - Run tests with UI interface

🏗️ Project Structure

src/
├── components/          # React components
│   ├── ui/             # shadcn/ui components
│   ├── ClaimCreation.tsx
│   ├── ProofGeneration.tsx
│   ├── ProofVerification.tsx
│   ├── ReusableProofManager.tsx
│   └── WalletConnection.tsx
├── hooks/              # Custom React hooks
│   ├── useClaims.ts
│   └── useReusableProofs.ts
├── services/           # Business logic services
│   ├── zkProofService.ts
│   └── reusableProofService.ts
├── lib/               # Utility libraries
│   └── storage.ts     # IndexedDB storage service
├── types/             # TypeScript type definitions
├── utils/             # Utility functions
└── test/              # Test files

🔧 How It Works

1. Create Identity Claims

• Connect your crypto wallet (MetaMask, WalletConnect, etc.)
• Input your identity information (birth year, country, humanity status)
• Sign the claim data with your wallet to create a cryptographic attestation
• Claims are stored locally in your browser using IndexedDB

2. Generate Zero-Knowledge Proofs

• Select a signed claim and choose the type of proof you want to generate
• Specify requirements (e.g., "age ≥ 18", "country = US", "is human = true")
• The system generates a ZK proof that validates the requirement without revealing your actual data
• Proofs can be shared as tokens or QR codes

3. Verify Proofs

• Submit ZK proofs for verification (via text input, QR code, or file upload)
• The system validates the cryptographic proof and displays the result
• Verification confirms requirements are met without accessing personal data

4. Reuse Proofs

• Generate multiple proof types from the same signed claim
• Use proof templates for common scenarios
• Benefit from intelligent caching to avoid regenerating identical proofs
• Track proof history and usage statistics

🧪 Testing

The project includes comprehensive test coverage:

# Run all tests
npm run test

# Run tests with coverage
npm run test:run

# Run tests with UI
npm run test:ui

Test files are located in the src/test/ directory and cover:

• ZK proof generation and verification
• Reusable proof system functionality
• Component rendering and interactions
• Storage operations and data integrity

🔒 Privacy & Security

• Client-Side Only: All operations happen in your browser, no data sent to servers
• Local Storage: Identity claims and proofs stored locally using encrypted IndexedDB
• Zero-Knowledge: Proofs reveal no personal information, only requirement satisfaction
• Wallet Security: Cryptographic signatures provide authenticity and integrity
• No Tracking: No analytics, cookies, or user tracking

🌐 Browser Compatibility

• Chrome/Chromium (recommended)
• Firefox
• Safari
• Edge

Note: Requires a modern browser with Web3 wallet extension support.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Troubleshooting

Common Issues

Wallet Connection Issues

• Ensure you have a Web3 wallet extension installed
• Check that your wallet is unlocked and connected to the correct network
• Try refreshing the page and reconnecting

Proof Generation Errors

• Verify that your claim data meets the proof requirements
• Check browser console for detailed error messages
• Ensure sufficient browser memory for ZK proof operations

Storage Issues

• Clear browser data if experiencing persistent storage errors
• Check that IndexedDB is enabled in your browser
• Ensure sufficient storage space is available

Getting Help

If you encounter issues:

1. Check the browser console for error messages
2. Review the troubleshooting section above
3. Open an issue on GitHub with detailed information about the problem

🔮 Future Enhancements

• Support for additional proof types and circuits
• Integration with more wallet providers
• Advanced proof composition and aggregation
• Mobile app development
• Integration with external verification services