Skip to content

Commit 50b1aa3

Browse files
author
TrustIn Coder
committed
feat: initial monorepo — @trustin/txgraph package, local-demo, VitePress docs
0 parents  commit 50b1aa3

29 files changed

Lines changed: 5602 additions & 0 deletions

‎.github/workflows/docs.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Deploy Docs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- 'packages/react/src/**'
9+
10+
jobs:
11+
deploy:
12+
runs-on: ubuntu-latest
13+
permissions:
14+
contents: write
15+
pages: write
16+
id-token: write
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- uses: pnpm/action-setup@v4
21+
with:
22+
version: latest
23+
24+
- uses: actions/setup-node@v4
25+
with:
26+
node-version: '20'
27+
cache: 'pnpm'
28+
29+
- name: Install dependencies
30+
run: pnpm install --frozen-lockfile
31+
32+
- name: Build docs
33+
run: pnpm --filter docs build
34+
35+
- name: Deploy to GitHub Pages
36+
uses: peaceiris/actions-gh-pages@v3
37+
with:
38+
github_token: ${{ secrets.GITHUB_TOKEN }}
39+
publish_dir: docs/.vitepress/dist

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
node_modules/
2+
dist/
3+
.vitepress/dist/
4+
.vitepress/cache/
5+
*.local
6+
.env
7+
.DS_Store

‎docs/.vitepress/config.ts‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
export default defineConfig({
4+
title: 'TxGraph',
5+
ignoreDeadLinks: true,
6+
description: 'Blockchain transaction tracing graph — open source React components',
7+
base: '/txgraph/',
8+
themeConfig: {
9+
logo: { src: '/logo.svg', alt: 'TxGraph' },
10+
nav: [
11+
{ text: 'Guide', link: '/guide/layer1-product' },
12+
{ text: 'API', link: '/api/components' },
13+
{ text: 'GitHub', link: 'https://github.com/trustin-info/txgraph' },
14+
],
15+
sidebar: [
16+
{
17+
text: 'Getting Started',
18+
items: [
19+
{ text: 'Introduction', link: '/' },
20+
{ text: '🌐 Use TrustIn Explorer', link: '/guide/layer1-product' },
21+
{ text: '💻 Run Demo Locally', link: '/guide/layer2-demo' },
22+
{ text: '🛠 Build Your Own', link: '/guide/layer3-component' },
23+
],
24+
},
25+
{
26+
text: 'API Reference',
27+
items: [
28+
{ text: 'Components', link: '/api/components' },
29+
{ text: 'Types', link: '/api/types' },
30+
{ text: 'REST API', link: '/api/rest-api' },
31+
],
32+
},
33+
],
34+
footer: {
35+
message: 'Released under the MIT License.',
36+
copyright: 'Copyright © 2024 TrustIn',
37+
},
38+
socialLinks: [
39+
{ icon: 'github', link: 'https://github.com/trustin-info/txgraph' },
40+
],
41+
},
42+
})

‎docs/api/components.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Components
2+
3+
## `GraphExplorer`
4+
5+
ReactFlow-based interactive graph renderer. Best for small-to-medium graphs (up to ~500 nodes).
6+
7+
```tsx
8+
import { GraphExplorer } from '@trustin/txgraph'
9+
```
10+
11+
### Props
12+
13+
| Prop | Type | Default | Description |
14+
|------|------|---------|-------------|
15+
| `nodes` | `TxNode[]` | required | Array of graph nodes |
16+
| `edges` | `TxEdge[]` | required | Array of graph edges |
17+
| `stats` | `TxGraphStats` | — | Optional stats (shown in panel) |
18+
| `loading` | `boolean` | `false` | Show full-screen loading overlay |
19+
| `expandingNode` | `string \| null` | `null` | Address of node currently being expanded (shows spinner) |
20+
| `selectedAddress` | `string \| null` | `null` | Highlight the path from root to this address |
21+
| `onNodeSelect` | `(node: TxNode \| null) => void` | — | Called when user clicks a node (or background) |
22+
| `onNodeExpand` | `(address: string) => void` | — | Called when user clicks the **+** expand button |
23+
| `onNodeDelete` | `(address: string) => void` | — | Called when user clicks the **✕** delete button |
24+
25+
### Layout
26+
27+
The graph uses **Dagre** for automatic left-to-right hierarchical layout. Nodes are arranged by transaction depth. Layout is recomputed whenever `nodes` or `edges` change.
28+
29+
### Selection & Path Highlighting
30+
31+
When `selectedAddress` is set, the component:
32+
1. Finds all paths from the root node to the selected address (DFS with backtracking)
33+
2. Highlights nodes and edges on any path
34+
3. Dims all other nodes and edges (opacity 0.25)
35+
36+
### Node Appearance
37+
38+
| State | Visual |
39+
|-------|--------|
40+
| Root node | Blue border + glow |
41+
| High risk | Red border + red background |
42+
| Medium risk | Yellow border + yellow background |
43+
| Low risk | Green border + green background |
44+
| Unknown risk | Gray border |
45+
| Stopped node | Dashed border + warning icon |
46+
| Selected | Blue glow ring |
47+
| Dimmed (not on path) | 25% opacity |
48+
| Expanding | Spinner overlay |
49+
50+
---
51+
52+
## `GraphExplorerSigma`
53+
54+
Sigma.js + WebGL-based renderer. Best for large graphs (500+ nodes). Uses canvas for labels, WebGL for nodes/edges.
55+
56+
```tsx
57+
import { GraphExplorerSigma } from '@trustin/txgraph'
58+
```
59+
60+
### Props
61+
62+
Same props as `GraphExplorer` — both components implement `GraphExplorerProps`.
63+
64+
### Interactions
65+
66+
| Action | Result |
67+
|--------|--------|
68+
| Click node | `onNodeSelect(node)` |
69+
| Click background | `onNodeSelect(null)` |
70+
| Double-click node | `onNodeExpand(address)` |
71+
| Right-click node | `onNodeDelete(address)` |
72+
| Scroll | Zoom in/out |
73+
| Drag | Pan |
74+
75+
### Built-in Controls
76+
77+
The Sigma renderer includes floating controls:
78+
- **+** / **−** — Zoom in/out
79+
- **⊡** — Fit all nodes in view
80+
81+
### Layout
82+
83+
Uses a custom depth-based left-to-right layout:
84+
- X position = `depth × 3.5` (graph coordinates)
85+
- Y position = evenly spaced within each depth level
86+
- No overlap guaranteed
87+
88+
### Camera
89+
90+
On mount, the camera auto-fits to show all nodes at a comfortable ~38px radius. The camera ratio adapts to graph size.

‎docs/api/rest-api.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# REST API
2+
3+
TxGraph components are designed to work with the **TrustIn graph_explore API**. You can also supply your own data from any source — just map to `TxNode[]` and `TxEdge[]`.
4+
5+
## Authentication
6+
7+
Contact [info@trustin.info](mailto:info@trustin.info) to obtain an API key.
8+
9+
Include the key in all requests:
10+
11+
```
12+
X-Api-Key: your_api_key_here
13+
```
14+
15+
## Endpoints
16+
17+
### `POST /api/v1/graph_explore`
18+
19+
Explore transaction graph starting from a given address.
20+
21+
**Base URL:** `https://api.trustin.info`
22+
23+
#### Request
24+
25+
```http
26+
POST /api/v1/graph_explore
27+
Content-Type: application/json
28+
X-Api-Key: your_api_key_here
29+
```
30+
31+
```json
32+
{
33+
"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
34+
"chain": "Ethereum",
35+
"direction": "out",
36+
"max_depth": 3,
37+
"from_date": "2024-01-01",
38+
"to_date": "2024-12-31"
39+
}
40+
```
41+
42+
#### Request Parameters
43+
44+
| Parameter | Type | Required | Description |
45+
|-----------|------|----------|-------------|
46+
| `address` | `string` | ✅ | Starting blockchain address |
47+
| `chain` | `'Ethereum' \| 'Tron'` | ✅ | Blockchain network |
48+
| `direction` | `'in' \| 'out' \| 'all'` | — | Default: `'out'` |
49+
| `max_depth` | `number` | — | Max hops to trace. Default: `3` |
50+
| `from_date` | `string` | — | Filter: start date `YYYY-MM-DD` |
51+
| `to_date` | `string` | — | Filter: end date `YYYY-MM-DD` |
52+
53+
#### Response
54+
55+
```json
56+
{
57+
"success": true,
58+
"data": {
59+
"nodes": [
60+
{
61+
"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
62+
"depth": 0,
63+
"is_root": true,
64+
"risk_level": "low",
65+
"risk_score": 5,
66+
"tags": [
67+
{
68+
"name": "Vitalik Buterin",
69+
"primaryCategory": "Individual"
70+
}
71+
],
72+
"is_stopped": false
73+
}
74+
],
75+
"edges": [
76+
{
77+
"from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
78+
"to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
79+
"formatted_amount": "1,234.56 USDT",
80+
"amount": 1234.56,
81+
"token": "USDT",
82+
"last_timestamp": 1704067200,
83+
"direction": "out",
84+
"tx_count": 3
85+
}
86+
],
87+
"stats": {
88+
"total_nodes": 42,
89+
"total_edges": 38,
90+
"stopped_nodes": 5
91+
}
92+
}
93+
}
94+
```
95+
96+
#### Error Response
97+
98+
```json
99+
{
100+
"success": false,
101+
"error": "Invalid API key",
102+
"code": 401
103+
}
104+
```
105+
106+
## Using the API Client
107+
108+
The `examples/local-demo/src/api.ts` provides a ready-to-use client:
109+
110+
```typescript
111+
import { exploreGraph } from './api'
112+
113+
const graph = await exploreGraph({
114+
address: '0xd8dA6BF...',
115+
chain: 'Ethereum',
116+
direction: 'out',
117+
maxDepth: 3,
118+
fromDate: '2024-01-01',
119+
})
120+
121+
// graph is TxGraph — ready for the components
122+
```
123+
124+
## Bring Your Own Data
125+
126+
The components don't require the TrustIn API. Supply any `TxNode[]` and `TxEdge[]` data:
127+
128+
```typescript
129+
import { GraphExplorer } from '@trustin/txgraph'
130+
import type { TxNode, TxEdge } from '@trustin/txgraph'
131+
132+
// Your own on-chain data pipeline
133+
const { nodes, edges } = await myOwnGraphProvider.query(address)
134+
135+
// Map to TxNode / TxEdge format
136+
const txNodes: TxNode[] = nodes.map(n => ({
137+
address: n.addr,
138+
depth: n.hopCount,
139+
is_root: n.addr === rootAddress,
140+
risk_level: mapRisk(n.riskScore),
141+
tags: n.labels.map(l => ({ name: l })),
142+
is_stopped: n.isLeaf,
143+
}))
144+
```

0 commit comments

Comments
 (0)