Professional blockchain forensic analysis toolkit with AI-powered MCP integration, Etherscan API V2 support, and comprehensive investigation management
npm install blockchain-forensic-toolkitbash
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.
``