chain-insights 0.44.0 → 0.44.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -95,7 +95,7 @@ approvals, contract creations and smart accounts (`APPROVED`,
95
95
  and bridge totals (`SWAPPED`, `ADDED_LIQUIDITY` and `REMOVED_LIQUIDITY` around
96
96
  `:Pool` nodes, `BRIDGED` to `:Chain` nodes). Both DEX layers set `:Pool`, so a
97
97
  pool with liquidity and no swap carries it. A trace through a pool follows the
98
- pool trace rule in the `chain-insights-schema-evm` skill.
98
+ pool trace rule in the `chain-insights-cypher` skill.
99
99
 
100
100
  ### `OPERATED_BY` — operator-mediated topology (topology only)
101
101
 
@@ -273,7 +273,7 @@ Every form above carries the pool guard and walks `SWAPPED` beside
273
273
  `FLOWS_TO`. `WHERE NOT a:Pool` keeps the walk from starting at a `:Pool`, the
274
274
  inner `WHERE NOT via:Pool` keeps each address in the middle of the walk off
275
275
  one, and `SWAPPED` crosses a swap from payer to recipient, per the
276
- [pool trace rule](../skills/chain-insights-schema-evm/SKILL.md#pool-trace-rule).
276
+ [pool trace rule](../skills/chain-insights-cypher/SKILL.md#pool-trace-rule).
277
277
  Only the target end may be a pool. Up to 4 guarded hops plus the last hop is
278
278
  1 to 5 hops. Keep the guards inside the path pattern: a `WHERE` after a
279
279
  `SHORTEST` pattern runs after the shortest route is chosen, so it drops a
@@ -309,7 +309,7 @@ rejected with a typed contract error before execution.
309
309
 
310
310
  | Construct | Notes |
311
311
  | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
312
- | `MATCH` on a mapped node / single relationship | `(from:Address)-[t:TRANSFER]->(to:Address)` (bounded individual transfer rows from `facts_transfers_view`). Lifetime address metrics are node properties on `USE topology` (the facts `AddressFeature` surface is retired). `SWAP`, `LIQUIDITY_ADD`, `LIQUIDITY_REMOVE` and `BRIDGE_CROSSING` are single-event rows on the same pattern, each with its own indexed predicate (see the `chain-insights-schema-evm` skill). Never serves `FLOWS_TO`, `OPERATED_BY`, `LINKED`, `SWAPPED`, `ADDED_LIQUIDITY`, `REMOVED_LIQUIDITY` or `BRIDGED` — those are topology-only. Labels and per-label risk live on the topology address node, not on `facts`. |
312
+ | `MATCH` on a mapped node / single relationship | `(from:Address)-[t:TRANSFER]->(to:Address)` (bounded individual transfer rows from `facts_transfers_view`). Lifetime address metrics are node properties on `USE topology` (the facts `AddressFeature` surface is retired). `SWAP`, `LIQUIDITY_ADD`, `LIQUIDITY_REMOVE` and `BRIDGE_CROSSING` are single-event rows on the same pattern, each with its own indexed predicate. Never serves `FLOWS_TO`, `OPERATED_BY`, `LINKED`, `SWAPPED`, `ADDED_LIQUIDITY`, `REMOVED_LIQUIDITY` or `BRIDGED` — those are topology-only. Labels and per-label risk live on the topology address node, not on `facts`. |
313
313
  | Chained fixed-hop patterns | up to 5 hops |
314
314
  | Bare `block_date` bound | `t.block_date >= ?` / `<`, `<=`, `>`, `=` — the caller's own day range, passed through. `BETWEEN` and `IN` are refused (`unsupported WHERE operator`): write a range as `>=` and `<`. The bound must be bare (no function around the column) and conjunctive (not inside an `OR` arm). An explicit full-range bound (`>= '1970-01-01'`) stays lifetime. |
315
315
  | `tx_id` equality | `t.tx_id = "…"` — a point lookup on the `TRANSFER` edge's row-level key; on EVM networks the `0x` transaction hash, served from the indexed hash columns. Lifetime semantics. `IN` and `BETWEEN` are refused (`unsupported WHERE operator "IN"`): send one equality per transaction, several in one `graph_query_batch`. |
@@ -428,5 +428,4 @@ filter.
428
428
  ## Related documentation
429
429
 
430
430
  - `docs/graph-tools.md` — tool tiers, timeouts, and capability transparency
431
- - Skill `chain-insights-cypher` — ISO GQL dialect and layer rules
432
- - Skill `chain-insights-schema-evm` — EVM / Robinhood GraphRAG map
431
+ - Skill `chain-insights-cypher` — ISO GQL dialect, layer rules, graph searches and how to find the fields
@@ -98,8 +98,7 @@ by `height` or `hash`, and `Head`, which takes no key. No lookup takes an
98
98
  address: `:Address` is a topology and a facts label, never a chain one. A lookup
99
99
  is one node with literal keys in braces and a `RETURN` of `var.property` items.
100
100
  It takes no `WHERE`, no relationship and no range. The properties of each lookup
101
- are named in the refusal of an unknown property, and in the
102
- [`chain-insights-schema-evm` skill](../skills/chain-insights-schema-evm/SKILL.md#use-chain).
101
+ are named in the refusal of an unknown property.
103
102
 
104
103
  A transaction, with its result and the day it was mined:
105
104
 
@@ -190,7 +189,7 @@ of truth.
190
189
  `:Pool` follows the pool trace rule:
191
190
 
192
191
  - The rule is stated once, in the
193
- [`chain-insights-schema-evm` skill](../skills/chain-insights-schema-evm/SKILL.md#pool-trace-rule).
192
+ [`chain-insights-cypher` skill](../skills/chain-insights-cypher/SKILL.md#pool-trace-rule).
194
193
  - The MCP server instructions serve the same four steps, word for word,
195
194
  because an MCP client loads no skill. A test keeps the two equal.
196
195
  - It stops a trace from fanning out to every trader who used the pool, and
@@ -213,7 +212,8 @@ cia mcp call graph_query \
213
212
  'query=USE topology MATCH p = SHORTEST 1 (a:Address {address: "0x..."} WHERE NOT a:Pool) (()-[:FLOWS_TO|SWAPPED]-(via:Address) WHERE NOT via:Pool){0,4} ()-[:FLOWS_TO|SWAPPED]-(b:Address {address: "0x..."}) RETURN [n IN nodes(p) | n.address] AS route LIMIT 5'
214
213
  ```
215
214
 
216
- Every property is listed in the `chain-insights-schema-evm` skill.
215
+ The `chain-insights-cypher` skill shows how to read the properties of a link
216
+ from a sample.
217
217
 
218
218
  Rug-pull check from a victim, under the rule:
219
219
 
@@ -261,7 +261,8 @@ and `:Sanctioned`. Each role also has a flag on the node.
261
261
  - Test a flag with `IS NOT NULL` or `IS NULL`. Do not test `= false`.
262
262
  - Only `is_exchange` ends a walk: exchange hot wallets are terminals, and a
263
263
  node with no `is_exchange` is walked through.
264
- - Every property is listed in the `chain-insights-schema-evm` skill.
264
+ - The `chain-insights-cypher` skill shows how to read every property from a
265
+ sample.
265
266
 
266
267
  ## Query Rules
267
268
 
@@ -311,12 +312,13 @@ and `:Sanctioned`. Each role also has a flag on the node.
311
312
  `USE facts`). It can lower a limit. It cannot raise one.
312
313
  - Returned rows live in `structuredContent.facts`.
313
314
 
314
- Agent installers ship two skills:
315
+ Agent installers ship one skill:
315
316
 
316
- - `chain-insights-cypher`: ISO GQL dialect, layer routing and the move for
317
- every refusal, for `graph_query` and `graph_query_batch`. No query cookbook.
318
- - `chain-insights-schema-evm`: EVM / Robinhood GraphRAG labels,
319
- relationships, and properties.
317
+ - `chain-insights-cypher`: ISO GQL dialect, layer routing, one query for each
318
+ kind of graph search (routes, walks, shared counterparties, ownership
319
+ clusters, operators, swaps, pools and bridges), how to find the fields of
320
+ the graph, and the move for every refusal, for `graph_query` and
321
+ `graph_query_batch`.
320
322
 
321
323
  Check public-free usage:
322
324
 
@@ -496,7 +498,7 @@ traversal node must be non-exchange.
496
498
 
497
499
  Liquidity pools are the other trace boundary. At a `:Pool`, manual traversal
498
500
  follows the
499
- [pool trace rule](../skills/chain-insights-schema-evm/SKILL.md#pool-trace-rule),
501
+ [pool trace rule](../skills/chain-insights-cypher/SKILL.md#pool-trace-rule),
500
502
  so a trace does not fan out to every trader who used the pool. The start and
501
503
  every address in the middle of a manual `FLOWS_TO` walk must satisfy
502
504
  `NOT src:Pool` and `NOT mid:Pool`, and the walk follows `SWAPPED` beside
package/docs/mcp-proxy.md CHANGED
@@ -203,9 +203,9 @@ address checks, sample address reads, sample flow reads, and the
203
203
  free-to-paid handoff, but bounded sample reads still returned topology data
204
204
  inside the same daily allowance.
205
205
 
206
- For graph reads, install `chain-insights-cypher` plus
207
- `chain-insights-schema-evm`. The cypher skill teaches ISO GQL and the three
208
- read layers. The schema skill holds the graph map.
206
+ For graph reads, install `chain-insights-cypher`. It teaches ISO GQL, the
207
+ three read layers, one query for each kind of graph search, and how to find
208
+ the fields of the graph.
209
209
 
210
210
  Paid x402 mode:
211
211
 
@@ -246,8 +246,7 @@ cia --hermes
246
246
  The Hermes installer writes Chain Insights skills under the Hermes skills
247
247
  directory and registers the stdio MCP proxy in the Hermes config.
248
248
 
249
- For graph-language work, agents use `chain-insights-cypher` plus
250
- `chain-insights-schema-evm`.
249
+ For graph-language work, agents use `chain-insights-cypher`.
251
250
 
252
251
  ## Supported Agent Setup
253
252
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "chain-insights",
3
- "version": "0.44.0",
3
+ "version": "0.44.1",
4
4
  "description": "AML investigation CLI and MCP proxy for blockchain risk screening and Chain Insights Graph access",
5
5
  "homepage": "https://chain-insights.ai",
6
6
  "repository": {
@@ -1,13 +1,12 @@
1
1
  ---
2
2
  name: chain-insights-cypher
3
- description: Use when answering any question about addresses, money flows, transfers, transactions or blocks with Chain Insights, when writing or reviewing graph_query or graph_query_batch ISO GQL, when choosing between USE topology, USE facts and USE chain, or when a graph query is refused. Address, timestamp, layer and refusal rules. Load the schema skill for labels and properties.
3
+ description: Use when answering any question about addresses, money flows, transfers, transactions or blocks with Chain Insights, when tracing where money went or came from, when writing or reviewing graph_query or graph_query_batch ISO GQL, when choosing between USE topology, USE facts and USE chain, or when a graph query is refused. Address, unit, layer, graph search and refusal rules, with one query for each kind of search.
4
4
  ---
5
5
 
6
6
  # Chain Insights Cypher
7
7
 
8
8
  Standard ISO GQL for `graph_query` and `graph_query_batch`. Read-only. No
9
- `CALL`, no procedures, no vendor syntax. Load `chain-insights-schema-evm` for
10
- labels and properties.
9
+ `CALL`, no procedures, no vendor syntax.
11
10
 
12
11
  Run a query with `cia mcp call graph_query network=robinhood "query=<query>"`.
13
12
  Send related reads in one call with `cia mcp call graph_query_batch network=robinhood 'queries=[{"id":"a","query":"<query>"}]'`.
@@ -23,7 +22,8 @@ need. Do not run `cia --help` to look for others.
23
22
  UTC. Compute them from the current date: a day is 86,400,000 ms. Never
24
23
  compare one with an ISO string. `block_date` is the string `"YYYY-MM-DD"`.
25
24
  `USE chain` returns `block_timestamp` as an ISO string: read it, never
26
- filter on it.
25
+ filter on it. Every `*_usd` field is US dollars. `*_raw` is the token's
26
+ smallest unit, not dollars.
27
27
  3. A shortened address, a mixed-case address, or an ISO string against a
28
28
  millisecond column gives zero rows with no error. Check these first. Zero
29
29
  rows is not proof of safety.
@@ -47,8 +47,8 @@ When two fit, as with a hash: ask `USE chain` first for the record and the resul
47
47
  The layers hand each other keys. Topology gives the pair and the first and last seen time. Chain gives the `block_date` of a hash or a height. Facts gives the `tx_id`.
48
48
  A list, a range or a whole-chain question is served on no layer. Say so, and go back to an anchored `USE topology` search.
49
49
 
50
- Recent active addresses of the whole chain, a top list, a count or a scan of a
51
- label are such questions. Do not search for a workaround. Say: "The graph
50
+ A top list, a count, a scan of a label or the recent active addresses of the
51
+ whole chain are such questions. Do not search for a workaround. Say: "The graph
52
52
  cannot list those. Name an address, a pair with a day, or a transaction hash."
53
53
 
54
54
  ## Topology
@@ -56,27 +56,18 @@ cannot list those. Name an address, a pair with a day, or a transaction hash."
56
56
  `USE topology` is the address graph: `FLOWS_TO` money flow, swaps, liquidity,
57
57
  bridges and the `LINKED` overlay. The server checks these before it runs:
58
58
 
59
- - Anchor every pattern on a full address: `{address: "<address>"}` in the
60
- node, or `WHERE a.address = "<address>"`. A list of at most 25 addresses is
61
- an anchor. An address in `RETURN`, in an `OR` or in a `$parameter` is no
62
- anchor.
63
- - The one read with no anchor is a probe: one node or one hop, no `WHERE`, no
64
- `ORDER BY`, no aggregate, and a small `LIMIT`. Its rows are arbitrary, never
65
- the newest.
66
- - A sort, an aggregate, `DISTINCT`, `collect()` or a filter on a link property
67
- needs an anchor on every pattern.
68
- - End every read with a literal `LIMIT` (`topology_admission.max_limit` holds
69
- the top). A path has at most 5 hops and a query at most 8.
70
- - Paths use bounded quantifiers such as `-[:FLOWS_TO]-{1,5}`. A `*` range, the
71
- legacy path functions, `PROFILE`, writes and `CALL` are refused.
72
- - Role flags such as `is_exchange` are absent unless true: use `IS NULL` or
73
- `IS NOT NULL`, never `= false`.
74
-
75
- A route search asks for one path: `MATCH SHORTEST 1`, or `MATCH ANY SHORTEST`
76
- in the same pattern. Use the form below as written and change only the
77
- addresses and the `RETURN`. The guard keeps the walk off pools and follows the
78
- pool trace rule in `chain-insights-schema-evm`. Keep it inside the pattern: a
79
- `WHERE` after the pattern runs too late.
59
+ - Anchor every pattern on a full address: `{address: "<address>"}` in the node, or `WHERE a.address = "<address>"`. A list of at most 25 addresses is an anchor. An address in `RETURN`, in an `OR` or in a `$parameter` is no anchor.
60
+ - The one read with no anchor is a probe: one node or one hop, no `WHERE`, no `ORDER BY`, no aggregate, and a small `LIMIT`. Its rows are arbitrary.
61
+ - A sort, an aggregate, `DISTINCT`, `collect()` or a filter on a link property needs an anchor on every pattern.
62
+ - End every read with a literal `LIMIT`: at most 5,000 rows, 100 for a probe. A path has at most 5 hops and a query at most 8. The live numbers are in `topology_admission` (`cia network robinhood --json`).
63
+ - Paths use bounded quantifiers such as `-[:FLOWS_TO]-{1,5}`. A `*` range, the legacy path functions, `PROFILE`, writes and `CALL` are refused.
64
+ - Role flags `is_exchange`, `is_scam`, `is_victim` and `is_sanctioned` are absent unless true: use `IS NULL` or `IS NOT NULL`, never `= false`.
65
+
66
+ ## Graph searches
67
+
68
+ Each query below is admitted by the live server. Change only the addresses and the `RETURN`. Keep the guards inside the pattern: they apply the [pool trace rule](#pool-trace-rule), and a `WHERE` after a `SHORTEST` pattern runs too late. A walk follows links, not coins: confirm a hop with a pair and a day on `USE facts`.
69
+
70
+ Route between two addresses, one path. Only `MATCH SHORTEST 1` and `MATCH ANY SHORTEST` are served: a count above 1 is `route_search_refused`.
80
71
 
81
72
  ```cypher
82
73
  USE topology
@@ -85,68 +76,153 @@ RETURN [n IN nodes(p) | n.address] AS route
85
76
  LIMIT 5
86
77
  ```
87
78
 
88
- One address, its labels, counts and activity window:
79
+ Several routes, up to 3 hops, in no set order. Add no `ORDER BY`: it can end in `query_timeout`.
80
+
81
+ ```cypher
82
+ USE topology
83
+ MATCH p = (a:Address {address: "0x31a817802ee183eb8b13167ffe24bd28dcc6f30c"} WHERE NOT a:Pool) (()-[:FLOWS_TO|SWAPPED]-(via:Address) WHERE NOT via:Pool){0,2} ()-[:FLOWS_TO|SWAPPED]-(b:Address {address: "0x7e3702e9dfaa847f9829a258f1e26fa431160662"})
84
+ RETURN [n IN nodes(p) | n.address] AS route, length(p) AS hops LIMIT 5
85
+ ```
86
+
87
+ Where the money went, up to 3 hops out:
88
+
89
+ ```cypher
90
+ USE topology
91
+ MATCH p = (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"} WHERE NOT a:Pool) (()-[:FLOWS_TO|SWAPPED]->(via:Address) WHERE NOT via:Pool){0,2} ()-[:FLOWS_TO|SWAPPED]->(b:Address)
92
+ RETURN b.address AS to_address, length(p) AS hops LIMIT 25
93
+ ```
94
+
95
+ Where the money came from, up to 3 hops in:
96
+
97
+ ```cypher
98
+ USE topology
99
+ MATCH p = (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"} WHERE NOT a:Pool) (()<-[:FLOWS_TO|SWAPPED]-(via:Address) WHERE NOT via:Pool){0,2} ()<-[:FLOWS_TO|SWAPPED]-(b:Address)
100
+ RETURN b.address AS from_address, length(p) AS hops LIMIT 25
101
+ ```
102
+
103
+ Counterparties that two addresses share:
104
+
105
+ ```cypher
106
+ USE topology
107
+ MATCH (a:Address {address: "0x7e3702e9dfaa847f9829a258f1e26fa431160662"})-[:FLOWS_TO|SWAPPED]-(c:Address)-[:FLOWS_TO|SWAPPED]-(b:Address {address: "0x31a817802ee183eb8b13167ffe24bd28dcc6f30c"}) WHERE NOT a:Pool AND NOT c:Pool
108
+ RETURN DISTINCT c.address AS shared_address LIMIT 25
109
+ ```
110
+
111
+ Ownership cluster: `LINKED` says one actor stands behind both addresses. It is undirected. One hop, `-[l:LINKED]-`, gives `l.basis` and `l.confidence`.
89
112
 
90
113
  ```cypher
91
114
  USE topology
92
- MATCH (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"})
93
- RETURN a.address AS address, a.labels AS labels, a.degree_in AS degree_in,
94
- a.degree_out AS degree_out, a.last_activity_timestamp AS last_activity_timestamp
95
- LIMIT 1
115
+ MATCH p = (a:Address {address: "0x9740a8e0197689d144b19da4bdc9ef65fef11cda"})-[:LINKED]-{1,2}(b:Address)
116
+ RETURN b.address AS linked_address, length(p) AS hops LIMIT 25
96
117
  ```
97
118
 
119
+ Operator view: the owners whose tokens an operator moved. A fact, not proof of malicious intent: relayers and sweepers look alike. A transfer with no USD value counts 0, so `amount_usd_sum` is a floor.
120
+
121
+ ```cypher
122
+ USE topology
123
+ MATCH (owner:Address)-[o:OPERATED_BY]->(operator:Address {address: "0xdd509c9f91f66a18802ef5b3d54c73b62ea1ca08"})
124
+ RETURN owner.address AS owner_address, o.tx_count AS tx_count, o.amount_usd_sum AS amount_usd_sum ORDER BY o.tx_count DESC LIMIT 10
125
+ ```
126
+
127
+ Swaps an address paid for. A facts `SWAP` row has no route: the pools are `SWAPPED.pools`. A side with no price adds 0 to `sold_usd` and `bought_usd`: 0 can mean no price.
128
+
129
+ ```cypher
130
+ USE topology
131
+ MATCH (a:Address {address: "0x0168d9f5cac7d63eb75095cef316d68b0dc42bc6"})-[s:SWAPPED]->(b:Address)
132
+ RETURN b.address AS recipient, s.sold_usd AS sold_usd, s.bought_usd AS bought_usd, s.pools AS pools ORDER BY s.swap_count DESC LIMIT 25
133
+ ```
134
+
135
+ Pool trace: who took liquidity out of the pools an address paid into.
136
+
137
+ ```cypher
138
+ USE topology
139
+ MATCH (a:Address {address: "0x7a31dd32a880827477ab2bbeff47db188c896815"})-[:FLOWS_TO]->(p:Pool)-[r:REMOVED_LIQUIDITY]->(b:Address) WHERE NOT a:Pool AND b.address <> a.address
140
+ RETURN p.address AS pool, b.address AS receiver, r.usd AS removed_usd, r.receiver_provided AS receiver_provided LIMIT 25
141
+ ```
142
+
143
+ Bridges: the remote chains an address used. A `:Chain` is no `Address`: two users of one bridge are not connected through it.
144
+
145
+ ```cypher
146
+ USE topology
147
+ MATCH (a:Address {address: "0x9a8f92a830a5cb89a3816e3d267cb7791c16b04d"})-[x:BRIDGED]->(c:Chain)
148
+ RETURN c.network AS remote_network, c.address AS endpoint, x.events AS events LIMIT 25
149
+ ```
150
+
151
+ ## Pool trace rule
152
+
153
+ `:Pool` is a second label on an `Address`: the pool of a swap route or a
154
+ liquidity event. A trace that walks out of a pool on `FLOWS_TO` lands on every
155
+ trader who used it. Every trace follows this rule:
156
+
157
+ 1. Enter a `:Pool` on any edge.
158
+ 2. Leave a `:Pool` only on `REMOVED_LIQUIDITY`, to the address the liquidity
159
+ was paid to.
160
+ 3. Never leave a `:Pool` on `FLOWS_TO`.
161
+ 4. Across a swap, follow `SWAPPED` from payer to recipient, between two
162
+ different addresses. Do not walk through the pool.
163
+
164
+ So a walk never starts at a pool and never passes through one. It may end at one. Guard the start with `WHERE NOT a:Pool` and each address in the middle with `WHERE NOT via:Pool`, and follow `FLOWS_TO|SWAPPED`, as above. Exchange hot wallets end a trace: pass through an address only when `is_exchange IS NULL`.
165
+
166
+ ## Find the fields
167
+
168
+ The graph holds more fields than this skill names. Read the keys of a sample. A contract carries more keys than a plain address. Read `degree_in` and `degree_out` of an address before you walk from it: a hub ends in `query_timeout`.
169
+
170
+ ```cypher
171
+ USE topology
172
+ MATCH (a:Address) RETURN keys(a) AS keys LIMIT 20
173
+ ```
174
+
175
+ ```cypher
176
+ USE topology
177
+ MATCH ()-[r:FLOWS_TO]->() RETURN keys(r) AS keys LIMIT 5
178
+ ```
179
+
180
+ Name another link type to read its keys: `SWAPPED`, `LINKED`, `OPERATED_BY`, `BRIDGED`, `ADDED_LIQUIDITY` or `REMOVED_LIQUIDITY`. `synced_through_height` and `pair_key` are bookkeeping: never filter or sort on them.
181
+
182
+ The catalog calls `CALL db.labels()`, `CALL db.relationshipTypes()`, `CALL db.propertyKeys()`, `CALL db.schema.visualization()` and `SHOW INDEXES` are being enabled on the server. Do not send them until it serves them.
183
+
98
184
  ## Facts: an address pair with one day
99
185
 
100
- `USE facts` looks up rows you already know. A facts read names an address pair with one day, or one `tx_id`. A pair is both addresses, from then to, each as `{address: "<address>"}`, and the day is `t.block_date = "YYYY-MM-DD"`. One address, a day alone, a window of days, a block range and a bare `LIMIT` are not enough.
186
+ `USE facts` looks up rows you already know. A facts read names an address pair with one day, or one `tx_id`. A pair is both addresses, from then to, each as `{address: "<address>"}`, and the day is `t.block_date = "YYYY-MM-DD"`. One address, a day alone, a window of days, a block range and a bare `LIMIT` are not enough. It serves `TRANSFER`, `SWAP`, `LIQUIDITY_ADD`, `LIQUIDITY_REMOVE` and `BRIDGE_CROSSING` rows.
101
187
 
102
188
  - A reply holds at most 200 rows, whatever the `LIMIT`.
103
189
  - A facts read has one relationship and no hop. For a walk, go to topology.
104
190
  - A facts read takes no `ORDER BY`. Rows come in the server's own order. Sort the page yourself.
105
191
  - A facts read covers one day. For more days, send one read for each day.
106
192
  - Amounts and USD values come back as text, such as `"5.23661492"`. Convert them before you add them.
193
+ - `TRANSFER` columns: `tx_id`, `block_date`, `block_height`, `block_timestamp`, `event_index`, `edge_index`, `kind`, `asset_contract`, `asset_symbol`, `amount`, `amount_usd`, `price_usd`, `price_missing`, `token_id`, `token_standard`, `operator_address`, `raw_amount` and `decimals`. `kind` is `token`, `native` or `internal`: an `internal` row is ETH a contract sends while it runs a call.
107
194
 
108
195
  ```cypher
109
196
  USE facts
110
- MATCH (a:Address {address: "0x31a817802ee183eb8b13167ffe24bd28dcc6f30c"})-[t:TRANSFER]->(b:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"})
111
- WHERE t.block_date = "2026-07-10"
112
- RETURN t.tx_id AS tx_id, t.block_timestamp AS block_timestamp, t.asset_symbol AS asset_symbol,
113
- t.amount AS amount, t.amount_usd AS amount_usd, t.kind AS kind
114
- LIMIT 50
197
+ MATCH (a:Address {address: "0x31a817802ee183eb8b13167ffe24bd28dcc6f30c"})-[t:TRANSFER]->(b:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"}) WHERE t.block_date = "2026-07-10"
198
+ RETURN t.tx_id AS tx_id, t.block_timestamp AS block_timestamp, t.asset_symbol AS asset_symbol, t.amount AS amount, t.amount_usd AS amount_usd, t.kind AS kind LIMIT 50
115
199
  ```
116
200
 
117
201
  One transaction hash needs no day. The server finds it:
118
202
 
119
203
  ```cypher
120
204
  USE facts
121
- MATCH (a:Address)-[t:TRANSFER]->(b:Address)
122
- WHERE t.tx_id = "0x044587122970de1e3c377a8ed7ab56a49c777a2b7441a2f5d9ca32dbab9fbe71"
123
- RETURN a.address AS from_address, b.address AS to_address, t.amount AS amount, t.kind AS kind
124
- LIMIT 50
205
+ MATCH (a:Address)-[t:TRANSFER]->(b:Address) WHERE t.tx_id = "0x044587122970de1e3c377a8ed7ab56a49c777a2b7441a2f5d9ca32dbab9fbe71"
206
+ RETURN a.address AS from_address, b.address AS to_address, t.amount AS amount, t.kind AS kind LIMIT 50
125
207
  ```
126
208
 
127
209
  ## Chain: one key, one node
128
210
 
129
- `USE chain` asks the chain node for one known thing: `Transaction` by `hash`,
130
- `Block` by `height` or `hash`, or `Head`. One node, literal keys in braces, a
131
- `RETURN` of `var.property` items, no `WHERE`, no range. Read its limits in
132
- `chain_admission` (`cia network robinhood --json`).
211
+ `USE chain` asks the chain node for one known thing: `Transaction` by `hash`, `Block` by `height` or `hash`, or `Head`. One node, literal keys in braces, a `RETURN` of `var.property` items, no `WHERE`, no range. Read its limits in `chain_admission` (`cia network robinhood --json`).
133
212
 
134
213
  ```cypher
135
214
  USE chain
136
- MATCH (t:Transaction {hash: "0x044587122970de1e3c377a8ed7ab56a49c777a2b7441a2f5d9ca32dbab9fbe71"})
137
- RETURN t.status, t.block_height, t.block_date
215
+ MATCH (t:Transaction {hash: "0x044587122970de1e3c377a8ed7ab56a49c777a2b7441a2f5d9ca32dbab9fbe71"}) RETURN t.status, t.block_height, t.block_date
138
216
  ```
139
217
 
140
218
  ```cypher
141
219
  USE chain
142
- MATCH (b:Block {height: 79841521})
143
- RETURN b.hash, b.block_date
220
+ MATCH (b:Block {height: 79841521}) RETURN b.hash, b.block_date
144
221
  ```
145
222
 
146
223
  ```cypher
147
224
  USE chain
148
- MATCH (h:Head)
149
- RETURN h.height, h.age_seconds, h.warehouse_blocks_behind, h.graph_blocks_behind
225
+ MATCH (h:Head) RETURN h.height, h.age_seconds, h.warehouse_blocks_behind, h.graph_blocks_behind
150
226
  ```
151
227
 
152
228
  ## When a query is refused
@@ -176,23 +252,14 @@ Claude Desktop draws a `graph_query` answer from its column names. Alias the
176
252
  | A `day`, `date` or `*_timestamp` column, and number columns | A chart, one line for each number column. |
177
253
  | Anything else | A table. |
178
254
 
179
- A graph also reads these optional columns: `amount_usd_sum`, `tx_count`,
180
- `first_seen_timestamp`, `last_seen_timestamp`, `link_kind`, `from_labels` and
181
- `to_labels`. In `graph_query_batch`, each query draws its own tab. Claude Code
182
- draws nothing and shows the rows as text.
255
+ A graph also reads these optional columns: `amount_usd_sum`, `tx_count`, `first_seen_timestamp`, `last_seen_timestamp`, `link_kind`, `from_labels` and `to_labels`. In `graph_query_batch`, each query draws its own tab. Claude Code draws nothing and shows the rows as text.
183
256
 
184
257
  A graph, the newest receivers of one address. Flip the arrow for its senders:
185
258
 
186
259
  ```cypher
187
260
  USE topology
188
- MATCH (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"})-[f:FLOWS_TO]->(b:Address)
189
- WHERE NOT a:Pool
190
- RETURN a.address AS from_address, b.address AS to_address,
191
- f.amount_usd_sum AS amount_usd_sum, f.tx_count AS tx_count,
192
- f.last_seen_timestamp AS last_seen_timestamp
193
- ORDER BY f.last_seen_timestamp DESC
194
- LIMIT 25
261
+ MATCH (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"})-[f:FLOWS_TO]->(b:Address) WHERE NOT a:Pool
262
+ RETURN a.address AS from_address, b.address AS to_address, f.amount_usd_sum AS amount_usd_sum, f.tx_count AS tx_count, f.last_seen_timestamp AS last_seen_timestamp ORDER BY f.last_seen_timestamp DESC LIMIT 25
195
263
  ```
196
264
 
197
- A chart is the facts read of one pair over one day above, with `block_timestamp`
198
- and `amount_usd` in the `RETURN`.
265
+ A chart is the facts read of one pair over one day above, with `block_timestamp` and `amount_usd` in the `RETURN`.
@@ -1,4 +1,4 @@
1
1
  interface:
2
2
  display_name: 'Chain Insights Cypher'
3
3
  short_description: 'Write bounded ISO GQL for graph_query and graph_query_batch'
4
- default_prompt: 'Use Chain Insights graph_query or graph_query_batch with explicit network. Pick the layer first: USE topology to search, USE facts or USE chain to look up one known thing. Write bounded ISO GQL on topology, and act on the class of a refusal. Load a schema skill for labels. Do not invent a query cookbook.'
4
+ default_prompt: 'Use Chain Insights graph_query or graph_query_batch with explicit network. Pick the layer first: USE topology to search, USE facts or USE chain to look up one known thing. Write bounded ISO GQL on topology, start a graph search from the query shown for its kind, find the fields of the graph with a sampling read, and act on the class of a refusal.'