Sherlock — Bitcoin Chain Analysis Engine

A chain analysis engine that applies privacy heuristics to real Bitcoin block data, classifies transactions, and surfaces insights through an interactive web dashboard.

Built from scratch in TypeScript/Node.js — parses raw .dat block files, applies 7 heuristics, and produces machine-readable JSON + human-readable Markdown reports.

Features

• Raw Block Parsing — Reads blk*.dat, rev*.dat, and xor.dat files directly, no external APIs needed
• 7 Chain Analysis Heuristics — CIOH, change detection, round number payment, consolidation, CoinJoin detection, address reuse, OP_RETURN analysis
• Transaction Classification — Categorizes every transaction as simple payment, consolidation, CoinJoin, self-transfer, batch payment, or unknown
• Per-Block Statistics — Fee rate distribution, script type breakdown, flagged transaction counts, per-heuristic detection counts
• Interactive Web Dashboard — Charts, filterable transaction lists, expandable block details
• File Upload Support — Upload your own block files for live analysis through the web UI

Demo

Video Walkthrough

Dashboard

Block Detail & Transaction Explorer

Architecture

blk.dat + rev.dat → XOR decode → Block Parser → Undo Matcher
    → Transaction Analyzer → 7 Heuristics → Priority Classifier
    → JSON Report + Markdown Report + Web Dashboard

Module	Description
src/parser/block.ts	Multi-block parser with undo matching
src/parser/transaction.ts	Transaction parsing (SegWit, witness, weight)
src/parser/undo.ts	Rev file undo data (CompactSize, varint)
src/parser/script.ts	O(1) script type classification
src/heuristics.ts	All 7 heuristic implementations
src/classifier.ts	Priority-based transaction classification
src/stats.ts	Fee rate stats, script distribution
src/server.ts	Express web server with REST API

Quick Start

# Install dependencies
npm install

# Build
npm run build

# Run analysis on block files
./cli.sh --block <blk.dat> <rev.dat> <xor.dat>

# Start the web dashboard
./web.sh
# Open http://localhost:3000

Heuristics

ID	Name	Description
cioh	Common Input Ownership	Multiple inputs → same entity
change_detection	Change Detection	Identifies likely change output (script type match, round numbers, value analysis)
round_number_payment	Round Number Payment	Round BTC amounts are likely payments
consolidation	Consolidation Detection	Many inputs → 1-2 outputs, same script type
coinjoin	CoinJoin Detection	Equal-value outputs + many inputs
address_reuse	Address Reuse	Same address in inputs & outputs, or across block
op_return	OP_RETURN Analysis	Embedded data detection and protocol classification

Output

JSON (out/<blk_stem>.json)

• File-level and per-block aggregated summaries
• Per-block heuristic_counts for quick access to detection stats
• Full per-transaction heuristic results and classifications
• Fee rate statistics and script type distributions

Markdown (out/<blk_stem>.md)

• Human-readable report with tables and per-block breakdowns
• Notable transactions highlighted (CoinJoin, consolidation, etc.)

Performance

Metric	blk04330	blk05051
Blocks	84	78
Transactions	341,792	256,523
Heuristics per tx	7	7

Tech Stack

• Language: TypeScript
• Runtime: Node.js
• Web Framework: Express
• Charts: Chart.js
• Styling: Custom CSS (dark theme, glassmorphism)

Detailed Approach

See APPROACH.md for in-depth documentation on:

• Each heuristic's detection method and confidence model
• Architecture and data flow
• Trade-offs and design decisions
• References (BIPs, papers, documentation)

License

MIT