feat: enhance graph analysis, multi-chain support, and interaction

Phase 1 - Data & Analysis:
- Dynamic token filter extracted from graph edges
- ENS reverse resolution for on-chain EVM queries
- Multi-address batch exploration with graph merging
- Client-side query cache with 5-minute TTL

Phase 2 - Chain Support:
- Generalize EtherscanAdapter for BSC, Polygon, Arbitrum
- Add SUPPORTED_CHAINS registry and chain presets
- Smart address detection (0x no longer forces Ethereum)

Phase 3 - Rendering & Interaction:
- Export graph as PNG/JSON/CSV
- In-graph search by address or ENS name
- Node annotation in selected node panel
- Auto-switch to Sigma renderer for large graphs (>200 nodes)

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

Author: Blackman99

examples/local-demo/package.json

@@ -11,6 +11,7 @@
     "@types/react": "^18",
     "@types/react-dom": "^18",
     "@vitejs/plugin-react": "^4",
+    "html-to-image": "^1.11.13",
     "typescript": "^5",
     "vite": "^5"
   },

examples/local-demo/src/App.tsx

@@ -1,18 +1,21 @@
-import React, { useState, useCallback, useEffect } from 'react'
+import React, { useState, useCallback, useEffect, useMemo } from 'react'
 import { GraphExplorer, GraphExplorerSigma } from '@trustin/txgraph'
 import type { TxNode, TxGraph } from '@trustin/txgraph'
+import { SUPPORTED_CHAINS, type ChainName } from '@trustin/txgraph-core'
 import { exploreGraph, expandNode } from './api'
 import type { DataSourceType } from './api'
 
 type Renderer = 'reactflow' | 'sigma'
-type Chain = 'Ethereum' | 'Tron'
 
-const SAMPLE_ADDRESSES = {
+const SAMPLE_ADDRESSES: Partial<Record<ChainName, string>> = {
   Ethereum: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
   Tron: 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9',
+  BSC: '0x8894e0a0c962cb723c1ef8f1d0de620172a38596',
+  Polygon: '0x8894e0a0c962cb723c1ef8f1d0de620172a38596',
+  Arbitrum: '0x8894e0a0c962cb723c1ef8f1d0de620172a38596',
 }
 
-function detectChain(addr: string): Chain | null {
+function detectChain(addr: string): ChainName | null {
   const trimmed = addr.trim()
   if (/^0x[0-9a-fA-F]{40}$/.test(trimmed)) return 'Ethereum'
   if (/^T[1-9A-HJ-NP-Za-km-z]{33}$/.test(trimmed)) return 'Tron'
@@ -66,7 +69,7 @@ export default function App() {
   const qp = useQueryParams()
   const [isDark, setIsDark] = useState(true)
   const [address, setAddress] = useState(qp.address)
-  const [chain, setChain] = useState<Chain>(qp.chain || (detectChain(qp.address) ?? 'Ethereum'))
+  const [chain, setChain] = useState<ChainName>(qp.chain as ChainName || (detectChain(qp.address) ?? 'Ethereum'))
   const [direction, setDirection] = useState<'in' | 'out' | 'all'>(qp.direction || 'out')
   const [token, setToken] = useState(qp.token)
   const [fromDate, setFromDate] = useState(qp.fromDate)
@@ -78,6 +81,8 @@ export default function App() {
   const [expandingNode, setExpandingNode] = useState<string | null>(null)
   const [selectedAddress, setSelectedAddress] = useState<string | null>(null)
   const [error, setError] = useState<string | null>(null)
+  const [searchQuery, setSearchQuery] = useState('')
+  const [annotations, setAnnotations] = useState<Record<string, string>>({})
 
   useEffect(() => {
     if (isDark) {
@@ -89,6 +94,76 @@ export default function App() {
 
   const c = themeColors(isDark)
 
+  const exportJSON = useCallback(() => {
+    if (!graph) return
+    const blob = new Blob([JSON.stringify(graph, null, 2)], { type: 'application/json' })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = 'txgraph.json'
+    a.click()
+    URL.revokeObjectURL(url)
+  }, [graph])
+
+  const exportCSV = useCallback(() => {
+    if (!graph) return
+    const header = 'from,to,direction,amount,formatted_amount,token,tx_count,last_timestamp\n'
+    const rows = graph.edges.map(e =>
+      [e.from, e.to, e.direction, e.amount, `"${e.formatted_amount}"`, e.token || '', e.tx_count ?? '', e.last_timestamp].join(',')
+    ).join('\n')
+    const blob = new Blob([header + rows], { type: 'text/csv' })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = 'txgraph.csv'
+    a.click()
+    URL.revokeObjectURL(url)
+  }, [graph])
+
+  const exportPNG = useCallback(() => {
+    // Capture the graph container as PNG via canvas
+    const container = document.querySelector('.react-flow, .sigma-container')?.closest('[style]')?.parentElement
+    if (!container) return
+    import('html-to-image').then(({ toPng }) => {
+      toPng(container as HTMLElement, { backgroundColor: isDark ? '#0f172a' : '#f8fafc' }).then(dataUrl => {
+        const a = document.createElement('a')
+        a.href = dataUrl
+        a.download = 'txgraph.png'
+        a.click()
+      }).catch(console.error)
+    }).catch(console.error)
+  }, [isDark])
+
+  const LARGE_GRAPH_THRESHOLD = 200
+
+  // Auto-switch to Sigma for large graphs
+  useEffect(() => {
+    if (graph && graph.nodes.length > LARGE_GRAPH_THRESHOLD && renderer === 'reactflow') {
+      setRenderer('sigma')
+    }
+  }, [graph])
+
+  // Search within graph: find first matching node by address or ENS tag
+  const handleSearch = useCallback(() => {
+    if (!graph || !searchQuery.trim()) return
+    const q = searchQuery.trim().toLowerCase()
+    const match = graph.nodes.find(n =>
+      n.address.toLowerCase().includes(q) ||
+      n.tags.some(t => (t.name || '').toLowerCase().includes(q))
+    )
+    if (match) setSelectedAddress(match.address)
+  }, [graph, searchQuery])
+
+  // Extract unique token symbols from graph edges for dynamic filtering
+  const availableTokens = useMemo(() => {
+    if (!graph) return []
+    const tokens = new Set<string>()
+    for (const edge of graph.edges) {
+      if (edge.token) tokens.add(edge.token)
+    }
+    return Array.from(tokens).sort()
+  }, [graph])
+
   const handleExplore = useCallback(async () => {
     // Clear query params after first explore to avoid re-triggering
     if (window.location.search) {
@@ -193,13 +268,15 @@ export default function App() {
         {/* Address input */}
         <input
           type="text"
-          placeholder="Enter blockchain address…"
+          placeholder="Enter address (or multiple separated by comma)…"
           value={address}
           onChange={(e) => {
             const val = e.target.value
             setAddress(val)
             const detected = detectChain(val)
-            if (detected) setChain(detected)
+            // Only auto-switch chain for Tron (unambiguous T prefix).
+            // 0x addresses are valid on all EVM chains, so keep current selection.
+            if (detected === 'Tron') setChain('Tron')
           }}
           onKeyDown={(e) => e.key === 'Enter' && handleExplore()}
           style={{
@@ -214,13 +291,14 @@ export default function App() {
         <select
           value={chain}
           onChange={(e) => {
-            setChain(e.target.value as Chain)
+            setChain(e.target.value as ChainName)
             setAddress('')
           }}
           style={inputStyle}
         >
-          <option>Ethereum</option>
-          <option>Tron</option>
+          {SUPPORTED_CHAINS.map((c) => (
+            <option key={c} value={c}>{c}</option>
+          ))}
         </select>
 
         {/* Data source */}
@@ -251,8 +329,15 @@ export default function App() {
           style={inputStyle}
         >
           <option value="">All Tokens</option>
-          <option value="usdt">USDT</option>
-          <option value="usdc">USDC</option>
+          {availableTokens.length > 0
+            ? availableTokens.map((t) => (
+                <option key={t} value={t.toLowerCase()}>{t}</option>
+              ))
+            : <>
+                <option value="usdt">USDT</option>
+                <option value="usdc">USDC</option>
+              </>
+          }
         </select>
 
         {/* Date range */}
@@ -327,7 +412,7 @@ export default function App() {
             <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 }}>
-              {dataSource === 'trustin' ? 'Powered by TrustIn API' : `On-Chain via ${chain === 'Tron' ? 'Tronscan' : 'Etherscan'}`}
+              {dataSource === 'trustin' ? 'Powered by TrustIn API' : `On-Chain via ${chain === 'Tron' ? 'Tronscan' : chain === 'BSC' ? 'BscScan' : chain === 'Polygon' ? 'PolygonScan' : chain === 'Arbitrum' ? 'Arbiscan' : 'Etherscan'}`}
             </div>
           </div>
         )}
@@ -379,6 +464,53 @@ export default function App() {
             <button onClick={() => setRenderer('sigma')} style={btnStyle(renderer === 'sigma')}>Sigma</button>
           </div>
         )}
+
+        {/* Search within graph */}
+        {graph && (
+          <div style={{
+            position: 'absolute',
+            top: 10,
+            left: '50%',
+            transform: 'translateX(-50%)',
+            display: 'flex',
+            gap: 4,
+            background: c.overlayBg,
+            borderRadius: 6,
+            border: `1px solid ${c.border}`,
+            padding: 2,
+            zIndex: 10,
+          }}>
+            <input
+              type="text"
+              placeholder="Search address or ENS…"
+              value={searchQuery}
+              onChange={(e) => setSearchQuery(e.target.value)}
+              onKeyDown={(e) => e.key === 'Enter' && handleSearch()}
+              style={{ ...inputStyle, fontSize: 12, minWidth: 180, padding: '4px 8px' }}
+            />
+            <button onClick={handleSearch} style={{ ...btnStyle(false), padding: '4px 10px', fontSize: 12 }}>Find</button>
+          </div>
+        )}
+
+        {/* Export buttons */}
+        {graph && (
+          <div style={{
+            position: 'absolute',
+            top: 10,
+            right: 10,
+            display: 'flex',
+            gap: 2,
+            background: c.overlayBg,
+            borderRadius: 6,
+            border: `1px solid ${c.border}`,
+            padding: 2,
+            zIndex: 10,
+          }}>
+            <button onClick={exportPNG} style={btnStyle(false)} title="Export as PNG">PNG</button>
+            <button onClick={exportJSON} style={btnStyle(false)} title="Export as JSON">JSON</button>
+            <button onClick={exportCSV} style={btnStyle(false)} title="Export as CSV">CSV</button>
+          </div>
+        )}
       </div>
 
       {/* Selected node info panel */}
@@ -398,6 +530,13 @@ export default function App() {
                   <span style={{ color: '#818cf8' }}>{node.tags.map((t) => t.name || t.primaryCategory).join(', ')}</span>
                 )}
                 {node.is_stopped && <span style={{ color: '#f59e0b' }}>{node.stop_reason || 'Stopped'}</span>}
+                <input
+                  type="text"
+                  placeholder="Add note…"
+                  value={annotations[node.address] || ''}
+                  onChange={(e) => setAnnotations(prev => ({ ...prev, [node.address]: e.target.value }))}
+                  style={{ ...inputStyle, fontSize: 11, padding: '2px 8px', minWidth: 120 }}
+                />
                 <button
                   onClick={() => setSelectedAddress(null)}
                   style={{ marginLeft: 'auto', padding: '2px 8px', borderRadius: 4, border: `1px solid ${c.border}`, background: 'transparent', color: c.dimmed, cursor: 'pointer', fontSize: 11 }}

examples/local-demo/src/api.ts

@@ -3,6 +3,8 @@ import {
   GraphBuilder,
   TrustInAdapter,
   createChainAdapter,
+  batchResolveENS,
+  mergeGraphs,
   type DataSource,
   type BuilderOptions,
 } from '@trustin/txgraph-core'
@@ -11,7 +13,7 @@ export type DataSourceType = 'trustin' | 'onchain'
 
 export interface GraphExploreParams {
   address: string
-  chain: 'Ethereum' | 'Tron'
+  chain: string
   direction?: 'in' | 'out' | 'all'
   token?: string
   maxDepth?: number
@@ -38,7 +40,65 @@ function getAdapter(dataSource: DataSourceType, chain: string): DataSource {
   })
 }
 
+// Simple in-memory cache for explore results
+const graphCache = new Map<string, { graph: TxGraph; timestamp: number }>()
+const CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
+
+function getCacheKey(params: GraphExploreParams): string {
+  return JSON.stringify({
+    address: params.address,
+    chain: params.chain,
+    direction: params.direction || 'out',
+    token: params.token || '',
+    maxDepth: params.maxDepth || 3,
+    fromDate: params.fromDate || '',
+    toDate: params.toDate || '',
+    dataSource: params.dataSource || 'trustin',
+  })
+}
+
+function getCached(key: string): TxGraph | null {
+  const entry = graphCache.get(key)
+  if (!entry) return null
+  if (Date.now() - entry.timestamp > CACHE_TTL_MS) {
+    graphCache.delete(key)
+    return null
+  }
+  return entry.graph
+}
+
+/**
+ * Enrich graph nodes with ENS names (EVM chains only, on-chain mode only).
+ * Runs in background — does not block graph rendering.
+ */
+async function enrichWithENS(graph: TxGraph): Promise<TxGraph> {
+  const evmAddresses = graph.nodes
+    .filter(n => n.address.startsWith('0x') && n.tags.length === 0)
+    .map(n => n.address)
+
+  if (evmAddresses.length === 0) return graph
+
+  const ensMap = await batchResolveENS(evmAddresses)
+  if (ensMap.size === 0) return graph
+
+  return {
+    ...graph,
+    nodes: graph.nodes.map(n => {
+      const ensName = ensMap.get(n.address.toLowerCase())
+      if (!ensName) return n
+      return {
+        ...n,
+        tags: [...n.tags, { primary_category: 'ENS', name: ensName }],
+      }
+    }),
+  }
+}
+
 export async function exploreGraph(params: GraphExploreParams): Promise<TxGraph> {
+  const cacheKey = getCacheKey(params)
+  const cached = getCached(cacheKey)
+  if (cached) return cached
+
   const dataSource = params.dataSource || 'trustin'
   const adapter = getAdapter(dataSource, params.chain)
 
@@ -50,8 +110,30 @@ export async function exploreGraph(params: GraphExploreParams): Promise<TxGraph>
     toDate: params.toDate,
   }
 
-  const builder = new GraphBuilder(adapter, options)
-  return builder.explore(params.address, params.chain)
+  // Support multiple addresses separated by comma
+  const addresses = params.address.split(',').map(a => a.trim()).filter(Boolean)
+
+  let graph: TxGraph
+  if (addresses.length <= 1) {
+    const builder = new GraphBuilder(adapter, options)
+    graph = await builder.explore(addresses[0] || params.address, params.chain)
+  } else {
+    const graphs = await Promise.all(
+      addresses.map(addr => {
+        const builder = new GraphBuilder(adapter, options)
+        return builder.explore(addr, params.chain)
+      })
+    )
+    graph = mergeGraphs(graphs)
+  }
+
+  // Enrich with ENS names for on-chain EVM queries
+  if (dataSource === 'onchain' && params.chain !== 'Tron') {
+    graph = await enrichWithENS(graph)
+  }
+
+  graphCache.set(cacheKey, { graph, timestamp: Date.now() })
+  return graph
 }
 
 export async function expandNode(