chain-insights 0.2.30 → 0.2.31

package/README.md

@@ -194,6 +194,10 @@ result envelope. Use explicit `LIMIT` and pagination in your query when you
 want bounded result sets. Endpoint access and authentication are configured
 separately; see [MCP proxy](docs/mcp-proxy.md).
 
+Agent installs include `chain-insights-cypher` for generic layer-aware
+GQL/Cypher work and `chain-insights-bittensor-cypher` for Bittensor-specific
+schema notes and examples.
+
 ## AML Tools
 
 The high-level AML tools are Chain Insights workflows built around graph access

package/docs/graph-tools.md

@@ -37,6 +37,13 @@ assumed to exist on the GraphRAG MCP endpoint.
 - `per_query_timeout_seconds` is optional and capped at `10` by default.
 - Returned rows live in `structuredContent.facts`.
 
+Agent installers ship two graph-query skills:
+
+- `chain-insights-cypher`: generic layer selection, schema capture, and
+  portable read-only GQL/Cypher examples.
+- `chain-insights-bittensor-cypher`: Bittensor-specific schema notes for SS58
+  and EVM-pallet addresses under `network=bittensor`.
+
 Check public-free usage:
 
 ```bash
@@ -313,12 +320,19 @@ Large JSON belongs under workspace report directories, not inline in evidence.
 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.
+queries. Different networks can expose different fact nodes and relationship
+properties, so do not assume a query that works on Bittensor will work on Base,
+Ethereum, or TRON without a fresh schema probe.
 
 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"}]'
+  per_query_timeout_seconds=5 \
+  'queries=[{"id":"live_address_sample","query":"USE live_topology MATCH (n:Address) RETURN n.address AS address, n.labels AS labels, n.is_exchange AS is_exchange LIMIT 10"},{"id":"live_flow_sample","query":"USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count LIMIT 10"},{"id":"archive_flow_sample","query":"USE archive_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count LIMIT 10"},{"id":"facts_address_sample","query":"USE facts MATCH (a:Address) RETURN a.address AS address, a.labels AS labels, a.is_exchange AS is_exchange LIMIT 10"}]'
 ```
+
+Use projections like `n.address` and `flow.tx_count` in probes. Metadata
+functions such as `keys()`, `labels()`, and `type()` are not portable across
+every GraphRAG MCP layer.

package/docs/mcp-proxy.md

@@ -165,6 +165,11 @@ directory and registers the stdio MCP proxy in the Hermes config.
 After installing, open an initialized investigation workspace in the agent and
 operate over the workspace files.
 
+For manual graph-language work, agents should use the shipped
+`chain-insights-cypher` skill. For Bittensor queries, load
+`chain-insights-bittensor-cypher` after the generic skill so SS58 and
+EVM-pallet addresses stay under `network=bittensor`.
+
 ## Claude Desktop
 
 Claude Desktop is supported for basic MCP calls. It is not the primary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chain-insights",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "description": "AML investigation CLI and MCP proxy for blockchain risk, fund-flow tracing, case reports, and GraphRAG MCP access",
   "homepage": "https://chain-insights.ai",
   "repository": {

package/skills/chain-insights-bittensor-cypher/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: chain-insights-bittensor-cypher
+description: Use when writing Chain Insights graph_query or graph_query_batch reads for network=bittensor, Bittensor SS58 and EVM-pallet addresses, TAO FLOWS_TO, STAKES_IN, hotkey/coldkey/neuron facts, or Bittensor-specific schema checks.
+---
+
+# Chain Insights Bittensor Cypher
+
+Load `chain-insights-cypher` first for generic layer rules. This skill adds the
+Bittensor schema and examples.
+
+## Network Rule
+
+Bittensor contains both native Substrate/SS58 addresses such as `5...` and
+EVM-pallet `0x...` addresses in one investigation network:
+
+- Use `network=bittensor` for both address families.
+- Do not switch networks just because an address is `0x...`.
+- Preserve the exact returned `address`, `address_type`, and `network` fields.
+- If an endpoint advertises legacy `bittensor_evm`, treat it as compatibility
+  evidence, not a reason to split the investigation unless the user asks.
+
+## Current Schema Notes
+
+Observed against staging on 2026-05-29:
+
+- `network_capabilities` advertises Bittensor as default with topology, facts,
+  risk, `graph_query`, and `graph_query_batch` available; dataset coverage was
+  `unknown`.
+- `live_topology` accepted `Address` and `FLOWS_TO` projection queries. Sample
+  `Address` rows included `address`, `network`, and `address_type`; `labels`,
+  `is_exchange`, degree, and tx-count fields were sparse in the sample.
+- `live_topology` accepted `STAKES_IN` count/projection shape but returned zero
+  rows in the staging sample.
+- `archive_topology` accepted `Address` to `FLOWS_TO` historical queries and
+  returned SS58 addresses with `edge_id`, `period_granularity`, amount fields,
+  tx count, and first/last timestamps.
+- `archive_topology` exposed `TopologySnapshot` in the staging sample.
+- Source mappings include archive `STAKES_IN` and facts labels/features/neuron
+  context, but staging returned generic backend errors for those sample reads;
+  verify them with a fresh schema probe before relying on them.
+
+## Bittensor Shapes
+
+Live topology:
+
+```cypher
+USE live_topology
+MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address)
+RETURN src.address AS from_address,
+       dst.address AS to_address,
+       flow.amount_sum AS amount_sum,
+       flow.amount_usd_sum AS amount_usd_sum,
+       flow.tx_count AS tx_count,
+       flow.first_seen_timestamp AS first_seen_timestamp,
+       flow.last_seen_timestamp AS last_seen_timestamp
+LIMIT 25
+```
+
+Archive topology:
+
+```cypher
+USE archive_topology
+MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address)
+RETURN src.address AS from_address,
+       dst.address AS to_address,
+       flow.edge_id AS edge_id,
+       flow.period_granularity AS period_granularity,
+       flow.amount_sum AS amount_sum,
+       flow.amount_usd_sum AS amount_usd_sum,
+       flow.tx_count AS tx_count,
+       flow.first_seen_timestamp AS first_seen_timestamp,
+       flow.last_seen_timestamp AS last_seen_timestamp
+LIMIT 25
+```
+
+Stake topology, when the endpoint proves it:
+
+```cypher
+USE live_topology
+MATCH (coldkey:Address)-[stake:STAKES_IN]->(hotkey:Address)
+RETURN coldkey.address AS coldkey,
+       hotkey.address AS hotkey,
+       stake.netuid AS netuid,
+       stake.amount AS amount,
+       stake.source_role AS source_role,
+       stake.destination_role AS destination_role,
+       stake.source_backend AS source_backend
+LIMIT 25
+```
+
+Facts, when the endpoint proves the mapping:
+
+```cypher
+USE facts
+MATCH (coldkey:Address)-[:REGISTERED_NEURON]->(hotkey:Hotkey)-[:SERVED_FROM]->(ip:IPAddress)
+RETURN coldkey.address AS coldkey,
+       hotkey.address AS hotkey,
+       ip.ip_address AS ip_address
+LIMIT 25
+```
+
+## Schema Probe
+
+Use this before a custom Bittensor query session:
+
+```bash
+cia mcp call graph_query_batch \
+  network=bittensor \
+  per_query_timeout_seconds=5 \
+  'queries=[{"id":"live_address_projection","query":"USE live_topology MATCH (n:Address) RETURN n.address AS address, n.labels AS labels, n.is_exchange AS is_exchange, n.address_type AS address_type, n.network AS network LIMIT 10"},{"id":"live_flow_sample","query":"USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count LIMIT 10"},{"id":"live_stake_count","query":"USE live_topology MATCH (:Address)-[stake:STAKES_IN]->(:Address) RETURN count(stake) AS stake_edges LIMIT 1"},{"id":"archive_flow_sample","query":"USE archive_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.edge_id AS edge_id, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count LIMIT 10"},{"id":"archive_snapshot","query":"USE archive_topology MATCH (s:TopologySnapshot) RETURN s.graph_name AS graph_name, s.default_period_granularity AS default_period_granularity, s.available_granularities AS available_granularities LIMIT 5"},{"id":"facts_address_sample","query":"USE facts MATCH (a:Address) RETURN a.address AS address, a.labels AS labels, a.is_exchange AS is_exchange LIMIT 10"}]'
+```
+
+Avoid `keys()`, `labels()`, `type()`, native BFS syntax, and variable-length
+paths in schema probes. They may be valid in a direct Memgraph console but are
+not portable across the GraphRAG MCP federation path.
+
+## Investigation Patterns
+
+Outflows from a SS58 or `0x...` Bittensor address:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (src:Address {address: "FULL_BITTENSOR_ADDRESS"})-[flow:FLOWS_TO]->(dst:Address) RETURN dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.amount_usd_sum DESC LIMIT 50'
+```
+
+Historical archive read for the same address:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE archive_topology MATCH (src:Address {address: "FULL_BITTENSOR_ADDRESS"})-[flow:FLOWS_TO]->(dst:Address) RETURN dst.address AS to_address, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.first_seen_timestamp AS first_seen_timestamp, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.last_seen_timestamp DESC LIMIT 50'
+```
+
+When comparing amounts, remember that archive StarRocks-backed numeric fields
+may arrive as strings while live Memgraph fields may arrive as numbers.

package/skills/chain-insights-bittensor-cypher/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bittensor Cypher"
+  short_description: "Write Bittensor-specific Chain Insights graph reads"
+  default_prompt: "Use Chain Insights graph_query or graph_query_batch on network=bittensor with SS58 and EVM-pallet address handling, Bittensor topology fields, bounded Cypher, and fresh schema probes."

package/skills/chain-insights-cypher/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: chain-insights-cypher
+description: Use when writing, reviewing, or debugging Chain Insights graph_query or graph_query_batch GQL/Cypher, choosing live_topology, archive_topology, or facts, capturing schema, or making schema-aware graph reads across networks.
+---
+
+# Chain Insights Cypher
+
+Use this for manual `graph_query` and `graph_query_batch` work. For case work,
+combine it with `chain-insights-investigation`. If a network-specific Cypher
+skill exists, load it after this one.
+
+## First Moves
+
+1. Inspect the endpoint before writing network-specific queries:
+   ```bash
+   cia mcp networks
+   cia mcp call usage_status
+   ```
+2. Always pass an explicit `network`.
+3. Always add your own `LIMIT`; GraphRAG MCP does not append one.
+4. Use `graph_query_batch` for related schema, topology, and facts reads.
+5. Save material query output as workspace evidence before summarizing it.
+
+## Layer Choice
+
+| Layer | Use for | Query style |
+| --- | --- | --- |
+| `USE live_topology` | Current or recent route discovery and fast topology reads | Memgraph-backed Cypher over topology nodes and relationships. Prefer directed `MATCH` patterns and narrow projections. |
+| `USE archive_topology` | Historical money-flow and long-window topology facts | StarRocks/MemGQL GQL-Cypher subset. Keep to simple `MATCH`, `WHERE`, property projections, aggregates, `ORDER BY`, and `LIMIT`. |
+| `USE facts` | Labels, address features, risk scores, assets, and enrichment | StarRocks/MemGQL facts mapping. Verify the current network schema before assuming fact labels or relationships exist. |
+
+Treat `archive_topology` and `facts` as mapped graph views, not full Memgraph.
+Avoid backend-specific functions such as `keys()`, `labels()`, `type()`,
+procedures, native BFS syntax, catalog operations, and variable-length path
+tricks unless the current endpoint has just accepted the exact pattern.
+
+## Common Schema
+
+Topology is intentionally stable across networks:
+
+- Node: `(:Address)` with `address`, usually sparse `labels` and `is_exchange`.
+- Edge: `(:Address)-[:FLOWS_TO]->(:Address)` for money flow.
+- Archive flow fields commonly include `edge_id`, `from_address`, `to_address`,
+  `period_granularity`, `period_start_date`, `period_end_date`,
+  `asset_contract`, `asset_symbol`, `tx_count`, `amount_sum`,
+  `amount_usd_sum`, `first_seen_timestamp`, `last_seen_timestamp`,
+  `first_tx_id`, and `last_tx_id`.
+- Facts may expose `AddressFeature`, `AddressLabel`, `RiskScore`, `Asset`, and
+  network-specific fact nodes.
+
+Different networks expose different schemas. Do not reuse a Bittensor stake
+query on Base or Ethereum unless that network advertises and proves the same
+labels and fields.
+
+## Schema Capture
+
+Use projections instead of metadata functions so the same probe works on both
+Memgraph-backed and mapped layers:
+
+```bash
+cia mcp call graph_query_batch \
+  network=<network> \
+  per_query_timeout_seconds=5 \
+  'queries=[{"id":"live_address_sample","query":"USE live_topology MATCH (n:Address) RETURN n.address AS address, n.labels AS labels, n.is_exchange AS is_exchange LIMIT 10"},{"id":"live_flow_sample","query":"USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.first_seen_timestamp AS first_seen_timestamp, flow.last_seen_timestamp AS last_seen_timestamp LIMIT 10"},{"id":"archive_flow_sample","query":"USE archive_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count LIMIT 10"},{"id":"facts_address_sample","query":"USE facts MATCH (a:Address) RETURN a.address AS address, a.labels AS labels, a.is_exchange AS is_exchange LIMIT 10"}]'
+```
+
+If a query fails with a generic backend error, narrow it before changing the
+investigation claim: remove metadata functions, remove cross-graph joins, use
+one relationship, project fewer fields, and lower the limit.
+
+## Query Examples
+
+Live outflows from one address:
+
+```bash
+cia mcp call graph_query \
+  network=<network> \
+  'query=USE live_topology MATCH (src:Address {address: "FULL_ADDRESS"})-[flow:FLOWS_TO]->(dst:Address) RETURN dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.first_seen_timestamp AS first_seen_timestamp, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.amount_usd_sum DESC LIMIT 50'
+```
+
+Archive flow history:
+
+```bash
+cia mcp call graph_query \
+  network=<network> \
+  'query=USE archive_topology MATCH (src:Address {address: "FULL_ADDRESS"})-[flow:FLOWS_TO]->(dst:Address) RETURN dst.address AS to_address, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.first_seen_timestamp AS first_seen_timestamp, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.last_seen_timestamp DESC LIMIT 50'
+```
+
+Facts lookup after schema proof:
+
+```bash
+cia mcp call graph_query \
+  network=<network> \
+  'query=USE facts MATCH (a:Address {address: "FULL_ADDRESS"})-[:HAS_LABEL]->(label:AddressLabel) RETURN label.label AS label, label.entity_type AS entity_type, label.address_type AS address_type, label.source AS source LIMIT 25'
+```
+
+## Hard Stops
+
+- No writes or catalog changes: no `CREATE`, `MERGE`, `SET`, `DELETE`,
+  `REMOVE`, `DROP`, `ADD`, `CONNECT`, or `CALL`.
+- No raw StarRocks table names through GraphRAG MCP.
+- Do not rely on dynamic labels such as `:Exchange`; use `is_exchange` or
+  label facts when the schema proves they exist.
+- Empty results mean no indexed match in the selected layer, not proof of
+  safety or non-existence.

package/skills/chain-insights-cypher/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Chain Insights Cypher"
+  short_description: "Write schema-aware GraphRAG MCP GQL/Cypher"
+  default_prompt: "Use Chain Insights graph_query or graph_query_batch with explicit network, layer selection, bounded read-only Cypher, schema capture, and evidence-safe output handling."

package/skills/chain-insights-developer-experience/SKILL.md

@@ -40,6 +40,10 @@ Chain Insights tools should be implemented as local AML workflows over these
 generic graph primitives unless there is a product reason to add a new
 primitive.
 
+For manual graph-language guidance, use the shipped `chain-insights-cypher`
+skill. For Bittensor schema-specific queries, load
+`chain-insights-bittensor-cypher` after the generic skill.
+
 ## Topology Language
 
 Use these names consistently:

package/skills/chain-insights-investigation/SKILL.md

@@ -188,6 +188,8 @@ Use manual `graph_query_batch` for custom topology or fact questions. Use
 `USE live_topology` for recent topology, `USE archive_topology` for historical
 topology, and `USE facts` for facts and enrichment.
 Use `graph_query` or `graph_query_batch` for all graph-language reads.
+When writing custom Cypher, use the shipped `chain-insights-cypher` skill; for
+Bittensor, also use `chain-insights-bittensor-cypher`.
 
 ## Query And Evidence Loop