Sherlock: Advanced Bitcoin Chain Analysis Visualizer

Sherlock is a lightweight, local-first Bitcoin transaction chain analysis tool and web application. It parses Bitcoin Core block data (.dat files) directly, reconstructs transaction graphs, and applies a suite of rule-based heuristics to identify and classify on-chain behaviors like CoinJoins, consolidations, batch payments, and peeling chains.

Built with Next.js, TypeScript, and Tailwind CSS, Sherlock provides both machine-readable JSON outputs and a rich, interactive human-readable dashboard.

Screenshots

Key Features

• Direct .dat Parsing: Operates directly on Bitcoin Core blk, rev, and xor files—no full node indexing or external API rate limits required.
• Transaction Graph Reconstruction: Uses undo (rev) data to reconstruct previous outputs (prevouts), enabling deep inspection of input values and scripts.
• Interactive Visualization: A modern, dark-mode Next.js UI to explore blocks, visualize transaction flows, and inspect script distributions and fee rates.
• 10+ On-Chain Heuristics:
  • Common Input Ownership Heuristic (CIOH)
  • Change Output Detection
  • Address Reuse
  • CoinJoin Fingerprinting (Whirlpool, JoinMarket, Wasabi-like)
  • UTXO Consolidation
  • Self-Transfer Detection
  • Batch Payment Classification
  • Peeling Chains
  • OP_RETURN Payload Extraction
  • Round Number Payment Detection

Tech Stack

• Framework: Next.js 15+ (React 19)
• Language: TypeScript
• Styling: Tailwind CSS v4 (with custom Sherlock UI theme)
• Bitcoin Primitives: bitcoinjs-lib
• Testing: Vitest (with v8 coverage)

Getting Started

Prerequisites

• Node.js (v18+ recommended)
• npm, yarn, or pnpm

Installation

1. Clone the repository:

git clone https://github.com/wolgwang1729/Sherlock.git
cd Sherlock

2. Install dependencies:

npm install

3. Run the development server:

npm run dev

Open http://localhost:3000 in your browser to view the application.

4. Run tests:

npm run test
# Or to run with UI: npm run test:ui

Required Data Files

To perform an analysis, Sherlock requires three files uploaded simultaneously. These files must come from a synced Bitcoin Core data directory.

• blkNNNNN.dat (Raw block data)
• revNNNNN.dat (Undo data for prevout reconstruction)
• xor.dat (The XOR key used by Bitcoin Core to obfuscate block data)

Note: blk and rev files must have matching numeric suffixes (e.g., blk05051.dat and rev05051.dat).

Where to find these files

• Windows: %APPDATA%\Bitcoin\blocks
• Linux: ~/.bitcoin/blocks
• macOS: ~/Library/Application Support/Bitcoin/blocks

If you are using a pruned node, only recent files will be available. If xor.dat is missing, you can create an 8-byte zero-filled file named xor.dat.

Note: You can also click Use Example .dat Files in the UI to load the bundled test fixtures (blk05051.dat).

How It Works

Sherlock's architecture is intentionally rule-based and localized.

1. Parsing: src/lib/block.ts XOR-decodes the files, parses raw block payloads, verifies transaction merkle roots, and pairs each block with its undo records.
2. Normalization: src/lib/transaction.ts converts parsed transactions into a normalized TransactionAnalysis object, computes fee rates and weights, infers RBF signaling, and decodes script types via src/lib/script.ts.
3. Context Building: A block-local context maps address frequencies and immediate spend_by_outpoint relationships.
4. Heuristics: src/lib/heuristics.ts runs each transaction through the heuristic pipeline. Detailed flowcharts and logic are in APPROACH.md.
5. Classification: Transactions are labeled (e.g., coinjoin, consolidation, simple_payment) and assigned confidence tiers based on heuristic confluence.

Project Structure

wolgwang1729-sherlock/
├── fixtures/          # Bundled test data (blk, rev, xor)
├── src/
│   ├── app/           # Next.js App Router (Pages, Layout, API Routes)
│   ├── components/    # React UI Components (BlockVisualizer, TransactionVisualizer)
│   ├── lib/           # Core logic (block parsing, script parsing, transaction normalization)
│   │   └── detectors/ # Individual heuristic implementations
│   ├── types/         # TypeScript interfaces and schemas
│   ├── utils/         # Helper functions (BufferCursor, math, parsing)
│   └── __tests__/     # Vitest unit and integration tests
├── APPROACH.md        # Deep-dive documentation into heuristic logic
└── README.md          # Project overview