---

📋 Table of Contents

- Overview
- Key Features
- Installation
- Quick Start
- Supported Blockchains
- Core Capabilities
- Use Cases
- Documentation
- Project Structure
- Contributing
- Security
- License

---

🎯 Overview

A comprehensive, open-source forensic toolkit designed for investigating blockchain-based criminal activity, including illegal gambling operations, fraud networks, money laundering, and asset theft. Built with a focus on evidence quality, court admissibility, and investigative efficiency.

$3

Traditional blockchain explorers provide raw data. This toolkit provides actionable intelligence:

- 🔎 Deep Investigation - Multi-chain transaction analysis with pattern recognition
- 🏷️ Attribution System - Tag and classify addresses with risk assessment
- 📊 Timeline Reconstruction - Chronological event sequencing for court presentation
- 🔗 Fund Flow Tracking - Trace stolen assets through complex laundering chains
- 📄 Report Generation - Export court-ready evidence in multiple formats
- 🗄️ Intelligence Database - Build and maintain threat actor profiles

$3

- Law Enforcement - Building cases against crypto criminals
- Security Researchers - Investigating DeFi exploits and hacks
- Compliance Teams - Monitoring sanctioned addresses and suspicious activity
- Exchanges - Fraud detection and stolen asset freezing
- Victims - Tracking stolen funds for recovery efforts

---

✨ Key Features

$3

- Transaction History Collection - Complete on-chain data gathering across 15+ networks
- Address Attribution & Tagging - Label known criminals, victims, and intermediaries
- Etherscan Label Auto-Import - Automatic public & private tag import from Etherscan
- MCP Integration - AI-powered blockchain analysis via Model Context Protocol
- Timeline Analysis - Reconstruct event sequences with millisecond precision
- Fund Flow Tracing - Multi-hop tracking through mixers and exchanges
- Pattern Detection - Automated identification of suspicious behaviors
- Event Registry - Catalog known hacks, scams, and fraud operations
- Address Clustering - Group related wallets with confidence scoring
- Investigation Management - Full case tracking with evidence and timeline management

$3

- Multi-Format Export - JSON, CSV, Markdown, HTML, TXT reports
- Investigation Reports - Professional ZIP archives with full documentation
- Court-Ready Evidence - Chronological timelines with investigator attribution
- Evidence Management - Attach files, URLs, and cryptographic hashes to cases

$3

- Model Context Protocol - Native support for AI assistant integration
- Etherscan MCP Server - Custom API V2 server for blockchain data queries
- AI Investigation Assistant - Enable Claude Desktop, VSCode, and other MCP clients for on-chain analysis
- Real-Time Data Access - Query balances, transactions, gas prices, and ENS names via AI
- Automated Workflow - Combine AI insights with forensic database for comprehensive analysis
- Court-Ready Reports - Professional documentation with source citations
- Chain-of-Custody - Immutable blockchain verification for all evidence
- Executive Summaries - High-level overviews for non-technical stakeholders

$3

- SQLite Backend - Fast, local, and privacy-preserving
- Persistent Attribution - Build institutional knowledge over time
- Query History - Track investigations and revisit past analyses
- Cross-Reference - Link addresses across multiple investigations
- Database Views - Pre-built queries for common forensic analysis
- Interactive Browser - CLI tool for exploring forensic data

---

🚀 Installation

$3

- Node.js v18.0.0 or higher (required for MCP integration)
- npm v7.0.0 or higher
- Etherscan API Key (Get one free) - Required for all features
- MCP Client (Optional) - Claude Desktop, VSCode with Continue, or other MCP-compatible AI assistant

$3

``bash

Clone the repository

git clone https://github.com/Fused-Gaming/blockchain-forensic-toolkit.git
cd blockchain-forensic-toolkit

Install dependencies

npm install

Configure environment

cp .env.example .env

Edit .env with your required credentials:

- ETHERSCAN_API_KEY (required for all functionality)

- INVESTIGATOR_NAME, EMAIL, ORGANIZATION (required for reports)

`

$3

1. Install MCP Client (Claude Desktop recommended)
2. Configure MCP Server - .mcp.json is pre-configured
3. Start Investigation - Use AI assistants for on-chain queries

See MCP_INTEGRATION.md for complete setup guide.

$3

`bash
npm run forensics
`

You should see the interactive forensic analysis menu.

$3

`bash

Test Etherscan MCP server connectivity

node test-mcp-integration.js

Expected output: ✅ All tests passing with real data

`

---

⚡ Quick Start

$3

`bash

Launch forensic toolkit

npm run forensics

Available options:

1. 🔍 Collect Transaction History

2. 📊 Analyze Timeline

3. 🏷️ Tag/Attribute Address

4. 🔗 Trace Fund Flow Path

5. 📁 Register Known Event

6. 📄 Generate Forensic Report

7. 📋 Investigation Management

`

Example Workflow:

1. Select: "🔍 Collect Transaction History"
2. Choose Chain: Ethereum Mainnet
3. Enter Address: 0x742d35Cc6634C0532925a3b844Bc454e4438f44e
4. Analyze: Review the timeline and patterns
5. Export: Generate a forensic report

See Quick Start Guide for a complete 5-minute tutorial.

---

🌐 Supported Blockchains

| Network | Mainnet | Testnets |
|---------|---------|----------|
| Ethereum | ✅ Mainnet | Sepolia, Holesky |
| Polygon | ✅ Mainnet | Amoy |
| Arbitrum | ✅ One | Sepolia |
| Optimism | ✅ Mainnet | Sepolia |
| Base | ✅ Mainnet | Sepolia |
| zkSync | ✅ Era | Sepolia |
| Blast | ✅ Mainnet | Sepolia |
| Solana | ✅ Mainnet | Devnet |
| Astar zkEVM | ✅ Mainnet | - |
| Zetachain | ✅ Mainnet | Testnet |

Additional chains can be easily added via RPC configuration

---

🛠️ Core Capabilities

$3

Fetch complete transaction records for any address across supported chains.

`bash
npm run forensics

→ Collect Transaction History

`

Features:
- Incoming + Outgoing transactions
- Smart contract interactions
- Token transfers (ERC20, ERC721, ERC1155)
- Internal transactions
- Automatic database storage

$3

Tag addresses with intelligence labels and risk assessments.

Categories:
- hack, exploit, fraud, scam, phishing
- mixer, exchange, sanctioned
- victim, intermediary

Risk Levels: critical, high, medium, low, info

$3

Reconstruct chronological sequences of events.

`bash
npm run forensics

→ Analyze Timeline

`

Outputs:
- Transaction sequences with timestamps
- Flagged address interactions
- Activity patterns and anomalies
- Date-range statistics

$3

Track assets through multiple wallet hops.

`bash
npm run forensics

→ Trace Fund Flow Path

`

Capabilities:
- Multi-hop tracking
- Mixer identification
- Exchange deposit detection
- Volume analysis

$3

Automated identification of suspicious behaviors.

Detects:
- Rapid successive transfers (< 1 minute)
- High-value transactions
- Identical transfer amounts (automation)
- Failed transaction patterns
- Contract interaction sequences

$3

Export comprehensive investigation reports.

`bash
npm run forensics

→ Generate Forensic Report

`

Export Formats:
- JSON - Complete data for programmatic access
- CSV - Transaction log for spreadsheet analysis
- Markdown - Human-readable investigation summary

---

💼 Use Cases

$3

Scenario: Investigating illegal gambling operation

1. Tag known operator addresses
2. Collect transaction history
3. Identify victim deposit addresses
4. Trace fund laundering paths
5. Generate evidence report for prosecution

$3

Scenario: DeFi protocol exploit analysis

1. Register the exploit event
2. Tag exploiter's addresses
3. Analyze attack timeline
4. Detect attack patterns
5. Create attribution cluster
6. Share intelligence with community

$3

Scenario: Stolen fund detection

1. Monitor for deposits from flagged addresses
2. Check reputation on incoming transfers
3. Trace fund origins
4. Freeze and report suspicious deposits
5. Coordinate with law enforcement

$3

Scenario: Stolen NFT tracking

1. Tag thief's wallet
2. Trace NFT movement chain
3. Identify current holder
4. Document chain-of-custody
5. Report to marketplaces for freezing

---

📚 Documentation

$3

- Quick Start Guide - 5-minute tutorial for beginners
- Forensics Guide - Complete toolkit reference (500+ lines)
- Investigation Examples - 5 real-world workflows
- Project Summary - Mission and capabilities overview

$3

- MCP Integration Guide - AI-powered blockchain analysis setup
- Etherscan Auto-Import - Automatic label import documentation
- Database Setup - Database browser and query guide
- Database README - Complete database documentation

$3

- Contributing Guide - How to contribute code or intelligence
- Security Policy - Responsible disclosure guidelines
- Code of Conduct - Community standards
- License - ISC License details

---

📁 Project Structure

`
FUCKIN-DANS-ASS/
├── forensics/ # Core forensic toolkit
│ ├── index.js # Interactive CLI
│ ├── transaction-fetcher.js # On-chain data collection + auto-import
│ ├── attribution-manager.js # Address tagging system
│ ├── timeline-analyzer.js # Event reconstruction
│ ├── report-exporter.js # Evidence generation
│ ├── etherscan-label-importer.js # Etherscan API v2 integration
│ ├── intelligence-importer.js # Threat intelligence imports
│ └── investigation-reporter.js # Investigation report generator
├── database/
│ ├── db.js # SQLite schema & queries
│ ├── sql-browser.js # Interactive database browser
│ ├── README.md # Database documentation
│ └── USEFUL_QUERIES.sql # 50+ pre-built forensic queries
├── docs/ # Comprehensive documentation
│ ├── FORENSICS_GUIDE.md
│ ├── INVESTIGATION_EXAMPLES.md
│ ├── QUICK_START.md
│ └── SUMMARY.md
├── getWalletContracts/ # Basic wallet queries
├── viewHistory/ # Investigation history viewer
├── voice/ # Optional narrator system
├── .env.example # Environment template
├── .mcp.json # MCP server configuration
├── MCP_INTEGRATION.md # MCP setup guide
├── ETHERSCAN_AUTO_IMPORT.md # Auto-import documentation
├── DATABASE_SETUP.md # Database quick start
├── package.json # Dependencies & scripts
├── README.md # This file
├── CONTRIBUTING.md # Contribution guidelines
├── SECURITY.md # Security policy
├── CODE_OF_CONDUCT.md # Community standards
└── LICENSE # ISC License
`

---

🤝 Contributing

We welcome contributions from the security research and blockchain investigation community!

$3

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

$3

- 🔗 Chain Support - Add new blockchain integrations
- 🧠 Pattern Detection - Improve anomaly detection algorithms
- 📊 Reporting - Enhance export formats and templates
- 🗄️ Intelligence - Contribute known bad actor addresses
- 📚 Documentation - Improve guides and examples
- 🐛 Bug Fixes - Report and fix issues

See CONTRIBUTING.md for detailed guidelines.

---

🔒 Security

$3

If you discover a security vulnerability, please follow our Security Policy.

DO NOT open public issues for security vulnerabilities.

$3

- All data stored locally (SQLite database)
- No telemetry or external data transmission
- API keys stored in .env (git-ignored)
- Investigation data is private by default

$3

- Never commit .env files with API keys
- Regularly update dependencies for security patches
- Use read-only API keys when possible
- Encrypt sensitive investigation databases

---

⚖️ Legal & Ethical Use

$3

This toolkit is designed for legitimate investigative purposes:

✅ Law enforcement investigations
✅ Security research and threat intelligence
✅ Compliance and regulatory monitoring
✅ Authorized incident response
✅ Asset recovery for verified victims

$3

❌ Harassment, doxxing, or stalking
❌ Creating fabricated evidence
❌ Unauthorized surveillance
❌ Privacy violations
❌ Illegal or unethical activities

$3

All analyzed data is public blockchain information:
- Publicly available on-chain
- Immutable and independently verifiable
- Not obtained through unauthorized access
- Court-admissible as evidence

Use responsibly. Investigate legally. Report ethically.

---

📦 Version Management & Releases

This project uses a VERSION.md system for managing releases and versioning.

$3

See VERSION.md for the current version and changelog.

$3

To bump the version for a new release:

`bash

Bump patch version (bug fixes)

npm run version:bump:patch

Bump minor version (new features)

npm run version:bump:minor

Bump major version (breaking changes)

npm run version:bump:major

Check current version

npm run version:check
`

$3

1. Update VERSION.md with changes
2. Run version bump script
3. Update CHANGELOG.md if needed
4. Create a pull request
5. Merge PR to master to trigger automated release

Releases are automatically created via GitHub Actions when a PR is merged to master.

---

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

`
Copyright (c) 2024 Fused-Gaming

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
``

---

🙏 Acknowledgments

- Alchemy - Multi-chain RPC infrastructure
- Etherscan - Blockchain explorer and API services
- Better-SQLite3 - Fast, synchronous SQLite database
- Archiver - ZIP archive creation for report bundling
- Node.js Community - Excellent tooling ecosystem
- Model Context Protocol - AI integration framework
- Blockchain Security Researchers - Pioneering on-chain forensics

---

📞 Support & Community

- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: docs/

---