Satyanveshi: Bitcoin Chain Analysis Engine

I built Satyanveshi, an offline chain-analysis engine that applies probabilistic heuristics to raw Bitcoin block data to infer patterns, identify entities, and classify transaction behavior.

This project parses raw block files directly to extract transaction and prevout data without relying on external nodes or third-party APIs. It processes this data, applies custom analytical reasoning, and surfaces the findings through machine-readable JSON, automated Markdown reports, and an interactive web visualizer.

---

Overview

The engine acts as a pipeline transforming raw blockchain data into actionable intelligence. By applying a suite of chain-analysis heuristics, Satyanveshi categorizes transactions into distinct patterns (e.g., consolidations, coinjoins, simple payments) and identifies likely entity relationships.

Core Components

1. CLI Chain Analyzer (cli.sh): A high-performance tool that ingests raw block data (blk*.dat, rev*.dat, xor.dat), applies the heuristic engine to every transaction, and outputs structured JSON.
2. Automated Reporter: Generates human-readable Markdown summaries detailing block statistics, fee distributions, and heuristic findings.
3. Web Visualizer (web.sh): An interactive UI for exploring chain analysis results, filtering transactions by classification, and visualizing block-level statistics.

---

Getting Started

To run the analyzer against a set of raw block files:

./cli.sh --block <blk.dat> <rev.dat> <xor.dat> (Outputs are generated in the out/ directory as <blk_stem>.json and <blk_stem>.md)

To launch the interactive web dashboard:

./web.sh (Runs on http://127.0.0.1:3000 by default and honors the PORT env variable)

---

Applied Heuristics

Because chain analysis is inherently probabilistic, I designed the engine to weigh multiple heuristics to build confidence in transaction classifications. The core heuristics implemented include:

• Common Input Ownership (cioh): The foundational assumption: if multiple inputs are spent together, they are highly likely controlled by the same wallet entity.
• Change Detection: Identifies the likely change output using a combination of script type matching, round number analysis, output ordering, and value comparison.
• Address Reuse: Detects when the same address appears in both inputs and outputs, or across multiple transactions in a block, linking activity to a single entity.
• CoinJoin Detection: Identifies privacy-enhancing transactions characterized by multiple inputs from different owners and symmetric, equal-value outputs.
• Consolidation Detection: Spots wallet maintenance operations where many inputs are combined into 1-2 outputs to reduce UTXO set footprint.
• Self-Transfer Detection: Flags transactions where all inputs and outputs appear to belong to the same entity (e.g., exact script type matches with no obvious payment component).
• Peeling Chain Detection: Tracks patterns where a large input is repeatedly split into a small payment and a large change output across sequential transactions.
• OP_RETURN Analysis: Identifies and categorizes embedded data outputs (e.g., Omni, OpenTimestamps).
• Round Number Analysis: Utilizes the behavioral tendency for human payments to be round fiat or BTC amounts, isolating change outputs.

---

Data Architecture & Output Schema

The CLI tool produces a comprehensive JSON report for every parsed block file. It wraps per-block data into an aggregated file-level summary containing total transactions analyzed, script type distributions, and fee rate statistics.

Automated Markdown Reports

In addition to the raw data, the engine automatically compiles out/<blk_stem>.md to provide immediate, readable insights. These reports include:

• Summary statistics: Fee rate distributions, script type breakdowns, and flagged transaction counts.
• Per-block highlights: Detailed findings on which heuristics fired most frequently and highlights of notable transactions (e.g., massive consolidations or complex coinjoins).

---

Web UI Features

The interactive visualizer allows for deep dives into specific blocks. Key features include:

• Transaction Graphs: Visual relationships between inputs and outputs.
• Color-Coded Classifications: Instantly visually separate simple payments from coinjoins or consolidations.
• Heuristic Inspection: Click-to-expand details revealing exactly why a transaction was flagged and the confidence level of the change detection algorithm.
• Global Stats Dashboard: High-level charts showing script type distribution and fee rate volatility within the block.