pyhdwallet/playbook.md

pyhdwallet v1.0.3

A command-line tool for generating and recovering HD wallets (BIP39) with support for Ethereum, Solana, and Bitcoin. Features offline operation, PGP encryption, and multi-chain address derivation.

Note: This tool requires a subcommand (e.g., gen, recover). Running without one displays help. Use <subcommand> -h for detailed options.

Table of Contents

• Features
• Installation
• Quick Start
• Commands
  • fetchkey
  • gen
  • recover
  • test
• Examples
• Security
• Troubleshooting
• Changelog

Features

• Offline-first: Generate and recover wallets without internet access.
• Multi-chain support: Derive addresses for Ethereum, Solana, and Bitcoin.
• PGP encryption: Securely encrypt sensitive data (mnemonics, private keys) to PGP public keys.
• Flexible input: Accept BIP39 mnemonics or hex seeds.
• BIP39 passphrase support: Optional passphrase for additional security.
• Private key export: Export derived private keys in encrypted payloads.
• Solana profiles: Multiple derivation paths for Solana compatibility.
• Self-testing: Built-in tests to verify functionality.
• Secure mode: Optional paranoid mode with memory zeroing, temp files, and no output printing for high-security use.

Installation

Prerequisites

• Python 3.11 or higher
• Virtual environment (recommended)

Setup

1. Clone or download the repository.

2. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

Dependencies

• bip-utils: BIP39 and derivation logic
• PGPy: PGP encryption
• PyNaCl & base58: Solana private key handling (optional for Solana private key export)

Quick Start

1. Generate a new wallet:

   python ./src/pyhdwallet.py gen --chains ethereum solana --addresses 3
   

2. Recover from a mnemonic:

   python ./src/pyhdwallet.py recover --mnemonic "abandon abandon ... about" --chains bitcoin
   

3. Fetch a PGP key:

   python ./src/pyhdwallet.py fetchkey "https://example.com/key.asc" --out mykey.asc
   

4. Use secure mode for high-security operations:

   python ./src/pyhdwallet.py gen --secure-mode --pgp-pubkey-file key.asc --chains ethereum --addresses 1
   

5. Run tests:

   python ./src/pyhdwallet.py test
   

Commands

fetchkey

Download and verify a PGP public key from a URL.

Usage:

python ./src/pyhdwallet.py fetchkey <url> [--out FILE] [--timeout SECONDS]

Options:

• url: URL to the ASCII-armored PGP key
• --out FILE: Save the key to a file
• --timeout SECONDS: Request timeout (default: 15)
• --secure-mode: Enable secure mode (temp files, no extra output)

Example:

python ./src/pyhdwallet.py fetchkey "https://keys.openpgp.org/pks/lookup?op=get&search=user@example.com" --out key.asc

gen

Generate a new BIP39 mnemonic and derive addresses.

Usage:

python ./src/pyhdwallet.py gen [options]

Options:

• --words {12,15,18,21,24}: Number of mnemonic words (default: 12)
• --dice-rolls "1 2 3 ...": Space-separated dice rolls for entropy
• --passphrase PASSPHRASE: BIP39 passphrase
• --passphrase-hint HINT: Hint for the passphrase
• --chains {ethereum,solana,bitcoin}: Chains to derive (default: all)
• --addresses N: Number of addresses per chain (default: 5)
• --sol-profile {phantom_bip44change,phantom_bip44,phantom_deprecated,solana_bip39_first32}: Solana derivation profile
• --output {text,json}: Output format (default: text)
• --file FILE: Save output to file
• --pgp-pubkey-file FILE: Encrypt payload to PGP key
• --pgp-ignore-usage-flags: Ignore PGP key usage flags
• --export-private: Include private keys in encrypted payload
• --include-source: Include mnemonic in encrypted payload
• --unsafe-print: Print mnemonic even when encrypting
• --secure-mode: Enable secure mode (no printing, temp files, memory zeroing)

Examples:

# Basic generation
python ./src/pyhdwallet.py gen

# With secure mode
python ./src/pyhdwallet.py gen --secure-mode --pgp-pubkey-file key.asc

# With passphrase and encryption
python ./src/pyhdwallet.py gen --passphrase "mysecret" --pgp-pubkey-file key.asc --export-private

# JSON output to file
python ./src/pyhdwallet.py gen --chains ethereum --addresses 10 --output json --file wallet.json

recover

Derive addresses from an existing mnemonic or seed.

Usage:

python ./src/pyhdwallet.py recover [options]

Options: Same as gen, plus:

• --mnemonic MNEMONIC: BIP39 mnemonic phrase
• --seed HEX_SEED: 128-character hex seed
• --interactive: Prompt for mnemonic/seed interactively
• --secure-mode: Enable secure mode (no printing, temp files, memory zeroing)

Examples:

# From mnemonic
python ./src/pyhdwallet.py recover --mnemonic "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about" --chains ethereum solana

# Interactive input
python ./src/pyhdwallet.py recover --interactive --chains bitcoin

# From seed
python ./src/pyhdwallet.py recover --seed "0123456789abcdef..." --chains solana

test

Run minimal self-tests to verify functionality.

Usage:

python ./src/pyhdwallet.py test [--secure-mode]

Options:

• --secure-mode: Enable secure mode (no extra output)

Output: Success/failure messages for derivation tests.

Examples

1. Generate and Encrypt a New Wallet

# Generate with encryption
python ./src/pyhdwallet.py gen --pgp-pubkey-file key.asc --include-source --export-private --chains ethereum solana --addresses 5

# Decrypt the output later with GPG
echo "-----BEGIN PGP MESSAGE-----..." | gpg -d

2. Recover from Mnemonic with Passphrase

python ./src/pyhdwallet.py recover --mnemonic "word1 word2 ... word12" --passphrase "mypass" --chains ethereum --addresses 10 --output json

3. Fetch and Use PGP Key

# Fetch key
python ./src/pyhdwallet.py fetchkey "https://example.com/pubkey.asc" --out mykey.asc

# Use in recovery
python ./src/pyhdwallet.py recover --interactive --pgp-pubkey-file mykey.asc --export-private

4. High-Security Operations with Secure Mode

# Generate without printing sensitive data
python ./src/pyhdwallet.py gen --secure-mode --pgp-pubkey-file key.asc --chains ethereum --addresses 1

# Recover in secure mode
python ./src/pyhdwallet.py recover --secure-mode --interactive --pgp-pubkey-file key.asc --export-private

5. Solana-Specific Derivation

python ./src/pyhdwallet.py gen --chains solana --sol-profile phantom_bip44change --addresses 3

Security

• Offline operation: gen, recover, and test commands block network access.
• No plaintext secrets: Mnemonics and private keys are never printed unless encrypted or --unsafe-print is used.
• PGP encryption: Use for secure storage of sensitive data.
• Secure mode: Use --secure-mode for paranoid operations—suppresses output, uses temp files with auto-deletion, and zeros memory.
• Passphrase handling: Passphrases are not stored; only hints are included.
• Private key export: Only export what's needed; treat encrypted payloads as sensitive.
• File permissions: Output files are set to owner-only (0o600) for security.
• Memory zeroing: In secure mode, sensitive variables are cleared after use.
• Best practices:
  • Use --interactive to avoid command-line history exposure.
  • Use --secure-mode for high-risk operations.
  • Verify PGP fingerprints out-of-band.
  • Run on trusted, offline machines.

Troubleshooting

• Missing dependencies: Run pip install -r requirements.txt
• Network errors in offline modes: Ensure no internet access; the tool blocks it.
• Invalid mnemonic: Check word count and spelling.
• PGP decryption fails: Ensure you have the correct private key.
• Secure mode issues: Ensure temp files are deleted; check permissions on output files.
• Version check: Run python ./src/pyhdwallet.py --version

Changelog

• v1.0.3: Changed default behavior to always show help without subcommand; added README.md; updated documentation.
• v1.0.2: Security patches - added --secure-mode, memory zeroing, file permission fixes, auto-deletion in secure mode, sanitized errors.
• v1.0.1: Renamed to pyhdwallet, added --version flag, updated documentation, excluded _toDelete in .gitignore.
• v1.0.0: Initial release with gen, recover, fetchkey, and test commands.