BlockBuster

AI-powered blockchain forensics dashboard that detects suspicious wallets, visualizes risky flows, and escalates alerts with investigation-ready reports.

Table of Contents

• Overview
• Highlights
• Architecture
• UI Preview
• Tech Stack
• Data and Models
• Project Structure
• Quickstart
• Environment Variables
• Running the Apps
• API Map
• Reporting and Alerting
• Troubleshooting
• Security Notes
• License

Overview

BlockBuster pairs a React + Vite frontend with a Flask AI backend to score Ethereum wallets, surface anomaly signals, and streamline investigations with reports and alerting.

Highlights

• Analyzes Ethereum wallet activity and computes multi-model risk signals.
• Visualizes transaction flows, anomalies, hotspots, and suspicious behaviors.
• Runs AI scoring for risk, anomaly, behavior shift, contagion, entity type, and alert priority.
• Generates investigation-ready PDF reports and email escalations with attachments.
• Supports MetaMask login and in-app review workflow (hold, release, freeze decisions).

Architecture

flowchart LR
  A[React + Vite Frontend] -->|REST API| B[Flask Backend]
  B --> C[Blockscout API]
  B --> D[Etherscan Fallback]
  B --> E[Local Dataset CSV]
  B --> F[Trained ML Models]
  A --> G[EmailJS]
  A --> H[jsPDF Report Export]

Loading

UI Preview

Dashboard	Login

Transaction Flow	Transaction Details

Suspicious Activity	Alert Monitor

Wallet Analyzer	Profile Risk Scoring

Report Generation	Workflow Overview

Tech Stack

• Frontend: React 18, Vite, TypeScript, Recharts, react-simple-maps, jsPDF, EmailJS
• Backend: Flask, Flask-CORS, pandas, scikit-learn, joblib, requests
• Infra helpers: PostCSS, Tailwind, ESLint, ts-node for tooling

Data and Models

• Transaction dataset: data/transaction_dataset.csv
• External intel: data/external
• Trained artifacts: backend/models
• Training and orchestration: backend/multi_model_trainer.py

Project Structure

BlockBuster/
  src/                  # React app (routes, pages, API clients, UI components)
  backend/              # Flask API + model training/prediction
  data/                 # Local datasets and external intel files
  images/               # Product and architecture visuals
  public/               # Static assets (logo, favicons)

Primary routes are configured in src/app/routes.ts.

Quickstart

Prerequisites

• Node.js 18+ and npm
• Python 3.10+
• Git

Clone and install frontend dependencies

git clone <your-repo-url>
cd BlockBuster
npm install

Configure frontend environment

Create root .env from .env.example:

VITE_API_BASE_URL=http://localhost:5000
VITE_EMAILJS_SERVICE_ID=your_service_id
VITE_EMAILJS_TEMPLATE_ID=your_template_id
VITE_EMAILJS_PUBLIC_KEY=your_public_key
VITE_EMAIL_ALERT_TO_EMAIL=authority@example.org
VITE_EMAIL_ALERT_TO_NAME=Cyber Crime Investigation Authority
VITE_EMAIL_ALERT_FROM_NAME=BlockBuster Risk Engine
VITE_EMAIL_ALERT_AGENCY=Cyber Crime Investigation Cell
VITE_EMAIL_ALERT_CONTACT_EMAIL=forensics@example.org
VITE_EMAIL_ALERT_CONTACT_PHONE=+1-000-000-0000

Setup backend environment

cd backend
python -m venv .venv

Activate the virtual environment:

• Windows PowerShell: ..\.venv\Scripts\Activate.ps1
• macOS/Linux: source .venv/bin/activate

Install backend dependencies:

pip install -r requirements.txt

Create backend .env at backend/.env with at least:

PORT=5000
FLASK_DEBUG=true

BLOCKSCOUT_BASE_URL=https://eth.blockscout.com/api/v2
BLOCKSCOUT_PAGE_SIZE=100
BLOCKSCOUT_MAX_TX=5000

ETHERSCAN_API_KEY=your_etherscan_key
ETHERSCAN_BASE_URL=https://api.etherscan.io/v2/api
ETHERSCAN_CHAIN_ID=1

TRANSACTION_DATASET_PATH=../data/transaction_dataset.csv
WALLET_ML_MODEL_PATH=./models/wallet_risk_model.joblib
WALLET_ML_MODEL_DIR=./models

Environment Variables

• Frontend: .env in repo root using VITE_ keys listed above.
• Backend: backend/.env for ports, API keys, and model paths.

Running the Apps

Backend (Flask)

cd backend
python app.py

Health check: http://localhost:5000/health

Frontend (Vite)

npm run dev

Default URL: http://localhost:5173

API Map

Defined in backend/app.py:

• GET /health
• GET /
• GET /api/analytics
• GET /api/suspicious
• GET /api/alerts
• POST /analyze_wallet
• GET /api/ml/status
• POST /api/ml/train
• POST /api/ml/predict
• POST /api/ml/train-all
• GET /api/ml/models
• POST /api/ml/predict-all
• POST /api/ml/predict-batch

Reporting and Alerting

• Forensic PDF generation in Wallet Analyzer and Review flows.
• Email escalation with attachment via EmailJS.
• Investigation report payload returned for medium/high-risk wallets.

Troubleshooting

• Frontend API errors: confirm VITE_API_BASE_URL is set and backend is running.
• Backend config errors: verify ETHERSCAN_API_KEY, dataset path, and model directory in backend .env.
• Empty predict-all responses: ensure models exist in backend/models.
• Missing charts or AI sections: confirm /api/analytics?include_ai=true returns data.

Security Notes

• Never commit real API keys or email credentials.
• Keep .env files local and out of source control.
• Restrict CORS in production to your frontend domain.

License

MIT License. See LICENSE.