chain-insights 0.2.16

package/docs/architecture.md

@@ -0,0 +1,145 @@
+# Architecture
+
+Chain Insights is a local investigation framework around a remote graph
+execution endpoint. It keeps sensitive workspace outputs as normal local files
+and leaves graph computation to the configured GraphRAG MCP backend.
+
+## Product Layers
+
+```mermaid
+flowchart LR
+  Agent[Agent or CLI user] --> Proxy[Chain Insights MCP proxy]
+  Agent --> CLI[Chain Insights CLI]
+  CLI --> Config[Local config]
+  CLI --> Wallet[Encrypted wallet]
+  CLI --> Workspace[Investigation workspace]
+  Proxy --> GraphMCP[GraphRAG MCP]
+  CLI --> GraphMCP
+  GraphMCP --> Memgraph[(Memgraph)]
+  GraphMCP --> StarRocks[(StarRocks)]
+  Wallet --> Base[Base RPC]
+  Workspace --> Browser[Local browser reports]
+```
+
+The CLI is the operator entry point. The MCP proxy exposes the same local
+framework to AI agents. The GraphRAG MCP endpoint executes graph-language reads
+against live topology, archive topology, and facts.
+
+## Module Responsibilities
+
+| Module area | Responsibility |
+| --- | --- |
+| CLI | Command routing and user-facing workflows |
+| Config | Local config schema and owner-only storage |
+| Wallet | Encrypted EVM wallet and Base USDC balance checks |
+| MCP client/proxy | x402, debug-token, test-key auth, schema cache, stdio proxy |
+| Cases | Case state, evidence, dossiers, sessions |
+| Playbooks | Legacy playbook runner and migration boundary |
+| Visualization | Graph data model and self-contained HTML generation |
+| Server | Local report and visualization server |
+| Workspace init | Investigation workspace scaffold and runtime schema notes |
+
+## Data Flow
+
+1. The user or agent works inside an initialized investigation workspace.
+2. Chain Insights reads local config for endpoint and auth mode.
+3. Graph queries go to the configured GraphRAG MCP endpoint.
+4. The graph backend executes against `live_topology`, `archive_topology`, or
+   `facts`.
+5. Chain Insights stores compact evidence, graph JSON, HTML reports, CSVs, and
+   summaries in the active workspace.
+6. Case evidence references report files instead of embedding large payloads.
+
+## Config
+
+Configuration is stored in `~/.chain-insights/config.json` with owner-only
+permissions.
+
+Primary GraphRAG MCP config:
+
+```bash
+chain-insights config get graphMcpEndpoint
+chain-insights config set graphMcpEndpoint https://staging-mcp.chain-insights.ai/mcp
+```
+
+Supported config keys:
+
+| Key | Purpose |
+| --- | --- |
+| `graphMcpEndpoint` | GraphRAG MCP endpoint used by CLI and proxy |
+| `graphMcpAuthToken` | GraphRAG MCP bearer credential for test access keys or local debug UAT |
+| `mcpEndpoint` | Legacy endpoint fallback |
+| `mcpAuthToken` | Legacy debug token fallback |
+| `walletAddress` | Optional wallet metadata |
+| `serverPort` | Local visualization and graph report server port |
+| `dataDir` | Local Chain Insights data directory |
+| `version` | Config schema version |
+
+Wallet private keys are intercepted before config write and stored encrypted in
+`~/.chain-insights/wallet.json`.
+
+## Local Data
+
+Default local data directory:
+
+```text
+~/.chain-insights/
+  config.json
+  wallet.json
+  mcp-schema-*.json
+  chain-insights.duckdb
+```
+
+Investigation outputs belong in initialized workspaces, not in the global data
+directory.
+
+Workspace outputs include:
+
+```text
+cases/
+imports/
+reports/
+reports/graphs/
+reports/tables/
+templates/
+.chain-insights/schema/
+.chain-insights/runtime/
+.chain-insights/runtime-skill/
+```
+
+## Security Model
+
+- `wallet.json`, `config.json`, and schema cache files use owner-only
+  permissions.
+- Wallet private keys are encrypted with AES-256-GCM.
+- Debug bearer tokens are redacted in CLI output.
+- Test access keys are payment bypass credentials.
+- Production x402 should use a hot wallet with limited funds.
+- Graph report JSON is stored in the active workspace and served from
+  `127.0.0.1`.
+- Chain Insights does not custody user funds.
+- CI runs typecheck, tests, build, npm package packing, vulnerability audit,
+  registry signature verification, secret-pattern scanning, CodeQL, OpenSSF
+  Scorecard, and Dependabot updates.
+
+## Test Access Keys
+
+Invited testers can use server-side test keys without x402 payment:
+
+```bash
+chain-insights access-key set ci_test_REDACTED --endpoint https://staging-mcp.chain-insights.ai/mcp
+chain-insights access-key status
+chain-insights mcp call graph_query network=bittensor query='USE live_topology MATCH (n) RETURN n LIMIT 1'
+```
+
+Operators configure the server with `MCP_TEST_ACCESS_KEY_HASHES`, a
+comma-separated list of `key_id:sha256(full_key)` entries:
+
+```bash
+export TEST_KEY="ci_test_$(openssl rand -hex 24)"
+printf '%s' "$TEST_KEY" | sha256sum
+export MCP_TEST_ACCESS_KEY_HASHES="partner-a:<sha256-from-command>"
+```
+
+Share the raw `ci_test_...` key once. Store only its SHA-256 hash in deployment
+config. Revoke by removing the entry and redeploying GraphRAG MCP.

package/docs/contributing.md

@@ -0,0 +1,68 @@
+# Contributing To Chain Insights
+
+Chain Insights is an AML investigation framework layered on top of GraphRAG
+MCP. Contributions should keep the product easy to try while preserving precise
+tool contracts for agents and analysts.
+
+## Local Setup
+
+```bash
+npm install
+npm run build
+node bin/cli.js --help
+```
+
+## Adding AML Tools
+
+Current AML tools live in the Chain Insights layer:
+
+- `address_risk`
+- `track_funds`
+- `scam_topology`
+
+When adding a tool, document:
+
+- User problem.
+- Required and optional inputs.
+- GraphRAG MCP primitive calls.
+- Use of `live_topology`, `archive_topology`, and `facts`.
+- Result contract.
+- Case evidence behavior.
+- Graph report behavior.
+- Tests and dogfood path.
+
+## Documentation Updates
+
+- README stays product-first.
+- Detailed graph contracts belong in `docs/graph-tools.md`.
+- Workspace behavior belongs in `docs/investigation-workspaces.md`.
+- MCP proxy/client setup belongs in `docs/mcp-proxy.md`.
+- Debug and UAT details belong in `docs/debugging.md`.
+- Agent-facing contributor guidance belongs in shipped skills under `skills/`.
+
+## Tests
+
+Run focused tests while developing:
+
+```bash
+npm test -- tests/skills-contract.test.ts
+npm test -- tests/cli.test.ts
+```
+
+Run the full local gate before a PR:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run release:check
+git diff --check
+```
+
+## Release Discipline
+
+Every PR to `main` must:
+
+- Bump `package.json` and `package-lock.json`.
+- Add a matching `CHANGELOG.md` entry.
+- Pass the GitHub verification checks.

package/docs/debugging.md

@@ -0,0 +1,68 @@
+# Debugging Chain Insights
+
+This document covers local GraphRAG MCP debugging, auth bypasses, Inspector
+checks, and UAT. Product quick starts belong in README; debugging details live
+here.
+
+## Local GraphRAG MCP Debug
+
+Start GraphRAG MCP with debug bypass from the RBMK ML repo:
+
+```bash
+cd /home/aphex5/work/rbmk/repos/ml
+test -f .env || cp .env.example .env
+set -a
+. ./.env
+set +a
+docker compose -f compose/shared.yml build graphrag-mcp-go
+MCP_DEBUG_BYPASS_ENABLED=true \
+MCP_DEBUG_BYPASS_TOKEN=chain-insights-dev-debug \
+docker compose -f compose/shared.yml up -d graphrag-mcp-go
+```
+
+Point Chain Insights at the local endpoint:
+
+```bash
+cd /home/aphex5/work/chain-insights
+node bin/cli.js debug on --token chain-insights-dev-debug --endpoint http://localhost:8012/mcp
+node bin/cli.js mcp tools --refresh
+```
+
+## Inspector
+
+Inspect the GraphRAG MCP endpoint directly:
+
+```bash
+npx @modelcontextprotocol/inspector \
+  --cli http://localhost:8012/mcp \
+  --transport http \
+  --method tools/list \
+  --header "X-MCP-Debug-Token: chain-insights-dev-debug"
+```
+
+Inspect the Chain Insights proxy:
+
+```bash
+npx @modelcontextprotocol/inspector \
+  --cli chain-insights-mcp-proxy \
+  --method tools/list
+```
+
+## Smoke Checks
+
+```bash
+node bin/cli.js mcp call graph_query_batch \
+  network=bittensor \
+  'queries=[{"id":"count","query":"USE live_topology MATCH (n) RETURN count(n) AS count LIMIT 1"}]'
+node bin/cli.js wallet address
+node bin/cli.js wallet balance
+```
+
+## UAT Script
+
+```bash
+skills/test-chain-insights-graphrag-mcp/scripts/run-uat.sh
+```
+
+The UAT script uses a temporary initialized workspace, calls the real GraphRAG
+MCP endpoint, verifies proxy tools, and checks graph report serving.

package/docs/development.md

@@ -0,0 +1,44 @@
+# Development
+
+This document is for engineers changing Chain Insights.
+
+## Install And Build
+
+```bash
+npm install
+npm run build
+node bin/cli.js --help
+```
+
+## Tests
+
+Run the full local gate:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run release:check
+git diff --check
+```
+
+Focused docs and workspace tests:
+
+```bash
+npm test -- tests/skills-contract.test.ts tests/cli.test.ts
+```
+
+## Global Install From Checkout
+
+```bash
+npm run build
+npm install -g .
+cia --version
+```
+
+## More Developer Docs
+
+- Contributor workflow: `docs/contributing.md`
+- Debugging and UAT: `docs/debugging.md`
+- Graph tool contracts: `docs/graph-tools.md`
+- Investigation workspace layout: `docs/investigation-workspaces.md`

package/docs/graph-tools.md

@@ -0,0 +1,251 @@
+# Chain Insights Graph Tools
+
+This document covers the graph-facing tools and the result contracts that
+agents should rely on during investigations.
+
+## Graph MCP Surface
+
+The GraphRAG MCP public graph surface is intentionally small:
+
+| Tool | Purpose |
+| --- | --- |
+| `graph_query` | Run one read-only GQL/Cypher query through the universal graph endpoint |
+| `graph_query_batch` | Run related read-only graph-language queries as one MCP call |
+
+Chain Insights AML tools such as `address_risk`, `track_funds`, and
+`scam_topology` are recipes built over `graph_query_batch`. They are not
+assumed to exist on the GraphRAG MCP endpoint.
+
+## Query Rules
+
+- `network` is required. Do not guess it in agent workflows.
+- GQL/Cypher must be read-only.
+- Use `USE live_topology` for Memgraph RAM topology.
+- Use `USE archive_topology` for StarRocks historical topology.
+- Use `USE facts` for StarRocks facts.
+- Use `graph_query_batch` for related reads that should share one paid call.
+- `per_query_timeout_seconds` is optional and capped at `600`.
+- Returned rows live in `structuredContent.facts`.
+
+Example single query:
+
+```bash
+chain-insights mcp call graph_query \
+  network=bittensor \
+  "query=USE live_topology MATCH (n) WHERE n.address IS NOT NULL RETURN n.labels AS labels, n.address AS address LIMIT 10"
+```
+
+Example batch query:
+
+```bash
+chain-insights mcp call graph_query_batch \
+  network=bittensor \
+  'queries=[{"id":"count","query":"USE live_topology MATCH (n) RETURN count(n) AS count LIMIT 1"},{"id":"archive_flows","query":"USE archive_topology MATCH (src:Address)-[f:FLOWS_TO]->(dst:Address) RETURN f.period_granularity AS granularity, src.address AS source, dst.address AS target LIMIT 3"}]'
+```
+
+Batch result facts include:
+
+```json
+{
+  "batch": {
+    "count": 2,
+    "completed": 2,
+    "failed": 0,
+    "per_query_timeout_seconds": 600,
+    "total_query_elapsed_ms": 1345,
+    "billable_seconds": 2,
+    "estimated_usdc": "0.02"
+  }
+}
+```
+
+## Address Risk
+
+`address_risk` screens one address for AML risk, behavior patterns,
+neighborhood context, and exchange exposure. Use it as the first tool for a
+single-address investigation.
+
+Required input:
+
+- `network`
+- `address`
+
+Optional input:
+
+- `compare_address`
+- `include_attachments`
+
+The tool can emit graph report metadata when attachments are requested. Store
+large graph payloads under workspace reports and save compact evidence pointers
+to cases.
+
+## Track Funds
+
+`track_funds` traces funds from trusted victim/source addresses through
+intermediaries to exchange deposit candidates.
+
+Required input:
+
+- `network`
+- `trusted_addresses`
+
+Optional input:
+
+- `untrusted_addresses`
+- `max_hops`
+- `min_amount_sum`
+- `per_address_limit`
+- `case_id`
+- `include_attachments`
+
+Victim/source addresses are case roles, not risky labels. The tool returns
+investigator-ready flow summaries and, when a case is provided, stores compact
+evidence pointers in the active workspace.
+
+CLI example:
+
+```bash
+cia mcp track-funds \
+  --network bittensor \
+  --trusted-addresses 5... \
+  --case 1
+```
+
+## Scam Topology
+
+`scam_topology` expands the topology around a known victim incident so the
+result can produce reviewable scam-label inputs for ML and analyst workflows.
+
+Contract summary: victim-only traversal is outward from victim/source funds;
+the primary graph is a node-relative novelty wave with non-expanding
+convergence edges; exchange terminal safety; `scam_labels` are ML-ready flags;
+label candidates are reviewable, not automatic writes.
+
+Required input:
+
+- `network`
+- `victim_address`
+- `incident_timestamp_ms`
+- `max_hops`
+
+Optional input:
+
+- `activity_policy`
+- `case_id`
+- `include_attachments`
+
+CLI examples:
+
+```bash
+cia mcp scam-topology \
+  --network bittensor \
+  --victim-address 5... \
+  --incident-timestamp-ms 1715532228001 \
+  --max-hops 16
+```
+
+```bash
+cia mcp scam-topology \
+  --network bittensor \
+  --victim-address 5... \
+  --incident-timestamp-ms 1715532228001 \
+  --max-hops 16 \
+  --activity-policy global_incident_only \
+  --case 1
+```
+
+### Traversal Semantics
+
+`scam_topology` starts from one victim/source address and
+`incident_timestamp_ms`, then runs directed `FLOWS_TO` traversal outward from
+that victim incident.
+
+The default traversal is `node_relative_only`. Each new node expands only once.
+Repeated targets are retained as non-expanding `convergence_edge` context.
+Downstream edges must have `first_seen_timestamp` or `last_seen_timestamp`
+greater than or equal to the current node's wave-arrival timestamp.
+
+The alternate policy is `global_incident_only`. In that mode every wave is
+filtered against the original `incident_timestamp_ms`.
+
+Exchange terminal safety is the only hard-coded terminal class. Other labels
+are generic context hints. Victim/source addresses, exchange endpoints, and
+generic labeled context nodes are not automatic scam labels.
+
+### Result Contract
+
+`scam_topology` returns `chain-insights.result.v1` JSON with this stable
+top-level shape:
+
+```json
+{
+  "schema": "chain-insights.result.v1",
+  "tool": "scam_topology",
+  "facts": {
+    "network": "bittensor",
+    "victim_address": "5...",
+    "incident_timestamp_ms": 1715532228001,
+    "topology_graphs": ["live_topology"],
+    "primary_activity_policy": "node_relative",
+    "activity_policy_mode": "node_relative_only",
+    "topology_edges": [],
+    "intermediaries": [],
+    "terminal_points": [],
+    "exchange_deposits": [],
+    "investigation_hints": [],
+    "scam_labels": [],
+    "label_candidates": [],
+    "case_roles": [],
+    "safety_decisions": [],
+    "runs": [
+      {
+        "graph_scope": "incident",
+        "topology_graph": "live_topology",
+        "activity_policy": "node_relative",
+        "primary": true
+      }
+    ]
+  }
+}
+```
+
+The tool returns ML-ready `scam_labels` plus `label_candidates` for analyst
+review before any write to warehouse address labels.
+
+## Graph Reports
+
+Graph reports use `chain-insights.graph.v1` JSON. Visual edges use the
+canonical `source` / `target` convention.
+
+For `scam_topology`:
+
+- Primary victim-flow edges are emitted in `flows`.
+- Exchange deposit candidates are emitted in `deposits`.
+- Deposit-cluster enrichment is emitted in `reverse_leads`.
+- Deposit-cluster enrichment is not emitted as primary victim-flow topology.
+
+For `track_funds`, the same graph report shape is used so renderers and import
+helpers can share one parser.
+
+When `case_id` or CLI `--case` is provided, `track_funds` and
+`scam_topology` store `chain-insights.evidence_pointer.v1` evidence entries.
+The pointer references workspace-local compact evidence JSON, graph JSON, graph
+HTML, CSV or table files, and Markdown reports.
+
+Evidence Markdown should be a provenance record with key facts and pointers.
+Large JSON belongs under workspace report directories, not inline in evidence.
+
+## Runtime Schema Capture
+
+Fresh workspaces include a runtime schema skill and schema capture directory.
+Before the first case query against a network, capture the live graph schema and
+use the observed labels, relationship types, and property names in subsequent
+queries.
+
+Useful schema probes:
+
+```bash
+cia mcp call graph_query_batch \
+  network=bittensor \
+  'queries=[{"id":"live_address_sample","query":"USE live_topology MATCH (n:Address) RETURN n.address AS address, n.labels AS labels LIMIT 5"},{"id":"archive_flow_sample","query":"USE archive_topology MATCH (src:Address)-[f:FLOWS_TO]->(dst:Address) RETURN src.address AS source, dst.address AS target, f.period_granularity AS granularity LIMIT 5"},{"id":"facts_sample","query":"USE facts MATCH (a:Address)-[:HAS_FEATURE]->(f:AddressFeature) RETURN a.address AS address, f.sent_count AS sent_count LIMIT 5"}]'
+```