{"id":48464086,"url":"https://github.com/edycutjong/nansenredstring","last_synced_at":"2026-04-07T04:01:04.513Z","repository":{"id":349667184,"uuid":"1203306358","full_name":"edycutjong/NansenRedString","owner":"edycutjong","description":"🔴 On-chain forensic investigation engine — BFS wallet graph traversal, financial enrichment, and interactive 3D WebGL visualization. Built on Nansen CLI.","archived":false,"fork":false,"pushed_at":"2026-04-07T02:03:18.000Z","size":29795,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T03:23:43.341Z","etag":null,"topics":["3d-visualization","blockchain","cli","defi","forensics","investigation","nansen","typescript","wallet-analysis","web3","webgl"],"latest_commit_sha":null,"homepage":"https://redstring.edycu.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edycutjong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T23:26:48.000Z","updated_at":"2026-04-07T02:03:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/edycutjong/NansenRedString","commit_stats":null,"previous_names":["edycutjong/nansenredstring"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/edycutjong/NansenRedString","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2FNansenRedString","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2FNansenRedString/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2FNansenRedString/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2FNansenRedString/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edycutjong","download_url":"https://codeload.github.com/edycutjong/NansenRedString/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2FNansenRedString/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31499193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-visualization","blockchain","cli","defi","forensics","investigation","nansen","typescript","wallet-analysis","web3","webgl"],"created_at":"2026-04-07T04:00:25.265Z","updated_at":"2026-04-07T04:01:04.488Z","avatar_url":"https://github.com/edycutjong.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔴 RedString — On-Chain Forensic Investigation Engine\n\n```text\n    ____          __  _____ __       _             \n   / __ \\___  ____/ / / ___// /______(_)___  ____  \n  / /_/ / _ \\/ __  /  \\__ \\/ __/ ___/ / __ \\/ __ `/\n / _, _/  __/ /_/ /  ___/ / /_/ /  / / / / / /_/ / \n/_/ |_|\\___/\\__,_/  /____/\\__/_/  /_/_/ /_/\\__, /  \n                                          /____/   \n```\n\n[![CI](https://github.com/edycutjong/NansenRedString/actions/workflows/ci.yml/badge.svg)](https://github.com/edycutjong/NansenRedString/actions)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green?logo=node.js)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](LICENSE)\n\n### 🔴 [Live Demo → redstring.edycu.dev](https://redstring.edycu.dev/)\n\n**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.\n\n\u003e Built for the **Nansen CLI Build Challenge — Week 4**\n\n---\n\n## 🎬 Demo\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/demo.gif\" alt=\"RedString Demo\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n---\n\n## ✨ Features\n\n- 🕵️ **BFS Graph Traversal** — Discover wallet networks with configurable depth (1–3) and width (5–20)\n- 💰 **Financial Enrichment** — Labels, balances, 30d PnL, DeFi protocol exposure per node\n- 🌐 **3D WebGL Visualization** — Self-contained HTML with auto-orbit cameras, particle effects, and screenshot export\n- 🔍 **OSINT Integration** — Off-chain intelligence via Nansen web search\n- ⚡ **Disk Cache** — SHA256-keyed persistent cache to minimize API costs (configurable TTLs)\n- 📊 **Telemetry Receipt** — Forensic audit trail of every API call with latency tracking\n- 🎭 **Mock Mode** — Full offline development with synthetic data (`NANSEN_MOCK=true`)\n\n## 🏗️ Architecture\n\n```\nredstring investigate 0xdead... --depth 2 --width 10\n        │\n        ├─── BFS Engine (graph-builder.ts)\n        │    ├── profiler trace → connections\n        │    ├── profiler counterparties → fallback\n        │    └── enrichNode → labels, balance, PnL, DeFi\n        │\n        ├─── OSINT Layer (osint.ts)\n        │    └── web search → off-chain intelligence\n        │\n        ├─── Terminal Report (terminal-report.ts)\n        │    └── Palantir-aesthetic forensic summary\n        │\n        ├─── HTML Renderer (html-renderer.ts)\n        │    └── 3D force-directed graph (3d-force-graph)\n        │\n        └─── Telemetry (telemetry.ts)\n             └── API call receipt with cache hit rates\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Node.js** ≥ 18\n- **Nansen CLI** installed and authenticated (`npm i -g @nansen/cli`)\n\n### Install \u0026 Run\n\n```bash\n# Clone\ngit clone https://github.com/edycutjong/nansen-redstring.git\ncd nansen-redstring\n\n# Install dependencies\nnpm install\n\n# Run in mock mode (no API key needed)\nNANSEN_MOCK=true npx tsx src/index.ts investigate 0xdead...beef\n\n# Run with live Nansen API\nnpx tsx src/index.ts investigate 0xdead...beef --depth 2 --width 10\n```\n\n### Global Install\n\n```bash\nnpm run build\nnpm link\nredstring investigate 0xdead...beef\n```\n\n## 📖 Commands\n\n### `investigate \u003caddress\u003e`\n\nCore forensic command. Traces wallet connections via BFS and renders a 3D graph.\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-d, --depth \u003cn\u003e` | BFS traversal depth (1–3) | `2` |\n| `-w, --width \u003cn\u003e` | Max counterparties per node (5–20) | `10` |\n| `-c, --chain \u003cchain\u003e` | Blockchain network | `ethereum` |\n| `-m, --min-volume \u003cusd\u003e` | Minimum USD volume filter | `0` |\n| `--osint` | Include off-chain web search | `false` |\n| `--no-cache` | Bypass disk cache | `false` |\n| `--no-open` | Skip auto-opening browser | `false` |\n| `--json` | Output raw graph JSON | `false` |\n| `-o, --output \u003cdir\u003e` | Output directory for HTML | `cwd` |\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/terminal-investigate.png\" alt=\"Investigate Command\" width=\"680\" /\u003e\n\u003c/p\u003e\n\n### `compare \u003caddress-a\u003e \u003caddress-b\u003e`\n\nHead-to-head wallet comparison. Shows correlation score, common counterparties, and shared tokens.\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-c, --chain \u003cchain\u003e` | Blockchain network | `ethereum` |\n| `--json` | Output raw JSON | `false` |\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/terminal-compare.png\" alt=\"Compare Command\" width=\"680\" /\u003e\n\u003c/p\u003e\n\n### `profile \u003caddress\u003e`\n\nDeep wallet profile — labels, balance, PnL, DeFi positions, and recent transactions.\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-c, --chain \u003cchain\u003e` | Blockchain network | `ethereum` |\n| `--json` | Output raw JSON | `false` |\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/terminal-profile.png\" alt=\"Profile Command\" width=\"680\" /\u003e\n\u003c/p\u003e\n\n## 🎮 3D Visualizer Controls\n\n| Shortcut | Action |\n|----------|--------|\n| `S` | Screenshot (PNG export) |\n| `R` | Reset camera position |\n| `L` | Toggle node labels |\n| Mouse drag | Rotate view |\n| Scroll | Zoom in/out |\n| Click node | Open detail panel |\n\n### Node Color Legend\n\n| Color | Meaning |\n|-------|---------|\n| 🔴 Neon Crimson | Seed / Target wallet |\n| 🟡 Cyber Gold | Smart Money |\n| 🔵 Neon Cyan | Labeled entity (Exchange, DEX, etc.) |\n| ⚫ Dim Slate | Unknown wallet |\n| 🔘 Muted Gray | Contract |\n\n## 📸 Gallery\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshots/terminal-investigate.png\" width=\"400\" /\u003e\u003cbr /\u003e\u003cb\u003eInvestigate\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshots/terminal-profile.png\" width=\"400\" /\u003e\u003cbr /\u003e\u003cb\u003eProfile\u003c/b\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshots/terminal-compare.png\" width=\"400\" /\u003e\u003cbr /\u003e\u003cb\u003eCompare\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshots/terminal-compare-full.png\" width=\"400\" /\u003e\u003cbr /\u003e\u003cb\u003eCompare (Full)\u003c/b\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" colspan=\"2\"\u003e\u003cimg src=\"docs/screenshots/terminal-telemetry.png\" width=\"400\" /\u003e\u003cbr /\u003e\u003cb\u003eTelemetry Receipt\u003c/b\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## 🧪 Development\n\n```bash\n# Type check\nnpm run typecheck\n\n# Lint\nnpm run lint\n\n# Run tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Full CI pipeline (typecheck + lint + test:coverage)\nnpm run ci\n```\n\n### Demo Cast (Suggested Wallets)\n\n| Alias | Address | Why |\n|-------|---------|-----|\n| jaredfromsubway.eth | `0xae2Fc483527B8EF99EB5D9B44875F005ba1FaE13` | MEV bot operator |\n| Wintermute | `0x0000000000000000000000000000000000000000` | Market maker |\n| Nomad Exploiter | `0x56D8B635A7C88Fd1104D23d632AF4003B16d0BF6` | Bridge exploit |\n\n## 🔧 Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `NANSEN_MOCK` | Enable synthetic data mode (`true`/`false`) |\n| `NANSEN_DEBUG` | Enable verbose API error logging (`true`/`false`) |\n\n## 📁 Project Structure\n\n```\nsrc/\n├── index.ts              # CLI entry point (Commander.js)\n├── commands/\n│   ├── investigate.ts    # BFS investigation command\n│   ├── compare.ts        # Wallet comparison command\n│   └── profile.ts        # Deep wallet profile command\n├── lib/\n│   ├── graph-builder.ts  # BFS traversal engine\n│   ├── nansen.ts         # Nansen CLI wrapper + caching\n│   ├── html-renderer.ts  # 3D WebGL HTML generator\n│   ├── enricher.ts       # Node financial enrichment\n│   ├── osint.ts          # Off-chain intelligence\n│   ├── disk-cache.ts     # SHA256-keyed persistent cache\n│   ├── telemetry.ts      # API call tracking\n│   ├── terminal-report.ts # Terminal formatting\n│   └── mock.ts           # Synthetic data generator\n└── types/\n    ├── graph.ts          # GraphNode, GraphEdge, GraphData\n    ├── investigation.ts  # InvestigationOptions, results\n    └── wallet.ts         # Raw API response shapes\n```\n\n## 📄 License\n\nMIT © [edycutjong](https://github.com/edycutjong)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedycutjong%2Fnansenredstring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedycutjong%2Fnansenredstring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedycutjong%2Fnansenredstring/lists"}