🔐 CypherD Wallet - Mock Web3 Wallet

A modern, secure mock Web3 wallet application that demonstrates core blockchain wallet features using mock ETH balances and real-world integrations.

🎯 Features

🔒 Core Wallet Features

• Create/Import Wallet: Generate new 12-word mnemonic phrases or import existing ones
• Mock ETH Balances: Each new wallet gets a random balance between 1-10 ETH
• Send Mock ETH: Transfer funds between addresses with concurrent processing
• USD to ETH Conversion: Convert USD amounts to ETH using Skip API
• Transaction History: View complete transaction history with status tracking
• Real-time Notifications: Email notifications and in-app toasts for transactions

🛡️ Security Features

• Message Signing: Users must sign transaction messages before execution
• Time-based Validation: Transfer messages expire after 30 seconds
• Price Tolerance Check: USD transfers include price fluctuation protection
• Encrypted Storage: Private keys and mnemonics are encrypted in the database
• Secure Email Notifications: HTML email notifications with transaction details

🎨 Modern UI/UX

• Responsive Design: Works seamlessly on desktop, tablet, and mobile
• Modern Interface: Clean, professional design with smooth animations
• Real-time Updates: Dynamic balance and address updates
• Toast Notifications: Beautiful in-app notifications for transactions
• Loading States: Visual feedback during transaction processing

🛠 Tech Stack

Backend

• Python 3.7+: Core application language
• Flask: Web framework for API and routing
• MongoDB: Database for user accounts and transactions
• Web3.py: Ethereum address generation and blockchain interaction
• PyCryptodome: AES encryption for secure data storage
• Skip API: Real-time USD to ETH conversion
• SMTP: Email notification system

Frontend

• HTML5/CSS3: Modern web standards
• JavaScript (ES6+): Interactive functionality
• Bootstrap 5: Responsive UI framework
• Font Awesome: Icon library
• Inter Font: Modern typography
• jQuery: DOM manipulation and AJAX

APIs & Services

• Skip API: USD to ETH conversion
• Gmail SMTP: Email notifications
• Google Charts: QR code generation

📋 Setup Instructions

Prerequisites

• Python 3.7 or higher
• MongoDB (local or cloud)
• Gmail account for email notifications
• Internet connection for API calls

Installation

1. Clone the repository

   git clone https://github.com/yourusername/cypherd-wallet.git
   cd cypherd-wallet

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment variables Create a .env file in the root directory:

   INFURA_ID=your_infura_project_id
   MONGODB_URI=your_mongodb_connection_string
   GMAIL_USER=your-email@gmail.com
   GMAIL_PASSWORD=your-app-password

5. Update email configuration In app.py, update the email settings in send_notification():

   sender_email = "your-email@gmail.com"
   sender_password = "your-app-password"

6. Run the application

   python app.py

7. Access the wallet Open your browser and go to http://localhost:5002

🚀 How to Use

Creating a New Wallet

1. Click "Create New Account" on the home page
2. Save your 12-word mnemonic phrase securely (this is crucial!)
3. Verify 5 random words from your mnemonic
4. Set a password for your wallet
5. Your wallet is created with a random mock balance (1-10 ETH)

Importing an Existing Wallet

1. Click "Import Existing Account" on the home page
2. Enter your 12-word mnemonic phrase
3. Set a password
4. Your wallet is imported with 0 ETH balance

Sending Mock ETH

1. Select your wallet address from the dropdown
2. Enter recipient address and amount
3. Choose ETH or USD for the amount
4. Click "Send" - transaction executes immediately
5. Receive email notification and in-app toast

Receiving Mock ETH

1. Click "Simulate Receive 1 ETH" to add funds
2. Share your address with others to receive funds
3. View QR code for easy sharing

Viewing Transaction History

1. Click "Transaction History" button
2. View all your sent and received transactions
3. See transaction details including amounts, addresses, and timestamps

🔧 API Endpoints

Wallet Management

• POST /api/add_new_account - Create additional wallet accounts
• GET /api/get_balance - Get balance for specific address
• GET /api/transaction_history - Get transaction history

Transfer Operations

• POST /api/execute_transfer_direct - Execute transfer with concurrent processing
• POST /api/simulate_receive - Simulate receiving funds

User Management

• POST /login - User authentication
• GET /logout - User logout

🏗 Architecture

Database Collections

• users: Encrypted mnemonic phrases, passwords, and email addresses
• accounts: Wallet addresses, encrypted private keys, and mock balances
• transactions: Complete transaction history with metadata

Security Model

• Mnemonic phrases encrypted with AES-256 using PBKDF2 key derivation
• Private keys encrypted separately using derived keys
• Message signing required for all transactions
• Time-based message validation (30-second expiry)
• HTML email notifications with transaction details

Transaction Flow

1. User initiates transfer
2. System validates balance and recipient
3. Transaction executes concurrently
4. Balances updated in database
5. Email notification sent
6. In-app toast notification displayed

🔒 Security Considerations

This is a mock wallet for educational purposes. For production use:

• Implement proper cryptographic signature verification
• Use hardware security modules for key storage
• Add multi-factor authentication
• Implement proper session management
• Use secure key derivation functions
• Add rate limiting and DDoS protection
• Implement proper email verification
• Add transaction limits and monitoring

📱 Screenshots

Home Page

• Modern login interface with wallet branding
• Feature highlights and security information
• Responsive design for all devices

Dashboard

• Real-time balance display in ETH and USD
• Send crypto with ETH/USD conversion
• Receive crypto with QR code display
• Transaction history with status tracking
• Toast notifications for transactions

Wallet Creation

• 12-word mnemonic phrase display
• Security warnings and instructions
• Interactive verification process

🎯 Bonus Features Implemented

• USD to ETH Conversion: Real-time conversion using Skip API
• Transaction History: Complete audit trail with status tracking
• Email Notifications: Beautiful HTML email notifications
• Toast Notifications: In-app notifications for transactions
• Concurrent Processing: Fast transaction execution
• Responsive Design: Works on all devices
• Modern UI: Professional design with animations

🐛 Known Issues

• Email notifications require Gmail SMTP configuration
• Signature verification is simplified (implement proper cryptographic verification)
• Price tolerance check is basic (enhance for production use)
• Mock balances are not persistent across server restarts

🤝 Contributing

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

📄 License

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

🆘 Support

For issues or questions:

1. Check the troubleshooting section
2. Review the code comments
3. Create an issue in the repository
4. Contact support at support@cypherd.wallet

🙏 Acknowledgments

• Skip API for USD to ETH conversion
• MongoDB for database services
• Bootstrap for UI framework
• Font Awesome for icons
• Google Charts for QR code generation

---

⚠️ Disclaimer: This is a mock wallet for educational purposes. Do not use for real cryptocurrency transactions. Always use official, audited wallets for real funds.

🔐 Security Notice: Never share your mnemonic phrase with anyone. Store it securely offline. We cannot recover your wallet if you lose your phrase.

---

Made with ❤️ by the CypherD Team

© 2024 CypherD Wallet. All rights reserved.