Skip to content

README.md

Latest commit

 

History

History
80 lines (49 loc) · 2.87 KB

README.md

File metadata and controls

80 lines (49 loc) · 2.87 KB

RedThread-Forensics: Forensic Analysis Tool

Overview

This project is a specialized blockchain forensics tool designed to investigate suspicious wallet activity on the Tron (TRC-20) network. It is specifically optimized for tracking USDT (Tether) movements—the primary currency used in modern Ponzi schemes.

Unlike a standard block explorer, this tool recursively traces "hops" (money transfers) across multiple levels to identify where stolen funds are being laundered and where they eventually "sink" (land in an exchange).

Key Features

  • Recursive Tracing: Automatically follows the money across multiple wallet layers (Level 1 → Level 2 → Level 3).
  • Anti-Spam Filtering: Ignores "dust" transactions (small amounts used by scammers to clutter logs).
  • Exchange Detection: Automatically identifies and labels major exchange hot-wallets (Binance, OKX, Huobi, etc.).
  • Interactive Visualization: Generates a draggable, zoomable 3D-physics graph (.html) of the network.
  • Persistent Caching: Saves transaction data locally to stay within API rate limits and speed up repeat investigations.

Setup Instructions

1. Prerequisites

Ensure you have Python 3.8+ installed on your machine.

2. Clone and Install Dependencies

Open your terminal in the project folder and run:

pip install requests networkx pyvis python-dotenv

3. API Key Configuration

This tool uses the Tronscan API.

  1. Get a free API key from Tronscan.org API.
  2. Create a file in your project root named .env.
  3. Add your key to the file like this:
TRONSCAN_API_KEY=your_key_here_without_quotes

4. Running the Investigation

  1. Open the script and update the target address variable with the suspect wallet.
  2. Run the script:
python main_forensics.py
  1. A file named ponzi_map.html will be generated. Open this in any web browser (Chrome, Safari, etc.) to view the interactive map.

Technical Logic & Edge Cases

To ensure accuracy, the tool handles the following blockchain edge cases:

Edge Case Solution
Rate Limiting Uses a 0.25s delay between calls to respect the 5 calls/second limit.
Fake USDT Validates every transaction against the official Tether contract: TR7NHqj....
Exchange "Blobs" Uses a "Sink" list to stop tracing once funds hit a massive exchange wallet (to prevent graph explosion).
Dust Attacks Automatically discards transfers smaller than 5.0 USDT.

📊 Understanding the Output

  • 🔴 Red Node: The Suspect (Starting point).
  • 🔵 Blue Nodes: Intermediate "Layer" wallets used to move money.
  • 🟢 Green Nodes: Known Exchanges (The "Cash-out" points).
  • Arrow Thickness: Represents the volume of USDT moved. Thick lines = High value transfers.