Blockchain Biometric Voting System

Decentralized voting platform with biometric verification and on-chain auditability

An end-to-end voting solution that combines Ethereum smart contracts with face and fingerprint authentication.

Overview

The Blockchain Biometric Voting System is an electronic voting platform designed for integrity, transparency, and strong voter verification.

Core guarantees:

Immutability: Votes are recorded on Ethereum and cannot be altered retroactively.
Transparency: Vote counts and election state are verifiable on-chain.
Security: Dual biometric verification (face and fingerprint) reduces impersonation risk.
Privacy: Individual choices are not exposed while maintaining verifiable outcomes.
Accessibility: Supports single-biometric flows for voters with disabilities.

The system is suitable for controlled pilots, institutional elections, and scalable production-oriented deployments with additional hardening.

Key Features

Dual Biometric Authentication

Face Recognition: 128-dimensional face encoding pipeline.
Fingerprint Verification: Sensor-driven fingerprint capture using Arduino with R307/R305.
Accessibility Support: Optional single-biometric onboarding for eligible users.

Blockchain Integration

Smart Contracts: Election lifecycle and voting logic implemented in Solidity.
ThirdWeb SDK: Frontend contract interactions and transaction flow management.
On-Chain State: Election, voter, and candidate state managed through contract methods.

Web Application

Next.js 14: Server-rendered React framework.
TypeScript: Safer development with static typing.
Bootstrap 5: Responsive UI components.
Chart.js: Live vote and election visualization.

Backend Services

Flask API: Endpoints for biometric workflows and hardware orchestration.
Face Processing: OpenCV + face_recognition stack.
Serial Communication: Arduino interface through PySerial.

System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              USER INTERFACE                                │
│                         (Next.js + TypeScript)                             │
│                                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────┐ │
│  │   Register   │    │    Admin     │    │ Verification │    │  Results  │ │
│  │    Page      │    │   Panel      │    │    Page      │    │   Page    │ │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘    └─────┬─────┘ │
└─────────┼───────────────────┼───────────────────┼───────────────────┼───────┘
          │                   │                   │                   │
          ▼                   ▼                   ▼                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              THIRDWEB SDK                                  │
│                    (Blockchain Communication Layer)                        │
└─────────────────────────────────────────────────────────────────────────────┘
          │                                       │
          ▼                                       ▼
┌─────────────────────────────┐     ┌─────────────────────────────────────────┐
│      ETHEREUM BLOCKCHAIN    │     │             PYTHON BACKEND             │
│   (BiometricVotingSystem)   │     │                (Flask)                 │
│                             │     │                                         │
│  • Voter Registration       │     │  • Face Recognition API                │
│  • Candidate Registration   │     │  • Fingerprint Controller              │
│  • Vote Casting             │     │  • OpenCV + dlib                       │
│  • Election Management      │     │  • PySerial                            │
│  • Result Declaration       │     │                                         │
└─────────────────────────────┘     └───────────────────────────┬─────────────┘
                                                                │
                                                                ▼
                                    ┌─────────────────────────────────────────┐
                                    │         ARDUINO MICROCONTROLLER         │
                                    │                (C++ Code)               │
                                    │                                         │
                                    │  • Register fingerprint                 │
                                    │  • Verify fingerprint                   │
                                    │  • Delete fingerprint                   │
                                    │                                         │
                                    │     R307/R305 Fingerprint Sensor        │
                                    └─────────────────────────────────────────┘

Technology Stack

Frontend

Technology	Version	Purpose
Next.js	14.2.x	React framework with SSR
TypeScript	5.x	Type-safe JavaScript
React	18.3.x	UI library
Bootstrap	5.3.x	CSS framework
ThirdWeb SDK	5.70.x	Blockchain integration
Chart.js	4.4.x	Vote visualization
Axios	1.7.x	HTTP client
pdf-lib	1.17.x	PDF generation

Backend

Technology	Version	Purpose
Python	3.8+	Runtime
Flask	Latest	Web framework
Flask-CORS	Latest	CORS support
face_recognition	Latest	Face encoding and comparison
OpenCV (cv2)	Latest	Image processing
NumPy	Latest	Numerical operations
PySerial	Latest	Arduino communication

Blockchain

Technology	Version	Purpose
Solidity	0.8.19	Smart contract language
Ethereum	-	Blockchain network
ThirdWeb	-	Deployment and interaction tooling

Hardware / Embedded

Technology	Version	Purpose
Arduino	C++	Microcontroller programming
Adafruit Fingerprint Library	Latest	Sensor communication
SoftwareSerial	-	Serial emulation
R307/R305 Sensor	-	Fingerprint capture

Project Structure

Blockchain-Voting-System/
│
├── Arduino c++/
│   └── c/
│       └── c.ino                    # Arduino fingerprint sensor code
│
├── blockchain solidity/
│   ├── blockchain.sol               # Main smart contract
│   └── artifacts/                   # Compiled contract artifacts
│
├── next.js frontend/
│   ├── src/
│   │   └── app/
│   │       ├── admin/               # Admin panel page
│   │       ├── register/            # Voter registration page
│   │       ├── verification/        # Vote verification page
│   │       └── page.tsx             # Home page
│   ├── package.json                 # Frontend dependencies
│   ├── tsconfig.json                # TypeScript configuration
│   └── next.config.mjs              # Next.js configuration
│
├── python backend/
│   ├── app.py                       # Main Flask application
│   ├── face.py                      # Face recognition utilities
│   ├── finger.py                    # Fingerprint controller
│   └── requirements.txt             # Python dependencies
│
└── README.md

Prerequisites

Software Requirements

Software	Version	Download Link
Node.js	18.x or higher	nodejs.org
Python	3.8 or higher	python.org
Arduino IDE	2.x	arduino.cc
Git	Latest	git-scm.com
Visual Studio Build Tools	2019+	visualstudio.microsoft.com
CMake	Latest	cmake.org

Python Build Prerequisites

Important

face_recognition depends on dlib, which requires C++ build tools.

Windows

pip install dlib
pip install face_recognition

Linux

sudo apt-get update
sudo apt-get install build-essential cmake libgtk-3-dev libboost-all-dev
pip install dlib face_recognition

macOS

brew install cmake boost
pip install dlib face_recognition

Installation and Setup

1. Arduino Fingerprint Sensor Setup

Hardware Connection

Connect the R307/R305 Fingerprint Sensor to Arduino Uno/Nano:

Sensor Pin	Arduino Pin	Wire Color (Typical)
VCC (Red)	5V	Red
GND (Black)	GND	Black
TX (Green)	Pin 2 (RX)	Green
RX (White)	Pin 3 (TX)	White

Warning

Sensor logic is typically 3.3V. Use a level shifter for long-term reliability.

Arduino IDE Setup

Install Arduino IDE.
Install Adafruit Fingerprint Sensor Library.
Open and upload:
```
cd "Arduino c++/c"
```
Verify serial output at 115200 baud: {"status":"ready","message":"Fingerprint sensor connected"}

Arduino Serial Commands

Command	Description
`REGISTER:<id>`	Register fingerprint with ID
`VERIFY`	Verify fingerprint and return matched ID
`DELETE:<id>`	Delete fingerprint by ID
`DELETEALL`	Delete all stored fingerprints
`DOWNLOAD`	Download fingerprint template

2. Python Backend Setup

cd "python backend"
python -m venv venv

Activate environment:

Windows:
```
venv\Scripts\activate
```
Linux/macOS:
```
source venv/bin/activate
```

Install dependencies:

pip install -r requirements.txt

requirements.txt:

flask
flask-cors
face_recognition
opencv-python
numpy
pyserial

Create .env in python backend/:

FLASK_APP=app.py
FLASK_ENV=development
FLASK_DEBUG=1
FINGERPRINT_PORT=COM3

Run backend:

python app.py

Default backend URL: http://localhost:5000

3. Blockchain Smart Contract Deployment

Option A: ThirdWeb Dashboard

Create ThirdWeb account and connect wallet.
Deploy blockchain solidity/blockchain.sol.
Set frontend env values in next.js frontend/.env.local:

NEXT_PUBLIC_THIRDWEB_CLIENT_ID=your_client_id
NEXT_PUBLIC_CONTRACT_ADDRESS=your_deployed_contract_address

Option B: Hardhat

npm install --save-dev hardhat
npx hardhat init
npx hardhat compile
npx hardhat run scripts/deploy.js --network sepolia

4. Next.js Frontend Setup

cd "next.js frontend"
npm install
npm run dev

Create next.js frontend/.env.local:

NEXT_PUBLIC_THIRDWEB_CLIENT_ID=your_thirdweb_client_id
NEXT_PUBLIC_CONTRACT_ADDRESS=0x_your_deployed_contract_address
NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_CHAIN_ID=11155111

Default frontend URL: http://localhost:3000

Hardware Requirements

Fingerprint Sensor Module

Component	Specification
Model	R307 or R305 Optical Fingerprint Sensor
Voltage	3.3V - 6V DC
Current	< 120mA
Interface	UART (TTL)
Baud Rate	9600 - 115200 (default: 57600)
Storage	162-500 templates
FAR	< 0.001%
FRR	< 1.0%

Arduino Board

Component	Specification
Model	Arduino Uno R3 / Nano / Mega
Microcontroller	ATmega328P / ATmega2560
Digital I/O	14-54 pins
USB	Type-B / Mini-B

Webcam

Component	Specification
Resolution	Minimum 720p (1080p recommended)
Frame Rate	30 FPS
Connection	USB 2.0 or higher

API Reference

Face Recognition

`POST /api/encode_face`

Encodes face image to a 128-dimensional vector.

curl -X POST http://localhost:5000/api/encode_face \
  -F "file=@face_image.jpg"

`POST /api/face/compare`

Compares two face encodings.

Request:

{
  "encoding1": [0.123, -0.456, "..."],
  "encoding2": [0.789, -0.012, "..."],
  "threshold": 0.6
}

Response:

{
  "success": true,
  "data": {
    "similarity_score": 0.85,
    "is_match": true,
    "threshold": 0.6,
    "face_distance": 0.15
  }
}

Fingerprint

`POST /api/fingerprint/init`

Initialize sensor connection.

`POST /api/fingerprint/register`

Register fingerprint for a voter.

`POST /api/fingerprint/verify`

Verify fingerprint and return voter identity match.

`DELETE /api/fingerprint/delete/<voter_id>`

Delete fingerprint template for a voter.

`POST /api/fingerprint/delete_all`

Delete all templates.

`POST /api/fingerprint/restart`

Restart fingerprint service.

Smart Contract Functions

Election Management

Function	Access	Description
`startElection()`	Public	Move from registration to voting
`endElection()`	Public	End voting and compute result
`newElection()`	Public	Reset election cycle
`getElectionStatus()`	View	Current election phase

Voter Management

Function	Access	Description
`registerVoter(...)`	Registration phase	Register voter with biometric references
`removeVoter(voterId)`	Registration phase	Remove voter
`getAllVoters()`	View	List all voters
`getTotalVoterCount()`	View	Voter count

Candidate Management

Function	Access	Description
`registerCandidate(name)`	Registration phase	Register candidate
`removeCandidate(candidateId)`	Registration phase	Remove candidate
`getAllCandidates()`	View	List all candidates
`getTotalCandidateCount()`	View	Candidate count

Voting

Function	Access	Description
`castVote(voterId, candidateId)`	Voting phase	Cast vote
`getVoteCounts()`	View	Current vote totals
`getVoterVotingStatus()`	View	Check voting status
`getWinner()`	Post-election	Return winner

Usage Guide

Administrators

Deploy smart contract.
Start backend service.
Connect and validate fingerprint sensor.
Open admin panel (/admin).
Register candidates.
Start election.
End election and publish results.

Voters

During registration:
- Open /register
- Submit voter details
- Complete face capture
- Complete fingerprint capture
During voting:
- Open /verification
- Complete biometric verification
- Select candidate and cast vote

Accessibility

Single-biometric registration is supported where required:

Face only
Fingerprint only

Note

At least one biometric credential is required.

Security Considerations

Biometric Security

Face data is processed as embeddings, not raw images for identity matching.
Fingerprint templates remain on sensor hardware.
On-chain storage should avoid raw biometric material.

Blockchain Security

Election actions are auditable through transaction history.
Contract guards restrict invalid state transitions.
Double voting is prevented by contract logic.

Application Security

Enable strict input validation.
Restrict CORS to trusted origins in production.
Protect secrets (wallet keys, API credentials, RPC endpoints).

Caution

Use HTTPS in production and perform independent security audits before real-world deployment.

Troubleshooting

Fingerprint Sensor

Issue	Action
Sensor not detected	Verify wiring and serial port
Communication failure	Validate baud rate and cable quality
Poor capture quality	Clean sensor surface
Enrollment failure	Retry with correct finger placement

Face Recognition

Issue	Action
Face not detected	Improve lighting and camera angle
Multiple faces detected	Ensure one subject in frame
dlib build fails	Install required C++ build toolchain
Low similarity score	Retake image in stable lighting

Blockchain

Issue	Action
Transaction failure	Check wallet funds and gas settings
Contract call error	Verify deployed address and chain ID
ThirdWeb errors	Validate client ID and network configuration

General

Issue	Action
CORS errors	Confirm Flask-CORS configuration
Port conflicts	Change backend/frontend port
Missing modules	Reinstall dependencies in active environment

Contributing

Contributions are welcome.

Fork repository.

Create feature branch:

git checkout -b feature/your-feature-name

Commit changes.
Push branch.
Open pull request.

Code Style

TypeScript/JavaScript: ESLint + Prettier
Python: PEP 8
Solidity: Solidity style guide
Arduino C++: Arduino conventions

Authors

Rahul — Initial development — @rahulratho15
Contact: rahulrathnavel15@gmail.com

Acknowledgments

ThirdWeb — blockchain development platform
Adafruit — fingerprint tooling
dlib — face recognition backend
OpenZeppelin — smart contract security patterns

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
Arduino c++/c		Arduino c++/c
blockchain solidity		blockchain solidity
next.js frontend		next.js frontend
python backend		python backend
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Blockchain Biometric Voting System

Table of Contents

Overview

Key Features

Dual Biometric Authentication

Blockchain Integration

Web Application

Backend Services

System Architecture

Technology Stack

Frontend

Backend

Blockchain

Hardware / Embedded

Project Structure

Prerequisites

Software Requirements

Python Build Prerequisites

Installation and Setup

1. Arduino Fingerprint Sensor Setup

Hardware Connection

Arduino IDE Setup

Arduino Serial Commands

2. Python Backend Setup

3. Blockchain Smart Contract Deployment

Option A: ThirdWeb Dashboard

Option B: Hardhat

4. Next.js Frontend Setup

Hardware Requirements

Fingerprint Sensor Module

Arduino Board

Webcam

API Reference

Face Recognition

POST /api/encode_face

POST /api/face/compare

Fingerprint

POST /api/fingerprint/init

POST /api/fingerprint/register

POST /api/fingerprint/verify

DELETE /api/fingerprint/delete/<voter_id>

POST /api/fingerprint/delete_all

POST /api/fingerprint/restart

Smart Contract Functions

Election Management

Voter Management

Candidate Management

Voting

Usage Guide

Administrators

Voters

Accessibility

Security Considerations

Biometric Security

Blockchain Security

Application Security

Troubleshooting

Fingerprint Sensor

Face Recognition

Blockchain

General

Contributing

Code Style

Authors

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

`POST /api/encode_face`

`POST /api/face/compare`

`POST /api/fingerprint/init`

`POST /api/fingerprint/register`

`POST /api/fingerprint/verify`

`DELETE /api/fingerprint/delete/<voter_id>`

`POST /api/fingerprint/delete_all`

`POST /api/fingerprint/restart`

Packages