275 lines
6.9 KiB
Markdown
275 lines
6.9 KiB
Markdown
# pyhdwallet – Secure HD Wallet Tool
|
||
|
||
A Python command-line tool for generating and recovering BIP39 HD wallets with support for Ethereum, Solana, and Bitcoin. Includes **BIP85 deterministic child mnemonic derivation** for creating multiple isolated wallets from a single master seed. Designed for offline operation with optional PGP encryption and AES-encrypted ZIP artifacts.
|
||
|
||
---
|
||
|
||
## 📦 Installation
|
||
|
||
### **Quick Start (macOS/Linux with Internet)**
|
||
|
||
```bash
|
||
# Clone repository
|
||
git clone https://github.com/<your-username>/hdwalletpy.git
|
||
cd hdwalletpy
|
||
|
||
# Install using automated script
|
||
./install_offline.sh
|
||
```
|
||
|
||
The script automatically:
|
||
|
||
- Creates Python 3.12 virtual environment
|
||
- Installs from vendored wheels (offline-capable)
|
||
- Verifies installation with test suite
|
||
- Leaves you in activated venv
|
||
|
||
---
|
||
|
||
### **Air-Gapped Installation (No Internet)**
|
||
|
||
This repository includes pre-built Python wheels for offline use.
|
||
|
||
**Supported platforms:**
|
||
|
||
- macOS ARM64 (M1/M2/M3/M4) - Python 3.12
|
||
- Linux x86_64 (Ubuntu/Tails) - Python 3.12
|
||
|
||
**Steps:**
|
||
|
||
1. On an online machine, clone and verify:
|
||
|
||
```bash
|
||
git clone https://github.com/<your-username>/hdwalletpy.git
|
||
cd hdwalletpy
|
||
|
||
# Verify checksums
|
||
cd vendor/linux-x86_64 # or macos-arm64
|
||
sha256sum -c SHA256SUMS # Linux
|
||
shasum -a 256 -c SHA256SUMS # macOS
|
||
```
|
||
|
||
2. Transfer entire repo to USB drive
|
||
|
||
3. On air-gapped machine:
|
||
|
||
```bash
|
||
cd hdwalletpy
|
||
./install_offline.sh
|
||
```
|
||
|
||
4. Generate wallet:
|
||
|
||
```bash
|
||
python src/pyhdwallet.py gen --off-screen --file
|
||
```
|
||
|
||
---
|
||
|
||
### **Developer Installation (with Docker)**
|
||
|
||
For development or building wheels for other platforms:
|
||
|
||
```bash
|
||
# Build Docker image
|
||
make build-image
|
||
|
||
# Build wheels for all platforms
|
||
make vendor-all
|
||
|
||
# Install development environment
|
||
make install
|
||
|
||
# Run tests
|
||
make test
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ Basic Usage
|
||
|
||
```bash
|
||
# Generate wallet (prints mnemonic - debug mode)
|
||
python src/pyhdwallet.py gen
|
||
|
||
# Generate with off-screen mode + encrypted ZIP
|
||
python src/pyhdwallet.py gen --off-screen --file
|
||
|
||
# Generate with PGP encryption + ZIP
|
||
python src/pyhdwallet.py gen \
|
||
--pgp-pubkey-file pubkeys/mykey.asc \
|
||
--expected-fingerprint A27B96F2B169B5491013D2DA892B822C14A9AA18 \
|
||
--off-screen \
|
||
--file
|
||
|
||
# Derive BIP85 child mnemonic (12/15/18/21/24 words)
|
||
python src/pyhdwallet.py gen-child \
|
||
--interactive \
|
||
--words 12 \
|
||
--index 0
|
||
|
||
# Derive BIP85 child with passphrase + encrypted output
|
||
python src/pyhdwallet.py gen-child \
|
||
--mnemonic-stdin \
|
||
--passphrase \
|
||
--words 24 \
|
||
--index 0 \
|
||
--pgp-pubkey-file pubkeys/mykey.asc \
|
||
--off-screen \
|
||
--file
|
||
|
||
# Recover wallet from mnemonic
|
||
python src/pyhdwallet.py recover --interactive --file
|
||
|
||
# Fetch PGP public key (requires internet)
|
||
python src/pyhdwallet.py fetchkey "https://example.com/key.asc" --out mykey.asc
|
||
|
||
# Run tests
|
||
python src/pyhdwallet.py test
|
||
pytest -v tests/test_vectors.py
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 Security Features
|
||
|
||
- **Offline-first**: Network access blocked during key generation/recovery
|
||
- **BIP85 deterministic entropy**: Derive unlimited child mnemonics from master seed
|
||
- **Test suite**: Regression tests with frozen vectors ensure derivation logic integrity
|
||
- **PGP fingerprint pinning**: Prevents key substitution attacks
|
||
- **TTY safety guard**: Refuses to print secrets when stdout is piped/redirected
|
||
- **AES-encrypted outputs**: Wallet artifacts encrypted with `pyzipper`
|
||
- **No shell history leaks**: Use `--interactive` or `--mnemonic-stdin` for recovery
|
||
- **Interoperable**: BIP85 children compatible with Coldcard, Ian Coleman tool, etc.
|
||
|
||
---
|
||
|
||
## 🛠️ Makefile Targets
|
||
|
||
**Vendoring (for air-gapped deployment):**
|
||
|
||
```bash
|
||
make vendor-macos # Build macOS ARM64 wheels
|
||
make vendor-linux # Build Linux x86_64 wheels (Docker)
|
||
make vendor-all # Build for both platforms
|
||
make verify-vendor # Test offline installation
|
||
```
|
||
|
||
**Development:**
|
||
|
||
```bash
|
||
make install # Create venv and install dependencies
|
||
make test # Run test suite
|
||
make build-image # Build Docker image
|
||
make shell # Open shell in Docker container
|
||
make clean # Remove venvs and build artifacts
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 Full Documentation
|
||
|
||
- **[playbook.md](playbook.md)** - Complete command reference and operational guide
|
||
- **[tests/](tests/)** - Regression test suite documentation
|
||
|
||
---
|
||
|
||
## 🔒 Recommended Air-Gapped Setup
|
||
|
||
For maximum security when generating production wallets:
|
||
|
||
1. Use fresh Ubuntu Live USB or Tails OS
|
||
2. Never connect to network after booting
|
||
3. Transfer this repository via separate USB
|
||
4. Run `./install_offline.sh`
|
||
5. Generate wallet: `python src/pyhdwallet.py gen --off-screen --file`
|
||
6. Write mnemonic to paper/metal backup
|
||
7. Transfer encrypted ZIP to secure storage
|
||
8. Wipe USB drives securely
|
||
|
||
See [playbook.md](playbook.md) for detailed air-gapped procedures.
|
||
|
||
## 🖥️ Platform Compatibility
|
||
|
||
### Makefile Targets
|
||
|
||
| Target | macOS | Linux | Notes |
|
||
| -------- | ------- | ------- | ------- |
|
||
| `make install` | ✅ | ✅ | Create venv + install deps |
|
||
| `make test` | ✅ | ✅ | Run test suite |
|
||
| `make vendor-macos` | ✅ | ❌ | Requires native macOS ARM64 |
|
||
| `make vendor-linux` | ✅ | ✅ | Uses Docker (any OS) |
|
||
| `make vendor-all` | ✅ | ⚠️ | Needs macOS for both platforms |
|
||
| `make binary` | ✅ | ❌ | Requires `build_binary.sh` |
|
||
| `make binary-linux` | ✅ | ✅ | Uses Docker (any OS) |
|
||
| `make build-image` | ✅ | ✅ | Docker required |
|
||
|
||
### Quick Commands by Platform
|
||
|
||
**macOS:**
|
||
|
||
```bash
|
||
make info # Show platform info
|
||
make vendor-current # Build for current platform only
|
||
make binary-current # Build binary for current platform
|
||
```
|
||
|
||
**Linux:***
|
||
|
||
```bash
|
||
make info # Show platform info
|
||
make vendor-linux # Build Linux wheels
|
||
make binary-linux # Build Linux binary
|
||
```
|
||
|
||
***Cross-platform (requires Docker):***
|
||
|
||
```bash
|
||
make vendor-linux # Works on any OS with Docker
|
||
make binary-linux # Works on any OS with Docker
|
||
```
|
||
|
||
## Quick Test
|
||
|
||
```bash
|
||
# Check platform detection
|
||
make info
|
||
|
||
# Build for your current platform
|
||
make vendor-current
|
||
|
||
# Or just the targets you need
|
||
make install # Works everywhere
|
||
make test # Works everywhere
|
||
```
|
||
|
||
## 📦 Binary Distribution
|
||
|
||
Pre-built standalone binaries are available for convenience (no Python required):
|
||
|
||
### Download Binary
|
||
|
||
```bash
|
||
# macOS ARM64
|
||
curl -LO https://github.com/user/hdwalletpy/releases/download/v1.1.0/pyhdwallet-macos-arm64
|
||
chmod +x pyhdwallet-macos-arm64
|
||
./pyhdwallet-macos-arm64 test
|
||
|
||
# Linux x86_64
|
||
curl -LO https://github.com/user/hdwalletpy/releases/download/v1.1.0/pyhdwallet-linux
|
||
chmod +x pyhdwallet-linux
|
||
./pyhdwallet-linux test
|
||
```
|
||
|
||
---
|
||
## 🆕 What's New in v1.1.0
|
||
|
||
- **BIP85 child mnemonic derivation** via new `gen-child` command
|
||
- Derive 12/15/18/21/24-word child mnemonics from master seed
|
||
- Full interoperability with BIP85-compatible wallets (Coldcard, etc.)
|
||
- Optional master BIP39 passphrase support
|
||
- Verified against official BIP85 test vectors
|
||
- No new dependencies required (uses existing bip-utils + stdlib)
|
||
|
||
---
|