pyhdwallet – Secure HD Wallet Tool

A Python command-line tool for generating and recovering BIP39 HD wallets with support for Ethereum, Solana, and Bitcoin. Designed for offline operation with optional PGP encryption and AES-encrypted ZIP artifacts.

---

📦 Installation

Quick Start (macOS/Linux with Internet)

# 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) - Python 3.12
• Linux x86_64 (Ubuntu/Tails) - Python 3.12

Steps:

1. On an online machine, clone and verify:

   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:

   cd hdwalletpy
   ./install_offline.sh
   

4. Generate wallet:

   python src/pyhdwallet.py gen --off-screen --file
   

---

Developer Installation (with Docker)

For development or building wheels for other platforms:

# 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

# 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

# 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
• 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

---

🛠️ Makefile Targets

Vendoring (for air-gapped deployment):

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:

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 - Complete command reference and operational guide
• 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 for detailed air-gapped procedures.