🗳️ Blockchain Voting System

A decentralized voting system built with Solidity, Hardhat, and Node.js that enables transparent and immutable elections on the blockchain.

✨ Features

• ✅ Add candidates (owner only)
• ✅ Vote (each user votes only once)
• ✅ List all candidates
• ✅ Get election winner
• ✅ Complete RESTful API
• ✅ Web3.js integration

🛠️ Tech Stack

• Solidity ^0.8.19 - Smart contracts
• Hardhat ^2.19.0 - Development framework
• Web3.js ^1.10.0 - Blockchain interface
• Express.js - Backend server
• Node.js - Runtime environment

📋 Prerequisites

• Node.js 16+
• npm or yarn
• MetaMask (for Sepolia network testing)

🚀 Installation & Setup

1. Clone the repository

git clone https://github.com/brunofullstack/blockchain-voting-system.git
cd blockchain-voting-system

2. Install dependencies

npm install

3. Configure environment variables

Create a .env file in the project root:

PRIVATE_KEY=your_metamask_private_key
SEPOLIA_URL=https://sepolia.infura.io/v3/your_infura_key
BLOCKCHAIN_URL=http://localhost:8545
PORT=3000

🏗️ Project Structure

blockchain-voting-system/
├── contracts/
│   └── Voting.sol          # Smart contract
├── scripts/
│   └── deploy.js           # Deployment script
├── artifacts/              # ABI and bytecode (generated)
├── contract-info.json      # Contract info (generated)
├── hardhat.config.js       # Hardhat configuration
├── server.js               # Backend server
├── .env                    # Environment variables
└── package.json

🔧 Available Commands

# Compile contracts
npm run compile

# Start local Hardhat network
npm run node

# Deploy contract
npm run deploy

# Start backend server
npm run server

# Run tests
npm run test

🌐 API Endpoints

POST /candidates

Add a new candidate (owner only)

Body:

{
  "name": "Candidate Name",
  "privateKey": "0x..."
}

GET /candidates

Get list of all candidates

Response:

[
  {
    "id": "1",
    "name": "Candidate A",
    "voteCount": "5"
  }
]

POST /vote

Cast a vote for a candidate

Body:

{
  "candidateId": 1,
  "privateKey": "0x..."
}

GET /winner

Get the winning candidate

Response:

{
  "id": "1",
  "name": "Candidate A",
  "voteCount": "10"
}

📖 How to Use

1. Start local network

npm run node

2. Deploy the contract

npm run deploy

3. Start the server

npm run server

4. Test endpoints

Add candidate:

curl -X POST http://localhost:3000/candidates \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "privateKey": "0x..."}'

List candidates:

curl http://localhost:3000/candidates

Vote:

curl -X POST http://localhost:3000/vote \
  -H "Content-Type: application/json" \
  -d '{"candidateId": 1, "privateKey": "0x..."}'

Get winner:

curl http://localhost:3000/winner

🔐 Security Features

• Only contract owner can add candidates
• Each address can vote only once
• Transactions are validated on blockchain
• Votes are immutable and transparent

🌍 Testnet Deployment

Sepolia Testnet

1. Configure your PRIVATE_KEY and SEPOLIA_URL in .env
2. Deploy contract:

npx hardhat run scripts/deploy.js --network sepolia

3. Update contract-info.json with the new address

📊 Smart Contract

Main Functions

function addCandidate(string memory _name) public onlyOwner
function vote(uint256 _candidateId) public
function getCandidates() public view returns (Candidate[] memory)
function getWinner() public view returns (Candidate memory)

Events

• CandidateAdded(uint256 candidateId, string name)
• Voted(address voter, uint256 candidateId)

🧪 Testing

Tests ensure that:

• Only owner can add candidates
• Users can vote only once
• Winner is calculated correctly
• Voting can be opened/closed

🤝 Contributing

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

📝 License

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

📞 Contact

Bruno Fullstack - brunofullstack@gmail.com

Project Link: https://github.com/brunofullstack/blockchain-voting-system

🙏 Acknowledgments

• OpenZeppelin for base contracts
• Hardhat team for excellent framework
• Ethereum community for the ecosystem

---

⚠️ Note: This is an educational project. Use in production only after complete security audit.