kccleoc/pyhdwallet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update for multi-platform vendor support (v1.1.0)

Browse Source 
- Update README.md with 6 vendor directories (macOS/Linux x86/ARM + dev)
- Update playbook.md with complete air-gapped workflow
- Document auto-detection in install_offline.sh
- Add dev mode documentation (--dev flag)
- Add platform-specific checksum verification commands
- Add operational security checklist
- Add vendor architecture diagram
- Document macOS native vs Docker build requirements

Complete support for:
- macOS ARM64 (Apple Silicon)
- Linux x86_64 (Intel/AMD)
- Linux aarch64 (ARM64/Raspberry Pi/Mac containers)
This commit is contained in:
LC mac
2026-01-12 18:22:57 +08:00
parent fb01a84ea6
commit 4933168ae4
2 changed files with 370 additions and 754 deletions
Download Patch File Download Diff File Expand all files Collapse all files

277
README.md
View File

@@ -1,8 +1,6 @@
# 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.
---
**Deterministic BIP32/BIP39/BIP44 HD wallet generator** for Bitcoin, Ethereum, and other cryptocurrencies. Designed for **air-gapped, offline use** with multi-platform support.
## 📦 Installation
@@ -10,82 +8,79 @@ A Python command-line tool for generating and recovering BIP39 HD wallets with s
```bash
# Clone repository
git clone https://github.com/<your-username>/hdwalletpy.git
git clone https://github.com/yourusername/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.
The project includes **pre-built vendored wheels** for offline installation on:
**Supported platforms:**
- macOS ARM64 (M1/M2/M3/M4) - Python 3.12
- Linux x86_64 (Ubuntu/Tails) - Python 3.12
- **macOS ARM64** (Apple Silicon)
- **Linux x86_64** (Intel/AMD servers)
- **Linux aarch64** (ARM64 servers, Raspberry Pi, Mac containers)
**Steps:**
1. On an online machine, clone and verify:
1. **On internet-connected machine:**
```bash
git clone https://github.com/<your-username>/hdwalletpy.git
git clone https://github.com/yourusername/hdwalletpy.git
cd hdwalletpy
# Verify checksums
cd vendor/linux-x86_64 # or macos-arm64
sha256sum -c SHA256SUMS # Linux
shasum -a 256 -c SHA256SUMS # macOS
# Verify vendor checksums
cd vendor/macos-arm64 && shasum -a 256 -c SHA256SUMS # macOS
cd vendor/linux-x86_64 && sha256sum -c SHA256SUMS # Linux x86
cd vendor/linux-aarch64 && sha256sum -c SHA256SUMS # Linux ARM
```
2. Transfer entire repo to USB drive
3. On air-gapped machine:
2. **Transfer to USB/CD:**
```bash
cd hdwalletpy
# Copy entire repository to USB drive
cp -r hdwalletpy /Volumes/USB/
```
3. **On air-gapped machine:**
```bash
cd /path/to/hdwalletpy
# Ensure Python 3.12 is installed
python3.12 --version
# Run offline installer (auto-detects platform)
./install_offline.sh
# Activate virtual environment
source .venv/bin/activate
# Generate wallet
python src/pyhdwallet.py gen --help
```
4. Generate wallet:
```bash
python src/pyhdwallet.py gen --off-screen --file
```
---
### **Developer Installation (with Docker)**
For development or building wheels for other platforms:
Build wheels and run tests across all platforms:
```bash
# Build Docker image
make build-image
# Build wheels for all platforms
make vendor-all
# Build vendor wheels for all platforms
make vendor-all # Runtime wheels only
make vendor-all-dev # Runtime + dev wheels (pytest)
# Install development environment
make install
make install-dev-offline
# Run tests
make test
```
---
## ✅ Basic Usage
```bash
@@ -93,182 +88,106 @@ make test
python src/pyhdwallet.py gen
# Generate with off-screen mode + encrypted ZIP
python src/pyhdwallet.py gen --off-screen --file
python src/pyhdwallet.py gen --file --zip
# 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
python src/pyhdwallet.py gen --file --zip --pgp recipient@example.com
# Recover wallet from mnemonic
python src/pyhdwallet.py recover --interactive --file
python src/pyhdwallet.py recover
# Fetch PGP public key (requires internet)
python src/pyhdwallet.py fetchkey "https://example.com/key.asc" --out mykey.asc
python src/pyhdwallet.py fetchkey keyserver.ubuntu.com recipient@example.com
# 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.
---
- ✅ **BIP39** 24-word mnemonic generation
- ✅ **BIP32** hierarchical deterministic wallet derivation
- ✅ **BIP44** multi-currency account structure
- ✅ **Air-gapped operation** with vendored dependencies
- ✅ **AES-256 encrypted ZIP** artifacts with password protection
- ✅ **PGP encryption** support for at-rest storage
- ✅ **Deterministic output** for reproducible wallet generation
- ✅ **Multi-platform** offline support (macOS, Linux x86/ARM)
- ✅ **Checksum verification** for vendored wheels
## 🛠️ Makefile Targets
**Vendoring (for air-gapped deployment):**
### **Vendoring (Air-Gapped Deployment)**
```bash
make vendor-macos # Build macOS ARM64 wheels
make vendor-macos-dev # Build macOS dev wheels (pytest)
make vendor-linux # Build Linux x86_64 wheels (Docker)
make vendor-all # Build for both platforms
make vendor-linux-dev # Build Linux x86_64 dev wheels
make vendor-linux-arm # Build Linux ARM64 wheels (Docker)
make vendor-linux-arm-dev # Build Linux ARM64 dev wheels
make vendor-all # Build runtime wheels for ALL platforms
make vendor-all-dev # Build dev wheels for ALL platforms
make verify-vendor # Test offline installation
```
**Development:**
### **Binary Distribution**
```bash
make binary # Build standalone binary for current platform
make binary-linux # Build Linux binary via Docker
make binary-all # Build binaries for all platforms
```
### **Development Workflow**
```bash
make install # Create venv and install dependencies
make install-offline # Install from vendor/ (offline)
make install-dev-offline # Install dev dependencies (offline)
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
make clean # Remove venv, cache, vendor/
make clean-vendor # Remove vendor/ only
```
---
### **Release Management**
```bash
make release # Build complete release package
make release-test # Test release binaries
make clean-release # Remove release artifacts
```
## 📖 Full Documentation
- **[playbook.md](playbook.md)** - Complete command reference and operational guide
- **[tests/](tests/)** - Regression test suite documentation
See [playbook.md](./playbook.md) for:
---
- Detailed air-gapped security setup
- Multi-platform installation guide
- PGP key management
- Operational security checklist
- Troubleshooting guide
- Testing and development workflows
## 🔒 Recommended Air-Gapped Setup
For maximum security when generating production wallets:
1. **Build/verify on trusted internet machine**
2. **Transfer via USB/CD** to air-gapped machine
3. **Verify checksums** before installation
4. **Generate wallet offline** with PGP encryption
5. **Store encrypted artifacts** on separate media
6. **Test recovery process** before real use
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
**Threat model:** Protects against network-based attacks, remote exploitation, and keyloggers. Physical security and operational discipline required.
See [playbook.md](playbook.md) for detailed air-gapped procedures.
## 📝 License
## 🖥️ Platform Compatibility
MIT License - See [LICENSE](./LICENSE) for details.
### Makefile Targets
## 🙏 Credits
| 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 |
Built with:
### 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)
---
- [bip-utils](https://github.com/ebellocchia/bip_utils) - BIP32/39/44 implementation
- [PyInstaller](https://www.pyinstaller.org/) - Binary packaging
- Python 3.12 and cryptography libraries

835
playbook.md
View File

File diff suppressed because it is too large Load Diff