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.
- package/README.md +6 -6
- package/bin/install.cjs +2 -4
- package/dist/public-tools-CZyeptJQ.mjs.map +1 -1
- package/docs/graph-query-compatibility.md +4 -5
- package/docs/graph-tools.md +13 -11
- package/docs/mcp-proxy.md +4 -5
- package/package.json +1 -1
- package/skills/chain-insights-cypher/SKILL.md +132 -65
- package/skills/chain-insights-cypher/agents/openai.yaml +1 -1
- package/skills/chain-insights-schema-evm/SKILL.md +0 -541
|
@@ -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-
|
|
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-
|
|
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
|
|
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
|
|
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
|
package/docs/graph-tools.md
CHANGED
|
@@ -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
|
|
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-
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
|
315
|
+
Agent installers ship one skill:
|
|
315
316
|
|
|
316
|
-
- `chain-insights-cypher`: ISO GQL dialect, layer routing
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
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-
|
|
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
|
|
207
|
-
|
|
208
|
-
|
|
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
|
|
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,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,
|
|
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.
|
|
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
|
-
|
|
51
|
-
|
|
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
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
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: "
|
|
93
|
-
RETURN
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
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.'
|