# floflo777/open-crypto-puzzles architecture

> Architecture diagram of the GitHub repository floflo777/open-crypto-puzzles, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/floflo777/open-crypto-puzzles
- Repository: https://github.com/floflo777/open-crypto-puzzles

## Overview

open-crypto-puzzles is a research collection for funded crypto-wallet puzzles, not a single solving service. The main workflow is to choose a puzzle, read its clues and prior work, investigate candidate derivations, test candidates against a puzzle-specific oracle, and independently check the escrow before acting on a result. The repository also documents CPU/GPU brute-force engines and includes puzzle-specific searches. The graph reflects README-described workflow and capabilities; sampled source shows a few search-to-oracle links, but not the wiring of every puzzle tool.

Main entry points: [`engines`](https://github.com/floflo777/open-crypto-puzzles/tree/main/engines) (Brute-force engines), [`4-solved/ftpk-season-4-166usdc/tools/oracle.py`](https://github.com/floflo777/open-crypto-puzzles/blob/main/4-solved/ftpk-season-4-166usdc/tools/oracle.py) (Puzzle oracle), [`2-mid-prizes`](https://github.com/floflo777/open-crypto-puzzles/tree/main/2-mid-prizes) (Puzzle dossier), [`1-big-prizes`](https://github.com/floflo777/open-crypto-puzzles/tree/main/1-big-prizes) (Puzzle catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Puzzle discovery"]
  node_catalog["Puzzle catalog"]
  node_dossier["Puzzle dossier"]
end

subgraph group_research["Puzzle research"]
  node_clues["Clues and leads"]
  node_priorwork["Tested hypotheses"]
  node_candidate_search["Candidate search<br/>[search_readings.py]"]
  node_reading_sweep["Reading-order sweep"]
end

subgraph group_validation["Candidate validation"]
  node_puzzle_oracle["Puzzle oracle<br/>[oracle.py]"]
  node_oracle_tools["Puzzle oracle tools"]
  node_derivation["Key derivation<br/>[bip39_multipath.py]"]
  node_escrow_check["Escrow check<br/>[check_escrows.py]"]
  node_chain[("Public blockchain")]
  node_sweep_result["Candidate result"]
end

subgraph group_compute["Search engines"]
  node_engines["Brute-force engines"]
  node_brainwallet_engine["Brainwallet engine<br/>[btc_p2pkh.py]"]
  node_arweave_engines["Arweave engines<br/>[arv_candfile.py]"]
end

node_researcher(("Puzzle solver"))

node_researcher -->|"chooses puzzle"| node_catalog
node_catalog -->|"opens puzzle"| node_dossier
node_dossier -->|"provides clues"| node_clues
node_dossier -->|"records attempts"| node_priorwork
node_researcher -->|"checks funding"| node_escrow_check
node_escrow_check -->|"checks balances"| node_chain
node_researcher -->|"investigates candidates"| node_candidate_search
node_candidate_search -->|"tests candidates"| node_puzzle_oracle
node_researcher -->|"runs search"| node_reading_sweep
node_reading_sweep -->|"delegates derivation"| node_puzzle_oracle
node_puzzle_oracle -->|"reports match"| node_sweep_result
node_oracle_tools -.->|"derives keys"| node_derivation
node_researcher -->|"runs computation"| node_engines
node_engines -->|"includes kernel"| node_brainwallet_engine
node_engines -->|"includes engines"| node_arweave_engines
node_engines -.->|"tests target"| node_puzzle_oracle

click node_catalog "https://github.com/floflo777/open-crypto-puzzles/tree/main/1-big-prizes"
click node_dossier "https://github.com/floflo777/open-crypto-puzzles/tree/main/2-mid-prizes"
click node_clues "https://github.com/floflo777/open-crypto-puzzles/tree/main/1-big-prizes"
click node_priorwork "https://github.com/floflo777/open-crypto-puzzles/tree/main/2-mid-prizes"
click node_candidate_search "https://github.com/floflo777/open-crypto-puzzles/blob/main/2-mid-prizes/arweave-puzzle-3-1000ar/tools/search_readings.py"
click node_reading_sweep "https://github.com/floflo777/open-crypto-puzzles/blob/main/1-big-prizes/guntis-vitolins-metamask-8-6eth/tools/sweep_reading_order.py"
click node_puzzle_oracle "https://github.com/floflo777/open-crypto-puzzles/blob/main/4-solved/ftpk-season-4-166usdc/tools/oracle.py"
click node_oracle_tools "https://github.com/floflo777/open-crypto-puzzles/tree/main/1-big-prizes"
click node_derivation "https://github.com/floflo777/open-crypto-puzzles/blob/main/engines/lib/bip39_multipath.py"
click node_escrow_check "https://github.com/floflo777/open-crypto-puzzles/blob/main/tools/check_escrows.py"
click node_engines "https://github.com/floflo777/open-crypto-puzzles/tree/main/engines"
click node_brainwallet_engine "https://github.com/floflo777/open-crypto-puzzles/blob/main/engines/lib/btc_p2pkh.py"
click node_arweave_engines "https://github.com/floflo777/open-crypto-puzzles/blob/main/engines/arv_candfile.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_catalog,node_dossier toneBlue
class node_clues,node_priorwork,node_candidate_search,node_reading_sweep toneAmber
class node_puzzle_oracle,node_oracle_tools,node_derivation,node_escrow_check,node_chain,node_sweep_result toneMint
class node_engines,node_brainwallet_engine,node_arweave_engines toneRose
class node_researcher toneIndigo
```

## Components

### Puzzle discovery

- [Puzzle catalog](https://github.com/floflo777/open-crypto-puzzles/tree/main/1-big-prizes): `1-big-prizes`
- [Puzzle dossier](https://github.com/floflo777/open-crypto-puzzles/tree/main/2-mid-prizes): `2-mid-prizes`

### Puzzle research

- [Clues and leads](https://github.com/floflo777/open-crypto-puzzles/tree/main/1-big-prizes): `1-big-prizes`
- [Tested hypotheses](https://github.com/floflo777/open-crypto-puzzles/tree/main/2-mid-prizes): `2-mid-prizes`
- [Candidate search](https://github.com/floflo777/open-crypto-puzzles/blob/main/2-mid-prizes/arweave-puzzle-3-1000ar/tools/search_readings.py): `2-mid-prizes/arweave-puzzle-3-1000ar/tools/search_readings.py`
- [Reading-order sweep](https://github.com/floflo777/open-crypto-puzzles/blob/main/1-big-prizes/guntis-vitolins-metamask-8-6eth/tools/sweep_reading_order.py): `1-big-prizes/guntis-vitolins-metamask-8-6eth/tools/sweep_reading_order.py`

### Candidate validation

- [Puzzle oracle](https://github.com/floflo777/open-crypto-puzzles/blob/main/4-solved/ftpk-season-4-166usdc/tools/oracle.py): `4-solved/ftpk-season-4-166usdc/tools/oracle.py`
- [Puzzle oracle tools](https://github.com/floflo777/open-crypto-puzzles/tree/main/1-big-prizes): `1-big-prizes`
- [Key derivation](https://github.com/floflo777/open-crypto-puzzles/blob/main/engines/lib/bip39_multipath.py): `engines/lib/bip39_multipath.py`
- [Escrow check](https://github.com/floflo777/open-crypto-puzzles/blob/main/tools/check_escrows.py): `tools/check_escrows.py`
- **Public blockchain**
- **Candidate result**

### Search engines

- [Brute-force engines](https://github.com/floflo777/open-crypto-puzzles/tree/main/engines): `engines`
- [Brainwallet engine](https://github.com/floflo777/open-crypto-puzzles/blob/main/engines/lib/btc_p2pkh.py): `engines/lib/btc_p2pkh.py`
- [Arweave engines](https://github.com/floflo777/open-crypto-puzzles/blob/main/engines/arv_candfile.py): `engines/arv_candfile.py`

### Other components

- **Puzzle solver**

## Connections

- Puzzle solver → Puzzle catalog: chooses puzzle (evidence: `README.md`)
- Puzzle catalog → Puzzle dossier: opens puzzle (evidence: `README.md`)
- Puzzle dossier → Clues and leads: provides clues (evidence: `README.md`)
- Puzzle dossier → Tested hypotheses: records attempts (evidence: `README.md`)
- Puzzle solver → Escrow check: checks funding (evidence: `README.md`)
- Escrow check → Public blockchain: checks balances (evidence: `README.md`)
- Puzzle solver → Candidate search: investigates candidates (evidence: `2-mid-prizes/arweave-puzzle-3-1000ar/tools/search_readings.py`)
- Candidate search → Puzzle oracle: tests candidates (evidence: `2-mid-prizes/arweave-puzzle-3-1000ar/tools/search_readings.py`)
- Puzzle solver → Reading-order sweep: runs search (evidence: `1-big-prizes/guntis-vitolins-metamask-8-6eth/tools/sweep_reading_order.py`)
- Reading-order sweep → Puzzle oracle: delegates derivation (evidence: `1-big-prizes/guntis-vitolins-metamask-8-6eth/tools/sweep_reading_order.py`)
- Puzzle oracle → Candidate result: reports match (evidence: `4-solved/ftpk-season-4-166usdc/tools/oracle.py`)
- Puzzle oracle tools → Key derivation: derives keys
- Puzzle solver → Brute-force engines: runs computation (evidence: `README.md`)
- Brute-force engines → Brainwallet engine: includes kernel (evidence: `README.md`)
- Brute-force engines → Arweave engines: includes engines (evidence: `README.md`)
- Brute-force engines → Puzzle oracle: tests target