# rebicul/24_seed_phrase_guesser architecture

> Architecture diagram of the GitHub repository rebicul/24_seed_phrase_guesser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rebicul/24_seed_phrase_guesser
- Repository: https://github.com/rebicul/24_seed_phrase_guesser

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI[/CLI / Main Controller/]:::core
    subgraph "Core Logic"
        CM["Checkpoint Manager"]:::core
        PE["Permutation Engine"]:::core
        MV["Mnemonic Validator"]:::core
        AC["Address Comparator"]:::core
    end
    HD["HD Wallet Derivation"]:::external
    FS[(Progress File)]:::persistence

    CLI -->|"load_progress(job_id)"| CM
    CM -->|"start index"| PE
    PE -->|"24-word phrase"| MV
    MV -->|"valid phrase"| HD
    HD -->|"derived address"| AC
    AC -->|"match?"| CLI

    PE -.->|"every N permutations"| CM
    CM -->|"writes count"| FS

    click CLI "https://github.com/rebicul/24_seed_phrase_guesser/blob/main/seed_guesser.py"
    click CM "https://github.com/rebicul/24_seed_phrase_guesser/blob/main/seed_guesser.py"
    click PE "https://github.com/rebicul/24_seed_phrase_guesser/blob/main/seed_guesser.py"
    click MV "https://github.com/rebicul/24_seed_phrase_guesser/blob/main/seed_guesser.py"
    click HD "https://github.com/rebicul/24_seed_phrase_guesser/blob/main/seed_guesser.py"
    click AC "https://github.com/rebicul/24_seed_phrase_guesser/blob/main/seed_guesser.py"
    click FS "https://github.com/rebicul/24_seed_phrase_guesser/blob/main/progress_checkpoint.txt"

    classDef core fill:#add8e6,stroke:#000,stroke-width:1px
    classDef external fill:#90ee90,stroke:#000,stroke-width:1px
    classDef persistence fill:#ffa500,stroke:#000,stroke-width:1px
```
