152 lines
3.9 KiB
Markdown
152 lines
3.9 KiB
Markdown
# hdwalletpy – Setup & Usage Guide
|
||
|
||
This project provides a Python-based HD Wallet tool with optional Docker-based build automation for fast, reproducible environments.
|
||
|
||
---
|
||
|
||
## 📦 Installation Options
|
||
|
||
### **Option 1: Standard Python Setup (Host Machine)**
|
||
|
||
1. Clone the repository:
|
||
|
||
```bash
|
||
git clone https://github.com/<your-username>/hdwalletpy.git
|
||
cd hdwalletpy
|
||
```
|
||
|
||
2. Create a virtual environment:
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
3. Install dependencies:
|
||
|
||
```bash
|
||
python -m pip install --upgrade pip
|
||
python -m pip install -r requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
### **Option 2: Fast Setup Using Docker + Makefile**
|
||
|
||
This method avoids installing compilers on your host and speeds up dependency builds.
|
||
|
||
#### **Step 1: Build Docker Image**
|
||
|
||
```bash
|
||
make build-image
|
||
```
|
||
|
||
Creates a reusable image `python-build-env:3.11` with build tools and `python3-venv`.
|
||
|
||
#### **Step 2: Compile Wheels in Container**
|
||
|
||
```bash
|
||
make wheels
|
||
```
|
||
|
||
Builds all dependency wheels into `./wheelhouse` for fast installs.
|
||
|
||
#### **Step 3: Create Host Virtual Environment**
|
||
|
||
```bash
|
||
make venv-host
|
||
source .venv_host/bin/activate
|
||
```
|
||
|
||
Installs dependencies from `wheelhouse` (no compilation needed).
|
||
|
||
#### **Optional: Work Inside a Warm Container**
|
||
|
||
```bash
|
||
make up # Start container
|
||
make shell # Open shell inside container
|
||
make venv-container # Create container-only venv at /opt/venv
|
||
```
|
||
|
||
#### **Cleanup**
|
||
|
||
```bash
|
||
make clean # Remove host venv and wheelhouse
|
||
make down # Stop/remove container
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ Basic Usage
|
||
|
||
Run the tool with subcommands. For help, use `-h` (e.g., `gen -h`, `recover -h`).
|
||
|
||
Examples:
|
||
|
||
```bash
|
||
# Generate mnemonic (prints to stdout; for debug/test)
|
||
python ./src/pyhdwallet.py gen
|
||
|
||
# Generate and save AES-encrypted ZIP artifact into ./.wallet (password prompted)
|
||
python ./src/pyhdwallet.py gen --file
|
||
|
||
# Generate with PGP encryption + ZIP artifact (ZIP contains only encrypted .asc payload)
|
||
python ./src/pyhdwallet.py gen --pgp-pubkey-file pubkeys/mykey.asc --file
|
||
|
||
# Recover from mnemonic (prefer --interactive to avoid shell history)
|
||
python ./src/pyhdwallet.py recover --interactive
|
||
|
||
# Recover and save AES ZIP artifact
|
||
python ./src/pyhdwallet.py recover --interactive --file
|
||
|
||
# Fetch PGP public key (online)
|
||
python ./src/pyhdwallet.py fetchkey "https://example.com/key.asc" --out mykey.asc
|
||
|
||
# Run tests
|
||
python ./src/pyhdwallet.py test
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 Notes on `--file`, AES ZIP, and PGP
|
||
|
||
- `--file` writes **only** an AES-encrypted ZIP (no raw `.json`/`.asc` left on disk), using `pyzipper`.
|
||
- If `--pgp-pubkey-file` is set, the ZIP contains a single ASCII-armored PGP message (`.asc`) created with PGPy-style `PGPMessage.new(...)` then `pubkey.encrypt(...)`.
|
||
|
||
---
|
||
|
||
## ⚠️ About `--force`
|
||
|
||
The tool includes a safety guard: if stdout is piped/redirected (non-TTY), it refuses to print sensitive output unless `--force` is set. Checking whether stdout is a terminal is commonly done via `isatty()`.
|
||
|
||
Example:
|
||
|
||
```bash
|
||
python ./src/pyhdwallet.py gen > out.txt # likely refused (non-TTY)
|
||
python ./src/pyhdwallet.py gen --force > out.txt # allowed
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ Why Use Makefile?
|
||
|
||
- **Speed:** Avoid repeated `apt-get` installs; wheels cached locally.
|
||
- **Reproducibility:** Same Docker image for builds; no environment drift.
|
||
- **Convenience:** One-liner tasks (`make wheels`, `make venv-host`, `make shell`).
|
||
- **Separation:** Host venv vs container venv for clean workflows.
|
||
|
||
---
|
||
|
||
## Common Makefile Targets
|
||
|
||
```bash
|
||
make build-image # Build Docker image with build tools
|
||
make wheels # Compile wheels into ./wheelhouse
|
||
make venv-host # Host venv install from wheelhouse
|
||
make up # Start warm container
|
||
make shell # Shell into warm container
|
||
make venv-container # Container venv at /opt/venv
|
||
make down # Stop/remove container
|
||
make clean # Remove .venv_host and wheelhouse
|
||
```
|