feat: add @trustin/txgraph-core multi-source data layer and embed demo in docs

- Create packages/core with DataSource adapter interface, GraphBuilder (BFS),
  and adapters for TrustIn, Etherscan, and Tronscan
- Add rate limiter, BigInt amount formatter, and transaction aggregator
- Update demo to support data source selection (TrustIn vs On-Chain)
- Embed built demo as iframe in docs site with /demo nav entry
- Update docs to link to live demo instead of v2.trustin.info

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Blackman99

.gitignore

@@ -3,6 +3,7 @@ dist/
 !packages/react/dist/
 .vitepress/dist/
 .vitepress/cache/
+docs/public/demo/
 *.local
 .env
 .DS_Store

docs/.vitepress/config.ts

@@ -13,14 +13,15 @@ export default defineConfig({
     nav: [
       { text: 'Guide', link: '/guide/layer1-product' },
       { text: 'API', link: '/api/components' },
+      { text: 'Demo', link: '/demo' },
       { text: 'GitHub', link: 'https://github.com/Blackman99/txgraph' },
     ],
     sidebar: [
       {
         text: 'Getting Started',
         items: [
           { text: 'Introduction', link: '/' },
-          { text: '🌐 Layer 1: Use Explorer', link: '/guide/layer1-product' },
+          { text: '🌐 Layer 1: Live Demo', link: '/guide/layer1-product' },
           { text: '🤖 Layer 2: AI Agent API', link: '/guide/layer2-agent' },
           { text: '💻 Layer 3: Local Demo', link: '/guide/layer3-demo' },
           { text: '🛠 Layer 4: Build Your Own', link: '/guide/layer4-component' },

docs/.vitepress/theme/DemoFrame.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import { useData } from 'vitepress'
+
+const { isDark } = useData()
+</script>
+
+<template>
+  <div class="demo-frame-container">
+    <iframe
+      :src="`${$frontmatter.demoBase || '/txgraph/demo/'}${isDark ? '' : '?theme=light'}`"
+      class="demo-frame"
+      allow="clipboard-read; clipboard-write"
+    />
+  </div>
+</template>
+
+<style scoped>
+.demo-frame-container {
+  width: 100%;
+  height: calc(100vh - var(--vp-nav-height) - 1px);
+  overflow: hidden;
+}
+
+.demo-frame {
+  width: 100%;
+  height: 100%;
+  border: none;
+}
+</style>

docs/.vitepress/theme/index.ts

@@ -0,0 +1,9 @@
+import DefaultTheme from 'vitepress/theme'
+import DemoFrame from './DemoFrame.vue'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('DemoFrame', DemoFrame)
+  },
+}

docs/demo.md

@@ -0,0 +1,6 @@
+---
+layout: page
+title: Live Demo
+---
+
+<DemoFrame />

docs/guide/layer1-product.md

@@ -1,23 +1,21 @@
-# 🌐 Use TrustIn Explorer
+# 🌐 Try the Live Demo
 
 The fastest way to trace blockchain transactions — no setup, no API key, no code.
 
-## What is TrustIn Explorer?
+## Open the Demo
 
-[TrustIn Explorer](https://v2.trustin.info/explore) is a full-featured AML (Anti-Money Laundering) investigation platform. It provides:
+Go to the [Live Demo](/demo) page to start tracing immediately. The demo supports two data source modes:
 
-- **Visual transaction graph** — trace fund flows across Ethereum and Tron
-- **Risk scoring** — AI-powered risk assessment for every address
-- **Entity tagging** — identify exchanges, mixers, sanctioned addresses
-- **Multi-hop tracing** — follow funds through multiple hops
-- **Inflow & outflow analysis** — see where funds came from and where they went
+- **TrustIn** — uses the TrustIn API with risk scoring and entity tagging
+- **On-Chain** — fetches raw data directly from Etherscan (Ethereum) or Tronscan (Tron)
 
 ## Getting Started
 
-1. Visit [v2.trustin.info](https://v2.trustin.info/explore)
+1. Open the [Live Demo](/demo)
 2. Enter a blockchain address (Ethereum or Tron)
-3. Select direction: **Inflow** / **Outflow** / **Both**
-4. Click **Explore** — the graph loads instantly
+3. Select data source: **TrustIn** or **On-Chain**
+4. Select direction: **Inflow** / **Outflow** / **All**
+5. Click **Explore** — the graph loads instantly
 
 ## Features
 
@@ -32,6 +30,10 @@ Each node (address) is colored by risk:
 | 🟢 Green | Low | Verified exchange, known entity |
 | ⚫ Gray | Unknown | No data available |
 
+::: tip
+Risk scoring and entity tags are only available when using the **TrustIn** data source. On-Chain mode shows all nodes as "unknown" risk.
+:::
+
 ### Expanding the Graph
 
 - Click any node to see its details
@@ -44,11 +46,11 @@ Switch between two renderers:
 - **ReactFlow** — best for interactive exploration, drag nodes, zoom
 - **Sigma.js** — best for large graphs (1000+ nodes), WebGL-accelerated
 
-## When to use TrustIn Explorer
+## When to use the Demo
 
-✅ Quick investigation — need an answer now  
-✅ No technical setup required  
-✅ Full feature set including AI risk scoring  
+✅ Quick investigation — need an answer now
+✅ No technical setup required
+✅ Compare TrustIn vs on-chain data
 ✅ Regular compliance checks
 
 → For programmatic access, see [Layer 2: AI Agent API](/guide/layer2-agent). To run locally, see [Layer 3: Local Demo](/guide/layer3-demo). To embed in your own app, see [Layer 4: Build Your Own](/guide/layer4-component).

docs/guide/layer3-demo.md

@@ -1,6 +1,10 @@
 # 💻 Run Demo Locally
 
-Run TxGraph as a local Vite app connected to the TrustIn API. Ideal for evaluation, internal tooling, or as a starting point for your own integration.
+Run TxGraph as a local Vite app with multi-source support (TrustIn API or on-chain via Etherscan/Tronscan). Ideal for evaluation, internal tooling, or as a starting point for your own integration.
+
+::: tip Try without setup
+You can also try the [Live Demo](/demo) directly in this documentation site — no installation needed.
+:::
 
 ## Prerequisites
 
@@ -25,26 +29,31 @@ Open [http://localhost:5173](http://localhost:5173)
 
 ## Configuration (Optional)
 
-The demo works out of the box without any API key. For higher rate limits, create `examples/local-demo/.env`:
+The demo works out of the box without any API key. For higher rate limits or on-chain API keys, create `examples/local-demo/.env`:
 
 ```env
 VITE_TRUSTIN_API_URL=https://api.trustin.info
 VITE_TRUSTIN_API_KEY=your_api_key_here
+VITE_ETHERSCAN_API_KEY=your_etherscan_key
+VITE_TRONSCAN_API_KEY=your_tronscan_key
 ```
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `VITE_TRUSTIN_API_URL` | `https://api.trustin.info` | API base URL |
-| `VITE_TRUSTIN_API_KEY` | — | Optional API key for higher rate limits |
+| `VITE_TRUSTIN_API_URL` | `https://api.trustin.info` | TrustIn API base URL |
+| `VITE_TRUSTIN_API_KEY` | — | Optional TrustIn API key for higher rate limits |
+| `VITE_ETHERSCAN_API_KEY` | — | Optional Etherscan API key (5 req/s free tier) |
+| `VITE_TRONSCAN_API_KEY` | — | Optional Tronscan API key |
 
 ## Using the Demo
 
 1. **Enter an address** — Ethereum (0x…) or Tron (T…)
 2. **Select chain** — Ethereum or Tron
-3. **Choose direction** — Outflow / Inflow / Both
-4. **Set date range** (optional) — filter by transaction date
-5. **Click Explore** — graph renders immediately
-6. **Toggle renderer** — switch between ReactFlow and Sigma.js
+3. **Select data source** — TrustIn (with risk scoring) or On-Chain (Etherscan/Tronscan)
+4. **Choose direction** — Outflow / Inflow / All
+5. **Set date range** (optional) — filter by transaction date
+6. **Click Explore** — graph renders immediately
+7. **Toggle renderer** — switch between ReactFlow and Sigma.js
 
 ### Node Interactions
 
@@ -81,7 +90,7 @@ If you use [Claude Code](https://claude.com/claude-code), the `/trace-graph` ski
 examples/local-demo/
 ├── src/
 │   ├── App.tsx          # Main UI with controls
-│   ├── api.ts           # TrustIn API client
+│   ├── api.ts           # Multi-source API client (TrustIn + on-chain)
 │   └── main.tsx         # React entry point
 ├── .env.example         # Environment template
 ├── index.html
@@ -109,4 +118,4 @@ The demo is intentionally simple. Common customizations:
 - **Multiple addresses** — extend the UI for batch exploration
 - **Export** — add JSON/CSV export of graph data
 
-For deeper integration, see [Layer 3: Build Your Own](/guide/layer3-component).
+For deeper integration, see [Layer 4: Build Your Own](/guide/layer4-component).

docs/index.md

@@ -17,18 +17,18 @@ hero:
 
 features:
   - icon: 🌐
-    title: Use TrustIn Explorer
-    details: Instantly trace transactions at v2.trustin.info — no setup required. Full-featured AML investigation tool.
-    link: /guide/layer1-product
-    linkText: Open Explorer
+    title: Try Live Demo
+    details: Instantly trace transactions in the browser — no setup required. Supports TrustIn API and on-chain data sources (Etherscan, Tronscan).
+    link: /demo
+    linkText: Open Demo
   - icon: 🤖
     title: AI Agent API
     details: Self-register your AI agent in one request and start tracing addresses immediately. No account needed — 200 requests/day free quota. MCP-compatible.
     link: /guide/layer2-agent
     linkText: Agent Setup
   - icon: 💻
-    title: Run Demo Locally
-    details: Clone the example project and connect to TrustIn API with your API key. Full control over data and UI.
+    title: Run Locally
+    details: Clone the repo and run TxGraph locally for full control. Connect to TrustIn API or use on-chain data via Etherscan/Tronscan.
     link: /guide/layer3-demo
     linkText: Setup Guide
   - icon: 🛠

examples/local-demo/package.json

@@ -3,10 +3,13 @@
   "private": true,
   "dependencies": {
     "@trustin/txgraph": "workspace:*",
+    "@trustin/txgraph-core": "workspace:*",
     "react": "^18",
     "react-dom": "^18"
   },
   "devDependencies": {
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
     "@vitejs/plugin-react": "^4",
     "typescript": "^5",
     "vite": "^5"

examples/local-demo/src/App.tsx

@@ -1,7 +1,8 @@
 import React, { useState, useCallback, useEffect } from 'react'
 import { GraphExplorer, GraphExplorerSigma } from '@trustin/txgraph'
 import type { TxNode, TxGraph } from '@trustin/txgraph'
-import { exploreGraph } from './api'
+import { exploreGraph, expandNode } from './api'
+import type { DataSourceType } from './api'
 
 type Renderer = 'reactflow' | 'sigma'
 type Chain = 'Ethereum' | 'Tron'
@@ -70,6 +71,7 @@ export default function App() {
   const [token, setToken] = useState(qp.token)
   const [fromDate, setFromDate] = useState(qp.fromDate)
   const [toDate, setToDate] = useState(qp.toDate)
+  const [dataSource, setDataSource] = useState<DataSourceType>('trustin')
   const [renderer, setRenderer] = useState<Renderer>('reactflow')
   const [graph, setGraph] = useState<TxGraph | null>(null)
   const [loading, setLoading] = useState(false)
@@ -106,14 +108,15 @@ export default function App() {
         token: token || undefined,
         fromDate: fromDate || undefined,
         toDate: toDate || undefined,
+        dataSource,
       })
       setGraph(data)
     } catch (e) {
       setError(e instanceof Error ? e.message : String(e))
     } finally {
       setLoading(false)
     }
-  }, [address, chain, direction, token, fromDate, toDate])
+  }, [address, chain, direction, token, fromDate, toDate, dataSource])
 
   // Auto-explore when opened with query params
   const autoExploreRef = React.useRef(qp.autoExplore)
@@ -128,32 +131,24 @@ export default function App() {
     if (!graph) return
     setExpandingNode(addr)
     try {
-      const data = await exploreGraph({
-        address: addr,
-        chain,
-        direction,
-        token: token || undefined,
-        maxDepth: 1,
-      })
-      const existingAddrs = new Set(graph.nodes.map((n) => n.address))
-      const newNodes = data.nodes.filter((n) => !existingAddrs.has(n.address))
-      const existingEdgeKeys = new Set(graph.edges.map((e) => `${e.from}->${e.to}`))
-      const newEdges = data.edges.filter((e) => !existingEdgeKeys.has(`${e.from}->${e.to}`))
-      setGraph({
-        nodes: [...graph.nodes, ...newNodes],
-        edges: [...graph.edges, ...newEdges],
-        stats: {
-          total_nodes: graph.nodes.length + newNodes.length,
-          total_edges: graph.edges.length + newEdges.length,
-          stopped_nodes: graph.stats?.stopped_nodes ?? 0,
+      const merged = await expandNode(
+        {
+          address: addr,
+          chain,
+          direction,
+          token: token || undefined,
+          maxDepth: 1,
+          dataSource,
         },
-      })
+        graph
+      )
+      setGraph(merged)
     } catch (e) {
       console.error('Expand failed:', e)
     } finally {
       setExpandingNode(null)
     }
-  }, [graph, chain, direction, token])
+  }, [graph, chain, direction, token, dataSource])
 
   const handleNodeDelete = useCallback((addr: string) => {
     if (!graph) return
@@ -228,6 +223,16 @@ export default function App() {
           <option>Tron</option>
         </select>
 
+        {/* Data source */}
+        <select
+          value={dataSource}
+          onChange={(e) => setDataSource(e.target.value as DataSourceType)}
+          style={inputStyle}
+        >
+          <option value="trustin">TrustIn</option>
+          <option value="onchain">On-Chain</option>
+        </select>
+
         {/* Direction */}
         <select
           value={direction}
@@ -321,7 +326,9 @@ export default function App() {
           <div style={{ height: '100%', display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 12, color: c.dimmed }}>
             <div style={{ fontSize: 48 }}>🔍</div>
             <div style={{ fontSize: 15 }}>Enter an address and click <strong>Explore</strong></div>
-            <div style={{ fontSize: 12, color: c.dimmed }}>Powered by TrustIn API</div>
+            <div style={{ fontSize: 12, color: c.dimmed }}>
+              {dataSource === 'trustin' ? 'Powered by TrustIn API' : `On-Chain via ${chain === 'Tron' ? 'Tronscan' : 'Etherscan'}`}
+            </div>
           </div>
         )}
         {(graph || loading) && (