chain-insights 0.43.0 → 0.44.0

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,6 +1,6 @@
1
1
  import { a as PACKAGE_VERSION } from "./print-result-k9kXVR2c.mjs";
2
2
  import { t as PaymentRequiredError } from "./client-gsLi528K.mjs";
3
- import { i as isAppOnlyTool, n as PUBLIC_MCP_TOOL_ALLOWED_ARGS, r as PUBLIC_MCP_TOOL_REQUIRED_ARGS, t as HIDDEN_REMOTE_TOOL_NAMES } from "./tool-visibility-Dn91j_gP.mjs";
3
+ import { i as isAppOnlyTool, n as PUBLIC_MCP_TOOL_ALLOWED_ARGS, r as PUBLIC_MCP_TOOL_REQUIRED_ARGS, t as HIDDEN_REMOTE_TOOL_NAMES } from "./tool-visibility-P9wETx-d.mjs";
4
4
  import { t as primitiveBackendUsageStatus } from "./usage-status-CXOnrq-s.mjs";
5
5
  import { n as unavailableSubscriptionStatus } from "./subscription-status-CJ-DaMW9.mjs";
6
6
  import { n as mirrorGraphNetworkCapabilities } from "./capabilities-DfWL6n_g.mjs";
@@ -577,14 +577,13 @@ function resolveMcpProxyMode(env = process.env) {
577
577
  if (raw === "no-workspace" || raw === "workspace-less") return "stateless";
578
578
  throw new Error(`CHAIN_INSIGHTS_MCP_PROXY_MODE must be workspace or stateless; got "${raw}"`);
579
579
  }
580
- const GRAPH_LAYERS_TEXT = "Use USE topology for topology (address/FLOWS_TO/OPERATED_BY/LINKED graph with SWAPPED, ADDED_LIQUIDITY, REMOVED_LIQUIDITY, BRIDGED and the Pool label, unified recent+historical, plus the node risk_score/risk_level verdict) and USE facts for bounded TRANSFER, SWAP, LIQUIDITY_ADD, LIQUIDITY_REMOVE and BRIDGE_CROSSING rows and enrichment, and USE chain for the chain node's own record of one known transaction, block or the head.";
580
+ const GRAPH_LAYERS_TEXT = "Use USE topology for topology (address/FLOWS_TO/OPERATED_BY/LINKED graph with SWAPPED, ADDED_LIQUIDITY, REMOVED_LIQUIDITY, BRIDGED and the Pool label, unified recent+historical) and USE facts for bounded TRANSFER, SWAP, LIQUIDITY_ADD, LIQUIDITY_REMOVE and BRIDGE_CROSSING rows and enrichment, and USE chain for the chain node's own record of one known transaction, block or the head.";
581
581
  const KNOWN_PUBLIC_TOOL_DESCRIPTIONS = {
582
582
  meta_network_capabilities: "Return the current Chain Insights network and tool support matrix.",
583
583
  meta_usage_status: "Return the caller's public free graph_query quota for the current UTC day.",
584
584
  meta_subscription_status: "Return the caller's CIA subscription window end, daily allowance, consumption, and tier.",
585
585
  meta_help: "Show a short guide to Chain Insights tools and workflow.",
586
586
  wallet_balance: "Show the local Chain Insights payment wallet address, payment network, token, and amount.",
587
- aml_address_risk: "Screen one blockchain address for AML risk, behavior patterns, neighborhood context, exchange exposure, and optional comparison with another address. Topology reads cover full lifetime history in one unified graph. Omit version to use the latest contract, or pass version=v1 to pin the v1 contract.",
588
587
  graph_query: `Run a read-only GQL/Cypher query through the Chain Insights graph endpoint. ${GRAPH_LAYERS_TEXT} Preserve full addresses exactly.`,
589
588
  graph_query_batch: "Run multiple read-only GQL/Cypher queries through the Chain Insights graph endpoint in one paid batch. Prefer this for related topology/facts reads."
590
589
  };
@@ -606,7 +605,7 @@ const PICTURE_HELP_LINE = "In hosts that draw views, a graph_query answer with f
606
605
  const CHAIN_INSIGHTS_WORKFLOW = [
607
606
  "Workflow:",
608
607
  "1. Do not call investigation tools until required arguments are known. Network is required; use meta_network_capabilities to check supported networks and available tools, or ask the user if missing.",
609
- "2. Use aml_address_risk for single-address enrichment. Use graph_query(_batch) for graph-level questions that aml_address_risk does not answer.",
608
+ "2. Use graph_query(_batch) for every question about addresses, money flow and transactions.",
610
609
  "3. Preserve tool summaries and structured facts as returned. Keep full blockchain addresses intact."
611
610
  ].join("\n");
612
611
  const GRAPH_SCHEMA_HINTS = [
@@ -617,9 +616,9 @@ const GRAPH_SCHEMA_HINTS = [
617
616
  "- The graph is address-grain. The only topology money node label is Address, keyed by the raw chain-native H160 address on EVM networks, for example 0x1874a43d7c6d888f9eda3d22a3a49704e3cadb24. The network value on Address nodes matches the tool argument. There is no separate identity key.",
618
617
  "- Address nodes carry address, network, labels, and the role flags is_exchange, is_scam, is_victim and is_sanctioned. (:Address)-[:LINKED]-(:Address) is an undirected ownership-overlay edge (basis derived/associated, plus confidence, source_event, declared_owner, owner_state) asserting the two addresses are controlled by the same actor. LINKED is served on the topology graph only. Enumerate LINKED neighbors with MATCH (a:Address {address: $addr})-[l:LINKED]-(b:Address) RETURN b.address, b.network, l.basis, l.confidence LIMIT 25.",
619
618
  "- Labels hold role words, never detector names: Exchange (plus the exchange name), Scam, Victim and Sanctioned (plus the entity name). Each role is also a node label and a flag on the Address: :Exchange and is_exchange follow the exchange label, :Scam and is_scam the risk label, :Victim and is_victim the protection label, :Sanctioned and is_sanctioned the sanctioned label. Each flag is present only when true and absent otherwise, never false: test IS NOT NULL or IS NULL, not = false. A withdrawn label removes its node label and its flag.",
620
- "- Address nodes also carry a risk verdict (risk_score float, risk_level string) plus base activity rollups: degree_in/degree_out/degree_total (distinct counterparty addresses), tx_in_count/tx_out_count/tx_total_count, total_in_usd/total_out_usd/total_volume_usd, net_flow_usd (in minus out; positive = net receiver) — all computed from external flows only — and first_activity_timestamp/last_activity_timestamp/activity_span_days, which include all flows (self-loops included). FLOWS_TO edges carry exactly tx_count, amount_usd_sum (total money flow, token and native value merged), first_seen_timestamp, last_seen_timestamp. Lifetime aggregates are the only serving window. Averages are computed inline (amount_usd_sum / toFloat(tx_count)). tx_count counts token and native transfers plus internal native transfers (a contract sending ETH during a call), and amount_usd_sum prices them all. USE facts TRANSFER lists all three, so the rows of a pair are the transfers its link counts, up to the height the link was built to. A link covers all time and a USE facts read covers one day: read the transfers of a pair one day at a time. A transaction anchor of a pair resolves through USE facts, on the UTC day of the first_seen_timestamp or last_seen_timestamp of the link: MATCH (a:Address {address: $from})-[t:TRANSFER]->(b:Address {address: $to}) WHERE t.block_date = \"YYYY-MM-DD\" RETURN t.tx_id, t.block_timestamp LIMIT 1.",
619
+ "- Address nodes carry base activity rollups: degree_in/degree_out/degree_total (distinct counterparty addresses), tx_in_count/tx_out_count/tx_total_count, total_in_usd/total_out_usd/total_volume_usd, net_flow_usd (in minus out; positive = net receiver) — all computed from external flows only — and first_activity_timestamp/last_activity_timestamp/activity_span_days, which include all flows (self-loops included). FLOWS_TO edges carry exactly tx_count, amount_usd_sum (total money flow, token and native value merged), first_seen_timestamp, last_seen_timestamp. Lifetime aggregates are the only serving window. Averages are computed inline (amount_usd_sum / toFloat(tx_count)). tx_count counts token and native transfers plus internal native transfers (a contract sending ETH during a call), and amount_usd_sum prices them all. USE facts TRANSFER lists all three, so the rows of a pair are the transfers its link counts, up to the height the link was built to. A link covers all time and a USE facts read covers one day: read the transfers of a pair one day at a time. A transaction anchor of a pair resolves through USE facts, on the UTC day of the first_seen_timestamp or last_seen_timestamp of the link: MATCH (a:Address {address: $from})-[t:TRANSFER]->(b:Address {address: $to}) WHERE t.block_date = \"YYYY-MM-DD\" RETURN t.tx_id, t.block_timestamp LIMIT 1.",
621
620
  "- For actor-level exposure (AC11), UNION FLOWS_TO and SWAPPED reachability over one visible LINKED hop instead of expanding through the LINKED edge itself: MATCH (a:Address {address: $addr})-[:LINKED]-(owned:Address)-[r:FLOWS_TO|SWAPPED]-(b:Address) WHERE NOT a:Pool AND NOT owned:Pool AND owned.address <> b.address AND a.address <> b.address RETURN owned.address, b.address, type(r), coalesce(r.amount_usd_sum, r.bought_usd) LIMIT 50.",
622
- "- The risk verdict lives on topology nodes (risk_score float, risk_level string). An absent risk_score means UNSCORED: the model gave the address no verdict, which is no signal and never low risk. Labels and per-label risk also live on the address node: the labels array plus three parallel lists, label_risk_labels, label_risk_levels and label_risk_updated_timestamps, where entry i of each list is one label row. USE facts serves bounded single-event rows (TRANSFER, SWAP, LIQUIDITY_ADD, LIQUIDITY_REMOVE and BRIDGE_CROSSING edges) only; lifetime address metrics (degrees, totals, activity window) are node properties on USE topology.",
621
+ "- Labels and per-label risk live on the address node: the labels array plus three parallel lists, label_risk_labels, label_risk_levels and label_risk_updated_timestamps, where entry i of each list is one label row. No overall risk score is served. USE facts serves bounded single-event rows (TRANSFER, SWAP, LIQUIDITY_ADD, LIQUIDITY_REMOVE and BRIDGE_CROSSING edges) only; lifetime address metrics (degrees, totals, activity window) are node properties on USE topology.",
623
622
  "- (from:Address)-[t:TRANSFER]->(to:Address) on USE facts returns individual transfer rows, not aggregates, with properties amount, amount_usd, asset_symbol, asset_contract, tx_id, block_height, block_timestamp, event_index, edge_index, kind, price_usd, and price_missing. Every TRANSFER row has a kind: token, native or internal. An internal row is ETH a contract sends while it runs a call, such as the ETH leg of a wrap. Add t.kind = \"internal\" to the pair and the day to read only the internal rows. A facts read names an address pair with one day, or one tx_id, whether it is a TRANSFER row-select or a count()/sum() aggregate: both endpoint addresses as {address: \"...\"} on from and to, with WHERE t.block_date = \"YYYY-MM-DD\", or WHERE t.tx_id = \"...\" on its own (on EVM networks tx_id is the 0x transaction hash). t.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 or a bare LIMIT is not enough. A facts read holds at most 200 rows in a reply, has one relationship and no hop, and takes no ORDER BY: sort the page yourself.",
624
623
  "- Facts graph labels include Address; the TRANSFER, SWAP, LIQUIDITY_ADD, LIQUIDITY_REMOVE and BRIDGE_CROSSING relationships each connect two Address nodes. Facts address keys match topology address values exactly.",
625
624
  "- Topology relationships include FLOWS_TO, SWAPPED, OPERATED_BY, LINKED, and RISK_PROXIMITY between Address nodes, ADDED_LIQUIDITY and REMOVED_LIQUIDITY to and from Pool nodes, and BRIDGED to and from Chain nodes.",
@@ -633,10 +632,10 @@ const GRAPH_SCHEMA_HINTS = [
633
632
  "- A USE facts SWAP row carries no route: it has no pools and no families column. A read that names one of them, to return it, to filter on it or to order by it, is refused. The route of a swap stays a topology question. For the pools of the swaps of an address, read SWAPPED.pools and SWAPPED.families on USE topology, anchored on the payer or the recipient. SWAPPED has one link per payer, recipient, sold asset and bought asset, so its pools cover every route on the link, not one route.",
634
633
  "- Traversal rule: for BFS, fixed-hop fallback, shortest-path, or manual FLOWS_TO traversal, exchange hot wallets are terminal endpoints only. Do not expand from, through, or classify exchange nodes as deposit, suspect, or intermediate candidates; filter every non-terminal node with is_exchange IS NULL. is_exchange is absent unless true, so a labelled node with no is_exchange is walked through, and is_scam, is_victim and is_sanctioned do not end a walk. At a Pool, follow the pool trace rule above.",
635
634
  "- Pool guard: a trace walks FLOWS_TO and SWAPPED, so it crosses a swap from payer to recipient without passing through the pool. A walk may end at a Pool, but never starts at one or passes through one: its start and every address in its middle stay off a Pool. A fixed-hop walk adds WHERE NOT src:Pool AND NOT mid:Pool, each its own AND term, never inside an OR. A quantified or shortest-path walk puts the guards inside the path pattern, on the start and on up to 4 guarded hops before one last hop: MATCH p = SHORTEST 1 (a:Address {address: $from} WHERE NOT a:Pool) (()-[:FLOWS_TO|SWAPPED]-(via:Address) WHERE NOT via:Pool){0,4} ()-[:FLOWS_TO|SWAPPED]-(b:Address {address: $to}) RETURN [n IN nodes(p) | n.address] AS route LIMIT 5. ANY SHORTEST takes the same pattern. A route search asks for one path. An open target from one address: MATCH SHORTEST 1 (a:Address {address: $addr} WHERE NOT a:Pool) (()-[:FLOWS_TO|SWAPPED]-(via:Address) WHERE NOT via:Pool){0,4} ()-[:FLOWS_TO|SWAPPED]-(b:Address) RETURN b.address LIMIT 50. Use these shapes as written, changing only the addresses and the RETURN. A WHERE placed after a SHORTEST pattern runs after the shortest route is chosen, so it drops a route that crosses a pool instead of finding the route that avoids it.",
636
- "- Start schema discovery with endpoint-safe property reads: MATCH (n:Address) RETURN n.address AS address, n.network AS network, n.labels AS labels, n.risk_score AS risk_score, n.risk_level AS risk_level LIMIT 20",
635
+ "- Start schema discovery with endpoint-safe property reads: MATCH (n:Address) RETURN n.address AS address, n.network AS network, n.labels AS labels, n.last_activity_timestamp AS last_activity_timestamp LIMIT 20",
637
636
  "- Relationship discovery: MATCH (:Address)-[r:FLOWS_TO]->(:Address) RETURN r.amount_usd_sum AS amount_usd_sum, r.tx_count AS tx_count LIMIT 20",
638
637
  "- Anchor every topology read that filters on a link property: put an address in its pattern. Without one, a read starts from every link of the type it names, and you should not count on the filter to narrow that: WHERE x.strength = 'swap' on SWAPPED checks every SWAPPED link, LIMIT stops the read only after enough rows match, and a filter that matches few or none can run to the 60 s topology limit and fail with query_timeout. Example: MATCH (a:Address {address: $addr})-[x:SWAPPED]->(b:Address) WHERE x.swap_count >= 2 RETURN b.address, x.swap_count LIMIT 25. Pick an address with few links: degree_out and degree_in are a rough guide, because they count neighbours, not links, and an address with hundreds of thousands of neighbours can fail the same way. Discovery probes with LIMIT and no filter stay valid. The queries of one batch share a 100 s budget; USE facts queries stop at 30 s.",
639
- "- graph_query uses the active Chain Insights graph endpoint. Select the graph with USE topology for topology (address/FLOWS_TO/OPERATED_BY/LINKED graph with SWAPPED, ADDED_LIQUIDITY, REMOVED_LIQUIDITY, BRIDGED and the Pool label, unified recent+historical, plus the node risk_score/risk_level verdict) and USE facts for bounded TRANSFER, SWAP, LIQUIDITY_ADD, LIQUIDITY_REMOVE and BRIDGE_CROSSING rows and enrichment, and USE chain for one keyed lookup on the chain node: a transaction by hash, a block by number or hash, or the head, and no address. On topology, address is the node grain, not the topology name.",
638
+ "- graph_query uses the active Chain Insights graph endpoint. Select the graph with USE topology for topology (address/FLOWS_TO/OPERATED_BY/LINKED graph with SWAPPED, ADDED_LIQUIDITY, REMOVED_LIQUIDITY, BRIDGED and the Pool label, unified recent+historical) and USE facts for bounded TRANSFER, SWAP, LIQUIDITY_ADD, LIQUIDITY_REMOVE and BRIDGE_CROSSING rows and enrichment, and USE chain for one keyed lookup on the chain node: a transaction by hash, a block by number or hash, or the head, and no address. On topology, address is the node grain, not the topology name.",
640
639
  "- All graph_query calls are read-only. Never use CREATE, INSERT, MERGE, SET, DELETE, REMOVE, DROP, DETACH, ADD, CONNECT, DISCONNECT, ALTER, TRUNCATE, GRANT, or REVOKE.",
641
640
  "- Use USE facts graph patterns for fact and enrichment reads. Do not query internal table namespaces directly."
642
641
  ].join("\n");
@@ -649,7 +648,7 @@ const SERVER_INSTRUCTIONS = [
649
648
  ].join("\n\n");
650
649
  const STATELESS_SERVER_INSTRUCTIONS = [
651
650
  "Chain Insights is running as a stateless AML proxy for a host application.",
652
- "Use meta_network_capabilities first when network support is unknown, then call aml_address_risk, graph_query, or graph_query_batch as needed.",
651
+ "Use meta_network_capabilities first when network support is unknown, then call graph_query or graph_query_batch as needed.",
653
652
  PICTURE_RULES,
654
653
  "Use wallet_balance to inspect the local payment wallet when payment setup is needed.",
655
654
  GRAPH_SCHEMA_HINTS,
@@ -657,12 +656,6 @@ const STATELESS_SERVER_INSTRUCTIONS = [
657
656
  ].join("\n\n");
658
657
  function knownPublicToolInputSchema(toolName) {
659
658
  switch (toolName) {
660
- case "aml_address_risk": return {
661
- address: z.string().min(1).describe("Blockchain address to screen."),
662
- network: NETWORK_SCHEMA,
663
- compare_address: z.string().optional().describe("Optional address to compare against the screened address."),
664
- version: z.string().optional().describe("Optional AML tool contract version. Omit to use the latest version.")
665
- };
666
659
  case "graph_query": return {
667
660
  query: z.string().min(1).describe(`Read-only GQL/Cypher query. ${GRAPH_LAYERS_TEXT}`),
668
661
  network: NETWORK_SCHEMA
@@ -928,23 +921,6 @@ function promptResult(text, description) {
928
921
  };
929
922
  }
930
923
  function registerLocalPrompts(server) {
931
- server.registerPrompt("aml-address-risk", {
932
- title: "AML Address Risk",
933
- description: "Screen a blockchain address for AML risk, behavioral patterns, neighborhood profile, member addresses, and exchange links.",
934
- argsSchema: {
935
- network: NETWORK_SCHEMA,
936
- address: z.string().describe("Blockchain address to screen"),
937
- compare_address: z.string().optional().describe("Optional address to compare against the screened address"),
938
- version: z.string().optional().describe("Optional AML tool contract version. Omit to use the latest version")
939
- }
940
- }, async ({ network, address, compare_address, version }) => promptResult([
941
- `Use Chain Insights aml_address_risk${version ? ` version ${version}` : ""} on ${network} for:`,
942
- "",
943
- `\`${address}\``,
944
- compare_address ? `\nCompare with: \`${compare_address}\`` : "",
945
- "",
946
- "Present the summary as-is. Do not add analysis, verdicts, or risk assessments; the tool output already contains the risk assessment."
947
- ].filter(Boolean).join("\n"), "AML address risk screening"));
948
924
  server.registerPrompt("meta-network-capabilities", {
949
925
  title: "Network Capabilities",
950
926
  description: "Inspect supported networks and available tools before selecting a network.",
@@ -1326,62 +1302,6 @@ async function createProxy() {
1326
1302
  };
1327
1303
  }
1328
1304
  });
1329
- if (!remoteToolNames.has("aml_address_risk")) server.registerTool("aml_address_risk", {
1330
- title: "Address Risk",
1331
- description: KNOWN_PUBLIC_TOOL_DESCRIPTIONS.aml_address_risk,
1332
- inputSchema: {
1333
- address: z.string().min(1).describe("Blockchain address to screen"),
1334
- network: NETWORK_SCHEMA,
1335
- compare_address: z.string().optional().describe("Optional address to compare against the screened address"),
1336
- version: z.string().optional().describe("Optional AML tool contract version. Omit to use the latest version")
1337
- },
1338
- annotations: {
1339
- readOnlyHint: true,
1340
- destructiveHint: false,
1341
- idempotentHint: true,
1342
- openWorldHint: true
1343
- }
1344
- }, async ({ address, network, compare_address, version }) => {
1345
- try {
1346
- if (!remoteConnected) return {
1347
- content: [{
1348
- type: "text",
1349
- text: `${remoteUnavailableMessage ?? `Chain Insights Graph is not connected at ${graphMcpEndpoint}`}. Restart the Chain Insights MCP proxy after the endpoint is reachable.`
1350
- }],
1351
- isError: true
1352
- };
1353
- const { runAmlAddressRisk } = await import("./public-tools-CZyeptJQ.mjs");
1354
- const result = await runAmlAddressRisk(remoteClient, {
1355
- address,
1356
- network,
1357
- compareAddress: compare_address,
1358
- writeArtifacts: workspaceArtifactsEnabled
1359
- }, version);
1360
- return {
1361
- content: [{
1362
- type: "text",
1363
- text: result.summaryText
1364
- }],
1365
- structuredContent: result.structuredContent,
1366
- isError: false
1367
- };
1368
- } catch (err) {
1369
- if (err instanceof PaymentRequiredError) return {
1370
- content: [{
1371
- type: "text",
1372
- text: err.message
1373
- }],
1374
- isError: true
1375
- };
1376
- return {
1377
- content: [{
1378
- type: "text",
1379
- text: `Address risk failed: ${err.message}`
1380
- }],
1381
- isError: true
1382
- };
1383
- }
1384
- });
1385
1305
  const flowsDependencies = {
1386
1306
  graphQuery: async (args) => {
1387
1307
  const options = remoteToolRequestOptions("graph_query");
@@ -1430,7 +1350,6 @@ async function createProxy() {
1430
1350
  "- meta_network_capabilities: inspect supported networks and available tools.",
1431
1351
  "- meta_usage_status: check the caller public free graph_query quota.",
1432
1352
  "- meta_subscription_status: check the caller CIA subscription window end, daily allowance, consumption, and tier.",
1433
- "- aml_address_risk: screen one blockchain address; optionally compare it with another address.",
1434
1353
  "- graph_query: run read-only GQL/Cypher through the universal graph endpoint. Use USE topology or USE facts.",
1435
1354
  "- graph_query_batch: run related read-only graph-language queries through one paid graph call.",
1436
1355
  "",
@@ -1446,7 +1365,6 @@ async function createProxy() {
1446
1365
  "- meta_network_capabilities: inspect supported networks and available tools.",
1447
1366
  "- meta_usage_status: check the caller public free graph_query quota.",
1448
1367
  "- meta_subscription_status: check the caller CIA subscription window end, daily allowance, consumption, and tier.",
1449
- "- aml_address_risk: screen one blockchain address; optionally compare it with another address.",
1450
1368
  "- graph_query: run read-only GQL/Cypher through the universal graph endpoint. Use USE topology or USE facts.",
1451
1369
  "- graph_query_batch: run related read-only graph-language queries through one paid graph call.",
1452
1370
  "",