https://github.com/edycutjong/nansenredstring
🔴 On-chain forensic investigation engine — BFS wallet graph traversal, financial enrichment, and interactive 3D WebGL visualization. Built on Nansen CLI.
https://github.com/edycutjong/nansenredstring
3d-visualization blockchain cli defi forensics investigation nansen typescript wallet-analysis web3 webgl
Last synced: 2 months ago
JSON representation
🔴 On-chain forensic investigation engine — BFS wallet graph traversal, financial enrichment, and interactive 3D WebGL visualization. Built on Nansen CLI.
- Host: GitHub
- URL: https://github.com/edycutjong/nansenredstring
- Owner: edycutjong
- License: mit
- Created: 2026-04-06T23:26:48.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-07T02:03:18.000Z (2 months ago)
- Last Synced: 2026-04-07T03:23:43.341Z (2 months ago)
- Topics: 3d-visualization, blockchain, cli, defi, forensics, investigation, nansen, typescript, wallet-analysis, web3, webgl
- Language: TypeScript
- Homepage: https://redstring.edycu.dev
- Size: 28.4 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🔴 RedString — On-Chain Forensic Investigation Engine
```text
____ __ _____ __ _
/ __ \___ ____/ / / ___// /______(_)___ ____
/ /_/ / _ \/ __ / \__ \/ __/ ___/ / __ \/ __ `/
/ _, _/ __/ /_/ / ___/ / /_/ / / / / / / /_/ /
/_/ |_|\___/\__,_/ /____/\__/_/ /_/_/ /_/\__, /
/____/
```
[](https://github.com/edycutjong/NansenRedString/actions)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](LICENSE)
### 🔴 [Live Demo → redstring.edycu.dev](https://redstring.edycu.dev/)
**Map wallet networks as interactive 3D graphs.** RedString is a forensic investigation CLI that wraps the [Nansen CLI](https://docs.nansen.ai) to perform BFS traversal of on-chain wallet connections, enrich nodes with financial intelligence, and render self-contained WebGL visualizations.
> Built for the **Nansen CLI Build Challenge — Week 4**
---
## 🎬 Demo
---
## ✨ Features
- 🕵️ **BFS Graph Traversal** — Discover wallet networks with configurable depth (1–3) and width (5–20)
- 💰 **Financial Enrichment** — Labels, balances, 30d PnL, DeFi protocol exposure per node
- 🌐 **3D WebGL Visualization** — Self-contained HTML with auto-orbit cameras, particle effects, and screenshot export
- 🔍 **OSINT Integration** — Off-chain intelligence via Nansen web search
- ⚡ **Disk Cache** — SHA256-keyed persistent cache to minimize API costs (configurable TTLs)
- 📊 **Telemetry Receipt** — Forensic audit trail of every API call with latency tracking
- 🎭 **Mock Mode** — Full offline development with synthetic data (`NANSEN_MOCK=true`)
## 🏗️ Architecture
```
redstring investigate 0xdead... --depth 2 --width 10
│
├─── BFS Engine (graph-builder.ts)
│ ├── profiler trace → connections
│ ├── profiler counterparties → fallback
│ └── enrichNode → labels, balance, PnL, DeFi
│
├─── OSINT Layer (osint.ts)
│ └── web search → off-chain intelligence
│
├─── Terminal Report (terminal-report.ts)
│ └── Palantir-aesthetic forensic summary
│
├─── HTML Renderer (html-renderer.ts)
│ └── 3D force-directed graph (3d-force-graph)
│
└─── Telemetry (telemetry.ts)
└── API call receipt with cache hit rates
```
## 🚀 Quick Start
### Prerequisites
- **Node.js** ≥ 18
- **Nansen CLI** installed and authenticated (`npm i -g @nansen/cli`)
### Install & Run
```bash
# Clone
git clone https://github.com/edycutjong/nansen-redstring.git
cd nansen-redstring
# Install dependencies
npm install
# Run in mock mode (no API key needed)
NANSEN_MOCK=true npx tsx src/index.ts investigate 0xdead...beef
# Run with live Nansen API
npx tsx src/index.ts investigate 0xdead...beef --depth 2 --width 10
```
### Global Install
```bash
npm run build
npm link
redstring investigate 0xdead...beef
```
## 📖 Commands
### `investigate
`
Core forensic command. Traces wallet connections via BFS and renders a 3D graph.
| Flag | Description | Default |
|------|-------------|---------|
| `-d, --depth ` | BFS traversal depth (1–3) | `2` |
| `-w, --width ` | Max counterparties per node (5–20) | `10` |
| `-c, --chain ` | Blockchain network | `ethereum` |
| `-m, --min-volume ` | Minimum USD volume filter | `0` |
| `--osint` | Include off-chain web search | `false` |
| `--no-cache` | Bypass disk cache | `false` |
| `--no-open` | Skip auto-opening browser | `false` |
| `--json` | Output raw graph JSON | `false` |
| `-o, --output ` | Output directory for HTML | `cwd` |
### `compare `
Head-to-head wallet comparison. Shows correlation score, common counterparties, and shared tokens.
| Flag | Description | Default |
|------|-------------|---------|
| `-c, --chain ` | Blockchain network | `ethereum` |
| `--json` | Output raw JSON | `false` |
### `profile
`
Deep wallet profile — labels, balance, PnL, DeFi positions, and recent transactions.
| Flag | Description | Default |
|------|-------------|---------|
| `-c, --chain ` | Blockchain network | `ethereum` |
| `--json` | Output raw JSON | `false` |
## 🎮 3D Visualizer Controls
| Shortcut | Action |
|----------|--------|
| `S` | Screenshot (PNG export) |
| `R` | Reset camera position |
| `L` | Toggle node labels |
| Mouse drag | Rotate view |
| Scroll | Zoom in/out |
| Click node | Open detail panel |
### Node Color Legend
| Color | Meaning |
|-------|---------|
| 🔴 Neon Crimson | Seed / Target wallet |
| 🟡 Cyber Gold | Smart Money |
| 🔵 Neon Cyan | Labeled entity (Exchange, DEX, etc.) |
| ⚫ Dim Slate | Unknown wallet |
| 🔘 Muted Gray | Contract |
## 📸 Gallery
Investigate
Profile
Compare
Compare (Full)
Telemetry Receipt
## 🧪 Development
```bash
# Type check
npm run typecheck
# Lint
npm run lint
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Full CI pipeline (typecheck + lint + test:coverage)
npm run ci
```
### Demo Cast (Suggested Wallets)
| Alias | Address | Why |
|-------|---------|-----|
| jaredfromsubway.eth | `0xae2Fc483527B8EF99EB5D9B44875F005ba1FaE13` | MEV bot operator |
| Wintermute | `0x0000000000000000000000000000000000000000` | Market maker |
| Nomad Exploiter | `0x56D8B635A7C88Fd1104D23d632AF4003B16d0BF6` | Bridge exploit |
## 🔧 Environment Variables
| Variable | Description |
|----------|-------------|
| `NANSEN_MOCK` | Enable synthetic data mode (`true`/`false`) |
| `NANSEN_DEBUG` | Enable verbose API error logging (`true`/`false`) |
## 📁 Project Structure
```
src/
├── index.ts # CLI entry point (Commander.js)
├── commands/
│ ├── investigate.ts # BFS investigation command
│ ├── compare.ts # Wallet comparison command
│ └── profile.ts # Deep wallet profile command
├── lib/
│ ├── graph-builder.ts # BFS traversal engine
│ ├── nansen.ts # Nansen CLI wrapper + caching
│ ├── html-renderer.ts # 3D WebGL HTML generator
│ ├── enricher.ts # Node financial enrichment
│ ├── osint.ts # Off-chain intelligence
│ ├── disk-cache.ts # SHA256-keyed persistent cache
│ ├── telemetry.ts # API call tracking
│ ├── terminal-report.ts # Terminal formatting
│ └── mock.ts # Synthetic data generator
└── types/
├── graph.ts # GraphNode, GraphEdge, GraphData
├── investigation.ts # InvestigationOptions, results
└── wallet.ts # Raw API response shapes
```
## 📄 License
MIT © [edycutjong](https://github.com/edycutjong)