KCoin - Custom Digital Currency

A full-stack web application simulating a digital currency ecosystem with wallets, transactions, and blockchain mining functionality.

🚀 Quick Start

Prerequisites

• Node.js (v16 or higher)
• npm

Clone the Repository

1. Clone the repository:

   git clone https://github.com/arthurr455565/KCoin-Project.git
   cd KCoin-Project

Backend Setup

1. Navigate to backend directory:

   cd Kcoin-backend

2. Install dependencies:

   npm install

3. Configure environment variables: Create a .env file in the backend directory:

   PORT=5000
   JWT_SECRET=your-secret-key-here
   POW_DIFFICULTY_PREFIX=00
   MINER_REWARD=10
   TRANSACTION_FEE_PERCENT=1
   COLLECT_TX_FEES=true
   TARGET_BLOCK_TIME_MS=5000
   DIFFICULTY_WINDOW=5

4. Start the backend server:

   npm run dev

   The backend will run on http://localhost:5000

Frontend Setup

1. Navigate to frontend directory:

   cd Kcoin-frontend

2. Install dependencies:

   npm install

3. Start the frontend development server:

   npm run dev

   The frontend will run on http://localhost:5173

🏗️ Architecture Overview

Backend Architecture (Node.js + TypeScript)

Core Components:

• Express.js Server with TypeScript for type safety
• JWT Authentication for secure user sessions
• WebSocket (Socket.IO) for real-time updates
• File-based Storage (JSON files) for simplicity
• Modular Route Structure for maintainability

Key Services:

• Blockchain Service: Handles block creation, mining, and chain validation
• Wallet Service: Manages balance calculations and transaction history
• Auth Middleware: Protects routes and validates JWT tokens

Data Models:

• User: id, email, username, passwordHash, walletAddress, createdAt
• Transaction: id, sender, recipient, amount, fee, timestamp
• Block: index, timestamp, transactions, previousHash, hash, nonce

Frontend Architecture (React + TypeScript)

Core Components:

• React 19 with TypeScript for type safety
• React Router for navigation
• Tailwind CSS for modern, responsive styling
• SweetAlert2 for user notifications
• Axios for API communication
• Socket.IO Client for real-time updates

Key Features:

• Authentication Pages: Login and Registration with form validation
• Wallet Dashboard: Balance display, transaction sending, and mining interface
• Blockchain Explorer: Visual representation of the entire blockchain
• Real-time Updates: Automatic balance updates via WebSocket

🔧 Key Features

✅ Core Requirements Implemented

1. User/Wallet Management

   • User registration and authentication
   • Unique wallet address generation
   • Balance calculation by iterating through blockchain

2. Transaction System

   • Create transactions with validation
   • Pending transaction pool
   • Transaction fee support (configurable)
   • Balance validation to prevent overspending

3. Blockchain & Mining

   • Proof-of-Work algorithm with configurable difficulty
   • Dynamic difficulty adjustment based on block times
   • Miner rewards (10 KCoin per block + transaction fees)
   • Genesis block creation

4. Real-time Updates

   • WebSocket integration for live balance updates
   • Automatic UI refresh when blocks are mined

🎯 Bonus Features Implemented

• Dynamic Difficulty: Adjusts mining difficulty based on recent block times
• Transaction Fees: Optional fee system for miners
• Real-time Updates: WebSocket-based live updates
• Modern UI/UX: Responsive design with Tailwind CSS
• Error Handling: Comprehensive error handling with user-friendly messages

🛠️ Technical Decisions

1. File-based Storage vs Database

Decision: Used JSON files for data persistence Rationale:

• Simpler setup and deployment
• No database configuration required
• Sufficient for demonstration purposes
• Easy to inspect and debug

2. WebSocket for Real-time Updates

Decision: Implemented Socket.IO for real-time communication Rationale:

• Provides instant feedback to users
• Enhances user experience
• Demonstrates modern web development practices
• Required for bonus features

3. SweetAlert2 for Notifications

Decision: Replaced toast notifications with SweetAlert2 Rationale:

• Better React 19 compatibility
• More reliable than toast libraries
• Better user experience with modal dialogs
• Consistent cross-browser support

4. Dynamic Difficulty Adjustment

Decision: Implemented adaptive mining difficulty Rationale:

• Maintains consistent block times
• Demonstrates advanced blockchain concepts
• Improves system scalability
• Shows understanding of PoW mechanics

5. Modular Architecture

Decision: Separated concerns into services, routes, and models Rationale:

• Better code maintainability
• Easier testing and debugging
• Follows SOLID principles
• Scalable for future enhancements

🔐 Security Considerations

• Password Hashing: bcrypt with salt rounds
• JWT Authentication: Secure token-based auth
• Input Validation: Server-side validation for all inputs
• CORS Configuration: Properly configured for frontend-backend communication
• Error Handling: No sensitive information leaked in error messages

📁 Project Structure

KCoin Project/
├── Kcoin-backend/
│   ├── src/
│   │   ├── data/           # JSON data files
│   │   ├── models/         # TypeScript interfaces
│   │   ├── routes/         # API endpoints
│   │   ├── services/       # Business logic
│   │   ├── utils/          # Helper functions
│   │   └── realtime/       # WebSocket setup
│   └── package.json
├── Kcoin-frontend/
│   ├── src/
│   │   ├── components/     # Reusable components
│   │   ├── pages/          # Page components
│   │   ├── hooks/          # Custom React hooks
│   │   └── api/            # API client setup
│   └── package.json
└── README.md

🚀 Usage Instructions

1. Register Accounts: Create two user accounts
2. Get Initial KCoin: Mine a block to receive 10 KCoin
3. Send Transactions: Transfer KCoin between accounts
4. Mine Blocks: Process pending transactions and earn rewards
5. Explore Blockchain: View the complete transaction history

🔧 Configuration

Environment Variables

Variable	Default	Description
PORT	5000	Backend server port
JWT_SECRET	-	Secret key for JWT tokens
POW_DIFFICULTY_PREFIX	"00"	Mining difficulty (leading zeros)
MINER_REWARD	10	KCoin reward per mined block
TRANSACTION_FEE_PERCENT	1	Transaction fee percentage
COLLECT_TX_FEES	true	Whether to collect transaction fees
TARGET_BLOCK_TIME_MS	5000	Target time per block (ms)
DIFFICULTY_WINDOW	5	Blocks to average for difficulty adjustment

📝 License

This project is created for educational and demonstration purposes.

---