chainforensics

🔗 ChainForensics

Enterprise-Grade Blockchain Analysis Platform

A privacy-focused UTXO forensics tool designed to work with your local Bitcoin node (Umbrel recommended). All analysis happens locally on your LAN - no external APIs, no data leakage. Claude descktop/docker MCP integration is optional. The App works without it out of the box.

📋 Features

Core Analysis

• UTXO Tracing - Track funds forward (where they went) and backward (where they came from)
• CoinJoin Detection - Identify Whirlpool, Wasabi (v1 & v2 WabiSabi), JoinMarket, and PayJoin transactions
• Peeling Chain Detection - Identify systematic spend-down patterns that link transactions
• Timeline Visualization - ASCII and graphical timelines of fund flows
• Address Validation - Validate addresses and identify types (P2PKH, P2SH, P2WPKH, P2TR)
• Background Jobs - Queue long-running analyses

🔬 Commercial-Grade Privacy Analysis

ChainForensics now includes sophisticated heuristics that rival commercial blockchain analytics firms:

Advanced Heuristics

• Temporal Correlation Analysis - Detects timing attacks, spend velocity patterns, and timezone fingerprinting
• Value Fingerprinting - Identifies unique/trackable amounts, subset sum leaks, and dust tracking pixels
• Wallet Fingerprinting - Detects script type patterns, BIP-69 ordering, fee strategies, and wallet software identification
• Unnecessary Input Detection - Identifies inputs beyond minimum needed, confirming same-wallet ownership
• Amount Correlation - Tracks amount flows across CoinJoin transactions to detect defeats of anonymity
• Change Detection - Multi-factor heuristics to identify change outputs with high accuracy

🎯 Enterprise-Grade Graph Analytics

NEW: ChainForensics now includes the same graph analytics used by $100,000+/year commercial platforms:

Graph Algorithms (powered by python-igraph)

• Louvain Community Detection - Identify distinct entities (exchanges, services, mixers) with 0.87 modularity (research: 74,286 nodes → 1,247 communities)
• PageRank Hub Analysis - Detect high-centrality addresses (exchanges, major hubs) by importance ranking
• Union-Find Clustering - O(α(n)) address clustering with Common Input Ownership Heuristic (85% confidence)
• Subgraph Pattern Detection - Identify rings (money laundering), trees, fan-out/fan-in patterns

Advanced Clustering Heuristics

• Fee Rate Fingerprinting - 81% accuracy wallet software identification (Bitcoin Core, Electrum, Wasabi)
• Locktime Analysis - Anti-fee-sniping detection for Bitcoin Core fingerprinting (85% confidence)
• Script Hash Clustering - Multisig address clustering for institutional wallets
• Deposit Address Detection - Identify exchange hot wallets and merchant processors

Critical Security Warnings

• WabiSabi Coordinator Attacks - CRITICAL warnings for malicious CoinJoin coordinators (Dec 2024 research)
• Lightning Network Linkability - 43.7% of LN nodes linkable to on-chain addresses
• RPC Timing Correlation - Timing attack mitigation advice (CVE-2025-43968)

Enhanced Privacy Scoring (0-100 Scale)

The privacy scoring system now evaluates 8 distinct categories:

• ⏱️ Temporal Privacy (-30 to +20) - Timing correlation risks
• 💰 Value Analysis (-30 to +5) - Amount fingerprinting vulnerabilities
• 🔑 Wallet Fingerprinting (-60 to +5) - Software pattern detection
• 🔗 Peeling Chains (-25) - Systematic spend-down patterns
• 🏦 Exchange Proximity (-40 to 0) - Distance from known exchanges
• 🔀 CoinJoin Quality (0 to +15) - Mixing effectiveness
• 👥 Cluster Analysis (-15 to +15) - Address clustering heuristics
• ⏰ UTXO Age (-5 to +5) - Time-based privacy factors

Privacy Reports

• Enhanced Privacy Scorecard - Professional HTML reports with color-coded risk assessment
• Attack Surface Analysis - Specific vectors adversaries can exploit with vulnerability scores
• Natural Language Summaries - Clear explanations of privacy status in plain English
• Actionable Recommendations - Prioritized steps to improve privacy with expected improvements
• Comparative Benchmarks - See how your privacy compares to typical users
• Confidence Assessment - How certain the analysis is, with disclosed limitations

KYC Privacy Analysis

• KYC Privacy Check - Simulates adversarial analysis to check if your withdrawal from a KYC exchange (like Coinbase, Kraken, Binance, etc.) can be traced to your current holdings
• Anonymity Set-Based Confidence - Realistic degradation based on actual CoinJoin participant counts
• Protocol-Aware Tracing - Different confidence calculations for Whirlpool, Wasabi, JoinMarket
• Multi-Hop Path Analysis - Follows complex transaction chains with cumulative confidence tracking

Integration

• MCP Integration - Use with Claude Desktop for natural language blockchain analysis
• Local Network Only - All analysis happens on your LAN - no external APIs, complete privacy

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     YOUR LAN ONLY                           │
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐ │
│  │   Claude    │    │  Web        │    │   Umbrel        │ │
│  │   Desktop   │───▶│  Dashboard  │    │   Bitcoin Node  │ │
│  └──────┬──────┘    └──────┬──────┘    └────────┬────────┘ │
│         │                  │                     │          │
│         │    ┌─────────────▼─────────────┐      │          │
│         └───▶│    ChainForensics API     │◀─────┘          │
│              │    (localhost:3000)       │                  │
│              └───────────┬───────────────┘                  │
│                          │                                  │
│              ┌───────────▼───────────────┐                  │
│              │      SQLite Database      │                  │
│              │      (local cache)        │                  │
│              └───────────────────────────┘                  │
└─────────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Bitcoin Core with txindex=1 enabled (Umbrel has this by default)
• Local network access to your Bitcoin node

Option 1: Docker (Recommended)

#1 Clone or download the project
cd chainforensics

#2 Copy and configure environment
cp .env.example .env
nano .env  # Add your Bitcoin RPC credentials

#=====Extra Info to Get Login Details from Umbrel/Bitcoin Node App==========
# You will need this info for the .env file
# =========
BITCOIN_RPC_HOST=192.168.0.5
BITCOIN_RPC_PORT=8332
BITCOIN_RPC_USER=__cookie__
BITCOIN_RPC_PASS=c3jj4j3j
# =========
# BITCOIN_RPC_HOST= will be the IP of YOUR umbrel node not the IP shown here
# BITCOIN_RPC_PORT=8332 is the default leave this as is
# BITCOIN_RPC_USER=__cookie__ leave this as is (need to work out a better way of loging in each time as theis keeps changeing after a reload)
# BITCOIN_RPC_PASS=c3jj4j3j you need to replace c3jj4j3j with your rpc password. Below are the steps to do this
# In the umbrel GUI open the bitcoin node app, go to setting -> advanced then in the "Custom bitcoin.conf overrides" section add this
rpcallowip=192.168.0.0/24
rpcbind=0.0.0.0
# note the rpcallowip= has a 192.168.0.0/24 subnet, yours maybe different, change this to mathch your subnet. You can be more spacific by using the exact IP of your machine using a /32 mask.  
# Next restart the bitcoin node app (right click on the app and select restart)(YOU MUST DO THIS STEP)
# Next on the umbrel main home screen click the settings icon at the bottom. Then "advanced settings" then "Terminal" then "umbrelOS".
# At the CLI go to cd umbrel/app-data/bitcoin/data/bitcoin and type in "cat .cookie"
# you will see something that looks like this "__cookie__:c3jj4j3j" the password is after the : symbol. Yours will be much longer than c3jj4j3j.
#========================END============================

#=====Extra Fulcrum Info to Get Login Details  App==========
# Fulcrum should be fully setup in Umbrel. In the App under "Local Network" you should have the address and port for the below config in the .env file
# Fulcrum is much more performant than Electrs
FULCRUM_HOST=192.168.0.5
FULCRUM_PORT=50002
# To test you can curl to the below address or just http to it in a browser
curl http://localhost:3000/api/v1/addresses/fulcrum/status
#========================END============================

#3a start manually with Docker Compose
docker compose build --no-cache
docker compose up -d

#======Useful docker comands======
docker compose build --no-cache
docker compose up -d
docker compose logs -f chainforensics-api
#===============END=====================


#3b  Or Run setup script
chmod +x setup.sh
./setup.sh

Access:

• 📊 Web Dashboard: http://localhost:8080
• 🔌 API Server: http://localhost:3000
• 📚 API Docs: http://localhost:3000/docs

Option 2: Manual Setup (Development)

# Create virtual environment
cd backend
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp ../.env.example ../.env
nano ../.env

# Run the API server
uvicorn app.main:app --host 0.0.0.0 --port 3000 --reload

🔧 Configuration

Finding Your Umbrel RPC Password

SSH into your Umbrel and run:

cat ~/umbrel/app-data/bitcoin/data/bitcoin/.cookie

The output format is __cookie__:PASSWORD - use the PASSWORD part.

.env Configuration

# Bitcoin Core RPC (REQUIRED)
BITCOIN_RPC_HOST=umbrel.local    # or your node's IP
BITCOIN_RPC_PORT=8332
BITCOIN_RPC_USER=umbrel
BITCOIN_RPC_PASS=your_password_here

# Fulcrum (for address history and enhanced features)
# Fulcrum is much more performant than Electrs
FULCRUM_HOST=umbrel.local
FULCRUM_PORT=50002

🤖 Claude Desktop Integration (MCP)

ChainForensics includes an MCP server for natural language blockchain analysis.

Setup

1. Start ChainForensics API first:

   docker compose up -d chainforensics-api
   

2. Add to Claude Desktop config (~/.config/claude/claude_desktop_config.json on Linux/Mac):

   {
     "mcpServers": {
       "chainforensics": {
         "command": "python",
         "args": ["/path/to/chainforensics/mcp/server.py"]
       }
     }
   }
   

3. Restart Claude Desktop

Usage Examples

Once configured, you can ask Claude:

• "Trace this transaction forward: abc123..."
• "Is this a CoinJoin transaction? def456..."
• "What's the privacy score for this UTXO?"
• "Show me a timeline of where these funds went"
• "Check if this address is valid: bc1q..."

📊 API Endpoints

Transactions

• GET /api/v1/transactions/{txid} - Get transaction details
• GET /api/v1/transactions/{txid}/utxo/{vout} - Check UTXO status

Analysis

• GET /api/v1/analysis/trace/forward - Trace UTXO forward (supports peeling chain detection)
• GET /api/v1/analysis/trace/backward - Trace inputs backward
• GET /api/v1/analysis/coinjoin/{txid} - Detect CoinJoin (Whirlpool, Wasabi v1/v2, JoinMarket, PayJoin)
• GET /api/v1/analysis/privacy-score - Calculate privacy score (basic)

🆕 Enhanced Privacy Analysis

• GET /api/v1/privacy-score/enhanced?txid={txid}&vout={vout}&max_depth={depth} - Commercial-grade privacy analysis with:
  • Temporal correlation detection
  • Value fingerprinting analysis
  • Wallet fingerprinting
  • Peeling chain detection
  • Attack surface breakdown
  • Natural language summaries
  • Actionable recommendations
  • Comparative benchmarks

Visualizations

• GET /api/v1/visualizations/timeline/ascii - ASCII timeline
• GET /api/v1/visualizations/timeline/html - Interactive HTML timeline
• GET /api/v1/visualizations/graph/html?show_communities={bool} - Force-directed graph with optional community coloring
  • Standard mode: Color by transaction type (CoinJoin, unspent, coinbase)
  • Community mode (show_communities=true): 8-color palette for Louvain communities
  • Interactive tooltips with TXID, value, status, CoinJoin score, community ID
• GET /api/v1/visualizations/sankey?txid={txid}&depth={depth} - Sankey flow diagram showing value splitting/merging
• GET /api/v1/visualizations/tree?txid={txid}&vout={vout}&depth={depth} - Hierarchical tree layout for peeling chains
• GET /api/v1/visualizations/attack-heatmap?txid={txid}&vout={vout} - Attack surface heat map with vulnerability visualization
• GET /api/v1/visualizations/privacy-scorecard?txid={txid}&vout={vout} - Professional HTML privacy report with:
  • Color-coded score indicator
  • Risk assessment matrix
  • Attack vector visualization
  • Privacy factors breakdown
  • Recommendations checklist
  • Benchmark comparison charts

🆕 Graph Analytics (Enterprise-Grade)

• GET /api/v1/graph/status - Check python-igraph availability
• GET /api/v1/graph/communities?txid={txid}&vout={vout}&max_depth={depth} - Louvain community detection
  • Identifies distinct entities (exchanges, services, mixers)
  • Returns modularity score (0.87 for 74,286 nodes in research)
  • Entity type classification
• GET /api/v1/graph/important-addresses?txid={txid}&vout={vout}&max_depth={depth}&top_n={n} - PageRank hub analysis
  • Ranks addresses by centrality
  • Identifies exchanges and major hubs
  • Returns PageRank scores with connection counts
• GET /api/v1/graph/patterns?txid={txid}&vout={vout}&max_depth={depth} - Subgraph pattern detection
  • Detects rings (money laundering - CRITICAL)
  • Identifies trees, fan-out/fan-in patterns
  • Returns confidence scores and privacy implications
• GET /api/v1/graph/clusters?txid={txid}&vout={vout}&max_depth={depth} - Union-Find address clustering
  • O(α(n)) complexity with path compression
  • Common Input Ownership Heuristic (85% confidence)
  • Groups addresses by wallet ownership

KYC Privacy

• GET /api/v1/kyc/check?withdrawal_txid={txid}&your_address={addr}&depth={depth} - Adversarial trace simulation
  • Anonymity set-based confidence degradation
  • Protocol-aware CoinJoin analysis
  • Multi-hop path tracking
  • Detailed destination breakdown

Jobs

• POST /api/v1/jobs/ - Create background analysis job
• GET /api/v1/jobs/{job_id} - Get job status

Address Lookup

• GET /api/v1/addresses/{address}/balance - Get address balance (requires Fulcrum)
• GET /api/v1/addresses/{address}/utxos - Get all UTXOs (requires Fulcrum)
• GET /api/v1/addresses/{address}/dust-check - Check for dust attacks (requires Fulcrum)
• GET /api/v1/addresses/validate/{address} - Validate address format

Health & Status

• GET /health or /api/v1/health - Full system health check
• GET /api/v1/fulcrum-status - Fulcrum connection and operational health

📈 Timeline View Example

================================================================================
UTXO TIMELINE
Start: abc123def456...
================================================================================

2023-01-15 │ ████████████████████ 5.0000 BTC     💰 Unspent
           │

2023-01-16 │ ██████████ 2.5000 BTC               📤 Spent
           │ ██████████ 2.5000 BTC               📤 Spent
           │

2023-02-01 │ ██ 0.5000 BTC                       📤 Spent
           │ ████████ 2.0000 BTC                 🔀 CoinJoin (85%)
           │

2023-02-01 │ █ 0.0100 BTC                        💰 Unspent

================================================================================
Unspent outputs: 2
CoinJoin transactions: 1
Total nodes: 5
================================================================================

🔒 Security

• All traffic stays on your LAN - No external API calls
• No data leaves your network - Analysis uses only your local node
• No tracking - Your queries are not logged externally
• Docker isolation - Services run in isolated containers
• Non-root containers - Enhanced security posture

🛠️ Development

Project Structure

chainforensics/
├── backend/
│   ├── app/
│   │   ├── api/              # FastAPI routes
│   │   │   ├── models.py     # Enhanced response models (NEW)
│   │   │   ├── privacy.py    # Privacy analysis endpoints
│   │   │   ├── graph.py      # Graph analytics endpoints (NEW)
│   │   │   └── visualizations.py  # HTML scorecard + graph viz (ENHANCED)
│   │   ├── core/             # Business logic
│   │   │   ├── bitcoin_rpc.py
│   │   │   ├── fulcrum.py
│   │   │   ├── tracer.py     # Enhanced with peeling chain detection
│   │   │   ├── coinjoin.py   # Whirlpool, Wasabi v1/v2, JoinMarket
│   │   │   ├── kyc_trace.py  # Anonymity set-based tracing
│   │   │   ├── privacy_analysis.py  # Multi-factor privacy scoring (ENHANCED)
│   │   │   ├── temporal_analysis.py  # Timing correlation (NEW)
│   │   │   ├── value_analysis.py     # Amount fingerprinting (NEW)
│   │   │   ├── wallet_fingerprint.py # Wallet pattern detection (NEW)
│   │   │   ├── graph_analytics.py    # Enterprise graph algorithms (NEW)
│   │   │   ├── clustering_heuristics.py # Advanced clustering (NEW)
│   │   │   ├── security_warnings.py  # Critical security warnings (NEW)
│   │   │   └── timeline.py
│   │   ├── workers/          # Background tasks
│   │   ├── main.py           # FastAPI app
│   │   ├── config.py         # Settings
│   │   └── database.py       # SQLAlchemy models (ENHANCED)
│   ├── requirements.txt      # Includes python-igraph
│   └── Dockerfile
├── frontend/
│   ├── public/
│   │   └── index.html        # Dashboard
│   ├── nginx.conf
│   └── Dockerfile
├── mcp/
│   ├── server.py             # MCP server
│   └── Dockerfile
├── config/
│   └── claude_desktop_config.json
├── docker-compose.yml
├── .env.example
├── setup.sh
├── README.md
└── APP_GUIDE.md              # Complete user guide

Running Tests

cd backend
source venv/bin/activate
pytest

⚠️ Requirements

Bitcoin Core Settings

Your Bitcoin node MUST have txindex=1 enabled. Without this, you cannot look up arbitrary transactions.

For Umbrel: This is enabled by default.

For manual Bitcoin Core: Add to bitcoin.conf:

txindex=1

⚠️ If you enable txindex after initial sync, you must resync the entire blockchain.

Python Dependencies

Required:

• Python 3.9+
• All dependencies in requirements.txt (installed automatically)

Optional but Recommended:

• python-igraph (included in requirements.txt) - Enables enterprise-grade graph analytics
  • 10-100x faster than NetworkX for large graphs
  • Powers Louvain, PageRank, pattern detection
  • Without it: Graph analytics endpoints return 501 Not Implemented
  • Privacy analysis degrades gracefully (continues without graph features)

📜 License

AGPL-3.0. (See LICENSE file)
Commercial licensing available—contact me for details.

Contributing

Contributions are welcome! Help make this Bitcoin chain forensics tool better for everyone.

• Open an issue to report bugs, suggest features, or ask questions.
• Fork the repo, make your changes, and submit a pull request.
• Follow basic code style: readable commits, meaningful PR descriptions.

By contributing code, you agree that your contributions are licensed under the same license as this project (AGPL-3.0). Commercial licensing available separately—contact for details.

Thank you for helping build this project!

🙏 Acknowledgments

• Bitcoin Core developers
• Umbrel team
• NetworkChuck on YouTube (MCP Server) https://github.com/theNetworkChuck
• Anthropic (Claude MCP protocol)
• Samourai Wallet (Whirlpool inspiration)
• Wasabi Wallet (research reference)
• Fulcrum team

---

Built with ❤️ for the Bitcoin community. Your keys, your coins, your privacy.