How rebicul/24_seed_phrase_guesser works
Project type and purpose
• This is a standalone Python command-line tool (an open-source demonstration utility) that systematically brute-forces the order of a 24-word BIP-39 seed phrase to find a known Bitcoin address.
• Its goal is to illustrate the infeasibility of full 24-word brute forcing, while showcasing a resume-capable permutation pipeline with checksum validation and HD wallet derivation.
Main components
a. CLI / Main Controller
• Parses input parameters (scrambled word list, target address, job_id)
• Invokes the pipeline and handles start/stop logic
b. Checkpoint Manager
• load_progress(job_id) reads progress_checkpoint_{job_id}.txt or returns 0
• save_progress(count, job_id) writes progress periodically
• Ensures resumability
c. Permutation Engine
• Uses itertools.permutations to generate each word ordering
• Receives a start offset from the Checkpoint Manager
d. Mnemonic Validator
• Applies BIP-39 checksum rules to each 24-word candidate
• Early filters out invalid mnemonics
e. HD Wallet Derivation
• Uses the external hdwallet library
• Derives addresses along configured paths (e.g., BIP-84)
f. Address Comparator
• Compares each derived address to the target
• If match found, returns the correct mnemonic and halts
g. File System (Progress File)
• Persists checkpoint data between runs
Relationships and data flow
• The CLI/Main Controller kicks off the pipeline by loading last progress from Checkpoint Manager.
• It then passes control to the Permutation Engine, supplying the scrambled word list and start index.
• For each permutation, control flows to Mnemonic Validator; valid ones proceed on to HD Wallet Derivation.
• The resulting address is handed to Address Comparator.
• Every N permutations (configurable), Checkpoint Manager is invoked to persist the current index to the File System.
• A successful match bubbles back through to the CLI, which outputs the discovered phrase and terminates.
Architectural patterns and design principles
• Pipeline / Chain of Responsibility: each stage (validation, derivation, comparison) is a distinct function/module.
• Single-threaded, sequential processing due to the enormous search space; easy to extend to multiprocessing if needed.
• Checkpointing decoupled from core logic, following single-responsibility.
Technologies and external dependencies
• Python standard library: itertools, os, json
• External library: hdwallet for BIP-32/BIP-39 derivation
• File I/O for checkpoint persistence