🚀 EtherVault3 CLI

    ███████╗████████╗██╗  ██╗███████╗██████╗ ██╗   ██╗ █████╗ ██╗   ██╗██╗  ████████╗██████╗ 
    ██╔════╝╚══██╔══╝██║  ██║██╔════╝██╔══██╗██║   ██║██╔══██╗██║   ██║██║  ╚══██╔══╝╚════██╗
    █████╗     ██║   ███████║█████╗  ██████╔╝██║   ██║███████║██║   ██║██║     ██║    █████╔╝
    ██╔══╝     ██║   ██╔══██║██╔══╝  ██╔══██╗╚██╗ ██╔╝██╔══██║██║   ██║██║     ██║    ╚═══██╗
    ███████╗   ██║   ██║  ██║███████╗██║  ██║ ╚████╔╝ ██║  ██║╚██████╔╝███████╗██║   ██████╔╝
    ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝   ╚═════╝ 

A secure, feature-rich, and user-friendly Ethereum-only command-line wallet. Built with TypeScript and powered by ethers.js, EtherVault3 provides enterprise-grade security with an intuitive CLI experience.

✨ Features

🔐 Security First

• AES-256-GCM Encryption: Military-grade encryption for all stored data
• PBKDF2 Key Derivation: 100,000 iterations with SHA-512 for master password
• Secure Storage: All sensitive data encrypted at rest
• Master Password Protection: Single password protects all wallets
• Memory-Only Keys: Private keys never stored in plaintext

🏦 HD Wallet Support

• Hierarchical Deterministic: Generate unlimited accounts from single seed
• BIP44 Standard: Industry-standard derivation paths (m/44'/60'/0'/0/n)
• Multi-Account Management: Create and manage multiple accounts per wallet
• Mnemonic Import/Export: Support for 12/24 word seed phrases

💰 Transaction Management

• Send Transactions: Native ETH transfers with gas optimization
• Balance Checking: Real-time balance queries across networks
• Transaction History: Complete transaction tracking and analytics
• Gas Estimation: Automatic gas price optimization
• Multi-Network Support: Ethereum, Sepolia, Goerli testnets

🎁 Advanced Features

• Airdrop Tokens: Bulk token distribution to multiple addresses
• Account Discovery: Automatic detection of existing accounts from mnemonic
• Transaction Analytics: Success rates, gas usage, and performance metrics
• Wallet Management: Create, import, delete, and organize wallets
• Secrets Management: Secure viewing of private keys and mnemonics

🌐 Network Support

• Ethereum Mainnet: Production-ready mainnet support
• Sepolia Testnet: Latest Ethereum testnet
• Goerli Testnet: Legacy testnet support
• Custom RPC: Support for custom network configurations

🚀 Quick Start

Prerequisites

• Node.js 18.0 or higher
• npm 8.0 or higher
• Git (for cloning)

Installation

# Clone the repository
git clone https://github.com/RAHULDINDIGALA-32/ethervault3-cli-wallet.git

# Navigate to project directory
cd ethervault3-cli-wallet

# Install dependencies
npm install

# Build the project
npm run build

# Start the wallet
npm start

First Time Setup

1. Run the application:

   npm start

2. Create your profile:

   • Enter a username
   • Set a strong master password (minimum 8 characters)
   • Confirm your password

3. Create or import a wallet:

   • Create New: Generate a new HD wallet with mnemonic
   • Import Existing: Import using 12/24 word mnemonic phrase

4. Start using your wallet:

   • Check balances
   • Send transactions
   • Manage multiple accounts
   • Use advanced features like airdrops

📖 Usage Guide

How to Use (One-Liner Install)

Linux/macOS (latest release tarball)

curl -fsSL https://raw.githubusercontent.com/RAHULDINDIGALA-32/ethervault3-cli-wallet/main/scripts/install.sh -o install.sh \
  && chmod +x install.sh \
  && ./install.sh

Windows (PowerShell, latest release tarball)

irm https://raw.githubusercontent.com/RAHULDINDIGALA-32/ethervault3-cli-wallet/main/scripts/install.ps1 | iex

Pin a specific version (example v1.0.1):

• Linux/macOS: ./install.sh v1.0.1 → installs https://github.com/RAHULDINDIGALA-32/ethervault3-cli-wallet/releases/download/v1.0.1/ethervault3-cli-1.0.1.tgz
• Windows: irm https://raw.githubusercontent.com/RAHULDINDIGALA-32/ethervault3-cli-wallet/main/scripts/install.ps1 | iex; install.ps1 -Tag v1.0.1

After installation:

ethervault3
# or
ethervault3-cli

Note:

• Requires Node.js >= 18 and npm.
• Create a .env with INFURA_PROJECT_ID=... to enable network access.

Provider Setup (Recommended for reliability)

By default, EtherVault3 uses public RPC endpoints (no keys required). These are fine for light usage but can be slow or rate‑limited. For a smoother experience, add your own provider key or custom RPC.

1. Quick start (no key)

• It “just works” using public RPCs. If you see rate‑limits or intermittent network errors, proceed to step 2 or 3.

2. Add your own provider key (Infura example)

• Create a free project: https://app.infura.io
• Copy your Project ID
• Create a .env file in the directory where you run the CLI and add:

INFURA_PROJECT_ID=your_infura_project_id_here

• Restart the CLI. Networks will resolve to:
  • mainnet: https://mainnet.infura.io/v3/${INFURA_PROJECT_ID}
  • sepolia: https://sepolia.infura.io/v3/${INFURA_PROJECT_ID}
  • goerli: https://goerli.infura.io/v3/${INFURA_PROJECT_ID}

3. Use your own custom RPC(s)

• Add any HTTPS RPC URL(s) via environment variables (highest priority):

CUSTOM_MAINNET_RPC=https://your-mainnet-rpc.example
CUSTOM_SEPOLIA_RPC=https://your-sepolia-rpc.example
CUSTOM_GOERLI_RPC=https://your-goerli-rpc.example

• These override both public fallbacks and Infura.

How resolution works (per network)

• 1. CUSTOM_*_RPC (if set)
• 2. INFURA_PROJECT_ID (if set)
• 3. Public fallback (no key) – best‑effort, may rate‑limit

Troubleshooting

• If you hit 429/rate limits or provider errors:
  • Add INFURA_PROJECT_ID or set a CUSTOM_*_RPC in .env
  • Check internet/firewall/VPN settings
  • Run again after a short delay (public RPCs throttle)

Main Menu Options

┌─────────────────────────────────────────────────────────────────────────────┐
│                            Available Options                                │
├─────────────────────────────────────────────────────────────────────────────┤
│ 1. 🆕 Create New Wallet                                                    │
│ 2. 📥 Import Wallet from Mnemonic                                          │
│ 3. 🗂️  Manage Wallet                                                       │
│ 4. 💰 Check Balance                                                        │
│ 5. 📤 Send Transaction                                                     │
│ 6. 📋 Transaction History                                                  │
│ 7. ⚙️  Settings                                                            │
│ 8. ❌ Exit Application                                                   │
└─────────────────────────────────────────────────────────────────────────────┘

Wallet Management

Creating a New Wallet

1. Select "Create New Wallet" from main menu
2. Choose a network (Sepolia, Goerli, Mainnet)
3. Wallet generates with:
   • 12/24 word mnemonic phrase
   • First account (index 0)
   • Private/public key pair
4. Save the wallet for future use

Importing Existing Wallet

1. Select "Import Wallet from Mnemonic"
2. Enter your 12/24 word mnemonic phrase
3. Choose network for account discovery
4. System automatically finds existing accounts
5. Save all discovered accounts as a single wallet

Managing Multiple Accounts

1. Go to "Manage Wallet" → Select wallet
2. View all accounts in the wallet
3. Create New Account: Generate additional accounts from same mnemonic
4. Switch Account: Change active account
5. View Secrets: Access private keys and mnemonic (password required)

Transaction Operations

Sending Transactions

1. From Main Menu: Option 5 (requires private key input)
2. From Account: Option 3 → Select Account → Send Transaction
3. Enter recipient address and amount
4. Set gas price (or use automatic)
5. Confirm transaction details
6. Transaction is automatically recorded in history

Airdrop Tokens

1. Go to "Manage Wallet" → Select Account → "Airdrop Tokens"
2. Enter recipient addresses (comma-separated, max 50)
3. Set amount per recipient
4. Review cost breakdown and gas estimates
5. Confirm and execute
6. Monitor real-time progress
7. View detailed results and transaction hashes

Checking Balances

1. Quick Check: Main menu option 4 (any address)
2. Account Balance: Through wallet management
3. Real-time balance queries across all supported networks

Security Features

Master Password

• Single Password: Protects all wallets and sensitive data
• Strong Encryption: AES-256-GCM with PBKDF2 key derivation
• Memory-Only: Password never stored, only derived key in memory
• Session Management: Automatic re-authentication when needed

Data Protection

• Encrypted Storage: All data encrypted at rest
• Secure Files: Restricted file permissions (600)
• No Plaintext: Private keys and mnemonics never stored unencrypted
• Salt Protection: Unique salt per installation

🛠️ Development

Project Structure

ethervault3-cli/
├── src/
│   ├── index.ts          # Main application entry point
│   ├── wallet.ts         # Wallet operations and transactions
│   ├── storage.ts        # Secure storage and encryption
│   ├── networks.ts       # Network configurations
│   ├── logger.ts         # Centralized logging utility
│   └── utils.ts          # Utility functions
├── dist/                 # Compiled JavaScript output
├── .wallet-storage/      # Encrypted user data (created at runtime)
├── package.json
├── tsconfig.json
└── README.md

Available Scripts

# Development
npm run build          # Compile TypeScript to JavaScript
npm start             # Build and run the application
npm run dev           # Run in development mode (if configured)

# Support/Reset (Development Only)
npm run reset:local    # DANGEROUS: Wipes .wallet-storage (uses --yes flag)

# Type Checking
npx tsc --noEmit      # Check TypeScript without compilation

# Dependencies
npm install           # Install all dependencies
npm update            # Update dependencies

Development/Support: Reset Tool

For local development and support, a reset script is provided to wipe the local wallet storage.

• Location: scripts/reset.js
• Behavior: Deletes the .wallet-storage directory after a --yes confirmation flag
• Usage:

node scripts/reset.js --yes
# or
npm run reset:local

Important:

• This script is NOT included in the npm package by default (GitHub only)
• It is destructive – use only in a dev/support context

Building from Source

# Clone repository
git clone https://github.com/RAHULDINDIGALA-32/ethervault3-cli-wallet.git

# Navigate to project directory
cd ethervault3-cli.git

# Install dependencies
npm install

# Build the project
npm run build

# Run the application
npm start

🔧 Configuration

Environment Variables

Create a .env file in the project root:

# Infura Project ID (for network access)
INFURA_PROJECT_ID=your_infura_project_id_here

# Optional: Custom RPC URLs
CUSTOM_RPC_URL=https://your-custom-rpc-url.com

Network Configuration

Networks are configured in src/networks.ts:

export const NETWORKS: { [key: string]: string } = {
    sepolia: `https://sepolia.infura.io/v3/${INFURA_PROJECT_ID}`,
    goerli: `https://goerli.infura.io/v3/${INFURA_PROJECT_ID}`,
    mainnet: `https://mainnet.infura.io/v3/${INFURA_PROJECT_ID}`,
};

📝 Logging

This project includes a centralized, industry-grade logging utility to ensure consistent, user-friendly, and structured logs across the CLI.

Highlights

• Consistent, human-friendly messages
• Structured categories and levels for easy filtering
• No sensitive data is logged (never logs private keys/mnemonics)
• Progress helpers and transaction status helpers

File

• src/logger.ts

Categories

• AUTH, WALLET, TRANSACTION, STORAGE, NETWORK, UI, SECURITY, SYSTEM

Levels

• DEBUG, INFO, WARN, ERROR

Common Helpers

import { log, LogCategory } from "./logger.js";

// Informational
log.info(LogCategory.WALLET, "Creating new wallet");

// Success
log.operationSuccess("Wallet Creation");

// Warnings and errors
log.warn(LogCategory.AUTH, "1 attempt remaining");
log.error(LogCategory.NETWORK, "RPC request failed", err);

// User-friendly error wrapper
log.userError("Send Transaction", "Insufficient balance. Please check your balance and try again.", err);

// Transaction lifecycle
log.transactionSent(tx.hash, toAddress, amount);
log.transactionConfirmed(tx.hash, receipt.blockNumber, receipt.gasUsed.toString());

// Progress and airdrops
log.progress("Sending transaction...");
log.airdropProgress(current, total, recipient);
log.airdropComplete(successful, failed, total);

Configuration

Logging behavior can be tuned via environment variables (optional):

# Set Node environment: production | development
NODE_ENV=production

Additional formatting options (timestamps, categories, emojis) can be toggled inside src/logger.ts if you want stricter or more verbose output.

Storage Location

• Windows: \.wallet-storage\
• Linux/Mac: ~/.wallet-storage/ (.wallet-storage/ located in the current working directory where you run the application)

Files:

• user.json - User profile (plaintext)
• salt.enc - Encryption salt (hex)
• wallets.enc - Encrypted wallet data
• transactions.enc - Encrypted transaction history
• config.json - Application settings

🔒 Security Considerations

Best Practices

1. Strong Master Password:

   • Use at least 12 characters
   • Include uppercase, lowercase, numbers, symbols
   • Never share or write down

2. Secure Environment:

   • Run on trusted machines only
   • Keep your system updated
   • Use antivirus software

3. Backup Strategy:

   • Save mnemonic phrases securely
   • Test recovery process
   • Store backups in multiple secure locations

4. Network Security:

   • Use HTTPS RPC endpoints
   • Verify network connections
   • Be cautious with public WiFi

Data Encryption

• Algorithm: AES-256-GCM
• Key Derivation: PBKDF2 with SHA-512, 100,000 iterations
• Salt: 16-byte random salt per installation
• Authentication: Additional authenticated data (AAD)

🐛 Troubleshooting

Common Issues

"Master password not set" Error

• Cause: Authentication state lost
• Solution: Restart application and re-enter password

"Decryption failed" Error

• Cause: Wrong master password or corrupted data
• Solution: Verify password, check data integrity

"Insufficient balance" Error

• Cause: Not enough ETH for transaction + gas
• Solution: Check balance, reduce amount, or add funds

Network Connection Issues

• Cause: RPC endpoint problems
• Solution: Check internet connection, verify Infura ID

Getting Help

1. Check Issues: GitHub Issues
2. Read Documentation: This README and code comments
3. Create Issue: Provide detailed error information

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Add comprehensive error handling
• Include unit tests for new features
• Update documentation
• Follow existing code style

📄 License

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

👨‍💻 Author

RAHUL DINDIGALA

• GitHub: @RAHULDINDIGALA-32
• Web3 Developer
• Blockchain Enthusiast

🙏 Acknowledgments

• ethers.js - Ethereum library
• inquirer.js - Interactive CLI prompts
• Node.js - Runtime environment
• TypeScript - Type safety
• Chalk - Terminal string styling
• Web3 Community - Inspiration and support

📊 Project Stats

• Features: 15+ major features
• Security: Military-grade encryption
• Networks: 3+ supported networks
• Accounts: Unlimited HD accounts
• Transactions: Full history tracking

---

⚠️ Disclaimer

This application is provided "as is" without warranty. Users are responsible for:

• Securing their private keys and passwords
• Verifying transaction details before confirmation
• Understanding the risks of cryptocurrency transactions
• Complying with local laws and regulations

Use at your own risk. The developers are not responsible for any loss of funds.

---

⭐ Star this repository if you found it helpful! ⭐

Made with ❤️ by RAHUL DINDIGALA