ShadowTrace-XAI

ShadowTrace-XAI is an explainable Bitcoin transaction forensics platform built for Smart India Hackathon 2026. It helps investigators ingest transaction data, detect suspicious flows, inspect graph evidence, and export court-ready dossiers with a cryptographic chain of custody.

• Project Title: ShadowTrace-XAI
• PS ID: SIH26146
• PS Title: AI-Powered Monitoring & Analysis of Bitcoin Transaction Traffic
• Category: Software
• Theme: Blockchain & Cybersecurity
• Team Name: LocalDost

Illicit cryptocurrency flows move quickly through peel chains, exchange cash-outs, darknet wallets, ransomware clusters, and other multi-hop patterns. Manual blockchain review is slow, expensive, and difficult to explain in a way that supports regulatory action or legal review.

ShadowTrace-XAI combines graph analytics, machine learning, explainable AI, and local evidence generation. The system builds a transaction graph, scores risky transactions, shows the surrounding money movement and network metadata, and generates a PDF dossier that preserves the evidence trail.

• CSV/JSON transaction ingestion with validation and enrichment.
• Wallet, transaction, IP, ASN, exchange, peel-chain, and timing graph signals.
• GCN/GraphSAGE-based suspicious transaction scoring.
• Explainable AI breakdowns for each alert.
• Investigator dashboard with alert queue, graph view, evidence view, dossier generation, and human feedback.
• Local SQLite/DuckDB-backed workflow suitable for offline or edge deployment.
• SHA-256 custody hashes and WeasyPrint dossier exports for review.
• Compatibility endpoints for the team ML prototype and feedback loop.

See docs/architecture.md.

Investigator
  |
  v
React Dashboard
  |
  v
FastAPI Backend
  |
  +--> DuckDB / SQLite Evidence Stores
  |
  +--> Graph Builder + Heuristics
  |
  +--> GCN / GraphSAGE Model
  |
  +--> XAI Evidence + Custody Hash
  |
  v
PDF Dossier / Alert Review Output

ShadowTrace-SIH/
|-- README.md
|-- assets/
|   `-- screenshots/
|-- backend/
|-- docs/
|-- frontend/
|-- ml-model/
`-- submission/

• submission/LocalDost_SIH2026_Presentation.pdf

• submission/DEMO.md

Home	Data Ingestion

Alerts	Transaction Graph

Analytics	Forensic Dossier

cd frontend
npm install

cd backend
python -m venv .venv
python -m pip install -r requirements.txt

For final offline Linux setup, follow the stricter instructions in backend/README.md, including wheelhouse and MaxMind GeoIP database requirements.

Start the backend API:

cd backend
python scripts/run_pipeline.py --sample
python -m uvicorn shadowtrace.main:app --host 127.0.0.1 --port 8000

Start the frontend dashboard in another terminal:

cd frontend
npm run dev

The dashboard runs at http://127.0.0.1:5173/ and proxies /api requests to the backend at http://127.0.0.1:8000.

The reviewer can inspect:

• Ranked suspicious transaction alerts.
• N-hop graph evidence around a selected transaction.
• XAI feature attribution for a threat score.
• Investigator feedback recording.
• Downloadable evidence dossiers with custody hashes.

Two large CSV assets are stored as GitHub Release assets instead of normal Git files. Restore instructions are in docs/DATASETS.md.