BlockBuster

AI-powered blockchain forensics dashboard for suspicious wallet detection, investigation workflow, and alert escalation.

What This Project Does

• Analyzes Ethereum wallet activity and computes risk signals.
• Visualizes transaction flows, anomalies, suspicious behavior, and hotspot trends.
• Runs multi-model AI scoring (risk, anomaly, behavior shift, contagion, entity type, alert priority).
• Generates investigation-ready forensic PDF reports.
• Sends escalation alerts by email (with PDF attachment) for higher-risk cases.
• 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

Tech Stack

• Frontend: React 18, Vite, TypeScript, Recharts, react-simple-maps, jsPDF, EmailJS
• Backend: Flask, Flask-CORS, pandas, scikit-learn, joblib, requests
• Data and Models:
• Transaction dataset: data/transaction_dataset.csv
• Trained artifacts: backend/models

Project Structure

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

Main app pages are configured in src/app/routes.ts.

Prerequisites

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

Setup

1) Clone and install frontend dependencies

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

2) 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

3) Setup backend environment

cd backend
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1

macOS/Linux:

source .venv/bin/activate

Install backend dependencies:

pip install -r requirements.txt

Create backend .env file 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

4) Run backend

cd backend
python app.py

API health check:

• http://localhost:5000/health

5) Run frontend

In a new terminal from repo root:

npm run dev

Default Vite URL:

• http://localhost:5173

Available Frontend Scripts

From package.json:

• npm run dev
• npm run build

Core Routes (Frontend)

Configured in src/app/routes.ts:

• /
• /app
• /app/flow
• /app/suspicious
• /app/wallet
• /app/review
• /app/profile
• /app/alerts
• /app/settings

API Endpoints (Backend)

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

AI/ML Capabilities

The backend supports:

• Wallet risk classification
• Transaction anomaly detection
• Counterparty contagion scoring
• Behavior shift detection
• Entity type classification
• Alert prioritization

Model training and prediction orchestration live in backend/multi_model_trainer.py.

Reporting and Alerting

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

Troubleshooting

• Frontend fails to start with API errors.
• Ensure VITE_API_BASE_URL is defined in root .env and backend is running.
• Wallet analysis returns backend configuration errors.
• Check ETHERSCAN_API_KEY and backend .env values.
• Predict-all returns warning with empty models.
• Wallet may not exist in the model dataset; rule-based analysis still works.
• Missing charts or AI sections.
• Confirm /api/analytics?include_ai=true is reachable and backend model files exist.

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.

Hackathon Notes

• This repository includes rapid iteration features for demos: live analysis UI, workflow gates, and generated reports.
• For production hardening, add authentication backend verification, persistent storage, and structured audit logging.

License

MIT License. See LICENSE.