BitBox01 Password Recovery — V4 (GPU Accelerated)

GPU-accelerated password recovery tool for BitBox01 (Digital Bitbox) hardware wallets. Uses a hybrid GPU/CPU pipeline: NVIDIA CUDA handles heavy PBKDF2 cryptography while CPU workers handle BIP32/49 address derivation.

Built for recovering access to a BitBox01 wallet when you've forgotten the device password but still have the backup SD card files.

Overview

The BitBox01 protects your Bitcoin with a password transformed through multiple cryptographic rounds before producing the wallet's master seed. To recover a forgotten password:

Generate password candidates using LLM + mutations
Derive the seed using the exact cryptographic chain the BitBox01 firmware uses
Generate Bitcoin addresses from that seed
Compare those addresses against your known target address

If any derived address matches your target, the password is correct and access is recovered.

The tool implements three generation modes:

Mutations Only: Fast deterministic variants (case changes, numbers, symbols, dates)
AI + Mutations: LLM brainstorming combined with mutations
Hashcat Engine: Industry-standard password candidate generation using hashcat rules, masks, and combinators

And two compute modes:

GPU: CUDA-accelerated PBKDF2 (91% of compute time), fallback to CPU for BIP derivation
CPU: Pure Python with multiprocessing

Architecture

Hybrid GPU→CPU Pipeline

┌─────────────────────────────────────────────────────────────────────┐
│                    PHASE 1: GENERATE CANDIDATES                     │
│                    (generator.py)                                    │
├─────────────────────────────────────────────────────────────────────┤
│  LLM Brainstorming (local llama.cpp OR OpenRouter with fallback)   │
│    └─► 500 plausible passwords/round                              │
│  Deterministic Mutations (case, leet, numbers, symbols, dates)    │
│    └─► Tier1 (base) → Tier2 (mutations) → Tier3 (combinator)     │
└─────────────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   PHASE 2: CRACK (GPU→CPU)                          │
├─────────────────────────────────────────────────────────────────────┤
│ GPU (CUDA Kernel, ~91% of time per password):                       │
│   Step 1: PBKDF2-SHA512(pwd, "Digital Bitbox", 20480)   → 64 bytes │
│   Step 2: Hex-encode stretched key → 128-char ASCII                │
│   Step 3: PBKDF2-SHA512(backup_hex, "mnemonic"+stretched, 2048)   │
│           → 64-byte seed                                            │
│                                                                      │
│ CPU Workers (BIP32/49 derivation, ~9% of time):                    │
│   Step 4: BIP32 master key from seed (HMAC-SHA512)                 │
│   Step 5: BIP49 address derivation (10 accounts × 2 chains × 20)  │
│           = 400 addresses/password                                  │
│           Compare against target address                            │
└─────────────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   NOTIFICATIONS & LOGGING                           │
│  ✓ Telegram + Webhook + Dashboard                                  │
│  ✓ SQLite derivation logging (WAL mode)                            │
│  ✓ Append-only feed log (one entry per password)                   │
└─────────────────────────────────────────────────────────────────────┘

Compute Time Breakdown (per password)

Step	Operation	Iterations	Share
1	PBKDF2-SHA512 (app-level)	20,480 × HMAC	~83%
3	PBKDF2-SHA512 (device-level)	2,048 × HMAC	~8%
4+5	BIP32/49 EC derivation	400 × secp256k1	~9%

Why GPU+CPU?

Steps 1 & 3 are pure SHA-512 hash grinding → perfect for GPU parallelism
Steps 4 & 5 use secp256k1 elliptic curves → better on CPU with bip_utils library
GPU computes seeds for a batch, hands them to CPU worker pool for address derivation

Cryptographic Chain

This is the exact PBKDF2 derivation chain used by BitBox01 firmware (verified against github.com/digitalbitbox/mcu).

Step 1 — App-level key stretching:

PBKDF2-SHA512(
    password    = user_password (raw UTF-8 bytes),
    salt        = "Digital Bitbox" (14 bytes, ASCII),
    iterations  = 20,480,
    dklen       = 64 bytes
) → stretched_key (64 bytes)

Step 2 — Hex encoding:

stretched_hex = hex_encode(stretched_key)
→ 128-character lowercase ASCII hex string

Step 3 — Device-level seed derivation:

PBKDF2-SHA512(
    password    = backup_hex (64-char hex from SD card, as raw ASCII bytes),
    salt        = "mnemonic" + stretched_hex (136 bytes raw ASCII),
    iterations  = 2,048,
    dklen       = 64 bytes
) → master_seed (64 bytes)

Critical detail: Firmware treats all strings as raw UTF-8/ASCII bytes. The backup hex and stretched hex are NOT decoded—they're used as literal ASCII character strings.

Step 4 — BIP32 master key:

HMAC-SHA512(key="Bitcoin seed", data=master_seed) → (private_key, chain_code)

Step 5 — BIP49 address derivation (P2SH-SegWit):

Derivation path: m/49'/0'/account'/chain/index
  account: 0 through 9
  chain: 0 (external/receiving) and 1 (internal/change)
  index: 0 through 19 (gap limit)
Each step uses secp256k1 elliptic curve child key derivation.
Final address: Base58Check-encoded P2SH wrapping a P2WPKH witness script.

Quick Start

Prerequisites

Python 3.10+
NVIDIA GPU with CUDA support (RTX 30/40 series, RTX 6000 Ada, or newer)
NVIDIA CUDA Toolkit (provides nvcc compiler)
MSVC C++ compiler (Windows) or GCC (Linux)
pip install -r requirements.txt

1. Build the CUDA Kernel

Find your GPU's SM version and compile:

GPU	SM flag
RTX 3060/3070/3080/3090	`sm_86`
RTX 4060/4070/4080/4090	`sm_89`
RTX 6000 Ada	`sm_89`
RTX 2070/2080	`sm_75`
GTX 1060/1070/1080	`sm_61`

Windows:

# Add CUDA and MSVC to PATH
$env:PATH += ";C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.2\bin"
$env:PATH += ";C:\Program Files\Microsoft Visual Studio\18\Community\VC\Tools\MSVC\14.44.35207\bin\Hostx64\x64"

# Build for RTX 3070 (sm_86)
cd cuda
nvcc -O3 --shared -arch=sm_86 -o pbkdf2_gpu.dll pbkdf2_gpu.cu
copy pbkdf2_gpu.dll ..
cd ..

Linux:

cd cuda
chmod +x build.sh && ./build.sh
cp libpbkdf2_gpu.so ..
cd ..

2. Verify GPU Kernel

python verify_gpu.py              # Quick: 10 passwords, ~15 seconds
python verify_gpu.py --thorough   # Full: 500 passwords, ~2 minutes

Expected output: ALL SEEDS MATCH with speedup factor (typically 20–100x).

3. Configure

copy config.json.template config.json
# Edit config.json with target address, backups, LLM settings, etc.

4. Generate Password Candidates

# Create input files first:
# - profile.txt or passwords.csv (base words)
# - personal_info.txt (dates, names, pets, etc.)

# Mutations only (instant)
python generator.py --mutate

# LLM + mutations (needs LLM endpoint)
python generator.py --llm --mutate --rounds 5

# Continuous live mode (mutations first, then LLM rounds in loop)
python generator.py --live --prompt-mode direct

# Hashcat rules-based generation (requires hashcat, see below)
python generator.py --hashcat --hashcat-mode rules

# Hashcat mask attack (e.g., word + 4 digits)
python generator.py --hashcat --hashcat-mode mask --hashcat-mask "driska?d?d?d?d"

5. Run

Web Dashboard (Recommended):

python server.py

Opens at http://localhost:3010 (accessible from network via http://YOUR-PC-IP:3010)

Command Line:

python cracker.py --mode gpu           # Force GPU
python cracker.py --mode cpu           # CPU only
python cracker.py --mode auto          # GPU if available, else CPU (default)
python cracker.py --benchmark          # Speed comparison
python cracker.py --verify             # Verify GPU output matches CPU

Configuration

All settings in config.json. See config.json.template for a complete example.

Target and Backups

Field	Description
`target_address`	Bitcoin address to recover (e.g., `37aCw...`). Cracker derives and compares.
`backups`	Array of hex strings from BitBox01 backup SD card. Paste raw content (NOT file paths).
`backup_files`	(Optional) File names for reference in notifications and logs.

Derivation Settings

Field	Default	Description
`derivation_standards`	`["BIP49"]`	Bitcoin address standards. BIP49 = P2SH-SegWit ("3..."), BIP44 = Legacy ("1..."), BIP84 = Native SegWit ("bc1...")
`accounts`	`[0–9]`	BIP49 account indices to check. 0 is default.
`address_gap_limit`	`20`	Sequential unused addresses to check per chain. BIP standard is 20.

Compute Settings

Field	Default	Description
`compute_mode`	`"auto"`	`"gpu"` = force, `"cpu"` = CPU only, `"auto"` = GPU→CPU
`gpu_device_id`	`0`	GPU device ID (0 = first GPU).
`gpu_batch_size`	`512`	Passwords per GPU kernel call. Increase to 1024 for high-end GPUs, decrease to 256 for OOM errors.
`num_workers`	`4`	CPU worker processes for BIP derivation. Set to your CPU core count. More workers = more RAM (~50MB each).

Password Generation Settings

Field	Default	Description
`candidate_dir`	`"candidates"`	Directory for generated password candidate files.
`state_dir`	`"state"`	Runtime state (checkpoints, feed log, status). Delete `checkpoint.json` to restart.
`tiers`	(none)	Array of tier definitions. Each tier has `name` and `file`. Processed in order (most likely first).
`password_length_min`	`5`	Minimum password length.
`password_length_max`	`17`	Maximum password length.

Web Server

Field	Default	Description
`server.host`	`"0.0.0.0"`	`"0.0.0.0"` = network accessible, `"127.0.0.1"` = localhost only.
`server.port`	`3010`	Web dashboard port.

Notifications

Field	Description
`notifications.telegram.enabled`	`true`/`false`
`notifications.telegram.bot_token`	Get from @BotFather on Telegram.
`notifications.telegram.chat_id`	Get from @userinfobot on Telegram.
`notifications.webhook.enabled`	`true`/`false`
`notifications.webhook.url`	Webhook endpoint URL.

LLM Settings

Supports multi-backend fallback chain with local llama.cpp AND OpenRouter.

{
  "llm": {
    "backends": [
      {
        "type": "llamacpp",
        "endpoint": "http://localhost:8081/v1/chat/completions",
        "model": "qwen"
      },
      {
        "type": "openrouter",
        "endpoint": "https://openrouter.ai/api/v1/chat/completions",
        "model": "mistralai/mistral-small",
        "api_key": "YOUR_KEY"
      }
    ],
    "temperature": 0.85,
    "max_tokens": 2000
  }
}

Field	Description
`llm.backends`	Array of LLM backends to try in order. First successful one is used.
`llm.temperature`	LLM creativity (0.0–2.0). 0.85 is balanced.
`llm.max_tokens`	Max tokens per LLM response (default 2000).

Hashcat Settings

Field	Default	Description
`hashcat.path`	`"hashcat"`	Path to hashcat binary. Use relative path for portable installs (e.g., `hashcat-6.2.6/hashcat.exe`).
`hashcat.default_rules`	`["best64.rule"]`	Rule files used when no specific rules are selected.

Hashcat Integration

Hashcat is used in --stdout mode only (no hashing, CPU-only) to generate password candidates. The GPU stays free for the cracker. Output files are fully compatible with the cracker pipeline.

Setup

Download hashcat from hashcat.net
Extract to hashcat-6.2.6/ inside the project folder (or anywhere, and set the path in config)
Verify: hashcat-6.2.6/hashcat.exe --version

Attack Modes

Mode	CLI	Description
Rules	`--hashcat-mode rules`	Apply rule files (best64, dive, etc.) to input words. Best general-purpose mode.
Mask	`--hashcat-mode mask --hashcat-mask "?u?l?l?l?d?d?d"`	Brute-force with character classes. Good for known patterns.
Combinator	`--hashcat-mode combinator`	Combine roots with suffixes (root+suffix pairs).
Hybrid	`--hashcat-mode hybrid --hashcat-mask "?d?d?d"`	Wordlist + appended mask (e.g., word + 3 digits).

Mask Character Classes

Class	Characters
`?l`	a-z
`?u`	A-Z
`?d`	0-9
`?s`	Special characters
`?a`	All printable

CLI Examples

# Rules: apply best64.rule to profile words
python generator.py --hashcat --hashcat-mode rules

# Rules: multiple rule files
python generator.py --hashcat --hashcat-mode rules --hashcat-rules best64.rule dive.rule

# Mask: exactly "Driska" + 5 digits
python generator.py --hashcat --hashcat-mode mask --hashcat-mask "Driska?d?d?d?d?d"

# Hybrid: all profile words + 3 digits appended
python generator.py --hashcat --hashcat-mode hybrid --hashcat-mask "?d?d?d"

# Combinator: roots x suffixes from profile
python generator.py --hashcat --hashcat-mode combinator

# Limit output to 50K candidates
python generator.py --hashcat --hashcat-mode rules --hashcat-limit 50000

All modes are also available from the web dashboard under "Hashcat Engine".

Password Generation Pipeline

LLM Brainstorming

The generator sends your personal information to an LLM to generate plausible passwords you might have used. Each round takes a different "angle":

Round 1: Word+number combinations, brands with PINs, personal dates
Round 2: Keyboard patterns, shifted characters, leetspeak
Round 3: Phonetic misspellings, reversed words, concatenations
Round 4: Cultural references 2017–2019, crypto/tech slang, gaming
Round 5+: Dynamic angles (music, sports, mythology, science, etc.)

Supports any OpenAI-compatible API (Ollama, vLLM, LM Studio, text-generation-webui, OpenRouter) with fallback chain.

Prompt Modes

Mode	Description
`direct`	"You are helping recover a forgotten password. Generate plausible candidates..." (direct password recovery framing)
`abstract`	"Generate creative passwords..." (abstracted framing to bypass LLM safety filters)

Deterministic Mutation Engine

Systematically generates variants from base words:

Case variations: dragon → Dragon, DRAGON, dRaGoN
Leetspeak: dragon → dr@g0n, drag0n, dr4g0n
Number suffixes: Dragon + 1, 123, 2018, 69, 007, all 3-digit combos
Symbol suffixes: Dragon + !, !!, #, @, !@#
Date suffixes: Auto-parsed from personal_info.txt in multiple formats
Separators: Dragon_123, Dragon.2018, Dragon-1
Two-word combos: DragonPhoenix, Dragon_Fire, Dragon123Phoenix
Reversed: gnusmaz
Keyboard patterns: qwerty123, 1q2w3e, asdfgh

Generation Modes

Mode	Command	Description
Mutations Only	`--mutate`	Fast deterministic variants (instant).
AI + Mutations	`--llm --mutate --rounds 5`	LLM brainstorming + mutations.
Continuous/Live	`--live`	Mutations first, then LLM rounds in a loop (for long-running recovery).
Hashcat	`--hashcat --hashcat-mode rules`	Hashcat-powered candidate generation (rules, mask, combinator, hybrid).

Tier System

Generated passwords sorted by likelihood:

Tier 1 (tier1_base.txt): Base words, case variations, reversed — tried first.
Tier 2 (tier2_mutations.txt): Leet, numbers, symbols, date combos — larger set.
Tier 3 (tier3_expanded.txt): Two-word combos — exponentially larger, less likely.

The cracker processes tiers in order, so most probable passwords are tested first.

Cracking Pipeline

GPU Mode (Default)

Load password batch (up to gpu_batch_size)
  ↓
GPU CUDA Kernel (parallel):
  For each (password, backup) pair:
    - PBKDF2-SHA512 app-level (20480 rounds) → stretched_key
    - Hex-encode → stretched_hex (128 chars)
    - PBKDF2-SHA512 device-level (2048 rounds) → seed
  ↓
Return array of (password, seed[]) to CPU
  ↓
CPU Worker Pool:
  For each password + seed:
    - BIP49 master key derivation (HMAC-SHA512)
    - For accounts 0–9, chains 0–1, indices 0–19:
      - Derive secp256k1 public key
      - Encode as P2SH-SegWit address
      - Compare against target address
      - Log derivation to SQLite (WAL mode)
  ↓
Deduplication + Feed logging
  ↓
Checkpoint save (for resume capability)

CPU Mode

Same flow but all PBKDF2 on CPU (no GPU):

CPU Worker Pool:
  For each password:
    - App-level PBKDF2 (20480 rounds)
    - Hex-encode
    - Device-level PBKDF2 (2048 rounds)
    - BIP49 derivation + address check

Found Password Flow

When a password matches:

Display: "FOUND" overlay on dashboard with audio alert
Log: state/found.json with password, address, seed, derivation path
Notify: Telegram + webhook (if enabled)
Stop: Cracker halts

Dashboard

Real-time web interface at http://localhost:3010 (dark terminal theme).

Status Display

Mode: GPU or CPU badge with color
Speed: Passwords/second over 30-second rolling window
Device: GPU name, compute capability, memory, utilization
Tier Progress: Bar for each tier with % completion
Controls: Start, Pause, Resume, Stop buttons

LLM Monitoring

Polls 4 endpoints following the CSM Monitor pattern:

Endpoint	Purpose
`/health`	Basic server status + slot counts
`/slots`	Per-slot status, model name, generation progress (n_decoded/n_predict)
`/metrics`	Prometheus format: speed gauges + cumulative token counters
`/v1/models`	Model name fallback

Displays:

Model: Currently loaded model
Status: Idle, Generating, or Offline
Speed: Tokens/sec (generation + prompt processing)
Progress: Current token count vs. max tokens
Slots: Busy/Total parallel request slots

Feed & Derivation Logging

Append-only feed log (state/feed.log): One JSON line per password, shows attempts in real-time
SQLite derivation DB (state/derivations.db, WAL mode): All derived addresses per password for forensic analysis

Notifications

Telegram: On start, stop, pause, resume, found password
Webhook: POST JSON payload with password found details
Dashboard: Side-panel notification system

API Endpoints

Web server (Flask + Flask-SocketIO) provides:

REST Endpoints

Endpoint	Method	Description
`/health`	GET	Server status, cracker/generator state
`/config`	GET	Current configuration (no secrets)
`/status`	GET	Speed, passwords checked, tier progress
`/feed`	GET	Last N password attempts (tail)
`/derivations/<password>`	GET	All derived addresses for a password
`/control/start`	POST	Start cracker (mode: gpu/cpu/auto)
`/control/pause`	POST	Pause cracker
`/control/resume`	POST	Resume cracker
`/control/stop`	POST	Stop cracker
`/generator/start`	POST	Start generator (mode, rounds, prompt_mode)
`/generator/stop`	POST	Stop generator
`/llm/status`	GET	LLM server health + metrics

WebSocket Events (Real-Time)

Event	Payload
`status_update`	Speed, checked count, tier progress
`feed_entry`	New password attempt (timestamp, password, addresses)
`found`	Password found! (password, address, derivation path, seed)
`llm_update`	LLM server status (model, speed, tokens, progress)
`notification`	Desktop notification (title, message, severity)

GPU Setup

Supported GPUs

Any NVIDIA GPU with CUDA Compute Capability 5.0+ (2014 onward):

GPU Series	Architecture	Compute	SM Flag
GTX 900	Maxwell	5.x	`sm_50`
GTX 1000	Pascal	6.x	`sm_61`
GTX 1600	Turing	7.5	`sm_75`
RTX 2000	Turing	7.5	`sm_75`
RTX 3000	Ampere	8.6	`sm_86`
RTX 4000	Ada Lovelace	8.9	`sm_89`
RTX 6000 Ada	Ada Lovelace	8.9	`sm_89`
RTX 5000	Blackwell	10.0	`sm_100`

VRAM Usage

Minimal: ~2.5 MB per 1024-password batch. Even a 2 GB GPU works fine. This workload is compute-bound, not memory-bound.

Performance Reference

GPU	Speed	Speedup vs CPU
RTX 3070 (8GB)	~670 PBKDF2/s, ~37 end-to-end pwd/s	25x (PBKDF2), 4x (end-to-end)

End-to-end speed limited by CPU BIP49 derivation (400 addresses/password). Increase num_workers to match CPU core count for better throughput.

Troubleshooting GPU

Problem	Solution
`nvcc not found`	Add CUDA Toolkit to PATH: `$env:PATH += ";C:\CUDA\v13.2\bin"`
`cl.exe not found`	Find MSVC path: `Get-ChildItem "C:\Program Files\Microsoft Visual Studio" -Recurse -Filter "cl.exe"`
`Unsupported gpu architecture`	Build for your specific GPU: `nvcc -O3 --shared -arch=sm_86 -o pbkdf2_gpu.dll pbkdf2_gpu.cu`
`No CUDA-capable GPU detected`	Update GPU driver or install older CUDA Toolkit matching your driver. Check `nvidia-smi` vs `nvcc --version`.
`Out of memory`	Reduce `gpu_batch_size` from 512 to 256 in config.
`Low end-to-end speed`	CPU is bottleneck. Increase `num_workers` to match CPU core count.

Files

v4/
├── cuda/
│   ├── pbkdf2_gpu.cu           CUDA kernel: SHA-512 + HMAC + PBKDF2 (FIPS 180-4/RFC 2898)
│   ├── pbkdf2_gpu.h            C header with ctypes API
│   ├── build.bat               Windows build script (multi-arch)
│   └── build.sh                Linux build script
├── cracker.py                  Main cracker engine (CPU/GPU hybrid)
├── server.py                   Flask + Flask-SocketIO web dashboard
├── generator.py                LLM brainstorming + mutations + hashcat integration
├── gpu_engine.py               Python ctypes wrapper for CUDA library
├── blockchain.py               Bitcoin address checker (API + Bloom filter modes)
├── verify_gpu.py               GPU vs CPU output verification
├── config.json.template        Configuration template (safe for git)
├── profile.example.txt         Profile template (passwords, roots, patterns)
├── requirements.txt            Python dependencies
├── static/
│   └── dashboard.html          Terminal-style web dashboard (monospace, dark)
├── hashcat-6.2.6/              Hashcat portable (download separately, not in git)
├── candidates/                 Generated password candidate files (runtime)
│   ├── tier1_llm_p1.txt        LLM-generated roots + suffixes
│   ├── tier1_mutations.txt     Programmatic mutations
│   ├── tier_hashcat_*.txt      Hashcat-generated candidates
│   └── tier3_keyboard.txt      Keyboard patterns
└── state/                      Runtime state (auto-created)
    ├── checkpoint.json         Resume point (tier file + line number)
    ├── status.json             Current speed, passwords checked
    ├── feed.log                Append-only password attempt log
    ├── derivations.db          SQLite WAL database of all derived addresses
    └── found.json              Found password details (if successful)

Usage Examples

Example 1: Generate mutations only (instant)

python generator.py --mutate
# Output: candidates/tier1_base.txt, tier2_mutations.txt, tier3_expanded.txt

Example 2: LLM + mutations

# Set up profile.txt with your personal info first
python generator.py --llm --mutate --rounds 5 --prompt-mode abstract
# Runs 5 rounds of LLM, then mutations, outputs to tier files

Example 3: Continuous recovery with live generation

# Start generator in live mode (runs in background)
python generator.py --live --prompt-mode direct

# In another terminal, start cracker with web dashboard
python server.py
# Opens http://localhost:3010

Example 4: GPU-only recovery (force GPU, fail if unavailable)

python cracker.py --mode gpu --config config.json

Example 5: CPU-only (slower but no GPU needed)

python cracker.py --mode cpu --config config.json

Example 6: Benchmark GPU vs CPU speed

python cracker.py --benchmark
# Compares speed on a sample batch

Reset & Recovery

Restart cracking from beginning

del state\checkpoint.json
# Cracker will start from tier1_base.txt, line 0

Clear all state (full reset)

rmdir /s state
# Deletes checkpoint, status, feed log, derivation database, and found.json

Regenerate password candidates

del candidates\*.txt
python generator.py --mutate

Troubleshooting

Problem	Cause	Solution
`All tiers exhausted, 0 passwords`	Missing `tiers` in config.json	Add `tiers` array to config.json (see template)
`Config backups not working`	Expects hex strings, not file paths	Open backup files and paste 64-char hex strings directly into config
`Low end-to-end speed`	CPU BIP49 derivation is bottleneck	Increase `num_workers` to match your CPU core count
Dashboard CONFIG section empty	Server sends config but dashboard didn't read it	Update to latest `dashboard.html`
`[ERROR]` in server logs	Cosmetic — cracker subprocess stderr logged as ERROR	Not a real error. Check actual message — usually INFO.
CUDA Toolkit version mismatch	`nvcc --version` > driver's CUDA version	Update GPU driver OR install older CUDA Toolkit matching driver
`function not found` in DLL	Missing `__declspec(dllexport)` in header	Ensure you have latest `pbkdf2_gpu.h` with `GPU_API` macros
LLM refusal / safety filter	LLM refused to generate passwords	Try `--prompt-mode abstract` or switch to different LLM backend
Out of memory on GPU	`gpu_batch_size` too large	Reduce from 512 to 256 in config
Generator stuck / no candidates	LLM endpoint unreachable	Check LLM server is running (Ollama, vLLM, etc.) or provide OpenRouter API key

Performance Tips

GPU Tuning:
- Increase gpu_batch_size to 1024+ on RTX 40-series / RTX 6000 Ada
- Decrease to 256 if you see OOM errors
CPU Tuning:
- Set num_workers = your CPU core count for maximum BIP derivation throughput
- Each worker uses ~50 MB RAM; scale accordingly
Password Generation:
- Start with --mutate only to quickly generate thousands of candidates
- Add --llm --rounds 3 if mutations aren't finding the password
- Use --live for long-running recovery with continuous AI brainstorming
Two-PC Setup:
- PC1 (dev): Run generator.py --live to brainstorm candidates
- PC2 (RTX 3070): Run server.py to crack with web dashboard
- Share candidates directory between PCs (network mount or rsync)
Multi-GPU (Advanced):
- Modify gpu_device_id in config to select different GPU
- Run multiple cracker.py instances with different device IDs
- Coordinate via shared state directory

License & Attribution

This tool is for password recovery of your own wallets only. Unauthorized access to others' wallets is illegal.

Implements BitBox01 firmware cryptography per github.com/digitalbitbox/mcu.

CUDA kernel follows FIPS 180-4 (SHA-512), RFC 2104 (HMAC), RFC 2898 (PBKDF2).

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
cuda		cuda
static		static
.gitignore		.gitignore
BitBoxRecovery1.png		BitBoxRecovery1.png
Dockerfile		Dockerfile
README.md		README.md
blockchain.py		blockchain.py
config.json.template		config.json.template
cracker.py		cracker.py
docker-compose.yml		docker-compose.yml
generator.py		generator.py
gpu_engine.py		gpu_engine.py
passwords.example.csv		passwords.example.csv
personal_info.example.txt		personal_info.example.txt
profile.example.txt		profile.example.txt
requirements.txt		requirements.txt
server.py		server.py
verify_gpu.py		verify_gpu.py

Folders and files

Latest commit

History

Repository files navigation

BitBox01 Password Recovery — V4 (GPU Accelerated)

Table of Contents

Overview

Architecture

Hybrid GPU→CPU Pipeline

Compute Time Breakdown (per password)

Cryptographic Chain

Quick Start

Prerequisites

1. Build the CUDA Kernel

2. Verify GPU Kernel

3. Configure

4. Generate Password Candidates

5. Run

Configuration

Target and Backups

Derivation Settings

Compute Settings

Password Generation Settings

Web Server

Notifications

LLM Settings

Hashcat Settings

Hashcat Integration

Setup

Attack Modes

Mask Character Classes

CLI Examples

Password Generation Pipeline

LLM Brainstorming

Prompt Modes

Deterministic Mutation Engine

Generation Modes

Tier System

Cracking Pipeline

GPU Mode (Default)

CPU Mode

Found Password Flow

Dashboard

Status Display

LLM Monitoring

Feed & Derivation Logging

Notifications

API Endpoints

REST Endpoints

WebSocket Events (Real-Time)

GPU Setup

Supported GPUs

VRAM Usage

Performance Reference

Troubleshooting GPU

Files

Usage Examples

Example 1: Generate mutations only (instant)

Example 2: LLM + mutations

Example 3: Continuous recovery with live generation

Example 4: GPU-only recovery (force GPU, fail if unavailable)

Example 5: CPU-only (slower but no GPU needed)

Example 6: Benchmark GPU vs CPU speed

Reset & Recovery

Restart cracking from beginning

Clear all state (full reset)

Regenerate password candidates

Troubleshooting

Performance Tips

License & Attribution

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Packages