# zaidalhawamdeh/bitcoin-forensics architecture

> Architecture diagram of the GitHub repository zaidalhawamdeh/bitcoin-forensics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zaidalhawamdeh/bitcoin-forensics
- Repository: https://github.com/zaidalhawamdeh/bitcoin-forensics

## Overview

This is a reproducible Bitcoin-mining forensics research repository, not a service: researchers inspect supplied chain and Stratum-share data, run focused analyses, and compare recomputed measurements with written findings. Its main domain stages are share calibration, block-version classification and skew analysis, and interpretation of saturated version masks; separate work examines a solo-mined block and hash-search hypotheses. The sampled scripts show direct data reads and one experiment-results write. Other documented investigations are represented without asserting unsampled implementation details.

Main entry points: [`repro/verify_version_class.py`](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/repro/verify_version_class.py) (Version-class analysis), [`repro/verify_saturated.py`](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/repro/verify_saturated.py) (Saturation analysis), [`calibration/repro/verify_calibration.py`](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/calibration/repro/verify_calibration.py) (Calibration verifier), [`repro/verify_version_skew.py`](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/repro/verify_version_skew.py) (Version-skew analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calibration["Share calibration"]
  node_calibration_data["Share submissions"]
  node_calibration_verify["Calibration verifier"]
  node_calibration_report["Calibration findings<br/>[CALIBRATION.md]"]
end

subgraph group_chain["Chain analyses"]
  node_block_headers["Block headers<br/>[headers.json]"]
  node_block_data["Block fields<br/>[blocks.json]"]
  node_class_a["Class exploration set"]
  node_class_b["Class holdout set"]
  node_pool_data["Pool attribution"]
  node_skew_verify["Version-skew analysis"]
  node_class_verify["Version-class analysis"]
  node_saturated_verify["Saturation analysis"]
end

subgraph group_experiments["Hash experiments"]
  node_merkle_experiment["Nonce-range experiment<br/>[followup_ranges.py]"]
  node_merkle_results["Experiment results"]
end

subgraph group_reports["Findings and methods"]
  node_block_case["Solo-mined block<br/>[CASE_957382.md]"]
  node_skew_case["Version-skew finding"]
  node_class_case["Version-class finding"]
  node_saturated_case["Saturated-pattern finding"]
  node_prior_methods["Prior-work limits<br/>[PRIOR_WORK.md]"]
  node_hashpower_prior["Hashpower prior work"]
  node_selection_prior["Work-selection prior"]
  node_method_plan["Pre-registered test<br/>[PRECOMMIT.md]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs"| node_calibration_verify
node_calibration_verify -->|"reads"| node_calibration_data
node_researcher -->|"runs"| node_skew_verify
node_skew_verify -->|"reads"| node_block_headers
node_researcher -->|"runs"| node_class_verify
node_class_verify -->|"reads"| node_class_a
node_class_verify -->|"reads"| node_class_b
node_researcher -->|"runs"| node_saturated_verify
node_saturated_verify -->|"reads"| node_class_b
node_saturated_verify -->|"reads"| node_pool_data
node_researcher -->|"runs"| node_merkle_experiment
node_merkle_experiment -->|"writes"| node_merkle_results

click node_calibration_data "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/calibration/calibration_submits.csv.gz"
click node_calibration_verify "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/calibration/repro/verify_calibration.py"
click node_calibration_report "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/calibration/CALIBRATION.md"
click node_block_headers "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/data/headers.json"
click node_block_data "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/data/blocks.json"
click node_class_a "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/data/version_class_A.jsonl"
click node_class_b "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/data/version_class_B.jsonl"
click node_pool_data "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/data/version_class_B_pools.jsonl"
click node_skew_verify "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/repro/verify_version_skew.py"
click node_class_verify "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/repro/verify_version_class.py"
click node_saturated_verify "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/repro/verify_saturated.py"
click node_block_case "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/findings/CASE_957382.md"
click node_skew_case "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/findings/CASE_VERSION_SKEW.md"
click node_class_case "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/findings/CASE_VERSION_CLASS.md"
click node_saturated_case "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/findings/CASE_VERSION_CLASS.md"
click node_prior_methods "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/PRIOR_WORK.md"
click node_hashpower_prior "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/HASHPOWER_PRIOR_WORK.md"
click node_selection_prior "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/WORK_SELECTION_PRIOR.md"
click node_method_plan "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/method/PRECOMMIT.md"
click node_merkle_experiment "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/merkle-templates/followup_ranges.py"
click node_merkle_results "https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/merkle-templates/results_followup.json"

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_calibration_data,node_calibration_verify,node_calibration_report toneBlue
class node_block_headers,node_block_data,node_class_a,node_class_b,node_pool_data,node_skew_verify,node_class_verify,node_saturated_verify toneAmber
class node_merkle_experiment,node_merkle_results toneMint
class node_block_case,node_skew_case,node_class_case,node_saturated_case,node_prior_methods,node_hashpower_prior,node_selection_prior,node_method_plan toneRose
class node_researcher toneIndigo
```

## Components

### Share calibration

- [Share submissions](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/calibration/calibration_submits.csv.gz): `calibration/calibration_submits.csv.gz`
- [Calibration verifier](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/calibration/repro/verify_calibration.py): `calibration/repro/verify_calibration.py`
- [Calibration findings](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/calibration/CALIBRATION.md): `calibration/CALIBRATION.md`

### Chain analyses

- [Block headers](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/data/headers.json): `data/headers.json`
- [Block fields](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/data/blocks.json): `data/blocks.json`
- [Class exploration set](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/data/version_class_A.jsonl): `data/version_class_A.jsonl`
- [Class holdout set](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/data/version_class_B.jsonl): `data/version_class_B.jsonl`
- [Pool attribution](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/data/version_class_B_pools.jsonl): `data/version_class_B_pools.jsonl`
- [Version-skew analysis](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/repro/verify_version_skew.py): `repro/verify_version_skew.py`
- [Version-class analysis](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/repro/verify_version_class.py): `repro/verify_version_class.py`
- [Saturation analysis](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/repro/verify_saturated.py): `repro/verify_saturated.py`

### Hash experiments

- [Nonce-range experiment](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/merkle-templates/followup_ranges.py): `merkle-templates/followup_ranges.py`
- [Experiment results](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/merkle-templates/results_followup.json): `merkle-templates/results_followup.json`

### Findings and methods

- [Solo-mined block](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/findings/CASE_957382.md): `findings/CASE_957382.md`
- [Version-skew finding](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/findings/CASE_VERSION_SKEW.md): `findings/CASE_VERSION_SKEW.md`
- [Version-class finding](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/findings/CASE_VERSION_CLASS.md): `findings/CASE_VERSION_CLASS.md`
- [Saturated-pattern finding](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/findings/CASE_VERSION_CLASS.md): `findings/CASE_VERSION_CLASS.md`
- [Prior-work limits](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/PRIOR_WORK.md): `PRIOR_WORK.md`
- [Hashpower prior work](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/HASHPOWER_PRIOR_WORK.md): `HASHPOWER_PRIOR_WORK.md`
- [Work-selection prior](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/WORK_SELECTION_PRIOR.md): `WORK_SELECTION_PRIOR.md`
- [Pre-registered test](https://github.com/zaidalhawamdeh/bitcoin-forensics/blob/main/method/PRECOMMIT.md): `method/PRECOMMIT.md`

### Other components

- **Researcher**

## Connections

- Researcher → Calibration verifier: runs
- Calibration verifier → Share submissions: reads
- Researcher → Version-skew analysis: runs
- Version-skew analysis → Block headers: reads
- Researcher → Version-class analysis: runs
- Version-class analysis → Class exploration set: reads
- Version-class analysis → Class holdout set: reads
- Researcher → Saturation analysis: runs
- Saturation analysis → Class holdout set: reads
- Saturation analysis → Pool attribution: reads
- Researcher → Nonce-range experiment: runs
- Nonce-range experiment → Experiment results: writes