chain-insights 0.68.2 → 0.69.0

package/dist/{tool-visibility-B4RAFMaB.cjs → tool-visibility-BopFnGsT.cjs}

@@ -47,6 +47,11 @@ const PUBLIC_MCP_TOOL_ALLOWED_ARGS = {
 		"queries",
 		"per_query_timeout_seconds",
 		"time_scope"
+	],
+	meta_dex_lookup: [
+		"network",
+		"name",
+		"pools"
 	]
 };
 function isHiddenRemoteToolName(name) {

package/dist/{tool-visibility-kclgGKL5.mjs → tool-visibility-Dq-Ruj-8.mjs}

@@ -47,6 +47,11 @@ const PUBLIC_MCP_TOOL_ALLOWED_ARGS = {
 		"queries",
 		"per_query_timeout_seconds",
 		"time_scope"
+	],
+	meta_dex_lookup: [
+		"network",
+		"name",
+		"pools"
 	]
 };
 function isHiddenRemoteToolName(name) {
@@ -86,4 +91,4 @@ function validatePublicMcpToolArguments(name, args) {
 //#endregion
 export { tool_visibility_exports as a, isAppOnlyTool as i, PUBLIC_MCP_TOOL_ALLOWED_ARGS as n, PUBLIC_MCP_TOOL_REQUIRED_ARGS as r, HIDDEN_REMOTE_TOOL_NAMES as t };
 
-//# sourceMappingURL=tool-visibility-kclgGKL5.mjs.map
+//# sourceMappingURL=tool-visibility-Dq-Ruj-8.mjs.map

package/dist/tool-visibility-Dq-Ruj-8.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-visibility-Dq-Ruj-8.mjs","names":[],"sources":["../src/mcp/tool-visibility.ts"],"sourcesContent":["import { McpToolError, formatMcpToolError } from './print-result.js'\n\nexport const HIDDEN_REMOTE_TOOL_NAMES = new Set([\n  'topup',\n  'address_risk',\n  // Hidden until its verdict is fixed: never listed, never registered, never\n  // called through the proxy. The remote graph endpoint does not serve it.\n  'aml_address_risk',\n  'trace_victim_funds',\n  'trace_suspect_funds',\n  'trace_deposit_sources',\n  'trace_funds',\n  'track_funds',\n  // Retired tools: never exposed publicly. Built by concatenation so the\n  // retired names do not appear as literals in this file.\n  ['aml_trace_victim', '_funds'].join(''),\n  ['aml_trace_suspect', '_funds'].join(''),\n  ['aml_trace_deposit', '_sources'].join(''),\n  'network_capabilities',\n  'usage_status',\n  'subscription_status',\n  'balance',\n  'help',\n  ['money', '_flows_between_exchanges'].join(''),\n  'address_connection_risk',\n])\n\nexport const PUBLIC_MCP_TOOL_REQUIRED_ARGS: Record<string, string[]> = {\n  graph_query: ['query', 'network'],\n  graph_query_batch: ['network', 'queries'],\n}\n\n// normalizeRemoteToolArguments FILTERS pass-through arguments to this list, so\n// an argument that is missing here is silently STRIPPED and the caller gets a\n// default-bounded result with no error and no warning. `time_scope` shipped\n// broken for exactly this reason. Every tunable search bound below\n// (per_address_limit, row_limit) must therefore be listed the moment it\n// appears on a tool schema, and is covered end-to-end through the proxy in\n// tests/mcp-proxy.test.ts.\nexport const PUBLIC_MCP_TOOL_ALLOWED_ARGS: Record<string, string[]> = {\n  // `time_scope` narrows a `USE topology` query to a temporal-shard subset\n  graph_query: ['query', 'network', 'time_scope'],\n  graph_query_batch: ['network', 'queries', 'per_query_timeout_seconds', 'time_scope'],\n  // A local tool of the proxy (src/mcp/dex-tool.ts): the exchange by name.\n  meta_dex_lookup: ['network', 'name', 'pools'],\n}\n\nexport function isHiddenRemoteToolName(name: string): boolean {\n  return HIDDEN_REMOTE_TOOL_NAMES.has(name)\n}\n\n/**\n * True for an MCP Apps tool only a view may call: `_meta.ui.visibility` is set\n * and does not include \"model\" (for example graph_expand, visibility [\"app\"]).\n * Such a tool never appears in a tool list built for the model or the CLI.\n */\nexport function isAppOnlyTool(tool: { _meta?: Record<string, unknown> }): boolean {\n  const ui = tool._meta?.ui\n  if (!ui || typeof ui !== 'object' || Array.isArray(ui)) return false\n  const visibility = (ui as Record<string, unknown>).visibility\n  return Array.isArray(visibility) && !visibility.includes('model')\n}\n\nexport function visibleRemoteTools<T extends { name: string; _meta?: Record<string, unknown> }>(\n  tools: T[]\n): T[] {\n  return tools.filter((tool) => !isHiddenRemoteToolName(tool.name) && !isAppOnlyTool(tool))\n}\n\nexport function assertPublicMcpToolName(name: string): void {\n  if (!isHiddenRemoteToolName(name)) return\n  const replacement =\n    name === 'network_capabilities'\n      ? ' Use meta_network_capabilities instead.'\n      : name === 'usage_status'\n        ? ' Use meta_usage_status instead.'\n        : name === 'subscription_status'\n          ? ' Use meta_subscription_status instead.'\n          : name === 'balance'\n            ? ' Use wallet_balance instead.'\n            : name === 'help'\n              ? ' Use meta_help instead.'\n              : ''\n  throw new Error(`MCP tool '${name}' is not exposed by Chain Insights.${replacement}`)\n}\n\nexport function formatMcpCallError(tool: string, err: unknown): string {\n  // A tool error with an envelope is the server's own answer: its text, then the\n  // line of its error_detail. It is never matched against the unknown-tool\n  // pattern below. A tool error with no envelope keeps the old reading, because\n  // a server can answer an unknown tool as an error reply.\n  if (err instanceof McpToolError && err.errorDetail) return formatMcpToolError(err)\n  const message = err instanceof Error ? err.message : String(err)\n  if (/\\bunknown tool\\b|\\btool\\b.*\\bnot found\\b/i.test(message)) {\n    return `Unknown MCP tool \"${tool}\". Run \\`cia mcp tools --refresh\\` to list available tools.`\n  }\n  return message\n}\n\nexport function validatePublicMcpToolArguments(name: string, args: Record<string, unknown>): void {\n  const allowedArgs = PUBLIC_MCP_TOOL_ALLOWED_ARGS[name]\n  if (!allowedArgs) return\n\n  const unsupportedArgs = Object.keys(args).filter((argName) => !allowedArgs.includes(argName))\n  if (unsupportedArgs.length === 0) return\n\n  throw new Error(\n    [\n      `Unsupported argument${unsupportedArgs.length === 1 ? '' : 's'} for ${name}: ${unsupportedArgs.join(', ')}.`,\n      `Allowed arguments: ${allowedArgs.join(', ')}.`,\n    ].join(' ')\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;AAEA,MAAa,2CAA2B,IAAI,IAAI;CAC9C;CACA;CAGA;CACA;CACA;CACA;CACA;CACA;CAGA,CAAC,oBAAoB,QAAQ,CAAC,CAAC,KAAK,EAAE;CACtC,CAAC,qBAAqB,QAAQ,CAAC,CAAC,KAAK,EAAE;CACvC,CAAC,qBAAqB,UAAU,CAAC,CAAC,KAAK,EAAE;CACzC;CACA;CACA;CACA;CACA;CACA,CAAC,SAAS,0BAA0B,CAAC,CAAC,KAAK,EAAE;CAC7C;AACF,CAAC;AAED,MAAa,gCAA0D;CACrE,aAAa,CAAC,SAAS,SAAS;CAChC,mBAAmB,CAAC,WAAW,SAAS;AAC1C;AASA,MAAa,+BAAyD;CAEpE,aAAa;EAAC;EAAS;EAAW;CAAY;CAC9C,mBAAmB;EAAC;EAAW;EAAW;EAA6B;CAAY;CAEnF,iBAAiB;EAAC;EAAW;EAAQ;CAAO;AAC9C;AAEA,SAAgB,uBAAuB,MAAuB;CAC5D,OAAO,yBAAyB,IAAI,IAAI;AAC1C;;;;;;AAOA,SAAgB,cAAc,MAAoD;CAChF,MAAM,KAAK,KAAK,OAAO;CACvB,IAAI,CAAC,MAAM,OAAO,OAAO,YAAY,MAAM,QAAQ,EAAE,GAAG,OAAO;CAC/D,MAAM,aAAc,GAA+B;CACnD,OAAO,MAAM,QAAQ,UAAU,KAAK,CAAC,WAAW,SAAS,OAAO;AAClE;AAEA,SAAgB,mBACd,OACK;CACL,OAAO,MAAM,QAAQ,SAAS,CAAC,uBAAuB,KAAK,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC;AAC1F;AAEA,SAAgB,wBAAwB,MAAoB;CAC1D,IAAI,CAAC,uBAAuB,IAAI,GAAG;CAanC,MAAM,IAAI,MAAM,aAAa,KAAK,qCAXhC,SAAS,yBACL,4CACA,SAAS,iBACP,oCACA,SAAS,wBACP,2CACA,SAAS,YACP,iCACA,SAAS,SACP,4BACA,IACsE;AACtF;AAEA,SAAgB,mBAAmB,MAAc,KAAsB;CAKrE,IAAI,eAAe,gBAAgB,IAAI,aAAa,OAAO,mBAAmB,GAAG;CACjF,MAAM,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;CAC/D,IAAI,4CAA4C,KAAK,OAAO,GAC1D,OAAO,qBAAqB,KAAK;CAEnC,OAAO;AACT;AAEA,SAAgB,+BAA+B,MAAc,MAAqC;CAChG,MAAM,cAAc,6BAA6B;CACjD,IAAI,CAAC,aAAa;CAElB,MAAM,kBAAkB,OAAO,KAAK,IAAI,CAAC,CAAC,QAAQ,YAAY,CAAC,YAAY,SAAS,OAAO,CAAC;CAC5F,IAAI,gBAAgB,WAAW,GAAG;CAElC,MAAM,IAAI,MACR,CACE,uBAAuB,gBAAgB,WAAW,IAAI,KAAK,IAAI,OAAO,KAAK,IAAI,gBAAgB,KAAK,IAAI,EAAE,IAC1G,sBAAsB,YAAY,KAAK,IAAI,EAAE,EAC/C,CAAC,CAAC,KAAK,GAAG,CACZ;AACF"}

package/docs/mcp-proxy.md

@@ -81,6 +81,7 @@ The proxy:
 | --------------------------- | ------------------------------------------------------------------------------------ |
 | `meta_network_capabilities` | Show the current Chain Insights network/tool support matrix                          |
 | `meta_schema`               | Show the live graph schema of a network: labels, link types, fields, indexes         |
+| `meta_dex_lookup`           | Turn an exchange name into its factories, routers or manager, pools and first reads  |
 | `meta_rules`                | Read the answer rules when the `chain-insights-cypher` skill is not loaded           |
 | `meta_help`                 | Show Chain Insights tool and workflow guidance                                       |
 | `meta_usage_status`         | Check the caller's daily free-tier graph query allowance                             |
@@ -101,6 +102,76 @@ note, and such a schema is kept for 10 minutes, not 24 hours. In the terminal,
 structured form and `--refresh` to rebuild it.
 `cia mcp call meta_schema network=robinhood` does the same.
 
+`meta_dex_lookup` turns the name of a decentralized exchange, a launchpad or a
+vault into its addresses. It takes `network` (required), `name` (optional:
+with no name it lists every covered exchange) and `pools` (default `true`).
+
+1. The name is matched against the exchange registry,
+   [`registry/robinhood.json`](../registry/robinhood.json): exact on the key,
+   the display name and the aliases, then within two letters of an alias of
+   four or more characters. One winner is `matched`; a misspelling is named in
+   `took_for`. A tie is listed in `candidates`, never guessed. No hit returns
+   `covered`, every covered exchange, and sends no graph read.
+2. For a match, one `graph_query_batch` reads `Head` for the three family
+   lags, each factory, manager and router by its address (`confirmed` is true
+   when the graph shows a contract), and the ten biggest pools each factory
+   deployed. It is billed as any read; the match itself costs nothing.
+   `pools: false` drops the pool reads.
+3. The answer carries `recipe`, the first reads of the exchange's trail type
+   with its addresses filled in, and the answer `hint` every graph reply
+   carries.
+
+The registry is read from the public file on `main`,
+`https://raw.githubusercontent.com/chainswarm/chain-insights/main/registry/<network>.json`,
+within 3 seconds, and cached for one hour in
+`~/.chain-insights/cache/dex-registry-<network>.json` (mode 0600). When the
+fetch fails, the stale cache answers; with no cache, the copy packaged with
+the installed version does. A malformed public file never replaces a good
+cache. `registry_source` in the answer says which copy answered: `fetched`,
+`cached` or `packaged`. `CHAIN_INSIGHTS_DEX_REGISTRY_URL` points the fetch
+somewhere else, for tests and the lab; `{network}` in it is filled in.
+
+## Host parity
+
+**A rule a host never loads does not exist for that host.** Each host loads a
+different part of what this package ships:
+
+| What a host loads | Claude Code | Desktop Code mode | Codex | Hermes | scout agent | Desktop chat / claude.ai |
+|---|---|---|---|---|---|---|
+| skill files (`cia setup`) | yes | yes | yes | yes | copied, 2 of 6 | no |
+| server instructions | yes | yes | yes | yes | yes | no (ignored) |
+| `meta_rules` | yes | yes | yes | yes | yes | no (never called) |
+| tool descriptions | yes | yes | yes | yes | yes | yes |
+| result `hint` | yes | yes | yes | yes | yes | yes |
+| protocol tool doors | yes | yes | yes | yes | yes | yes |
+
+The scout agent pins the CLI by version in its image and copies only
+`chain-insights-cypher` and `chain-insights-virtuals` into its project, yet asks
+an exchange question by name every run. Until 0.69.0 that question ran with no
+exchange skill: the same gap as Desktop chat. From 0.69.0 the door answers it.
+
+```mermaid
+flowchart LR
+    Q["a question that names an exchange"] --> D["meta_dex_lookup<br/>the tool door, read by every host"]
+    Q --> S["skills/chain-insights-dex*<br/>read by hosts that load skills"]
+    S -->|"step 1"| D
+    D --> R["addresses, pools, first reads, hint"]
+```
+
+The rule:
+
+1. A protocol skill ships with a tool door: frontmatter `door: <tool>`.
+2. The door's description carries the rule the skill opens with, and names
+   the skill's trigger words.
+3. The skill names the door as its first step.
+
+A host that loads skills gets both. A host that loads none gets the door.
+`tests/host-parity.test.ts` checks it: every
+`skills/chain-insights-<protocol>/SKILL.md` has a door, the door is in
+`LOCAL_TOOL_NAMES` of `src/mcp/proxy.ts`, and its description names the
+skill's trigger words. The core skill `chain-insights-cypher` is exempt: its
+door is `meta_rules` plus the `graph_query` description.
+
 ## Views in Claude
 
 Claude Desktop and Cowork sessions on your computer draw MCP Apps views next

package/docs/stability.md

@@ -18,12 +18,13 @@ Exit codes are contract. Scripts and agent harnesses may rely on them.
 
 ### MCP tool names
 
-The public MCP surface is these ten tools:
+The public MCP surface is these eleven tools:
 
 - `graph_query`
 - `graph_query_batch`
 - `meta_network_capabilities`
 - `meta_schema`
+- `meta_dex_lookup`
 - `meta_rules`
 - `meta_help`
 - `meta_usage_status`
@@ -31,7 +32,7 @@ The public MCP surface is these ten tools:
 - `wallet_balance`
 - `wallet_topup`
 
-`graph_expand` is the eleventh tool the proxy registers. The view calls it
+`graph_expand` is the twelfth tool the proxy registers. The view calls it
 when you click in a picture; hosts keep it out of the model's tool list. It
 is not part of the public surface.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chain-insights",
-  "version": "0.68.2",
+  "version": "0.69.0",
   "description": "AML investigation CLI and MCP proxy for blockchain risk screening and Chain Insights Graph access",
   "homepage": "https://chain-insights.ai",
   "repository": {
@@ -50,6 +50,7 @@
     "dist",
     "skills",
     "!skills/rbmk-*",
+    "registry",
     "docs/*.md"
   ],
   "scripts": {
@@ -92,7 +93,7 @@
     "vitest": "^5.0.3"
   },
   "chainInsights": {
-    "dexRegistryVersion": 1
+    "dexRegistryVersion": 2
   },
   "overrides": {
     "ws": "8.21.0",

package/registry/README.md

@@ -0,0 +1,133 @@
+# The exchange registry
+
+**One reviewed table per network names every decentralized exchange and its
+factory, manager and router contracts.** A user names an exchange (Aero,
+Uniswap), not a factory address. This folder is the one home of name to
+addresses. The proxy tool `meta_dex_lookup` serves it to every host.
+
+```mermaid
+flowchart LR
+    MD["registry/robinhood.md<br/>one row per exchange and role"]
+    PIN["scripts/pin-dex-registry.mjs<br/>md to json, --check in CI"]
+    JSON["registry/robinhood.json<br/>the served copy"]
+    RAW["raw.githubusercontent.com<br/>main branch"]
+    PROXY["meta_dex_lookup<br/>cached 1 hour, packaged copy offline"]
+    MEMO["scripts/render-dex-registry.mjs<br/>the memo tables of the exchange skills"]
+    MD --> PIN --> JSON
+    JSON --> RAW --> PROXY
+    JSON --> MEMO
+```
+
+## The files
+
+| File | Rows served | Why |
+|---|---|---|
+| [robinhood.md](robinhood.md) | 44 | registry version 2, recorded 2026-10-24; the one `dyor` row is not served |
+| [robinhood.json](robinhood.json) | 29 exchanges | the served copy of `robinhood.md`, never edited by hand |
+
+A change to the rows merged on `main` reaches every running proxy within one
+hour. No release is needed for a data change.
+
+## The review rule
+
+1. **No source link, no row.** Every row carries the one link that confirms
+   it. Pin the link to a commit where the source has one.
+2. **No chain check, no serve.** A row is served only when the chain's own
+   data shows the address does what its role says:
+   - `factory`: a contract that created pools;
+   - `manager`: a contract that holds pools;
+   - `router`: a contract that forwards swaps.
+   Write the check into the file's `## Verification` section.
+3. **An unchecked row stays in the table.** Its verification cell says
+   `not served:` and the reason. It is served later, when a check passes.
+4. **The chain wins over the source.** When the chain shows a different
+   factory or block than the source, the row follows the chain and the file
+   says so.
+5. **An exchange needs a pool row.** An exchange with no served row of role
+   `factory` or `manager` is refused whole, router rows included.
+6. **One key per exchange.** A second spelling is an alias, never a second
+   key. Two exchanges may share an alias only when a user's word fits both
+   (`Balancer`): the lookup then lists both and guesses neither.
+
+## The columns
+
+The `## Rows` table has twelve columns, in this order.
+
+| Column | Means |
+|---|---|
+| dex | the key as a user says it, in lowercase: `aero`, `uniswap-v4`. Letters, digits, `.`, `_` and `-`, at most 32 |
+| display | the exchange name as a reader sees it, at most 96 characters. Every row of an exchange carries the same display |
+| aliases | the names a user types, comma separated, on one row of the exchange or spread over several |
+| trail type | how money is traced through the exchange: `plain`, `vault`, `gauge` or `launchpad`. Every row of an exchange carries the same trail type |
+| adapter | the adapter id of the DEX indexer that reads the row's pools: `cl-gauge-v1`, `uniswap-v4` |
+| role | `factory` creates pools, `manager` holds pools, `router` forwards swaps |
+| address | lowercase `0x` hex in backticks |
+| valid from block | the first block the row holds from, `0` when it is not known yet |
+| example pool | optional: one pool of the exchange, read live by the release suite. Empty or `-` when not given |
+| pool floor | optional: the least number of pools the exchange must show on a lane. Empty or `-` when not given |
+| source link | the one link that confirms the row, as `[text](https://…)` |
+| verification | `served`, or `not served:` and the reason |
+
+Each network file states `Registry version: N`. Bump it in every change to
+the rows. Each file also states `Recorded on: YYYY-MM-DD`, the day of the
+last row change. The pin script copies both into the served copy.
+
+A row is refused for one of these reasons:
+
+| Reason | When |
+|---|---|
+| `malformed row` | the row has the wrong number of cells, or no display |
+| `duplicate row` | the same key, role and address twice |
+| `bad dex key` | the key is not lowercase letters, digits, `.`, `_` or `-` |
+| `bad address` | the address is not lowercase `0x` and 40 hex digits |
+| `unknown role` | the role is not `factory`, `manager` or `router` |
+| `unknown trail type` | the trail type is not `plain`, `vault`, `gauge` or `launchpad` |
+| `bad adapter` | the adapter is empty or not an id |
+| `no source link` | the source link is not `[text](https://…)` |
+| `bad block`, `bad example pool`, `bad pool floor` | the cell is not a number or a pool |
+| `too long` | a value does not fit its column |
+| `dex rows disagree` | two rows of one exchange give a different display, trail type, example pool or pool floor |
+| `no factory or manager row for the dex` | the exchange has router rows only |
+
+## The check
+
+Regenerate the served copy after a row change:
+
+```bash
+node scripts/pin-dex-registry.mjs registry/robinhood.md
+```
+
+Check that the committed copy is what the file gives. CI runs this on every
+pull request:
+
+```bash
+node scripts/pin-dex-registry.mjs --check registry/robinhood.md
+```
+
+It prints `rows: N served, M refused, K not served` and
+`registry/robinhood.json up to date, registry version V`. It exits 1 when a
+row is refused or the committed copy differs, and names both versions.
+
+The skill memo follows the served copy:
+
+```bash
+node scripts/render-dex-registry.mjs          # rewrite the memo tables
+node scripts/render-dex-registry.mjs --check   # exit 1 when a memo table differs
+```
+
+## The served copy
+
+`registry/<network>.json` has the schema `chain-insights.dex-registry.v1`:
+
+- one entry per exchange, in the order the file first names it;
+- `factories` lists its `factory` and `manager` addresses, `routers` its
+  `router` addresses; an exchange with no router row lists its manager there,
+  because a vault forwards its own swaps;
+- `adapters`, `since_block` and `source` come from the factory and manager
+  rows: every adapter in order, the lowest block, the first source;
+- `example_pool` and `pool_floor` are `null` when the exchange gives none.
+
+The release suite `tests/dex-registry-live.integration.test.ts` reads every
+row against a live graph per release candidate: every factory, manager and
+router is a contract, every factory with a pool floor shows at least that many
+pools, and every example pool is a `:Pool` deployed by its factory.