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

---