chain-insights 0.56.21 → 0.57.1

package/dist/{graph-schema-CXD7NtEX.cjs → graph-schema-_u1aB_f1.cjs}

@@ -26,6 +26,16 @@ let node_crypto = require("node:crypto");
 *   on one UTC day, newest first, at most 50, a short text summary and
 *   chain-insights.transfers.v1 in structuredContent. One anchored USE facts
 *   graph_query read.
+* - link page, {network, from, to, day, limit, skip?, first_day?}: a page of
+*   `limit` transfers (1 to 50) newest first, read from `day` back one UTC day
+*   at a time, at most TRANSFERS_MAX_DAYS (a week of) reads a call, never before
+*   first_day. The answer carries `next` ({day, skip}, or null when every
+*   transfer back to first_day is listed) which the next call sends back as
+*   day and skip. The view's "More transfers".
+* - details, {network, address, details: true}: the lifetime totals, counts,
+*   role and labels of one address, chain-insights.address.v1, one anchored
+*   topology read. The view fills its panel with it when the rows of a query
+*   carried no totals.
 *
 * Every read goes through the proxy's remote client, the same path and payment
 * wrapping a graph_query call takes, and is billed as a graph_query. Every
@@ -38,10 +48,15 @@ const FLOWS_NETWORK = "robinhood";
 /** Where a graph_expand page may start on each side, at most. */
 const FLOWS_MAX_OFFSET = 1e4;
 const TRANSFERS_SCHEMA = "chain-insights.transfers.v1";
+const ADDRESS_SCHEMA = "chain-insights.address.v1";
 const INVALID_ADDRESS_TEXT = "invalid_address: a full 0x address of 40 hexadecimal characters is needed, for example 0x04911a118f11c75667e4d0dfb8e640af5a353550";
 const OFFSET_TOO_LARGE_TEXT = `invalid_offset: in_offset and out_offset must each be at most ${FLOWS_MAX_OFFSET}`;
 const OFFSET_NEGATIVE_TEXT = "invalid_offset: in_offset and out_offset must each be a whole number, 0 or more";
 const BOTH_FORMS_TEXT = "invalid_arguments: pass address (with in_offset and out_offset) to expand a node, or from, to and day to list the transfers of a link, not both";
+const INVALID_LIMIT_TEXT = "invalid_limit: limit must be a whole number from 1 to 50";
+const INVALID_SKIP_TEXT = "invalid_skip: skip must be a whole number of 0 or more";
+const INVALID_FIRST_DAY_TEXT = "invalid_first_day: first_day must be a calendar date written YYYY-MM-DD (UTC), not after day";
+const DETAILS_FORM_TEXT = "invalid_arguments: details takes address alone; pass no from, to, day or offsets with it";
 const ADDRESS_PATTERN = /^0x[0-9a-f]{40}$/;
 const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 const CODE_PREFIX = /^([a-z][a-z0-9_]*):\s*/;
@@ -77,6 +92,41 @@ function normalizeFlowsDay(raw) {
 function transfersReadFor(from, to, day) {
 	return `USE facts MATCH (a:Address {address: "${from}"})-[t:TRANSFER]->(b:Address {address: "${to}"}) WHERE t.block_date = "${day}" RETURN t.tx_id AS tx_id, t.block_timestamp AS block_timestamp, t.amount AS amount, t.asset_symbol AS asset_symbol, t.amount_usd AS amount_usd LIMIT 200`;
 }
+/** The UTC day before a YYYY-MM-DD day. */
+function dayBefore(day) {
+	return (/* @__PURE__ */ new Date(Date.parse(`${day}T00:00:00Z`) - 864e5)).toISOString().slice(0, 10);
+}
+/**
+* The one topology read of a details call: the address alone, with its
+* lifetime rollups and activity span. The address has passed its check, so it
+* is written into the read as a literal.
+*/
+function detailsReadFor(address) {
+	return `USE topology MATCH (b:Address {address: "${address}"}) RETURN ${NODE_FIELDS}, b.first_activity_timestamp AS first_activity_timestamp, b.last_activity_timestamp AS last_activity_timestamp LIMIT 1`;
+}
+/** chain-insights.address.v1 from the one row of a details read. */
+function buildAddressView(network, address, row) {
+	const node = flowsNodeOf({
+		...row,
+		address
+	});
+	return {
+		schema: ADDRESS_SCHEMA,
+		network,
+		...node,
+		is_exchange: row.is_exchange === true,
+		is_sanctioned: row.is_sanctioned === true,
+		is_scam: row.is_scam === true,
+		is_victim: row.is_victim === true,
+		pool: row.pool === true,
+		first_activity_timestamp: flowsNumberOrNull(row.first_activity_timestamp),
+		last_activity_timestamp: flowsNumberOrNull(row.last_activity_timestamp)
+	};
+}
+/** The one line of a details answer. */
+function addressSummary(view) {
+	return `${view.address} on ${view.network}: ${view.role}; lifetime ${formatFlowsUsd(view.total_in_usd)} in, ${formatFlowsUsd(view.total_out_usd)} out; ${view.degree_in} senders and ${view.degree_out} receivers in the topology graph` + (view.labels.length ? `; labels ${view.labels.join(", ")}` : "") + ".";
+}
 const NODE_FIELDS = "b.address AS address, b.labels AS labels, b.is_exchange AS is_exchange, b.is_sanctioned AS is_sanctioned, b.is_scam AS is_scam, b.is_victim AS is_victim, b:Pool AS pool, b.total_in_usd AS total_in_usd, b.total_out_usd AS total_out_usd, b.degree_in AS degree_in, b.degree_out AS degree_out";
 const PARTY_FIELDS = NODE_FIELDS + ", f.amount_usd_sum AS usd, f.tx_count AS tx_count, " + "f.first_seen_timestamp AS first_seen, f.last_seen_timestamp AS last_seen";
 const PAGE_ORDER = " ORDER BY f.last_seen_timestamp DESC, b.address";
@@ -321,11 +371,14 @@ function transferLine(transfer) {
 }
 /** The short text of a link answer: the pair, the day, the count and the newest few transfers. */
 function transfersSummary(view) {
-	const head = `Transfers from ${view.from} to ${view.to} on ${view.day} (UTC) on ${view.network}`;
-	if (view.transfers.length === 0) return `${head}: none.`;
-	const lines = [`${head}: ${view.truncated ? `the newest ${view.transfers.length}, and the day holds more` : `${view.transfers.length}`}, newest first.`, ...view.transfers.slice(0, 5).map(transferLine)];
+	const paged = view.through_day !== void 0;
+	const span = paged && view.through_day !== view.day ? `${view.through_day} to ${view.day}` : view.day;
+	const head = `Transfers from ${view.from} to ${view.to} on ${span} (UTC) on ${view.network}`;
+	if (view.transfers.length === 0) return paged && view.next ? `${head}: none; earlier days remain before ${view.next.day}.` : `${head}: none.`;
+	const lines = [`${head}: ${view.truncated ? paged ? `${view.transfers.length}, and a day holds more than one read lists` : `the newest ${view.transfers.length}, and the day holds more` : `${view.transfers.length}`}, newest first.`, ...view.transfers.slice(0, 5).map(transferLine)];
 	const rest = view.transfers.length - 5;
 	if (rest > 0) lines.push(`- and ${rest} more in the picture.`);
+	if (paged && view.next) lines.push(`- earlier transfers remain, from ${view.next.day} back.`);
 	return lines.join("\n");
 }
 function errorResult$1(text) {
@@ -385,6 +438,21 @@ function checkAddress(raw, name) {
 function checkDay(raw) {
 	return normalizeFlowsDay(raw) ?? { error: "invalid_day: day must be a calendar date written YYYY-MM-DD (UTC), for example 2026-07-10" };
 }
+function checkLimit(value) {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 50) return { error: INVALID_LIMIT_TEXT };
+	return value;
+}
+function checkSkip(value) {
+	if (value === void 0 || value === null) return 0;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0) return { error: INVALID_SKIP_TEXT };
+	return value;
+}
+function checkFirstDay(value, day) {
+	if (value === void 0 || value === null) return null;
+	const first = normalizeFlowsDay(value);
+	if (!first || first > day) return { error: INVALID_FIRST_DAY_TEXT };
+	return first;
+}
 function checkOffset(value) {
 	if (value === void 0 || value === null) return 0;
 	if (typeof value !== "number" || !Number.isInteger(value) || value < 0) return { error: OFFSET_NEGATIVE_TEXT };
@@ -468,6 +536,127 @@ async function runLink(deps, network, from, to, day) {
 		isError: false
 	};
 }
+/** One facts read of a day, as the paged walk needs it: the rows newest first, or the error that ends the call. */
+async function readDay(deps, network, from, to, day) {
+	let answer;
+	try {
+		answer = await deps.graphQuery({
+			network,
+			query: transfersReadFor(from, to, day)
+		});
+	} catch (err) {
+		return { error: deps.describeFailure(err) };
+	}
+	if (answer.isError === true) return { error: refusalText(answer) };
+	const rows = rowsOf(answer);
+	if (!rows) return { error: "graph_query_failed: the graph endpoint answered without chain-insights.result.v1 rows" };
+	return {
+		rows: rows.map(transferOf).sort((a, b) => (b.block_timestamp ?? -Infinity) - (a.block_timestamp ?? -Infinity)),
+		cut: rows.length >= 200
+	};
+}
+/**
+* Read and answer one page of a link's transfers: from `day` back, one day a
+* read, until the page holds `limit` transfers, TRANSFERS_MAX_DAYS days were
+* read, or the day before first_day is reached. `skip` passes over the
+* transfers of `day` an earlier page listed. The first read that does not
+* answer ends the call.
+*/
+async function runLinkPage(deps, network, from, to, day, page) {
+	const unavailable = deps.unavailable?.();
+	if (unavailable) return errorResult$1(unavailable);
+	const floor = page.firstDay ?? "2015-01-01";
+	const transfers = [];
+	let current = day;
+	let skip = page.skip;
+	let daysRead = 0;
+	let through = day;
+	let truncated = false;
+	let next = null;
+	for (;;) {
+		if (current < floor) break;
+		if (daysRead >= 7) {
+			next = {
+				day: current,
+				skip
+			};
+			break;
+		}
+		const read = await readDay(deps, network, from, to, current);
+		if ("error" in read) return errorResult$1(read.error);
+		daysRead += 1;
+		through = current;
+		if (read.cut) truncated = true;
+		const rest = read.rows.slice(skip);
+		const room = page.limit - transfers.length;
+		if (rest.length > room) {
+			transfers.push(...rest.slice(0, room));
+			next = {
+				day: current,
+				skip: skip + room
+			};
+			break;
+		}
+		transfers.push(...rest);
+		const earlier = dayBefore(current);
+		if (transfers.length >= page.limit) {
+			next = earlier < floor ? null : {
+				day: earlier,
+				skip: 0
+			};
+			break;
+		}
+		current = earlier;
+		skip = 0;
+	}
+	const view = {
+		schema: TRANSFERS_SCHEMA,
+		network,
+		from,
+		to,
+		day,
+		transfers,
+		truncated,
+		through_day: through,
+		days_read: daysRead,
+		next
+	};
+	return {
+		content: [{
+			type: "text",
+			text: transfersSummary(view)
+		}],
+		structuredContent: view,
+		isError: false
+	};
+}
+/** Read and answer the details of one address: a single anchored topology read. */
+async function runDetails(deps, network, address) {
+	const unavailable = deps.unavailable?.();
+	if (unavailable) return errorResult$1(unavailable);
+	let answer;
+	try {
+		answer = await deps.graphQuery({
+			network,
+			query: detailsReadFor(address)
+		});
+	} catch (err) {
+		return errorResult$1(deps.describeFailure(err));
+	}
+	if (answer.isError === true) return errorResult$1(refusalText(answer));
+	const rows = rowsOf(answer);
+	if (!rows) return errorResult$1("graph_query_failed: the graph endpoint answered without chain-insights.result.v1 rows");
+	if (rows.length === 0) return errorResult$1(`${address} is not in the ${network} topology graph`);
+	const view = buildAddressView(network, address, rows[0]);
+	return {
+		content: [{
+			type: "text",
+			text: addressSummary(view)
+		}],
+		structuredContent: view,
+		isError: false
+	};
+}
 function given(record, keys) {
 	return keys.some((key) => record[key] !== void 0 && record[key] !== null);
 }
@@ -488,7 +677,8 @@ async function handleGraphExpand(args, deps) {
 	if (isLink && given(record, [
 		"address",
 		"in_offset",
-		"out_offset"
+		"out_offset",
+		"details"
 	])) return errorResult$1(BOTH_FORMS_TEXT);
 	if (isLink) {
 		const from = checkAddress(record.from, "from");
@@ -497,8 +687,32 @@ async function handleGraphExpand(args, deps) {
 		if (typeof to !== "string") return errorResult$1(to.error);
 		const day = checkDay(record.day);
 		if (typeof day !== "string") return errorResult$1(day.error);
+		if (given(record, [
+			"limit",
+			"skip",
+			"first_day"
+		])) {
+			const limit = checkLimit(record.limit);
+			if (typeof limit !== "number") return errorResult$1(limit.error);
+			const skip = checkSkip(record.skip);
+			if (typeof skip !== "number") return errorResult$1(skip.error);
+			const firstDay = checkFirstDay(record.first_day, day);
+			if (firstDay !== null && typeof firstDay !== "string") return errorResult$1(firstDay.error);
+			return runLinkPage(deps, network, from, to, day, {
+				skip,
+				firstDay,
+				limit
+			});
+		}
 		return runLink(deps, network, from, to, day);
 	}
+	if (record.details !== void 0 && record.details !== null) {
+		if (record.details !== true) return errorResult$1(DETAILS_FORM_TEXT);
+		if (given(record, ["in_offset", "out_offset"])) return errorResult$1(DETAILS_FORM_TEXT);
+		const address = checkAddress(record.address);
+		if (typeof address !== "string") return errorResult$1(address.error);
+		return runDetails(deps, network, address);
+	}
 	const address = checkAddress(record.address);
 	if (typeof address !== "string") return errorResult$1(address.error);
 	const inOffset = checkOffset(record.in_offset);
@@ -508,7 +722,7 @@ async function handleGraphExpand(args, deps) {
 	return runNode(deps, network, address, inOffset, outOffset);
 }
 const GRAPH_EXPAND_TITLE = "Expand a node or a link in the picture";
-const GRAPH_EXPAND_DESCRIPTION = "Expand an open Chain Insights picture. Called by the view when the investigator clicks, never by the model. A node, {network, address, in_offset?, out_offset?}, loads the newest senders and receivers of one address (up to 250 a side, from the offsets); billed as at most five graph_query topology reads. A link, {network, from, to, day}, lists the transfers between two addresses on one UTC day (YYYY-MM-DD), newest first, at most 50; billed as one graph_query facts read. Read-only; an argument refused before a read costs nothing.";
+const GRAPH_EXPAND_DESCRIPTION = "Expand an open Chain Insights picture. Called by the view when the investigator clicks, never by the model. A node, {network, address, in_offset?, out_offset?}, loads the newest senders and receivers of one address (up to 250 a side, from the offsets); billed as at most five graph_query topology reads. A link, {network, from, to, day}, lists the transfers between two addresses on one UTC day (YYYY-MM-DD), newest first, at most 50; billed as one graph_query facts read. A link page, {network, from, to, day, limit, skip?, first_day?}, lists `limit` (1-50) transfers from `day` back across days, newest first, and answers a `next` cursor ({day, skip}) while older ones remain; billed as at most seven facts reads (a week). Details, {network, address, details: true}, answer the lifetime totals, counts, role and labels of one address; billed as one topology read. Read-only; an argument refused before a read costs nothing.";
 //#endregion
 //#region src/mcp/graph-schema-cache.ts
 /** How long a schema with a failed read stays fresh. */

package/dist/mcp-proxy.cjs

@@ -6,7 +6,7 @@ const require_tool_visibility = require("./tool-visibility-CDe-ft0L.cjs");
 const require_usage_status = require("./usage-status-BdwwgYsu.cjs");
 const require_subscription_status = require("./subscription-status-Cm7LqY_h.cjs");
 const require_capabilities = require("./capabilities-BGkL9yAr.cjs");
-const require_graph_schema = require("./graph-schema-CXD7NtEX.cjs");
+const require_graph_schema = require("./graph-schema-_u1aB_f1.cjs");
 const require_action_log = require("./action-log-HniMMF7f.cjs");
 let node_url = require("node:url");
 let node_path = require("node:path");
@@ -1708,7 +1708,11 @@ async function createProxy() {
 			out_offset: zod.number().int().min(0).max(require_graph_schema.FLOWS_MAX_OFFSET).optional(),
 			from: zod.string().optional(),
 			to: zod.string().optional(),
-			day: zod.string().optional()
+			day: zod.string().optional(),
+			limit: zod.number().int().min(1).max(50).optional(),
+			skip: zod.number().int().min(0).optional(),
+			first_day: zod.string().optional(),
+			details: zod.boolean().optional()
 		},
 		annotations: VIEW_TOOL_ANNOTATIONS,
 		_meta: APP_ONLY_TOOL_META

package/dist/mcp-proxy.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-proxy.d.cts","names":[],"sources":["../src/mcp/proxy.ts"],"mappings":";;qBAuEa;qBACA;;;;;wBAyBG;YAkBJ;wBAEI,oBAAoB,MAAK,OAAO,aAA2B;KAsCtE,iBAAiB,eAAe,EAAE;qBAgB1B;wBAyGG,2BAA2B,mBAAmB;;;;;;;;wBAomBxC,eAAe"}
+{"version":3,"file":"mcp-proxy.d.cts","names":[],"sources":["../src/mcp/proxy.ts"],"mappings":";;qBAwEa;qBACA;;;;;wBAyBG;YAkBJ;wBAEI,oBAAoB,MAAK,OAAO,aAA2B;KAsCtE,iBAAiB,eAAe,EAAE;qBAgB1B;wBAyGG,2BAA2B,mBAAmB;;;;;;;;wBAomBxC,eAAe"}

package/dist/mcp-proxy.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-proxy.d.mts","names":[],"sources":["../src/mcp/proxy.ts"],"mappings":";;qBAuEa;qBACA;;;;;wBAyBG;YAkBJ;wBAEI,oBAAoB,MAAK,OAAO,aAA2B;KAsCtE,iBAAiB,eAAe,EAAE;qBAgB1B;wBAyGG,2BAA2B,mBAAmB;;;;;;;;wBAomBxC,eAAe"}
+{"version":3,"file":"mcp-proxy.d.mts","names":[],"sources":["../src/mcp/proxy.ts"],"mappings":";;qBAwEa;qBACA;;;;;wBAyBG;YAkBJ;wBAEI,oBAAoB,MAAK,OAAO,aAA2B;KAsCtE,iBAAiB,eAAe,EAAE;qBAgB1B;wBAyGG,2BAA2B,mBAAmB;;;;;;;;wBAomBxC,eAAe"}

package/dist/mcp-proxy.mjs

@@ -4,7 +4,7 @@ import { i as isAppOnlyTool, n as PUBLIC_MCP_TOOL_ALLOWED_ARGS, r as PUBLIC_MCP_
 import { t as primitiveBackendUsageStatus } from "./usage-status-CXOnrq-s.mjs";
 import { n as unavailableSubscriptionStatus } from "./subscription-status-CJ-DaMW9.mjs";
 import { r as mirrorGraphNetworkCapabilities } from "./capabilities-Cur8x6c7.mjs";
-import { a as handleMetaSchema, c as GRAPH_EXPAND_TITLE, l as GRAPH_EXPAND_TOOL, n as META_SCHEMA_DESCRIPTION, o as FLOWS_MAX_OFFSET, r as META_SCHEMA_TITLE, s as GRAPH_EXPAND_DESCRIPTION, t as GraphSchemaError, u as handleGraphExpand } from "./graph-schema-D7wSNOT5.mjs";
+import { a as handleMetaSchema, c as GRAPH_EXPAND_TITLE, l as GRAPH_EXPAND_TOOL, n as META_SCHEMA_DESCRIPTION, o as FLOWS_MAX_OFFSET, r as META_SCHEMA_TITLE, s as GRAPH_EXPAND_DESCRIPTION, t as GraphSchemaError, u as handleGraphExpand } from "./graph-schema-CwsQBYrP.mjs";
 import { r as appendActionLog, t as actionLogSignalsFromResult } from "./action-log-D49Par9P.mjs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
@@ -1704,7 +1704,11 @@ async function createProxy() {
 			out_offset: z.number().int().min(0).max(FLOWS_MAX_OFFSET).optional(),
 			from: z.string().optional(),
 			to: z.string().optional(),
-			day: z.string().optional()
+			day: z.string().optional(),
+			limit: z.number().int().min(1).max(50).optional(),
+			skip: z.number().int().min(0).optional(),
+			first_day: z.string().optional(),
+			details: z.boolean().optional()
 		},
 		annotations: VIEW_TOOL_ANNOTATIONS,
 		_meta: APP_ONLY_TOOL_META