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.
@@ -1,541 +0,0 @@
1
- ---
2
- name: chain-insights-schema-evm
3
- description: Use when reading the EVM / Robinhood graph map — node labels, relationships, and properties for graph_query and graph_query_batch. Names only what the live server serves.
4
- ---
5
-
6
- # Chain Insights schema: EVM / Robinhood
7
-
8
- The map of the graph that `network=robinhood` serves. Every label,
9
- relationship and property below was read from the live server. Load
10
- `chain-insights-cypher` for the query rules and the three read layers.
11
-
12
- ## Units and addresses
13
-
14
- - An address is 42 characters: `0x` and 40 lowercase hex digits. Write it in
15
- full in every query and every answer. Never shorten it with `...` or `…`. A
16
- shortened or mixed-case address matches nothing and gives zero rows, with no
17
- error.
18
- - `*_timestamp` on topology and facts is an integer in milliseconds since the
19
- Unix epoch, UTC. Never compare it with an ISO string. `USE chain` is the
20
- exception: its `block_timestamp` is an ISO string such as
21
- `"2026-07-10T14:17:12Z"`.
22
- - `block_date` is a UTC day, `"YYYY-MM-DD"`.
23
- - `amount_usd_sum`, `total_*_usd` and every `*_usd` field are US dollars.
24
- They are numbers on topology and text on facts, such as `"5.23661492"`.
25
- - `*_raw` fields are exact token quantities in the token's smallest unit. They
26
- are not USD.
27
- - `*_height` and `*_block` fields are block numbers.
28
-
29
- ## Topology labels
30
-
31
- | Label | What it is |
32
- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
33
- | `Address` | One chain address. Keyed by raw `address`. |
34
- | `Pool` | A second label on an `Address`: the pool of a swap route or a liquidity event. Both DEX layers set it, so a pool with liquidity and no swap carries it. The node keeps `:Address` and its properties. See the [pool trace rule](#pool-trace-rule). |
35
- | `Chain` | The far side of a bridge: a remote chain and the endpoint used on it. Never an `Address`, so no `FLOWS_TO` walk passes through it. |
36
- | `EvmAuthorizationRequest` | One EIP-7702 authorization, keyed by `request_id`. Never an `Address`, so no `FLOWS_TO` walk passes through it. |
37
- | `Exchange`, `Scam`, `Victim`, `Sanctioned` | Role labels, a second label on an `Address`. See [Role labels and flags](#role-labels-and-flags). |
38
- | `SmartAccount`, `Bundler`, `Paymaster`, `EntryPoint` | Account-abstraction roles, a second label on an `Address`. An `EntryPoint` is the contract the user operations go through. |
39
- | `Protocol` | A token, contract, DEX or DeFi address, a second label on an `Address`. The contract name is in `labels`. |
40
-
41
- ## Topology relationships
42
-
43
- | Relationship | Shape | Meaning |
44
- | ---------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
45
- | `FLOWS_TO` | `(:Address)-[:FLOWS_TO]->(:Address)` | Lifetime money flow. Directed. |
46
- | `SWAPPED` | `(:Address)-[:SWAPPED]->(:Address)` | Swap payer to swap recipient, two different addresses. Directed. |
47
- | `ADDED_LIQUIDITY` | `(:Address)-[:ADDED_LIQUIDITY]->(:Pool)` | Provider to pool. Directed. |
48
- | `REMOVED_LIQUIDITY` | `(:Pool)-[:REMOVED_LIQUIDITY]->(:Address)` | Pool to the address the liquidity was paid to. Directed. |
49
- | `BRIDGED` | `(:Address)-[:BRIDGED]->(:Chain)` out, `(:Chain)-[:BRIDGED]->(:Address)` in | Bridge use, per address and remote endpoint. Directed. |
50
- | `OPERATED_BY` | `(:Address)-[:OPERATED_BY]->(:Address)` | Owner to the transaction sender or event operator. Directed. Topology only. |
51
- | `LINKED` | `(:Address)-[:LINKED]-(:Address)` | Same-actor overlay. Undirected. Topology only. |
52
- | `APPROVED` | `(:Address)-[:APPROVED]->(:Address)` | Token owner to spender. One link per pair. Directed. |
53
- | `DEPLOYED_CONTRACT` | `(:Address)-[:DEPLOYED_CONTRACT]->(:Address)` | Deployer to the contract it created. One link per creation. Directed. |
54
- | `SPONSORED` | `(:Address)-[:SPONSORED]->(:Address)` | Paymaster to the smart account it paid for. Directed. |
55
- | `BUNDLED` | `(:Address)-[:BUNDLED]->(:Address)` | Bundler to the smart account it submitted for. Directed. |
56
- | `SIGNED_FOR` | `(:Address)-[:SIGNED_FOR]->(:Address)` | Signing key to the smart account it signs for. Directed. |
57
- | `SIGNED_AUTHORIZATION` | `(:Address)-[:SIGNED_AUTHORIZATION]->(:EvmAuthorizationRequest)` | EIP-7702: a wallet to the authorization it signed. Directed. |
58
-
59
- `LINKED`, `SWAPPED`, `ADDED_LIQUIDITY`, `REMOVED_LIQUIDITY` and `BRIDGED` are
60
- topology-only. Do not query them on facts. Facts serves their rows under other
61
- names: see [Facts labels and relationships](#facts-labels-and-relationships).
62
-
63
- One edge holds the lifetime totals of one pair. Single events are facts rows.
64
-
65
- Not served today: the risk layer is off (`layers.risk.enabled` is false in
66
- `meta_network_capabilities`). An `Address` has no `risk_score` or `risk_level`,
67
- and the graph holds no ML pattern link such as `RISK_PROXIMITY`. Do not read or
68
- query them.
69
-
70
- ## Bookkeeping fields on links
71
-
72
- These fields show up in `keys()`. They are not part of the contract. Do not
73
- filter, sort or group on them.
74
-
75
- | Field | On | Meaning |
76
- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77
- | `synced_through_height` | `FLOWS_TO`, `SWAPPED`, `OPERATED_BY`, `ADDED_LIQUIDITY`, `REMOVED_LIQUIDITY`, `BRIDGED`, `APPROVED`, `SPONSORED`, `BUNDLED`, `SIGNED_FOR` | End block of the last sync range added into the link. The link holds every event up to this block. `graph_progress` in `meta_network_capabilities` says how far each kind of link has been synced. |
78
- | `pair_key` | `FLOWS_TO`, `SWAPPED` | Lookup key the sync builds from the ids of the two nodes. It can change when the graph is rebuilt. |
79
-
80
- `LINKED`, `DEPLOYED_CONTRACT` and `SIGNED_AUTHORIZATION` carry neither field.
81
-
82
- ## Address properties
83
-
84
- | Property | Notes |
85
- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
86
- | `address` | Raw H160, lowercase. Public results keep this form. |
87
- | `network` | Address space. `robinhood` here. |
88
- | `labels` | Role words and names on the node. |
89
- | `is_exchange` / `is_scam` / `is_victim` / `is_sanctioned` | Role flags. Each is absent unless true. |
90
- | `label_risk_labels` / `label_risk_levels` / `label_risk_updated_timestamps` | Per-label risk, three parallel lists. Entry i of each list is one label row. |
91
- | `tx_in_count` / `tx_out_count` / `tx_total_count` | Lifetime counts. |
92
- | `degree_in` / `degree_out` / `degree_total` | Neighbor counts. |
93
- | `total_in_usd` / `total_out_usd` / `total_volume_usd` / `net_flow_usd` | Lifetime USD. |
94
- | `first_activity_timestamp` / `last_activity_timestamp` / `activity_span_days` | Activity window. |
95
-
96
- A contract address also carries `is_contract` and the creation fields
97
- `contract_creation_tx_id`, `contract_creation_type`,
98
- `contract_creation_confidence`, `contract_creation_block_height` and
99
- `contract_creation_timestamp`. They come from its newest creation.
100
- `is_contract` is `true` or absent. A token contract also carries
101
- `token_standard`, such as `ERC20`.
102
-
103
- ## Role labels and flags
104
-
105
- The graph says what an address is, not why a detector said so. `labels` holds
106
- role words, never detector names.
107
-
108
- | Label kind | Node label | Flag | Role word in `labels` |
109
- | ------------ | ------------- | --------------- | ---------------------------------- |
110
- | `exchange` | `:Exchange` | `is_exchange` | `Exchange`, plus the exchange name |
111
- | `risk` | `:Scam` | `is_scam` | `Scam` |
112
- | `protection` | `:Victim` | `is_victim` | `Victim` |
113
- | `sanctioned` | `:Sanctioned` | `is_sanctioned` | `Sanctioned`, plus the entity name |
114
-
115
- - `:Exchange` is a node label. It is a second label on an `Address`, like
116
- `:Scam`, `:Victim` and `:Sanctioned`.
117
- - The four role flags `is_exchange`, `is_scam`, `is_victim` and
118
- `is_sanctioned` are markers. Each is absent unless true. No flag is ever
119
- `false`. Test one with `IS NOT NULL` or `IS NULL`. Do not test `= false`.
120
- - A withdrawn label removes its node label and its flag.
121
- - Only `is_exchange` marks a terminal in a trace. See
122
- [Exchange terminals](#exchange-terminals).
123
-
124
- Read the flags of one address. A flag the address does not have reads as null:
125
-
126
- ```cypher
127
- USE topology
128
- MATCH (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"})
129
- RETURN a.labels AS labels, a.is_exchange AS is_exchange, a.is_scam AS is_scam,
130
- a.is_victim AS is_victim, a.is_sanctioned AS is_sanctioned
131
- LIMIT 1
132
- ```
133
-
134
- ## FLOWS_TO properties
135
-
136
- Lifetime aggregates. USD only. Do not use native `amount_sum`.
137
-
138
- | Property | Notes |
139
- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
140
- | `tx_count` | Count on the pair: token and native transfers plus internal native transfers (a contract sending ETH during a call, such as the ETH leg of a wrap). |
141
- | `amount_usd_sum` | Lifetime USD, internal native transfers included. |
142
- | `first_seen_timestamp` / `last_seen_timestamp` | First and last flow time. |
143
-
144
- `FLOWS_TO` carries value only. Its `pair_key` and `synced_through_height` are
145
- [bookkeeping](#bookkeeping-fields-on-links). Compute an average inline:
146
- `amount_usd_sum / toFloat(tx_count)`.
147
-
148
- `tx_count` counts token and native transfers and also internal native
149
- transfers. `USE facts` `TRANSFER` lists all three, so the rows of a pair are
150
- the transfers its link counts, up to the height the link was built to. A link
151
- covers all time, and a `USE facts` read covers one day: read a pair's
152
- transfers one day at a time. See
153
- [Facts labels and relationships](#facts-labels-and-relationships).
154
-
155
- `FLOWS_TO` into and out of pools stays as it is. A pool is a real
156
- counterparty. Follow the [pool trace rule](#pool-trace-rule) when a trace
157
- reaches one.
158
-
159
- ## Pool trace rule
160
-
161
- A pool holds many people's money. A trace that walks out of a pool on
162
- `FLOWS_TO` lands on every trader who used the pool. Every trace follows
163
- this rule:
164
-
165
- 1. Enter a `:Pool` on any edge.
166
- 2. Leave a `:Pool` only on `REMOVED_LIQUIDITY`, to the address the liquidity
167
- was paid to.
168
- 3. Never leave a `:Pool` on `FLOWS_TO`.
169
- 4. Across a swap, follow `SWAPPED` from payer to recipient, between two
170
- different addresses. Do not walk through the pool.
171
-
172
- This section is the rule's one home. The other guides point here. The MCP
173
- server's graph hints carry these four steps word for word, and a test keeps
174
- the two the same.
175
-
176
- A walk keeps step 3 with the pool guard: a `FLOWS_TO` walk never starts at a
177
- `:Pool` and never passes through one. It may end at one. A fixed-hop walk
178
- writes `WHERE NOT src:Pool AND NOT mid:Pool`. A quantified or shortest-path
179
- walk puts `WHERE NOT a:Pool` on its start and `WHERE NOT via:Pool` inside the
180
- path pattern. A walk keeps step 4 by following `FLOWS_TO|SWAPPED`, so it
181
- crosses a swap from payer to recipient. `chain-insights-cypher` shows the
182
- route form.
183
-
184
- ## Pool properties
185
-
186
- A `:Pool` node carries the `Address` properties plus its lifetime liquidity
187
- totals.
188
-
189
- | Property | Notes |
190
- | ----------------------- | ------------------------------------------ |
191
- | `liquidity_added_usd` | USD all providers added. |
192
- | `liquidity_removed_usd` | USD all receivers removed. |
193
- | `liquidity_net_usd` | Added minus removed. Near 0 means emptied. |
194
- | `provider_count` | Distinct named providers. |
195
- | `receiver_count` | Distinct named receivers. |
196
-
197
- ## SWAPPED properties
198
-
199
- One edge per payer, recipient, sold asset and bought asset. It sums the swap
200
- routes whose payer differs from the recipient. A self swap, where the payer
201
- gets the output back, makes no edge. It is still a facts `SWAP` row.
202
-
203
- Swap attribution is read from `SWAPPED`, the aggregate (`strength`, `pools`,
204
- `families`), or from the facts `SWAP` row, one route. `FLOWS_TO` carries value
205
- only, so it holds no swap stamp.
206
-
207
- | Property | Notes |
208
- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
209
- | `sold_asset` / `bought_asset` | Asset contract. `native` is the chain's native asset. |
210
- | `swap_count` | Routes summed on the edge. |
211
- | `sold_amount_raw` / `bought_amount_raw` | Exact raw token quantities, not USD. |
212
- | `sold_usd` / `bought_usd` | USD at the day price, summed over the routes on the edge. A route side with no price adds 0, so 0 can mean no price. Do not read 0 as worth nothing. |
213
- | `pools` | Pool addresses the routes used. |
214
- | `families` | Protocol families. Today every route reads `unknown`. |
215
- | `strength` | The weakest route counted: `swap` or `swap_like`. Today always `swap_like`. |
216
- | `first_seen_height` / `last_seen_height` | First and last block height. |
217
-
218
- - `swap`: the complete route is proven. Payer, recipient, assets, exact raw
219
- amounts and conservation all check out. The proof needs an execution trace
220
- (the record of the calls inside a transaction).
221
- - `swap_like`: the shape is a swap and the money moved. The pool's code is
222
- not proven, so no protocol is named.
223
-
224
- Today no route is `swap`. The swap reader reads transaction receipts only,
225
- with no execution trace. Every served route is `swap_like`, with `reason`
226
- `unknown_pool_code` and `families` `unknown`. A Uniswap V2 or V3 swap reads
227
- this way. `unknown` does not mean the protocol is unsupported. A filter on
228
- `strength = 'swap'` or on a known family matches nothing.
229
-
230
- A route whose legs could not be paired has strength `swap_unsplit`. It has no
231
- payer, recipient or pool: without a trace the reader cannot tell who paid
232
- whom. It exists in the warehouse only. It makes no edge and no facts row.
233
- `strength` is `swap` or `swap_like` on `SWAPPED` and on facts `SWAP`. A
234
- missing `SWAPPED` edge is not proof that no swap happened. Every Uniswap v4
235
- swap reads `swap_unsplit`, by design, so v4 swaps are hidden.
236
-
237
- `sold_usd` and `bought_usd` are always numbers on a link. A route side with no
238
- price adds 0 to the sum, and the link has no count of unpriced routes. The
239
- facts `SWAP` row of one route tells which: `sold_price_missing` and
240
- `bought_price_missing` say which side had no price, and the matching
241
- `sold_usd` or `bought_usd` is empty there.
242
-
243
- `pair_key` and `synced_through_height` on `SWAPPED` are
244
- [bookkeeping](#bookkeeping-fields-on-links).
245
-
246
- ## ADDED_LIQUIDITY and REMOVED_LIQUIDITY properties
247
-
248
- One edge per named provider and pool, and one per pool and named receiver.
249
- An event whose provider or receiver cannot be named makes no edge. Its facts
250
- row says `party_state` `unnamed`.
251
-
252
- | Property | Notes |
253
- | ---------------------------------------- | ------------------------------------------------------------------------------- |
254
- | `event_count` | Liquidity events summed on the edge. |
255
- | `totals_raw` | Raw amount per asset. |
256
- | `usd` | USD over the priced sides. |
257
- | `unpriced_count` | Events with a side no price service covers. |
258
- | `first_seen_height` / `last_seen_height` | First and last block height. |
259
- | `fees_raw` | `REMOVED_LIQUIDITY` only. Fees per asset, paid on top of the principal. |
260
- | `receiver_added_usd` | `REMOVED_LIQUIDITY` only. USD the receiver itself added to the same pool, or 0. |
261
- | `receiver_provided` | `REMOVED_LIQUIDITY` only. True when the receiver also added to the pool. |
262
-
263
- A receiver's profit from a pool is `usd` minus `receiver_added_usd`. A drain by
264
- a stranger has `receiver_provided` false and `receiver_added_usd` 0. A rug pull
265
- by the pool's creator has `receiver_provided` true and `usd` far above
266
- `receiver_added_usd`.
267
-
268
- ## BRIDGED properties
269
-
270
- One edge per address and remote endpoint, in each direction. `(:Address)-[:BRIDGED]->(:Chain)`
271
- is outbound. `(:Chain)-[:BRIDGED]->(:Address)` is inbound. The `:Chain` node
272
- carries `network` (the remote chain) and `address` (the endpoint on it).
273
-
274
- | Property | Notes |
275
- | ------------------------------ | -------------------------------------------------- |
276
- | `kinds` | Bridge event kinds on the pair. |
277
- | `events` | Bridge events summed on the edge. |
278
- | `totals_raw` | Raw totals per event kind and asset, as JSON text. |
279
- | `first_height` / `last_height` | First and last block height. |
280
- | `last_bridge_event_id` | The latest event on the pair. |
281
-
282
- A `:Chain` is not an `Address`. Two users of the same bridge are not
283
- connected through it.
284
-
285
- ## OPERATED_BY properties
286
-
287
- One edge aggregates one directed owner/operator pair. The source is the
288
- owner (`from_address`). The destination is the transaction sender that moved
289
- the owner's tokens (ERC-20/721), or the event operator (ERC-1155);
290
- not the approved spender. Direct transfers with an empty operator create no
291
- edge. Topology only. Do not query `OPERATED_BY` on facts.
292
-
293
- | Property | Notes |
294
- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
295
- | `tx_count` | Operator-mediated transfers in the aggregate. |
296
- | `amount_usd_sum` | Lifetime USD through the operator. |
297
- | `first_seen_timestamp` / `last_seen_timestamp` | First and last mediated transfer. |
298
- | `token_standard` | `ERC20`/`ERC721`/`ERC1155` when unambiguous. Optional — mixed-standard pairs omit it. |
299
- | `owner_address` / `operator_address` / `pair_id` | Endpoint identity on the edge. |
300
- | `valuation_tracked_count` | Transfers on the pair that are checked for a USD value: those kept with their raw amount. It can be lower than `tx_count`. |
301
- | `valued_count` | Of those, transfers that got a USD value. |
302
- | `missing_valuation_price_count` | Of those, transfers with no price for their day. |
303
- | `unknown_quantity_count` | Of those, transfers whose token decimals are unknown, so the amount is unknown. |
304
- | `unrepresentable_quantity_count` | Of those, transfers whose amount does not fit the warehouse number format. |
305
- | `usd_range_count` | Of those, transfers whose USD value is 10^20 or more. No USD value is stored. |
306
- | `valuation_complete` | `true` when `valued_count` equals `valuation_tracked_count`. |
307
- | `valuation_coverage_ratio` | `valued_count` divided by `valuation_tracked_count`. 0 when none is tracked. |
308
-
309
- `amount_usd_sum` counts a transfer with no USD value as 0. It is a floor unless
310
- `valuation_complete` is true. The counters do not add up to
311
- `valuation_tracked_count`: a transfer that fails a basic check is tracked, is
312
- not valued, and sits in none of the four reason counters.
313
-
314
- `OPERATED_BY` is a topology fact. It is not proof of malicious intent: relayers
315
- and sweepers look like drainers. Confirm with `FLOWS_TO` and label context.
316
-
317
- ## LINKED properties
318
-
319
- | Property | Notes |
320
- | ---------------- | -------------------------------------------------------------------- |
321
- | `basis` | `derived` or `associated`. |
322
- | `confidence` | Overlay confidence. |
323
- | `source_event` | Why the link exists. |
324
- | `declared_owner` | Declared controller when present. |
325
- | `last_height` | Block height of the newest owner action. |
326
- | `owner_state` | `added` on every link served. An owner that was removed has no link. |
327
-
328
- Use one visible `LINKED` hop, then `FLOWS_TO`. Do not collapse linked
329
- addresses into one node.
330
-
331
- ## APPROVED properties
332
-
333
- One link per token owner and spender, from `Approval` and `ApprovalForAll`
334
- events. An ERC-2612 permit lands here, and only here. Permit2 allowances are
335
- not in the source.
336
-
337
- | Property | Notes |
338
- | ------------------------------ | ------------------------------------------------------------------------------------ |
339
- | `granted_tokens` | Tokens the owner approved for the spender. Gains a grant, loses a revoke. |
340
- | `infinite_tokens` | Tokens whose allowance is unlimited now. Leaves on a revoke or a later finite grant. |
341
- | `has_infinite_grant` | Ever granted unlimited. Stays true after a revoke, as risk history. |
342
- | `first_height` / `last_height` | First and last block height of the approval events. |
343
- | `source_event` | `approval`. |
344
-
345
- An approval is a fact, not proof of malicious intent.
346
-
347
- ## DEPLOYED_CONTRACT properties
348
-
349
- One link per contract creation, from the deployer to the contract. An address
350
- created twice has two links.
351
-
352
- | Property | Notes |
353
- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
354
- | `kind` | How the contract was created: `direct` or `factory`. |
355
- | `tx_id` / `block_height` / `block_timestamp` | The creation transaction. |
356
- | `deployer_address` / `factory_address` / `tx_origin` | Who deployed it, through which factory, and who sent the transaction. |
357
- | `source_event` | `contract_creation`. |
358
- | `confidence_score` | The indexer's confidence in how the creation was classified (`kind`). It is 1 on every creation today. |
359
- | `call_type` / `amount` | Only when the creation was funded: the funding call (`CREATE` or `CREATE2`) and the native amount sent, as decimal text. Absent otherwise. |
360
-
361
- ## SPONSORED properties
362
-
363
- One link per paymaster and smart account, from the paymaster to the account
364
- it paid for. Lifetime totals per pair.
365
-
366
- | Property | Notes |
367
- | ------------------------------ | ----------------------------------------- |
368
- | `operations` | User operations summed on the link. |
369
- | `failed_operations` | Operations that failed. |
370
- | `entrypoints` | EntryPoint contracts the operations used. |
371
- | `first_height` / `last_height` | First and last block height. |
372
- | `source_event` | `user_operation`. |
373
-
374
- ## BUNDLED properties
375
-
376
- One link per bundler and smart account, from the bundler to the account it
377
- submitted for. It has the same properties as `SPONSORED`: `operations`,
378
- `failed_operations`, `entrypoints`, `first_height`, `last_height` and
379
- `source_event` `user_operation`.
380
-
381
- ## SIGNED_FOR properties
382
-
383
- One link per signing key and smart account, from the key to the account it
384
- signs for.
385
-
386
- | Property | Notes |
387
- | ------------------------------ | ------------------------------------------------------------------- |
388
- | `operations` | User operations the key signed for the account, summed on the link. |
389
- | `failed_operations` | Of those, operations whose user operation failed. |
390
- | `first_height` / `last_height` | First and last block height. |
391
- | `source_event` | `account_signer`. |
392
-
393
- ## SIGNED_AUTHORIZATION properties
394
-
395
- The EIP-7702 link. A plain wallet, the authority, signs a `SET_CODE`
396
- authorization and acts as a smart account from then on, running a contract's
397
- code. The link runs from the wallet to an `:EvmAuthorizationRequest`, one
398
- node per `request_id`. A token permit lands on `APPROVED`, never here.
399
-
400
- | Property | Notes |
401
- | ------------------------------ | ---------------------------- |
402
- | `source_event` | `authorization`. |
403
- | `first_height` / `last_height` | First and last block height. |
404
-
405
- ## Facts labels and relationships
406
-
407
- | Label / relationship | Shape | Notes |
408
- | -------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
409
- | `Address` | — | Row endpoint only. No `network` property. No `Pool` label. |
410
- | `TRANSFER` | `(from:Address)-[t:TRANSFER]->(to:Address)` | One transfer row: a token, a native or an internal native transfer, told by `kind`. Needs a pair and one day, or a `tx_id`. |
411
- | `SWAP` | `(payer:Address)-[s:SWAP]->(recipient:Address)` | One swap route. Needs a pair and one day, or a `tx_id`. |
412
- | `LIQUIDITY_ADD` | `(provider:Address)-[l:LIQUIDITY_ADD]->(pool:Address)` | One liquidity add. Needs a pair and one day, or a `tx_id`. |
413
- | `LIQUIDITY_REMOVE` | `(pool:Address)-[l:LIQUIDITY_REMOVE]->(receiver:Address)` | One liquidity removal. Needs a pair and one day, or a `tx_id`. |
414
- | `BRIDGE_CROSSING` | `(sender:Address)-[c:BRIDGE_CROSSING]->(recipient:Address)` | One bridge event. Needs a pair and one day, or a `tx_id`. |
415
-
416
- A relationship is served only where its data exists. Check
417
- `meta_network_capabilities` before you query one.
418
-
419
- `TRANSFER` properties include `tx_id`, `block_height`, `block_timestamp`,
420
- `event_index`, `edge_index`, `kind`, `amount`, `amount_usd`, `asset_symbol`,
421
- `asset_contract`, `price_usd`, `price_missing`. `amount`, `amount_usd` and
422
- `price_usd` come back as text.
423
-
424
- `tx_id` is the `0x` transaction hash. A facts read names an address pair with
425
- one day, or one `tx_id`. The pair is both endpoint addresses, from then to,
426
- and the day is a `block_date` equality. A `block_timestamp` window in epoch
427
- milliseconds narrows the day and is refused on its own. A facts read has one
428
- relationship and takes no `ORDER BY`.
429
-
430
- Every `TRANSFER` row has a `kind`: `token`, `native` or `internal`. A `token`
431
- row is a token or NFT transfer event. A `native` row is the chain's own coin,
432
- sent by a transaction. An `internal` row is ETH a contract sends while it runs
433
- a call, such as the ETH leg of a wrap. The `FLOWS_TO` link counts all three:
434
- see [`FLOWS_TO` properties](#flows_to-properties).
435
-
436
- `kind` is a column and a filter. Add `t.kind = "internal"` to the pair and the
437
- day to read only the internal rows. A `kind` filter narrows the read of a pair
438
- and one day. It never replaces them. For example:
439
-
440
- ```cypher
441
- USE facts
442
- MATCH (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"})-[t:TRANSFER]->(b:Address {address: "0x7e3702e9dfaa847f9829a258f1e26fa431160662"})
443
- WHERE t.block_date = "2026-07-10" AND t.kind = "internal"
444
- RETURN t.tx_id AS tx_id, t.event_index AS event_index, t.kind AS kind,
445
- t.amount AS amount, t.amount_usd AS amount_usd
446
- LIMIT 50
447
- ```
448
-
449
- An `internal` row is one call frame. Its `event_index` is the frame's position
450
- in the transaction's calls and its `edge_index` is 0. Its `amount` is the value
451
- in ETH, and `amount_usd` is that value at the day's price. `raw_amount` and
452
- `decimals` read null, so a sum of `raw_amount` skips it: sum `amount` or
453
- `amount_usd`. The call depth, the call type and the parent frame are not
454
- served.
455
-
456
- `SWAP` holds one row per route of a `swap` or `swap_like` reading, self swaps
457
- included. Read it by the payer, the recipient and one day, or by a `tx_id`.
458
- `block_timestamp` is epoch milliseconds, in filters and in results, as on
459
- `TRANSFER`.
460
-
461
- A `USE facts` `SWAP` row carries no route: it has no `pools` and no `families`
462
- column. A read that names one of them, to return it, to filter on it or to
463
- order by it, is refused. The route of a swap stays a topology question.
464
-
465
- - For the pools of the swaps of an address, read `SWAPPED.pools` and
466
- `SWAPPED.families` on `USE topology`, anchored on the payer or the recipient.
467
- `SWAPPED` has one link per payer, recipient, sold asset and bought asset, so
468
- its `pools` cover every route on the link, not one route.
469
- - `route_id` stays on the row. It ties every leg of one route together and
470
- names no pool.
471
-
472
- | Property group | Properties |
473
- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
474
- | Where | `block_date`, `block_height`, `block_timestamp`, `tx_id`, `row_index` |
475
- | Claim | `strength` (`swap` or `swap_like`), `reason` (why a claim is `swap_like`: `unknown_pool_code` today), `route_id` (ties every leg of one route together), `registry_version` |
476
- | Parties | `payer`, `recipient` |
477
- | Sold side | `sold_asset`, `sold_asset_symbol`, `sold_decimals`, `sold_amount_raw`, `sold_amount`, `sold_price_usd`, `sold_usd`, `sold_price_missing` |
478
- | Bought side | `bought_asset`, `bought_asset_symbol`, `bought_decimals`, `bought_amount_raw`, `bought_amount`, `bought_price_usd`, `bought_usd`, `bought_price_missing` |
479
-
480
- `LIQUIDITY_ADD` and `LIQUIDITY_REMOVE` hold one row per liquidity event.
481
- Read them by the two endpoints of the pattern and one day, or by a `tx_id`.
482
- `block_timestamp` is epoch milliseconds, in filters and in results, as on
483
- `TRANSFER`.
484
-
485
- | Property group | Properties |
486
- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
487
- | Where | `block_date`, `block_height`, `block_timestamp`, `tx_id`, `log_index` |
488
- | Parties | `party`, `party_state` (`named` or `unnamed`), `pool`, `family` |
489
- | First asset | `asset0`, `asset0_symbol`, `asset0_decimals`, `amount0_raw`, `amount0`, `amount0_usd`, `amount0_price_missing` |
490
- | Second asset | `asset1`, `asset1_symbol`, `asset1_decimals`, `amount1_raw`, `amount1`, `amount1_usd`, `amount1_price_missing` |
491
- | Totals | `usd`, `evidence_state` (`matched` or `amount_mismatch`), `registry_version` |
492
- | `LIQUIDITY_REMOVE` only | `principal0_raw`, `principal1_raw`, `fees0_raw`, `fees1_raw`, `principal_usd`, `fees_usd` |
493
-
494
- `usd` sums the priced sides and is empty when neither side has a price.
495
- `amount0_price_missing` and `amount1_price_missing` say which side had none.
496
- `family` on a liquidity row is `v2` or `v3`, read from the event shape. It is
497
- not a swap family: `SWAPPED.families` reads `unknown` today.
498
-
499
- `BRIDGE_CROSSING` holds one row per bridge event. Read it by the sender, the
500
- recipient and one day, or by a `tx_id`. Properties: `block_date`,
501
- `block_height`, `tx_id`, `kind`, `direction`, `lifecycle_state`,
502
- `counterpart_status`, `counterpart_chain_id`, `sender`, `recipient`,
503
- `asset_kind`, `amount_raw`, `source_kind`, `source_index`, `route_id`,
504
- `protocol`. It has no `block_timestamp`.
505
-
506
- On a facts row, USD comes from the daily price services, never from a swap.
507
- With no price, USD is empty and the matching `…price_missing` is true. A
508
- topology link sums its rows and counts a side with no price as 0: see
509
- [`SWAPPED` properties](#swapped-properties).
510
-
511
- A single-node `MATCH (a:Address)` on facts is refused. Lifetime metrics
512
- live on topology, not facts.
513
-
514
- ## USE chain
515
-
516
- `USE chain` asks the chain node for one known thing by its key. It is not a
517
- graph: there is no relationship to walk and nothing to search. Each lookup is
518
- one node with its key in braces. Load `chain-insights-cypher` for the rule that
519
- sends a question here, and for the shape of a lookup.
520
-
521
- | Label | Key | Properties |
522
- | ------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
523
- | `Transaction` | `hash` | `status`, `block_height`, `block_date`, `block_timestamp`, `block_hash`, `tx_index`, `tx_type`, `from_address`, `to_address`, `created_contract`, `value`, `nonce`, `gas_limit`, `gas_used`, `effective_gas_price`, `input_selector`, `input_size`, `log_count`, `hash`, `tx_key` |
524
- | `Block` | `height` or `hash`, exactly one | `height`, `hash`, `parent_hash`, `block_date`, `block_timestamp`, `tx_count`, `gas_limit`, `gas_used`, `base_fee_per_gas` |
525
- | `Head` | none | `height`, `hash`, `block_timestamp`, `age_seconds`, `warehouse_complete_through_block`, `warehouse_blocks_behind`, `graph_complete_through_block`, `graph_blocks_behind` |
526
-
527
- These labels are all the chain layer serves. There is no `:Address` lookup
528
- here: find an address on `USE topology`, then read the pair and one day on
529
- `USE facts`. The labels that the server serves are listed in
530
- `chain_admission.lookups` of `meta_network_capabilities`. The refusal of an
531
- unknown property (`chain_not_served`) lists the properties of that label.
532
- A `block_date` is a UTC day, the same day that a facts `block_date` names.
533
- `value`, `effective_gas_price` and `base_fee_per_gas` are text, in wei.
534
-
535
- ## Exchange terminals
536
-
537
- Treat `is_exchange IS NOT NULL` nodes as terminals. Do not walk through
538
- them as intermediate hops. `is_exchange` is absent unless true, so a node
539
- with no `is_exchange` property, labelled or not, is walked through:
540
- `is_exchange IS NULL` lets a walk pass. `is_scam`, `is_victim` and
541
- `is_sanctioned` do not end a walk.