🛡️ VoteGuard Documentation
Complete guide to the blockchain-based secure voting system — from setup to API reference.
📖 Overview
VoteGuard is a production-ready electronic voting system that combines traditional database authentication with Ethereum blockchain technology for transparent, tamper-proof vote recording.
Every vote is encrypted, digitally signed, and recorded as an immutable transaction on the Sepolia Ethereum testnet, ensuring no vote can ever be altered or deleted.
Blockchain Voting
All votes recorded immutably on Ethereum Sepolia testnet
Two-Factor Auth
Password + Email OTP verification for every login
Govt Registry
Citizen ID verified against PostgreSQL government database
Smart Contracts
Solidity contracts manage elections, candidates & votes
RSA Encryption
End-to-end encryption via RSA-2048 key exchange
Vote Receipts
Cryptographic receipt hashes for vote verification
🏗️ Architecture
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 14, React, Tailwind CSS | Voter portal, admin panel, ballot UI |
| Backend API | Node.js, Express.js | REST API, auth, vote processing |
| Auth Database | PostgreSQL (Supabase) + Prisma | User identity & government registry |
| Blockchain | Ethereum Sepolia, Solidity 0.8.20 | Elections, candidates, votes (immutable) |
| RPC Provider | Alchemy (free tier) | Blockchain read/write access |
| Security | JWT, bcrypt, RSA-2048, OTP | Authentication & encryption |
📋 Prerequisites
- Node.js v18 or higher
- MetaMask browser extension — Install →
- Alchemy account — Get free API key →
- Sepolia ETH — Get from faucet →
- PostgreSQL database (or Supabase free tier)
📦 Installation
1. Clone the Repository
git clone https://github.com/mouniksai/vote-guard.git cd vote-guard
2. Install Backend Dependencies
cd vote-guard-server npm install
3. Install Frontend Dependencies
cd .. # back to root npm install
🔧 Environment Configuration
Backend — vote-guard-server/.env
# Server PORT=5001 # Database (Supabase / PostgreSQL) DATABASE_URL="postgresql://user:password@host:5432/vote_guard?schema=public" # Blockchain BLOCKCHAIN_NETWORK=sepolia CONTRACT_ADDRESS=0xE08b2c325F4e64DDb7837b6a4b1443935473ECB2 ALCHEMY_API_KEY=your_alchemy_key SEPOLIA_PRIVATE_KEY=your_wallet_private_key # Security JWT_SECRET=your_super_secret_key # Email (for OTP) EMAIL_USER=your-email@gmail.com EMAIL_PASS=your-app-password
Frontend — .env.local
NEXT_PUBLIC_API_URL=http://localhost:5001 NEXT_PUBLIC_CONTRACT_ADDRESS=0xE08b2c325F4e64DDb7837b6a4b1443935473ECB2 NEXT_PUBLIC_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/your_key NEXT_PUBLIC_ALCHEMY_API_KEY=your_alchemy_key NEXT_PUBLIC_CHAIN_ID=11155111
.env files to Git. Use dedicated test wallets and never
purchase test ETH.🗄️ Database Setup
VoteGuard uses Prisma ORM with PostgreSQL. Only user identity & authentication data is stored in the database.
1. Generate Prisma Client
npx prisma generate
2. Run Migrations
# Development (prototyping) npx prisma db push # Production (versioned) npx prisma migrate dev --name init
Schema Overview
| Model | Table | Purpose |
|---|---|---|
| GovtRegistry | govt_registry | Government citizen records (name, DOB, constituency) |
| User | users | Registered voter accounts (username, password hash, OTP, role) |
⛓️ Blockchain Setup
The smart contract is already deployed on Sepolia testnet. All team members connect to the same contract.
| Property | Value |
|---|---|
| Contract Address | 0xE08b2c325F4e64DDb7837b6a4b1443935473ECB2 |
| Network | Sepolia Testnet (Chain ID: 11155111) |
| Solidity Version | 0.8.20 |
| Etherscan | View on Etherscan → |
Compile & Test Contracts (optional)
cd vote-guard-server npx hardhat compile npx hardhat test
🚀 Running the Project
1. Start the Backend
cd vote-guard-server npm run dev
✅ VOTEGUARD SERVER RUNNING! with blockchain connection confirmed on port
5001.2. Start the Frontend
cd .. # root directory npm run dev
Open http://localhost:3000 in your browser.
3. Connect MetaMask
- Click "Connect Wallet" on any voting page
- Switch MetaMask to Sepolia Test Network
- Approve the network switch
- You're ready to vote!
🔒 Security Features
JWT + HttpOnly Cookies
Stateless auth with secure session cookies resistant to XSS
RSA-2048 Key Exchange
Asymmetric encryption for secure client-server communication
Two-Factor Auth (2FA)
Email OTP verification required for every login
bcrypt Password Hashing
Salted hashing with cost factor 10 for password storage
Blockchain Immutability
Votes cannot be altered once recorded on Ethereum
Cryptographic Receipts
SHA-256 receipt hashes for independent vote verification
🐳 Deployment
Docker (Backend)
FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . RUN npx prisma generate EXPOSE 5001 CMD ["node", "server.js"]
docker build -t voteguard-server . docker run -p 5001:5001 --env-file .env voteguard-server
Docker (Frontend)
docker build -t voteguard-frontend . docker run -p 3000:3000 voteguard-frontend
🆘 Troubleshooting
❓ Backend won't start?
Verify SEPOLIA_PRIVATE_KEY and ALCHEMY_API_KEY are set correctly in .env. Ensure CONTRACT_ADDRESS matches the deployed contract.
❓ Wrong network error in MetaMask?
Open MetaMask → Settings → Advanced → Enable "Show test networks" → Switch to Sepolia.
❓ Slow transactions?
Sepolia transactions take 15-30 seconds. Check transaction status on Etherscan.
❓ Team members see different data?
Ensure everyone uses the same CONTRACT_ADDRESS and BLOCKCHAIN_NETWORK=sepolia in their .env files.
❓ OTP email not received?
Check EMAIL_USER and EMAIL_PASS in .env. For Gmail, use an App Password (not your regular password).
❓ Prisma errors?
Run npx prisma generate followed by npx prisma db push to sync the schema.