Sherlock

A Bitcoin chain analysis engine that studies real block data and uncovers patterns, behaviors, and hidden relationships between transactions.

Built on raw block parsing + deterministic heuristics, with a visual UI to make blockchain activity understandable.

---

What it does

Given raw Bitcoin block data, it:

• parses transactions and prevouts
• applies chain-analysis heuristics
• detects patterns (change, CoinJoin, consolidation, etc.)
• classifies transactions
• generates JSON + Markdown reports
• visualizes results in an interactive web UI

see ./demo.md for a demo

---

Quick start

Run ./setup.sh to set things up

CLI

./cli.sh --block blk.dat rev.dat xor.dat

Outputs:

• out/<file>.json -> machine-readable analysis
• out/<file>.md -> human-readable report

---

Web UI

./web.sh

• explore blocks, transactions, and patterns
• default: http://127.0.0.1:3000

---

What you’ll see

Insights

• who likely controls inputs (CIOH)
• which output is change
• privacy leaks (address reuse)
• patterns like CoinJoin, consolidation, self-transfer

Block-level view

• fee rate distribution
• script type breakdown
• flagged transactions

---

Heuristics (core ideas)

This tool uses deterministic heuristics (not ML) for explainability and speed.

• CIOH (Common Input Ownership) -> multiple inputs likely same wallet
• Change detection -> script-type + round-number analysis
• CoinJoin detection -> equal-value outputs + many inputs
• Consolidation -> many inputs -> few outputs
• Address reuse -> definitive ownership leak
• Self-transfer -> wallet moving funds internally
• Round-number payments -> likely user-facing payments
• OP_RETURN analysis -> protocol detection (Omni, OpenTimestamps)

---

How it works

blk.dat + rev.dat + xor.dat
 -> decode + parse
 -> recover prevouts
 -> run heuristics per transaction
 -> classify transactions
 -> aggregate stats per block
 -> output JSON + Markdown + UI

---

Design philosophy

• Heuristic, not absolute -> accepts ambiguity
• Explainability first -> every decision is visible
• Protocol-grounded -> built on raw Bitcoin data
• Fast + deterministic -> no ML, O(n) per transaction

---

Notes

• Does not validate signatures or execute scripts
• Built for analysis, not transaction creation
• this project was a part of 2026 Summer of Bitcoin Challenge round

---

Deep dive

For full methodology, heuristics, architecture, and limitations, see:
./APPROACH.md