chain-insights 0.45.0 → 0.46.2

package/docs/graph-query-compatibility.md

@@ -2,12 +2,18 @@
 
 Chain Insights Graph accepts ISO GQL through `graph_query` and
 `graph_query_batch`. A query is routed by its leading `USE <graph>` clause to
-one of two backends, each with its own accepted surface:
+one of three backends, each with its own accepted surface:
 
-| Graph      | Backend                     | Query surface                              |
-| ---------- | --------------------------- | ------------------------------------------ |
-| `topology` | DozerDB, directly over Bolt | **ISO GQL**, bounded (see topology bounds) |
-| `facts`    | StarRocks warehouse         | Corpus-scoped GQL subset, compiled to SQL  |
+| Graph      | Backend                     | Query surface                                                           |
+| ---------- | --------------------------- | ----------------------------------------------------------------------- |
+| `topology` | DozerDB, directly over Bolt | **ISO GQL**, bounded (see topology bounds)                              |
+| `facts`    | StarRocks warehouse         | Corpus-scoped GQL subset, compiled to SQL                               |
+| `chain`    | The chain node              | One keyed lookup: `Transaction`, `Block`, `Address` or `Head`, by a key |
+
+The same thing has the same name on all three: `address`, `tx_id`,
+`block_height` and `block_hash`, with time in epoch milliseconds and `network`
+from the query. The `chain-insights-cypher` skill holds the table, and
+`meta_schema` reads the fields of each from the live graph.
 
 Two consequences drive everything below:
 
@@ -26,7 +32,7 @@ Two consequences drive everything below:
 > removed in the 2026-09 Robinhood Dozer cutover. Docs and skills that teach
 > those path operators or client merge are historical.
 
-## The shared-graph model — what `network` actually selects
+## The `network` argument and the `network` property
 
 Read this before writing any query that matches `:Address` without an exact
 address.
@@ -36,49 +42,44 @@ space over ONE address-grain topology graph. There is no SS58/H160 split and
 no second query network — `network=robinhood` selects the one public graph and
 there is no `network=robinhood_evm` argument to pass.
 
-The consequence is exact and easy to get wrong:
-
-> **The `network` argument selects the GRAPH, not the subset of addresses
-> inside it.**
+`network` is also a property of every node and every relationship on
+`USE topology`, `USE facts` and `USE chain`. Its value is the query's `network`
+argument. It is computed and never stored, with one exception: on a `:Chain`
+node (the far side of a bridge) it names the remote chain, and it is stored and
+read as it is.
 
-A `USE topology` query that matches `:Address` without a network predicate
-scans the whole public H160 space; scope by the node property when you want an
-explicit subset:
+> **A filter on `network` never narrows a scan.** `WHERE a.network = "robinhood"`
+> keeps every row, and a filter on another value gives no rows. Narrow a query
+> with an address anchor.
 
 ```cypher
--- WRONG: unbounded sweep — returns every H160 address in the public space
-USE topology MATCH (a:Address) RETURN a.address AS address LIMIT 100
+-- A probe: one node, no WHERE, a LIMIT of 100 or less
+USE topology MATCH (a:Address) RETURN a.address AS address, a.network AS network LIMIT 20
 
--- RIGHT: scope by the node property
-USE topology MATCH (a:Address) WHERE a.network = "robinhood"
-RETURN a.address AS address LIMIT 100
+-- Anchored: an address in the pattern
+USE topology MATCH (a:Address {address: "0x…"})-[f:FLOWS_TO]->(b:Address)
+WHERE NOT a:Pool
+RETURN b.address AS address LIMIT 100
 ```
 
-Exact-address lookups (`MATCH (a:Address {address: "0x…"})`) need no predicate:
-the address is already a unique key, and adding a network predicate there fails
-closed on an H160 address screened under the chain's primary network name.
-
-### `USE facts` is the opposite case
+### `USE facts` serves it too
 
-`facts` is the one place each network _does_ get its own backing database —
-the routing metadata on a result reports it as
-`facts.routing.starrocks_database`. Because the database already scopes the
-network, the facts `Address` label has **no mapped `network` property at all**:
+Facts rows and the facts `Address` endpoint carry `network` as well. The server
+computes it from the query's `network` argument. No view holds a column for it:
 
 ```text
 USE facts MATCH (a:Address {address:"0x…"})-[t:TRANSFER]->(b:Address {address:"0x…"})
           WHERE t.block_date = "2026-07-11"
-          RETURN a.network AS from_network
-→ unknown graph identifier: property "network" is not mapped on label "Address"
+          RETURN a.network AS from_network, t.network AS row_network
+→ from_network = robinhood, row_network = robinhood
 ```
 
-`Address` on facts is served only as a `TRANSFER` relationship endpoint, so a
-single-node `MATCH (a:Address)` is refused there as well. Read address-grain
-node properties — including `network` — on `USE topology`.
-
-Getting these two rules backwards is not a stylistic problem. An unscoped
-topology sweep publishes wrong-network results at double the metered cost, and
-a facts query projecting `network` hard-fails rather than degrading.
+A filter on `network` is no anchor: a facts read still names an address pair
+with one day, or one `tx_id`. `Address` on facts is served only as a `TRANSFER`
+relationship endpoint, so a single-node `MATCH (a:Address)` is refused there as
+well. Facts serves no kind label: a read that names `:Account` or `:Contract` is
+refused, so read the kind on `USE topology`, or on `USE chain` with
+`is_contract` and `nonce`.
 
 ## `topology` — ISO GQL
 
@@ -147,8 +148,9 @@ not valued, and sits in none of the four reason counters.
 
 The canonical probe is point-anchored and sub-second on the hosted endpoint:
 given one operator address, its top owners. Scope comes from the tool's
-`network=robinhood` argument (it selects the graph — see the shared-graph
-model above), so no in-query network predicate is needed:
+`network=robinhood` argument (it selects the graph — see
+[the `network` argument](#the-network-argument-and-the-network-property)), so no
+in-query network predicate is needed:
 
 ```cypher
 USE topology
@@ -172,18 +174,15 @@ acting.
 The whole-graph high-fan-in sweep — every operator grouped by distinct owner
 count — is a valid shape but a heavy one: at millions of edges it can exceed
 the per-query limit (60 seconds by default), and a sweep that times out can
-still consume the metered seconds. Scope both endpoints by the network
-property (this match has no exact-address key, so the shared-graph rule
-applies), bound it by a recent `last_seen_timestamp` window — recompute the
-cutoff rather than copying a literal, for example now minus 7 days in Unix
-milliseconds — and prefer the point-anchored probe on metered endpoints:
+still consume the metered seconds. A `network` filter does not narrow it. Bound
+it by a recent `last_seen_timestamp` window — recompute the cutoff rather than
+copying a literal, for example now minus 7 days in Unix milliseconds — and
+prefer the point-anchored probe on metered endpoints:
 
 ```cypher
 USE topology
 MATCH (owner:Address)-[operation:OPERATED_BY]->(operator:Address)
-WHERE owner.network = "robinhood"
-  AND operator.network = "robinhood"
-  AND operation.last_seen_timestamp >= 1787631843154  -- now minus 7 days, ms
+WHERE operation.last_seen_timestamp >= 1787631843154  -- now minus 7 days, ms
 WITH operator,
      count(DISTINCT owner) AS owner_count,
      sum(operation.tx_count) AS transfer_count
@@ -382,6 +381,7 @@ StarRocks. Use the topology graph, or restructure:
 | Self-joins / node-to-node comparison `WHERE a <> b`                             | Compare key properties: `a.address <> b.address`                                                                        |
 | Untyped relationship `-[r]->`                                                   | Name the relationship type                                                                                              |
 | Metadata functions `keys(n)`, `labels(n)`, `type(r)`                            | Project known properties explicitly                                                                                     |
+| `:Account` and `:Contract` kind labels                                          | `USE topology` for the label, or `USE chain` for `is_contract` and `nonce`. Facts serves no kind                        |
 
 There is no longer a local pinned conformance suite; verify supported and
 rejected shapes against a live Chain Insights Graph endpoint.
@@ -408,6 +408,16 @@ Caveats: facts carries only its mapped labels, so role-label patterns are
 topology-only. The property-flag form (`is_exchange`) remains the canonical
 filter.
 
+## Kind labels (topology graph)
+
+A kind is a second label on an `Address`, set from a chain fact: `:Account` for
+a key holder and `:Contract` for a contract (`:Contract:SmartAccount` for a
+contract wallet). `is_contract` stays beside `:Contract`. An address that only
+received has no kind, and no address carries both kinds. A role label stays
+beside the kind. Facts serves no kind, and a kind is never a `USE chain` lookup
+label: `USE chain MATCH (a:Address {address: "0x…"}) RETURN a.is_contract, a.nonce`
+reads it at one block.
+
 ## Practical guidance
 
 - **Prefer inline property maps for equality lookups**:

package/docs/graph-tools.md

@@ -35,35 +35,61 @@ primitive-backend status instead.
 A graph query goes to one of three layers. Name the layer at the start of the
 query: `USE topology`, `USE facts` or `USE chain`.
 
-Route by what you know: topology searches, while facts and chain look up one known thing.
+Route by what the question names: an address, a pair with a day, a transaction or a block. Topology searches outward from an address, while facts and chain look up one known thing.
 
-1. I do not know the thing yet: `USE topology`.
-2. I know the pair and the day, or the transaction hash, and want the indexed rows: `USE facts`.
-3. I want the chain's own record of a transaction by its hash, a block by its number or hash, or the head: `USE chain`.
+1. I know an address and want its links, senders, receivers, hops or a route: `USE topology`, anchored on that address.
+2. I know both addresses of a pair and one day, and want the rows of that day: `USE facts`.
+3. I want the chain's own record of a transaction by its `tx_id`, a block by its `block_height` or `block_hash`, an address at one block (`Address`), or the head: `USE chain`.
 
-`USE chain` has no address lookup. Find the address on `USE topology`, then read the pair and one day on `USE facts`.
+`USE chain` with `Address` reads the balance, the nonce or the kind of one address, now or at a past block with `at_block`. A past block must be at least `chain_admission.at_block_min_depth` blocks below the tip. To find the counterparties of an address, search `USE topology`, then read the pair and one day on `USE facts`.
 
-When two fit, as with a hash: ask `USE chain` first for the record and the result, then `USE facts` for the transfers it caused.
+A transaction is a chain question: read it on `USE chain` by its `tx_id`. Chain gives its `block_date`; the transfers between a pair on that day are a `USE facts` read.
 
-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`.
+The layers hand each other keys, and each key keeps its name. Topology gives the pair and the first and last seen time. Facts gives the `tx_id` and the `block_height`. Chain takes an `address`, a `tx_id`, a `block_height` or a `block_hash`, and gives the `block_date` of a transaction or a block.
 
-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.
+A list, a range or a whole-chain question names no address, pair, transaction or block, so no layer serves it today. Say so in one line, ask the user for one of those, and send no workaround query.
 
-| The question                                                | Layer      | First query                                                  |
-| ----------------------------------------------------------- | ---------- | ------------------------------------------------------------ |
-| Who is connected to this address? Where did the money go?   | `topology` | One anchored hop on `FLOWS_TO`, with a `LIMIT`.              |
-| What moved between A and B on one day?                      | `facts`    | `TRANSFER` with both addresses and `block_date`.             |
-| Which days did A and B trade?                               | `topology` | The link's `first_seen_timestamp` and `last_seen_timestamp`. |
-| Did transaction `0x…` succeed? Which block, which day?      | `chain`    | `Transaction {hash}`.                                        |
-| Which day is block N?                                       | `chain`    | `Block {height}`, and return `block_date`.                   |
-| How far behind are the graph and the warehouse?             | `chain`    | `Head`.                                                      |
-| Every transaction of block N, or every address with label X | none       | A list or a scan. Say so. Do not retry.                      |
+| The question                                               | Layer      | First query                                                                 |
+| ---------------------------------------------------------- | ---------- | --------------------------------------------------------------------------- |
+| Recent activity or newest links of one address?            | `topology` | `FLOWS_TO` out of the address, `ORDER BY last_seen_timestamp`.              |
+| Who sent money to an address? Who received from it?        | `topology` | `FLOWS_TO` into or out of the address, with a `LIMIT`.                      |
+| Where did the money go, or come from, in N hops?           | `topology` | A guarded quantified walk, at most 4 hops, with a `LIMIT`.                  |
+| Is there a route between A and B?                          | `topology` | `SHORTEST 1` with both addresses.                                           |
+| How many, how much, first or last active, for one address? | `topology` | The address node: `degree_in`, `tx_total_count`, `last_activity_timestamp`. |
+| What moved between A and B on one day?                     | `facts`    | `TRANSFER` with both addresses and `block_date`.                            |
+| Which days did A and B trade?                              | `topology` | The link's `first_seen_timestamp` and `last_seen_timestamp`.                |
+| Did transaction `0x…` succeed? Which block, which day?     | `chain`    | `Transaction {tx_id}`.                                                      |
+| Which day is block N?                                      | `chain`    | `Block {block_height}`, and return `block_date`.                            |
+| Does this address hold a balance? Is it a contract?        | `chain`    | `Address {address}`, with `at_block` for a past block.                      |
+| How far behind are the graph and the warehouse?            | `chain`    | `Head`.                                                                     |
+| Recent addresses, biggest senders, a top list of the chain | none       | A list of the whole chain. Say so. Do not retry.                            |
 
 The server publishes the limits of a layer in `meta_network_capabilities`
 (`cia network robinhood --json` prints the same reply): the `chain_admission`
 block today, and `topology_admission` and `facts_admission` when the server
 sends them. Read a limit there. Do not write one down.
 
+## One name on every layer
+
+A thing has one name on topology, facts and chain. Copy a value from one layer
+into the next as it is. The layers differ by properties only.
+
+| Thing      | `USE topology`                                | `USE facts`                   | `USE chain`                                         |
+| ---------- | --------------------------------------------- | ----------------------------- | --------------------------------------------------- |
+| An address | `:Address {address}`, and a kind label        | `:Address {address}`, no kind | `Address {address}`, optional `at_block`            |
+| A kind     | `:Account` or `:Contract`, `is_contract` kept | none: refused with a hint     | `is_contract`, `nonce` and `delegated_to`, no label |
+| A tx       | `tx_id` on `DEPLOYED_CONTRACT` only           | `tx_id` on every row          | `Transaction {tx_id}`                               |
+| A block    | `block_height` on `DEPLOYED_CONTRACT` only    | `block_height` on every row   | `Block {block_height}` or `Block {block_hash}`      |
+| Time       | epoch milliseconds                            | epoch milliseconds            | epoch milliseconds                                  |
+| `network`  | the query's `network`                         | the query's `network`         | the query's `network`                               |
+
+`network` is a property of every node and every relationship, and its value is
+the query's `network`. It is never stored, except on a `:Chain` node, where it
+names the remote chain. A filter on another value gives no rows. A kind is a
+second label that topology takes from chain facts: `:Account` for a key holder,
+`:Contract` for a contract. An address that only received has none. Facts
+serves no kind.
+
 ## When a query is refused
 
 A refusal is an answer, not an outage: the endpoint is up.
@@ -93,19 +119,32 @@ lists every code with its layer, its class and the next move.
 ## Chain lookups
 
 `USE chain` asks the chain node for one known thing by its key. It serves the
-lookups that `chain_admission.lookups` lists: `Transaction` by `hash`, `Block`
-by `height` or `hash`, and `Head`, which takes no key. No lookup takes an
-address: `:Address` is a topology and a facts label, never a chain one. A lookup
-is one node with literal keys in braces and a `RETURN` of `var.property` items.
-It takes no `WHERE`, no relationship and no range. The properties of each lookup
-are named in the refusal of an unknown property.
+lookups that `chain_admission.lookups` lists: `Transaction` by `tx_id`, `Block`
+by `block_height` or `block_hash` (exactly one), `Address` by `address` (with an
+optional `at_block`), and `Head`, which takes no key. A lookup is one node with
+literal keys in braces and a `RETURN` of `var.property` items. It takes no
+`WHERE`, no relationship and no range. The names `hash` and `height` are no key
+and no property of any label: they are refused like any name a label lacks. The
+properties of each lookup are named in the refusal of an unknown property, and
+`meta_schema` lists the lookups the network serves.
 
 A transaction, with its result and the day it was mined:
 
 ```bash
 cia mcp call graph_query \
   network=robinhood \
-  'query=USE chain MATCH (t:Transaction {hash: "0x..."}) RETURN t.status, t.block_height, t.block_date'
+  'query=USE chain MATCH (t:Transaction {tx_id: "0x..."}) RETURN t.status, t.block_height, t.block_date'
+```
+
+An address at the newest block, and at a past block:
+
+```bash
+cia mcp call graph_query \
+  network=robinhood \
+  'query=USE chain MATCH (a:Address {address: "0x..."}) RETURN a.balance, a.nonce, a.is_contract'
+cia mcp call graph_query \
+  network=robinhood \
+  'query=USE chain MATCH (a:Address {address: "0x...", at_block: 79000000}) RETURN a.balance, a.nonce, a.is_contract'
 ```
 
 The head of the chain, and how far the graph and the warehouse are behind it:
@@ -113,11 +152,16 @@ The head of the chain, and how far the graph and the warehouse are behind it:
 ```bash
 cia mcp call graph_query \
   network=robinhood \
-  'query=USE chain MATCH (h:Head) RETURN h.height, h.age_seconds, h.warehouse_blocks_behind, h.graph_blocks_behind'
+  'query=USE chain MATCH (h:Head) RETURN h.block_height, h.age_seconds, h.warehouse_blocks_behind, h.graph_blocks_behind'
 ```
 
-A chain lookup that comes back `chain_unavailable` means the chain layer is off
-or behind: read `chain_admission.status`. Topology and facts still work.
+`block_timestamp` is an integer number of epoch milliseconds on every layer,
+chain included. `network` is served on every label, from the query's `network`.
+An `Address` lookup reads the kind from `is_contract`, `nonce` and
+`delegated_to`, and a past block must be at least
+`chain_admission.at_block_min_depth` blocks below the tip. A chain lookup that
+comes back `chain_unavailable` means the chain layer is off or behind: read
+`chain_admission.status`. Topology and facts still work.
 
 ## Swaps, liquidity pools and bridges
 
@@ -279,9 +323,9 @@ and `:Sanctioned`. Each role also has a flag on the node.
   labels, risk, lifetime metrics, and `FLOWS_TO`/`LINKED` relationships
   belong to `USE topology`.
 - Use `USE chain` for the chain node's own record of one known transaction,
-  block or the head. It looks up one key and never searches.
-- A facts read names an address pair with one day, or one `tx_id` (the `0x`
-  transaction hash on EVM networks). The pair is both endpoint addresses, from
+  block, address or the head. It looks up one key and never searches.
+- A facts read names an address pair with one day. A transaction is read on
+  `USE chain` by its `tx_id`, not on facts. The pair is both endpoint addresses, from
   then to, and the day is a `block_date` equality. `block_timestamp` bounds in
   epoch milliseconds may narrow the day to a time window. One address, a day
   alone, a window of days, a block range and a bare `LIMIT` are not enough. A
@@ -518,10 +562,10 @@ statements of the graph (`CALL db.labels()`, `CALL db.relationshipTypes()`,
 each main link, through one session, and keeps the answer for 24 hours. Fields
 come from a sample, so a rare field may be missing. The probes below are the
 fallback. The current public Chain Insights Graph network is
-the single robinhood network; the network argument selects the graph, and
-the address-space split lives on the `:Address.network` node property. Do not
-infer support for unadvertised networks from internal database names or
-historical examples.
+the single robinhood network; the network argument selects the graph.
+`network` is the query's network on every node and relationship, never stored,
+except on `:Chain`. Do not infer support for unadvertised networks from
+internal database names or historical examples.
 
 Useful schema probes:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chain-insights",
-  "version": "0.45.0",
+  "version": "0.46.2",
   "description": "AML investigation CLI and MCP proxy for blockchain risk screening and Chain Insights Graph access",
   "homepage": "https://chain-insights.ai",
   "repository": {

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

@@ -1,6 +1,6 @@
 ---
 name: chain-insights-cypher
-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.
+description: Load this before the first graph_query or graph_query_batch call: without it, most queries are refused. 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.
 ---
 
 # Chain Insights Cypher
@@ -8,7 +8,8 @@ description: Use when answering any question about addresses, money flows, trans
 Standard ISO GQL for `graph_query` and `graph_query_batch`. Read-only. No
 `CALL`, no procedures, no vendor syntax.
 
-Run a query with `cia mcp call graph_query network=robinhood "query=<query>"`.
+In an MCP host, such as Claude Desktop, call the `graph_query` tool with `network` and `query`; `graph_query_batch` takes `queries`. There is no shell. In a shell, run a query with
+`cia mcp call graph_query network=robinhood "query=<query>"`.
 Send related reads in one call with `cia mcp call graph_query_batch network=robinhood 'queries=[{"id":"a","query":"<query>"}]'`.
 Always pass `network` and your own `LIMIT`. These two commands, and
 `cia network robinhood --schema` for field names, are all you need. Do not run
@@ -19,12 +20,11 @@ Always pass `network` and your own `LIMIT`. These two commands, and
 1. Write every address in full, in lowercase: `0x` plus 40 hex characters, 42
    in all. Never shorten one with `...` or `…`, in a query or in an answer.
    Copy addresses from results exactly.
-2. Timestamps on topology and facts are integer milliseconds since the epoch,
-   UTC. Compute them from the current date: a day is 86,400,000 ms. Never
-   compare one with an ISO string. `block_date` is the string `"YYYY-MM-DD"`.
-   `USE chain` returns `block_timestamp` as an ISO string: read it, never
-   filter on it. Every `*_usd` field is US dollars. `*_raw` is the token's
-   smallest unit, not dollars.
+2. Timestamps on every layer are integer milliseconds since the epoch, UTC,
+   and `USE chain` is no exception. Compute them from the current date: a day
+   is 86,400,000 ms. Never compare one with an ISO string. `block_date` is the
+   string `"YYYY-MM-DD"`. Every `*_usd` field is US dollars. `*_raw` is the
+   token's smallest unit, not dollars.
 3. A shortened address, a mixed-case address, or an ISO string against a
    millisecond column gives zero rows with no error. Check these first. Zero
    rows is not proof of safety.
@@ -37,20 +37,56 @@ Always pass `network` and your own `LIMIT`. These two commands, and
 
 ## Pick the layer first
 
-Route by what you know: topology searches, while facts and chain look up one known thing.
+Route by what the question names: an address, a pair with a day, a transaction or a block. Topology searches outward from an address, while facts and chain look up one known thing.
 
-1. I do not know the thing yet: `USE topology`.
-2. I know the pair and the day, or the transaction hash, and want the indexed rows: `USE facts`.
-3. I want the chain's own record of a transaction by its hash, a block by its number or hash, or the head: `USE chain`.
+1. I know an address and want its links, senders, receivers, hops or a route: `USE topology`, anchored on that address.
+2. I know both addresses of a pair and one day, and want the rows of that day: `USE facts`.
+3. I want the chain's own record of a transaction by its `tx_id`, a block by its `block_height` or `block_hash`, an address at one block (`Address`), or the head: `USE chain`.
 
-`USE chain` has no address lookup. Find the address on `USE topology`, then read the pair and one day on `USE facts`.
-When two fit, as with a hash: ask `USE chain` first for the record and the result, then `USE facts` for the transfers it caused.
-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`.
-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.
+`USE chain` with `Address` reads the balance, the nonce or the kind of one address, now or at a past block with `at_block`. A past block must be at least `chain_admission.at_block_min_depth` blocks below the tip. To find the counterparties of an address, search `USE topology`, then read the pair and one day on `USE facts`.
+A transaction is a chain question: read it on `USE chain` by its `tx_id`. Chain gives its `block_date`; the transfers between a pair on that day are a `USE facts` read.
+The layers hand each other keys, and each key keeps its name. Topology gives the pair and the first and last seen time. Facts gives the `tx_id` and the `block_height`. Chain takes an `address`, a `tx_id`, a `block_height` or a `block_hash`, and gives the `block_date` of a transaction or a block.
+A list, a range or a whole-chain question names no address, pair, transaction or block, so no layer serves it today. Say so in one line, ask the user for one of those, and send no workaround query.
 
-A top list, a count, a scan of a label or the recent active addresses of the
-whole chain are such questions. Do not search for a workaround. Say: "The graph
-cannot list those. Name an address, a pair with a day, or a transaction hash."
+Find the question in this table. Send its first query, once, with the addresses the user gave.
+
+| The user asks                                                | Layer      | First query                                                            |
+| ------------------------------------------------------------ | ---------- | ---------------------------------------------------------------------- |
+| Recent activity or newest links of one address               | `topology` | Newest links of one address (see Graph searches)                       |
+| Who sent money to an address? Who received from it?          | `topology` | Newest links of one address, the arrow flipped for senders             |
+| Where did the money go, or come from, in N hops?             | `topology` | Where the money went, or came from (`{0,N-1}`, N up to 5)              |
+| Is there a route between two addresses?                      | `topology` | Route between two addresses, `SHORTEST 1`                              |
+| What do two addresses have in common?                        | `topology` | Counterparties that two addresses share                                |
+| Biggest senders or receivers of one address                  | `topology` | Newest links of one address, `ORDER BY f.amount_usd_sum DESC LIMIT 10` |
+| How many, how much, first or last active, for one address    | `topology` | Profile of one address                                                 |
+| The transfers of a pair on one day                           | `facts`    | `TRANSFER` of the pair and the day, see Facts                          |
+| What happened in this transaction hash?                      | `chain`    | `Transaction {tx_id}`, see Chain                                       |
+| The latest block, block N, how far behind the graph is       | `chain`    | `Head`, or `Block {block_height}`                                      |
+| What fields does an Address have?                            | none       | Call `meta_schema {network}`. Send no query.                           |
+| Recent addresses, biggest senders, any top list of the chain | none today | Send no query. Say the line below.                                     |
+
+For a question of the last row, do not probe, scan or try another layer: a probe returns arbitrary rows, never the newest or the biggest. Say: "The graph cannot list the whole chain yet. Give me an address, a pair with a day, or a transaction hash, and I will show its recent links and flows."
+
+## One name on every layer
+
+A thing has one name on topology, facts and chain. Copy a value from one layer into the next as it is. The layers differ by properties only.
+
+| Thing      | `USE topology`                                | `USE facts`                   | `USE chain`                                    |
+| ---------- | --------------------------------------------- | ----------------------------- | ---------------------------------------------- |
+| An address | `:Address {address}`, and a kind label        | `:Address {address}`, no kind | `Address {address}`, optional `at_block`       |
+| A kind     | `:Account` or `:Contract`, `is_contract` kept | none: refused with a hint     | `is_contract`, `nonce` and `delegated_to`      |
+| A tx       | `tx_id` on `DEPLOYED_CONTRACT` only           | `tx_id` on every row          | `Transaction {tx_id}`, see Chain               |
+| A block    | `block_height` on `DEPLOYED_CONTRACT` only    | `block_height` on every row   | `Block {block_height}` or `Block {block_hash}` |
+| Time       | epoch milliseconds                            | epoch milliseconds            | epoch milliseconds                             |
+| `network`  | the query's `network`                         | the query's `network`         | the query's `network`                          |
+
+`block_timestamp` is an integer number of epoch milliseconds on every layer, chain included. `block_date` is a UTC day, `YYYY-MM-DD`. The old chain names `hash` and `height` are gone: they are refused like any name a label lacks.
+
+`network` is a property of every node and every relationship, and its value is the query's `network`. It is never stored, except on a `:Chain` node, where it names the remote chain. A filter `x.network = "robinhood"` keeps every row, and a filter on another value gives no rows. It never narrows a scan: anchor on an address instead.
+
+A kind is a second label that topology takes from a chain fact: `:Account` for a key holder, `:Contract` for a contract (`:Contract:SmartAccount` for a contract wallet). Never both on one address. An address that only received has none, and so does a Nitro precompile on topology (chain reads it as a contract). A role label such as `:Pool` stays beside the kind. `is_contract` stays beside `:Contract`. Facts serves no kind: a facts read that names `:Account` or `:Contract` is refused, so ask `USE topology`, or `USE chain` for `is_contract` and `nonce`.
+
+A topology link is a lifetime summary of a pair, and a facts row is one event. They are two things, so they keep two names: `SWAPPED`, `ADDED_LIQUIDITY` and `REMOVED_LIQUIDITY` on topology, `SWAP`, `LIQUIDITY_ADD` and `LIQUIDITY_REMOVE` on facts. Read the summary on topology, anchored on an address, then the events behind it on facts, by the pair and one day.
 
 ## Topology
 
@@ -58,16 +94,39 @@ cannot list those. Name an address, a pair with a day, or a transaction hash."
 bridges and the `LINKED` overlay. The server checks these before it runs:
 
 - 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.
-- 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.
+- 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: never call them recent, top or biggest.
 - A sort, an aggregate, `DISTINCT`, `collect()` or a filter on a link property needs an anchor on every pattern.
 - 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`).
 - Paths use bounded quantifiers such as `-[:FLOWS_TO]-{1,5}`. A `*` range, the legacy path functions, `PROFILE`, writes and `CALL` are refused.
 - Role flags `is_exchange`, `is_scam`, `is_victim` and `is_sanctioned` are absent unless true: use `IS NULL` or `IS NOT NULL`, never `= false`.
+- A kind label sits beside `:Address`: `WHERE a:Contract` or `WHERE a:Account` tests it, as `:Pool` is tested. It is no anchor.
 
 ## Graph searches
 
 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`.
 
+Newest links of one address, its receivers. Its newest senders are the same read with the arrow flipped:
+
+```cypher
+USE topology
+MATCH (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"})-[f:FLOWS_TO]->(b:Address) WHERE NOT a:Pool
+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
+```
+
+```cypher
+USE topology
+MATCH (b:Address)-[f:FLOWS_TO]->(a:Address {address: "0x7e3702e9dfaa847f9829a258f1e26fa431160662"}) WHERE NOT a:Pool
+RETURN b.address AS from_address, a.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
+```
+
+Profile of one address: counterparties, transactions, volume and the active window, all from the node. Timestamps are milliseconds.
+
+```cypher
+USE topology
+MATCH (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"})
+RETURN a.degree_in AS senders, a.degree_out AS receivers, a.tx_total_count AS tx_count, a.total_volume_usd AS volume_usd, a.first_activity_timestamp AS first_active, a.last_activity_timestamp AS last_active LIMIT 1
+```
+
 Route between two addresses, one path. Only `MATCH SHORTEST 1` and `MATCH ANY SHORTEST` are served: a count above 1 is `route_search_refused`.
 
 ```cypher
@@ -180,17 +239,19 @@ USE topology
 MATCH ()-[r:FLOWS_TO]->() RETURN keys(r) AS keys LIMIT 5
 ```
 
-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.
+Name another link type to read its keys: `SWAPPED`, `LINKED`, `OPERATED_BY`, `BRIDGED`, `ADDED_LIQUIDITY` or `REMOVED_LIQUIDITY`. The keys of an address and of a link include `network`: it is the query's `network`, computed on every node and link. `synced_through_height` and `pair_key` are bookkeeping: never filter or sort on them.
 
 The server serves five read-only catalog calls: `CALL db.labels()`, `CALL db.relationshipTypes()`, `CALL db.propertyKeys()`, `CALL db.schema.visualization()` and `SHOW INDEXES`. `meta_schema` sends four of them for you through one session and keeps the answer, so do not send them yourself.
 
 ## Facts: an address pair with one day
 
-`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.
+`USE facts` looks up rows you already know. A facts read names an address pair with one day. A transaction is read on `USE chain`, not here. 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.
 
 - A reply holds at most 200 rows, whatever the `LIMIT`.
 - A facts read has one relationship and no hop. For a walk, go to topology.
 - A facts read takes no `ORDER BY`. Rows come in the server's own order. Sort the page yourself.
+- Every row and both endpoints carry `network`, the query's `network`. A filter on it is no anchor: it never replaces the pair and the day.
+- Facts serves no kind. A read that names `:Account` or `:Contract` is refused with `facts_no_anchor`: ask `USE topology` for the kind, or `USE chain` for `is_contract` and `nonce`.
 - A facts read covers one day. For more days, send one read for each day.
 - Amounts and USD values come back as text, such as `"5.23661492"`. Convert them before you add them.
 - `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.
@@ -201,33 +262,41 @@ MATCH (a:Address {address: "0x31a817802ee183eb8b13167ffe24bd28dcc6f30c"})-[t:TRA
 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
 ```
 
-One transaction hash needs no day. The server finds it:
+## Chain: one key, one node
+
+`USE chain` asks the chain node for one known thing: `Transaction` by `tx_id`, `Block` by `block_height` or `block_hash` (exactly one), `Address` by `address` (with an optional `at_block`), 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`).
 
 ```cypher
-USE facts
-MATCH (a:Address)-[t:TRANSFER]->(b:Address) WHERE t.tx_id = "0x044587122970de1e3c377a8ed7ab56a49c777a2b7441a2f5d9ca32dbab9fbe71"
-RETURN a.address AS from_address, b.address AS to_address, t.amount AS amount, t.kind AS kind LIMIT 50
+USE chain
+MATCH (t:Transaction {tx_id: "0x044587122970de1e3c377a8ed7ab56a49c777a2b7441a2f5d9ca32dbab9fbe71"}) RETURN t.status, t.block_height, t.block_date
 ```
 
-## Chain: one key, one node
+```cypher
+USE chain
+MATCH (b:Block {block_height: 79841521}) RETURN b.block_hash, b.block_date
+```
 
-`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`).
+An address at the newest block, and at a past block:
 
 ```cypher
 USE chain
-MATCH (t:Transaction {hash: "0x044587122970de1e3c377a8ed7ab56a49c777a2b7441a2f5d9ca32dbab9fbe71"}) RETURN t.status, t.block_height, t.block_date
+MATCH (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"}) RETURN a.balance, a.nonce, a.is_contract
 ```
 
 ```cypher
 USE chain
-MATCH (b:Block {height: 79841521}) RETURN b.hash, b.block_date
+MATCH (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550", at_block: 79000000}) RETURN a.balance, a.nonce, a.is_contract
 ```
 
 ```cypher
 USE chain
-MATCH (h:Head) RETURN h.height, h.age_seconds, h.warehouse_blocks_behind, h.graph_blocks_behind
+MATCH (h:Head) RETURN h.block_height, h.age_seconds, h.warehouse_blocks_behind, h.graph_blocks_behind
 ```
 
+An `Address` lookup always answers one row, because every address has a state. `a.balance` is decimal text. Read the kind from `a.is_contract`, `a.nonce` and `a.delegated_to`: `a.is_contract` is `true` for a contract and null for any other address, a `nonce` above 0 with `a.is_contract` null is an account, and `a.delegated_to` names the target of an EIP-7702 delegation, which is an account. `a.code_size` is the size of the code, and the code itself is never returned. `:Account` and `:Contract` are never a chain lookup label.
+
+`at_block` must be at least `chain_admission.at_block_min_depth` blocks below the tip. A nearer block is refused with `chain_block_out_of_range` and the rule `at_block_near_tip`: leave `at_block` out to read the newest block. The names `hash` and `height` are no key and no property of any label.
+
 ## When a query is refused
 
 A refusal is an answer, not an outage. Act on its class.
@@ -257,12 +326,4 @@ Claude Desktop draws a `graph_query` answer from its column names. Alias the
 
 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.
 
-A graph, the newest receivers of one address. Flip the arrow for its senders:
-
-```cypher
-USE topology
-MATCH (a:Address {address: "0x04911a118f11c75667e4d0dfb8e640af5a353550"})-[f:FLOWS_TO]->(b:Address) WHERE NOT a:Pool
-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
-```
-
-A chart is the facts read of one pair over one day above, with `block_timestamp` and `amount_usd` in the `RETURN`.
+A graph is the newest-links read of one address, receivers or senders, in Graph searches. A chart is the facts read of one pair over one day above, with `block_timestamp` and `amount_usd` in the `RETURN`.