🎓 CredVerify - Blockchain-Based Credential Verification Platform

Eliminate credential fraud with blockchain-powered Soulbound Tokens (SBTs)
CredVerify provides educational institutions with a modern, gasless, and fraud-proof way to issue verifiable digital certificates.

---

🌟 What Makes CredVerify Unique?

1. Truly Soulbound Credentials

Unlike traditional NFTs, CredVerify certificates are non-transferable tokens bound to the recipient's identity. Built on ERC-721 with transfer restrictions, these credentials cannot be sold, traded, or transferred—ensuring authentic ownership.

2. Zero-Friction Web2 Experience

• No crypto knowledge required: Students claim certificates using familiar Gmail/Twitter login
• Gasless claiming: Institution sponsors all blockchain transaction costs
• One-click verification: QR codes and public URLs for instant credential verification
• Mobile-optimized: Full QR scanning support for on-the-go verification

3. Privacy-Preserving Architecture

• Email hashing: Student emails are hashed using deterministic salting before blockchain storage
• Selective disclosure: Only authorized parties see full credential details
• IPFS metadata: Decentralized storage ensures data persistence without central servers
• Encrypted storage: Sensitive data encrypted at rest using DEK/KEK hierarchy

4. Enterprise-Grade Scalability

• Async queue processing: BullMQ-powered background job system handles thousands of certificates
• Batch issuance: CSV upload supports bulk credential generation
• Redis-backed caching: Sub-100ms verification response times
• CDN-optimized: Certificate images served via IPFS gateway with caching

5. Advanced Custom Templates ✨ NEW

• Drag-and-drop editor: Visual template builder for branded certificates
• Dynamic field positioning: Place recipient name, date, and custom fields anywhere
• Multi-template support: Gold, Silver, Bronze, and unlimited custom templates
• Per-credential customization: Override templates on individual certificates
• Renameable fields: Double-click custom field names to rename them
• Auto-injected credential ID: QR codes automatically include credential IDs for custom templates
• CredVerify branding: Prominent logo placement with bordered QR codes for easy scanning
• Supabase Storage integration: Templates and backgrounds stored in cloud storage

6. Institutional Control & Compliance

• Granular revocation: Instant on-chain revocation with public/private reasons
• Audit trail: Immutable blockchain event logs for compliance
• Role-based access: Super admin, institution, and student permission levels
• Approval workflow: Admin-approved institution onboarding process

---

🚀 Key Features

For Educational Institutions

🎯 Certificate Issuance

• CSV Batch Upload: Issue hundreds of certificates at once via spreadsheet
• Manual Entry: Single credential creation for special cases
• Custom Fields: Add institution-specific fields (honors, major, license numbers)
• Template Selection: Choose from standard templates or create custom designs
• Real-time Preview: See exactly how certificates will look before issuing
• Progress Tracking: Monitor batch processing status in dashboard
• Certificate Type Analytics: View distribution by certificate type (degrees, licenses, diplomas)

📊 Dashboard & Analytics

• Issuance Statistics: Track certificates issued, claimed, and pending
• Time-series Graphs: Visualize credential distribution over time
• Certificate Type Breakdown: Bar charts showing credentials by type (not just degrees)
• Audit Logs: Complete transaction history with blockchain verification
• Verification Counter: Track how many times your credentials have been verified
• Recent Activity: Real-time feed of certificate issuances and claims

🔐 Credential Management

• Search & Filter: Find credentials by recipient, date, or type
• Revocation System: Instantly revoke credentials with reason logging
• Status Monitoring: Track minted, pending, and revoked states
• Batch Operations: Bulk actions on credential sets
• Template Management: Create, edit, and archive certificate templates

For Students

🎫 Certificate Claiming

• Email Notifications: Automatic claim emails with secure links
• One-Click Claim: Mint credentials to Web3Auth wallet with zero gas fees
• Profile Dashboard: View all earned credentials in one place
• Modern Statistics: Clean 3-card layout showing Total, Claimed, and Pending certificates
• Download Options: Export as PDF or high-resolution PNG
• Social Sharing: LinkedIn-optimized credential cards
• Real Activity Feed: See recent certificate issuances and revocations (no placeholders!)
• Full-Screen Preview: Zoom, pan, and download certificates in a lightbox viewer

✅ Verification & Sharing

• Privacy-First Public Profiles: Secure shareable URLs using random IDs (e.g., credverify.com/u/aB3xF9k2pQ1m)
• Enhanced QR Codes: Prominently bordered QR codes with embedded credential IDs
• Live Status: Real-time blockchain verification on every view
• Revocation Awareness: Clear indicators if credential is revoked (expandable section in My Credentials)
• Blockchain Explorer: Direct links to Polygon Amoy Testnet transactions
• One-Click Share: Copy secure profile link to clipboard from dashboard

For Verifiers (HR/Background Checks)

🔍 Instant Verification

• QR Scan: Mobile camera verification in under 3 seconds
• URL Lookup: Paste credential URL to verify authenticity
• Blockchain Proof: View transaction hash, block number, and timestamp
• Institution Verification: Confirm issuing institution's identity on Polygon Amoy Testnet
• Tamper Detection: Automatic IPFS hash comparison
• Credential ID Display: Every certificate shows its unique identifier for manual verification

---

🏗️ Architecture & Technology Stack

Frontend (Next.js 16 App Router)

website/
├── app/                    # App Router pages
│   ├── student/           # Student dashboard, certificates, profile
│   ├── university/        # Institution dashboard, issuance, templates
│   ├── admin/             # Super admin panel
│   ├── verify/[id]/       # Public verification pages
│   └── claim/[id]/        # Gasless claiming flow
├── components/
│   ├── templates/         # Template editor components
│   ├── certificate-card.tsx
│   └── clipped-card.tsx   # Custom UI components
└── context/
    └── AuthContext.tsx    # Web3Auth + role-based auth

Key Technologies:

• Next.js 16: App Router, Server Components, React 19
• shadcn/ui: Accessible component library (Radix UI + Tailwind)
• Web3Auth: Embedded wallet (no browser extension required)
• ethers.js: Smart contract interactions
• Tailwind CSS: Utility-first styling

Backend (Node.js + Express)

server/
├── src/
│   ├── routes/            # API endpoints
│   ├── services/
│   │   ├── certificate-generator-puppeteer.ts  # PDF/PNG generation
│   │   ├── email.service.ts                    # Nodemailer integration
│   │   └── storacha.service.ts                  # IPFS uploads
│   ├── workers/
│   │   └── credential-worker.ts               # BullMQ job processor
│   └── queues/
│       └── credential-queue.ts                # Job queue management
├── assets/
│   └── templates/         # Gold, Silver, Bronze HTML templates
└── migrations/            # Supabase SQL migrations

Key Technologies:

• Express.js: RESTful API server
• BullMQ: Redis-backed job queue for async processing
• Puppeteer: Headless Chrome for certificate rendering
• Storacha (w3up): IPFS client for decentralized storage
• Nodemailer: Email notifications via Gmail SMTP
• jose: JWT verification for Web3Auth tokens

Blockchain (Polygon Amoy Testnet)

contracts/
├── contracts/
│   └── CredentialSBT.sol  # ERC-721 Soulbound Token
├── scripts/
│   └── deploy.ts          # Hardhat deployment script
└── test/
    └── CredentialSBT.test.ts  # Contract test suite

Smart Contract Features:

• Soulbound: Overrides _beforeTokenTransfer to prevent transfers
• Gasless: ERC-2771 meta-transaction support (Biconomy)
• Revocable: revokeCredential() function for institutions
• On-chain metadata: IPFS CID stored in contract events
• Enumerable: Query all tokens owned by an address

Deployed Contract: 0x96a16c773b5EA4A9A3d0bD56D7e4C0cb989D3d39 (Polygon Amoy)

Database (Supabase PostgreSQL)

-- Core Tables
certificates       # Certificate records with encryption metadata
institutions       # Verified institutions
users              # Students, institutions, admins
institution_templates  # Custom certificate templates
invite_tokens      # Institution invite system
audit_log          # Immutable action history
certificate_views  # Verification analytics

Key Features:

• Row-Level Security (RLS): Fine-grained access control
• Real-time subscriptions: Live dashboard updates
• Storage bucket: Template backgrounds and assets
• Full-text search: Certificate lookup by name/email

---

🎨 Recent Feature Updates (January 2026)

Privacy & Security

✅ Private Public Profile URLs: Profile URLs now use secure NanoID-style random IDs (/u/aB3xF9k2pQ1m) instead of exposing email addresses
✅ Auto-generated public_id: Database trigger auto-assigns secure IDs to new users
✅ Masked Wallet Addresses: Public profiles show only first 6 and last 4 characters (0x742d...5f9a)
✅ Legacy URL Redirects: Old email/wallet-based URLs automatically redirect to secure public_id URLs

Certificate Preview System

✅ Full-Screen Lightbox: Preview certificates with zoom, pan, and download controls
✅ Keyboard Navigation: ESC to close, scroll to zoom
✅ Touch Gestures: Pinch to zoom on mobile devices
✅ IPFS Integration: Direct preview from decentralized storage

Dashboard Improvements

✅ Modern 3-Card Stats Layout: Student dashboard now uses responsive grid (Total/Claimed/Pending)
✅ Real Recent Activity: Activity feed pulls actual certificate data (issuances, claims, revocations)
✅ Revoked Credentials Section: Moved to My Credentials page with expandable UI (shows 2, "Show All" if more)
✅ Consistent Share Button: Same styling across Dashboard and My Credentials pages
✅ Removed Fake Data: Eliminated placeholder charts and fake counters

Certificate Design Enhancements

✅ Prominent QR Codes with Borders: All certificates now feature bordered QR codes with enhanced visibility
✅ Auto-injected Credential IDs: Credential IDs automatically appear below QR codes (no template modification needed)
✅ CredVerify Logo Styling: Purple gradient logo badges with white borders for brand consistency
✅ Custom Template Support: Credential IDs inject dynamically for both standard and custom templates

Network & Infrastructure

✅ Polygon Amoy Testnet Labels: All pages correctly display "Polygon Amoy Testnet"
✅ Verified Contract Addresses: Updated to match actual deployment on Amoy
✅ Polygonscan Integration: Direct links to Amoy explorer for all transactions

Template System

✅ Field Name Alignment: Backend and frontend now use consistent field names (studentName, credentialTitle)
✅ Database Migration: Existing templates auto-migrated to new field naming convention
✅ Supabase Storage Integration: Templates stored in institution-assets bucket

UI/UX Fixes

✅ Revoke Modal Styling: Fixed transparent dropdown and button color issues
✅ Institution Dashboard: Removed unnecessary verifications counter, 3-card grid layout
✅ Certificate Type Analytics: Institution dashboards show "Certificate Type" (not "Degree Type")

---

🔧 Setup & Installation

Prerequisites

• Node.js v20+ and npm
• PostgreSQL (via Supabase account)
• Redis server (local or cloud)
• Metamask wallet (for super admin)
• Gmail account (for SMTP emails)

1. Clone Repository

git clone https://github.com/yourusername/credverify.git
cd credverify

2. Install Dependencies

# Backend
cd server && npm install

# Frontend
cd ../website && npm install

3. Environment Configuration

Server (.env)

# Database
DATABASE_URL=postgresql://...
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key

# Blockchain (Polygon Amoy Testnet)
RPC_URL=https://rpc-amoy.polygon.technology
CONTRACT_ADDRESS=0x96a16c773b5EA4A9A3d0bD56D7e4C0cb989D3d39
MASTER_WALLET_PRIVATE_KEY=your-private-key

# IPFS (Storacha)
W3UP_EMAIL=your-email@example.com

# Email
SMTP_USER=your-gmail@gmail.com
SMTP_PASS=your-app-specific-password

# Encryption
MASTER_KEK_BASE64=<generate with scripts/generate-master-key.js>

# Queue
REDIS_HOST=localhost
REDIS_PORT=6379

Website (.env.local)

NEXT_PUBLIC_BACKEND_API_URL=http://localhost:3001
NEXT_PUBLIC_WEB3AUTH_CLIENT_ID=your-web3auth-client-id
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

4. Database Setup

cd server
# Run migrations (execute SQL files in migrations/ folder via Supabase dashboard)
# Or use Supabase CLI:
npx supabase db push

5. Create Supabase Storage Bucket

# Via Supabase dashboard:
# 1. Go to Storage > Create bucket
# 2. Name: "institution-assets"
# 3. Make public: Yes
# 4. File size limit: 10MB
# 5. Allowed MIME types: image/jpeg, image/png, image/webp

6. Deploy Smart Contract (if needed)

cd contracts
npx hardhat compile
npx hardhat run scripts/deploy.ts --network amoy

7. Start Services

# Terminal 1: Backend API
cd server && npm run dev

# Terminal 2: Worker (BullMQ)
cd server && npm run worker:watch

# Terminal 3: Frontend
cd website && npm run dev

# Terminal 4: Redis (if not running as service)
redis-server

8. Access Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• Admin Dashboard: http://localhost:3000/admin

---

📁 Project Structure

CredVerify/
├── contracts/                 # Solidity smart contracts
│   ├── contracts/
│   │   └── CredentialSBT.sol
│   ├── scripts/deploy.ts
│   └── test/
├── server/                    # Backend Node.js API
│   ├── src/
│   │   ├── routes/           # Express API routes
│   │   ├── services/         # Business logic
│   │   ├── workers/          # BullMQ job processors
│   │   ├── middleware/       # Auth, validation
│   │   └── utils/            # Helpers
│   ├── assets/
│   │   └── templates/        # Certificate HTML templates
│   └── migrations/           # Database migrations
├── website/                   # Next.js frontend
│   ├── app/                  # App Router pages
│   │   ├── student/
│   │   ├── university/
│   │   ├── admin/
│   │   ├── verify/[id]/
│   │   └── claim/[id]/
│   ├── components/
│   │   ├── templates/        # Template editor
│   │   ├── dashboard/        # Dashboard widgets
│   │   └── ui/               # shadcn components
│   └── context/
│       └── AuthContext.tsx
└── README.md

---

🔐 Security Features

Encryption

• DEK/KEK Hierarchy: Each credential encrypted with unique Data Encryption Key (DEK), wrapped by master Key Encryption Key (KEK)
• AES-256-GCM: Authenticated encryption prevents tampering
• GDPR Compliance: Crypto-shredding support (delete DEK to make data unrecoverable)

Authentication

• Web3Auth: Non-custodial wallet with social login
• JWT Verification: Backend validates Web3Auth tokens using JOSE
• Role-Based Access Control: Separate permissions for students, institutions, admins
• Email Hashing: SHA-256 with deterministic salt before blockchain storage

Blockchain

• Soulbound Tokens: Transfer-restricted ERC-721
• On-chain Revocation: Immutable revocation events
• Meta-transactions: Students claim without gas fees (Biconomy)
• Testnet-First: Polygon Amoy for risk-free development

---

🚦 API Endpoints

Public Endpoints

GET  /api/verify/:credentialId          # Verify certificate
GET  /api/certificate/:credentialId     # Get certificate details

Student Endpoints (Requires Auth)

GET  /api/student/certificates          # List student's certificates
POST /api/student/claim/:claimToken     # Claim certificate to wallet
GET  /api/student/profile               # Get student profile

Institution Endpoints (Requires Auth)

POST /api/institution/issue             # Issue single certificate
POST /api/institution/batch             # Batch issue via CSV
GET  /api/institution/stats             # Dashboard analytics
POST /api/institution/revoke/:id        # Revoke certificate
GET  /api/institution/templates         # List custom templates
POST /api/institution/templates         # Create custom template

Admin Endpoints (Super Admin Only)

GET  /api/admin/pending-institutions    # Institutions awaiting approval
POST /api/admin/approve/:id             # Approve institution
POST /api/admin/reject/:id              # Reject institution

---

🧪 Testing

Smart Contract Tests

cd contracts
npx hardhat test

Backend API Tests

cd server
npm test

E2E Tests (Playwright)

cd website
npx playwright test

---

🌐 Deployment

Frontend (Vercel)

cd website
vercel --prod

Backend (Railway/Render)

cd server
# Configure environment variables in Railway/Render dashboard
git push railway main  # or deploy via Render dashboard

Database (Supabase)

• Already cloud-hosted, no separate deployment needed
• Configure RLS policies via Supabase dashboard

Smart Contract (Polygon Amoy)

cd contracts
npx hardhat run scripts/deploy.ts --network amoy
# Note the deployed contract address for .env files

---

📖 Usage Guide

For Institutions

1. Sign Up & Approval

1. Register at /university/register using Web3Auth
2. Fill institution details (name, country, accreditation)
3. Wait for super admin approval

2. Create Certificate Templates

1. Go to Dashboard > Templates > Create Template
2. Upload background image (1920x1080px recommended)
3. Drag fields to desired positions
4. Double-click field labels to rename
5. Save template

3. Issue Certificates

Single Issuance:

1. Dashboard > Issue Certificate
2. Enter student email, degree name, date
3. Select template
4. Preview and confirm

Batch Issuance:

1. Download CSV template
2. Fill with student data
3. Upload CSV file
4. Monitor batch progress

For Students

1. Receive Notification

• Check email for certificate claim link
• Click "Claim Certificate" button

2. Claim to Wallet

1. Login with Gmail/Twitter (Web3Auth)
2. Review certificate details
3. Click "Claim to Wallet" (gasless!)
4. Wait for blockchain confirmation

3. Share & Verify

• Download PDF/PNG
• Share public URL
• Show QR code for instant verification

For Verifiers

Verify via QR Code

1. Scan QR code with mobile camera
2. View certificate details
3. Check blockchain status (green = valid)
4. Verify issuing institution

Verify via URL

1. Visit credverify.com/verify
2. Paste certificate URL or credential ID
3. View full details and blockchain proof

---

🤝 Contributing

We welcome contributions! Please follow these steps:

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

Development Guidelines

• Use TypeScript for type safety
• Follow existing code style (ESLint + Prettier)
• Write tests for new features
• Update README for significant changes

---

📄 License

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

---

🙋‍♂️ Support

• Email: support@credverify.com
• Discord: Join our community
• Documentation: docs.credverify.com
• Issues: GitHub Issues

---

🏆 Acknowledgments

• Polygon for gasless transactions via Amoy testnet
• Web3Auth for seamless Web2-to-Web3 onboarding
• Supabase for robust PostgreSQL + Storage infrastructure
• Storacha (w3up) for decentralized IPFS storage
• shadcn/ui for beautiful, accessible components

---

Built with ❤️ by the CredVerify Team