chain-insights 0.44.1 → 0.46.2

package/dist/graph-schema-D1orCe5F.mjs

@@ -0,0 +1,914 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
+import { t as PaymentRequiredError } from "./client-gsLi528K.mjs";
+import { n as findNetworkCapability, r as mirrorGraphNetworkCapabilities } from "./capabilities-Cur8x6c7.mjs";
+import { n as chainInsightsHome, t as CACHE_TTL_MS } from "./cache-location-BO2XkfgI.mjs";
+import path from "node:path";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+//#region src/mcp/flows.ts
+/**
+* graph_expand, the one dedicated tool of the local proxy, called by the Chain
+* Insights view (ui://chain-insights/view) when the investigator clicks. Its
+* _meta says visibility ["app"], so a host keeps it away from the model: the
+* model writes its own graph_query, and the view draws the rows by their column
+* names.
+*
+* Two forms, told apart by the arguments:
+*
+* - node, {network, address, in_offset?, out_offset?}: one address with its
+*   newest senders and receivers, a text summary and chain-insights.flows.v1 in
+*   structuredContent. Composed from three anchored graph_query reads on the
+*   topology graph (the node, its outgoing FLOWS_TO and its incoming FLOWS_TO,
+*   newest first).
+* - link, {network, from, to, day}: the transfers between two known addresses
+*   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.
+*
+* 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
+* argument is checked before the first read, so a refused call reaches no graph
+* endpoint and costs nothing.
+*/
+const FLOWS_SCHEMA = "chain-insights.flows.v1";
+const GRAPH_EXPAND_TOOL = "graph_expand";
+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 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 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*/;
+/**
+* The address lower-cased, or null when it is not 0x and 40 hexadecimal
+* characters. Only an address that passes is ever written into a read, so the
+* reads can carry it as a literal.
+*/
+function normalizeFlowsAddress(raw) {
+	if (typeof raw !== "string") return null;
+	const address = raw.trim().toLowerCase();
+	return ADDRESS_PATTERN.test(address) ? address : null;
+}
+/**
+* The day as YYYY-MM-DD when it is a real calendar date, or null. Only a day
+* that passes is ever written into a read.
+*/
+function normalizeFlowsDay(raw) {
+	if (typeof raw !== "string") return null;
+	const day = raw.trim();
+	if (!DAY_PATTERN.test(day)) return null;
+	const time = Date.parse(`${day}T00:00:00Z`);
+	if (Number.isNaN(time) || new Date(time).toISOString().slice(0, 10) !== day) return null;
+	return day;
+}
+/**
+* The one facts read of a link: the transfers from one address to another on
+* one day. A facts read names the pair with one day, takes no ORDER BY and
+* holds at most 200 rows, so the read asks for the whole cap and the order is
+* made in buildTransfersView. Both addresses and the day have passed their
+* checks, so they are written into the read as literals.
+*/
+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`;
+}
+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";
+/**
+* The three anchored reads of one page. Each side asks for one row more than
+* it shows: the extra row says another page exists.
+*/
+function flowsReadsFor(address, inOffset, outOffset) {
+	const page = (offset) => `${PAGE_ORDER}${offset > 0 ? ` SKIP ${offset}` : ""} LIMIT 13`;
+	return [
+		{
+			id: "node",
+			query: `USE topology MATCH (b:Address {address: '${address}'}) RETURN ${NODE_FIELDS} LIMIT 1`
+		},
+		{
+			id: "out",
+			query: `USE topology MATCH (a:Address {address: '${address}'})-[f:FLOWS_TO]->(b:Address) RETURN ${PARTY_FIELDS}${page(outOffset)}`
+		},
+		{
+			id: "in",
+			query: `USE topology MATCH (b:Address)-[f:FLOWS_TO]->(a:Address {address: '${address}'}) RETURN ${PARTY_FIELDS}${page(inOffset)}`
+		}
+	];
+}
+/** The role word of an address, first match wins. */
+function flowsRole(row) {
+	if (row.is_exchange === true) return "exchange";
+	if (row.is_sanctioned === true) return "sanctioned";
+	if (row.is_scam === true) return "scam";
+	if (row.is_victim === true) return "victim";
+	if (row.pool === true) return "pool";
+	return "other";
+}
+function flowsFloat(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function flowsInt(value) {
+	return typeof value === "number" && Number.isFinite(value) ? Math.trunc(value) : 0;
+}
+function flowsNodeOf(row) {
+	const labels = Array.isArray(row.labels) ? row.labels.filter((label) => typeof label === "string") : [];
+	return {
+		address: typeof row.address === "string" ? row.address : "",
+		role: flowsRole(row),
+		labels,
+		total_in_usd: flowsFloat(row.total_in_usd),
+		total_out_usd: flowsFloat(row.total_out_usd),
+		degree_in: flowsInt(row.degree_in),
+		degree_out: flowsInt(row.degree_out)
+	};
+}
+function assembleFlowView(network, page, senders, receivers, truncated) {
+	const center = flowsNodeOf(page.center);
+	const view = {
+		schema: FLOWS_SCHEMA,
+		network,
+		center: center.address,
+		nodes: [center],
+		edges: [],
+		cursor: {
+			in_offset: page.inOffset + senders.length,
+			out_offset: page.outOffset + receivers.length
+		},
+		truncated
+	};
+	const seen = /* @__PURE__ */ new Set([center.address]);
+	const add = (row, incoming) => {
+		const node = flowsNodeOf(row);
+		if (!seen.has(node.address)) {
+			seen.add(node.address);
+			view.nodes.push(node);
+		}
+		view.edges.push({
+			from: incoming ? node.address : center.address,
+			to: incoming ? center.address : node.address,
+			usd: flowsFloat(row.usd),
+			tx_count: flowsInt(row.tx_count),
+			first_seen_ms: flowsInt(row.first_seen),
+			last_seen_ms: flowsInt(row.last_seen)
+		});
+	};
+	for (const row of senders) add(row, true);
+	for (const row of receivers) add(row, false);
+	return view;
+}
+function fitsFlowBudget(view) {
+	return view.nodes.length <= 60 && JSON.stringify(view).length < 4e4;
+}
+/**
+* flows.v1 from one page: the centre first, then the senders and the
+* receivers, each newest first, at most FLOWS_PER_SIDE a side. When the view
+* data would hold more than FLOWS_MAX_NODES addresses or reach FLOWS_MAX_CHARS
+* characters, the oldest links go first, the view is marked truncated, and the
+* cursor still says where the next page starts.
+*/
+function buildFlowView(network, page) {
+	let truncated = page.senders.length > 12 || page.receivers.length > 12;
+	let senders = page.senders.slice(0, 12);
+	let receivers = page.receivers.slice(0, 12);
+	for (;;) {
+		const view = assembleFlowView(network, page, senders, receivers, truncated);
+		if (fitsFlowBudget(view) || senders.length + receivers.length === 0) return view;
+		truncated = true;
+		if (senders.length >= receivers.length) senders = senders.slice(0, -1);
+		else receivers = receivers.slice(0, -1);
+	}
+}
+function formatFlowsUsd(value) {
+	if (!(value > 0)) return "$0";
+	if (value < .01) return "under $0.01";
+	const whole = Math.floor(value);
+	const cents = Math.round((value - whole) * 100);
+	if (cents === 100) return formatFlowsUsd(whole + 1);
+	return `$${whole.toFixed(0).replace(/\B(?=(\d{3})+(?!\d))/g, ",")}.${String(cents).padStart(2, "0")}`;
+}
+function formatFlowsAge(lastSeenMs, now) {
+	if (lastSeenMs <= 0) return "at an unknown time";
+	const date = new Date(lastSeenMs).toISOString().slice(0, 10);
+	const days = Math.trunc((now.getTime() - lastSeenMs) / 864e5);
+	if (days < 1) return `${date} (less than a day ago)`;
+	if (days === 1) return `${date} (1 day ago)`;
+	return `${date} (${days} days ago)`;
+}
+/** The role word, with up to three address labels beside it. */
+function roleText(node) {
+	if (!node) return "other";
+	if (node.labels.length === 0) return node.role;
+	return `${node.role} (${node.labels.slice(0, 3).join(", ")})`;
+}
+function sideLines(title, parties) {
+	if (parties.length === 0) return [`${title}, newest first: none.`];
+	const lines = [`${title}, newest first (${parties.length}):`];
+	const perLine = parties.length > 6 ? 2 : 1;
+	for (let start = 0; start < parties.length; start += perLine) lines.push(`- ${parties.slice(start, start + perLine).join("; ")}`);
+	return lines;
+}
+/**
+* The text of a node answer: the centre, its role and lifetime totals, then
+* every counterparty of the view with its USD, transaction count and last-seen
+* date and age. At most FLOWS_SUMMARY_MAX_LINES lines.
+*/
+function flowsSummary(view, now) {
+	const nodes = new Map(view.nodes.map((node) => [node.address, node]));
+	const center = nodes.get(view.center);
+	const party = (address, edge) => `${address} ${roleText(nodes.get(address))}, ${formatFlowsUsd(edge.usd)} in ${edge.tx_count} tx, last seen ${formatFlowsAge(edge.last_seen_ms, now)}`;
+	const senders = [];
+	const receivers = [];
+	for (const edge of view.edges) if (edge.to === view.center) senders.push(party(edge.from, edge));
+	else receivers.push(party(edge.to, edge));
+	const body = [
+		`Money flows of ${view.center} on ${view.network}: ${roleText(center)}; lifetime ${formatFlowsUsd(center?.total_in_usd ?? 0)} in, ${formatFlowsUsd(center?.total_out_usd ?? 0)} out; ${center?.degree_in ?? 0} senders and ${center?.degree_out ?? 0} receivers in the topology graph.`,
+		...sideLines("Recent senders", senders),
+		...sideLines("Recent receivers", receivers)
+	].slice(0, 18);
+	const footer = pagingLines(view, senders.length, receivers.length, center);
+	return [...body, ...footer].join("\n");
+}
+/** Where this page sits, and that the picture loads the rest when an address is clicked. */
+function pagingLines(view, shownSenders, shownReceivers, center) {
+	const totalIn = center?.degree_in ?? 0;
+	const totalOut = center?.degree_out ?? 0;
+	const { in_offset: nextIn, out_offset: nextOut } = view.cursor;
+	const range = (shown, next, total) => shown === 0 ? `none of ${total}` : `${next - shown + 1} to ${next} of ${total}`;
+	const where = `Showing senders ${range(shownSenders, nextIn, totalIn)} and receivers ${range(shownReceivers, nextOut, totalOut)}, newest first.`;
+	if (!view.truncated && nextIn >= totalIn && nextOut >= totalOut) return [where];
+	return [where, "More senders and receivers load when an address in the picture is clicked."];
+}
+/** A finite number, or a decimal string read as one, or null. */
+function flowsNumberOrNull(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	return null;
+}
+function transferOf(row) {
+	const amount = typeof row.amount === "number" && Number.isFinite(row.amount) ? row.amount : typeof row.amount === "string" && row.amount.trim() !== "" ? row.amount : null;
+	return {
+		tx_id: typeof row.tx_id === "string" ? row.tx_id : "",
+		block_timestamp: flowsNumberOrNull(row.block_timestamp),
+		amount,
+		asset_symbol: typeof row.asset_symbol === "string" && row.asset_symbol !== "" ? row.asset_symbol : null,
+		amount_usd: flowsNumberOrNull(row.amount_usd)
+	};
+}
+/**
+* chain-insights.transfers.v1 from the rows of one facts read: newest first,
+* at most TRANSFERS_MAX, truncated when more rows than that came back. The
+* facts layer takes no ORDER BY, so the order is made here.
+*/
+function buildTransfersView(network, from, to, day, rows) {
+	const newestFirst = rows.map(transferOf).sort((a, b) => (b.block_timestamp ?? -Infinity) - (a.block_timestamp ?? -Infinity));
+	return {
+		schema: TRANSFERS_SCHEMA,
+		network,
+		from,
+		to,
+		day,
+		transfers: newestFirst.slice(0, 50),
+		truncated: newestFirst.length > 50
+	};
+}
+function transferLine(transfer) {
+	return `- ${transfer.block_timestamp === null ? "at an unknown time" : `${new Date(transfer.block_timestamp).toISOString().slice(0, 19).replace("T", " ")} UTC`}, ${transfer.amount === null ? "an unknown amount" : String(transfer.amount)}${transfer.asset_symbol ? ` ${transfer.asset_symbol}` : ""}, ${transfer.amount_usd === null ? "no USD price" : formatFlowsUsd(transfer.amount_usd)}, tx ${transfer.tx_id}`;
+}
+/** 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 rest = view.transfers.length - 5;
+	if (rest > 0) lines.push(`- and ${rest} more in the picture.`);
+	return lines.join("\n");
+}
+function errorResult$1(text) {
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		isError: true
+	};
+}
+function isRecord$1(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function answerText(answer) {
+	return (answer.content ?? []).map((block) => block.type === "text" && typeof block.text === "string" ? block.text : "").filter(Boolean).join("\n").trim();
+}
+/**
+* The refusal of a read that did not answer, naming its code first:
+* error_detail.code when the graph endpoint sent its typed refusal, the code
+* its text starts with otherwise, and graph_query_failed when it names none.
+* The view marks the address it was expanding.
+*/
+function refusalText(answer) {
+	const text = answerText(answer);
+	const detail = isRecord$1(answer.structuredContent) ? answer.structuredContent.error_detail : void 0;
+	const detailCode = isRecord$1(detail) && typeof detail.code === "string" ? detail.code : "";
+	const textCode = CODE_PREFIX.exec(text)?.[1] ?? "";
+	const code = detailCode || textCode || "graph_query_failed";
+	const rest = textCode === code ? text.replace(CODE_PREFIX, "") : text;
+	return rest ? `${code}: ${rest}` : `${code}: the graph endpoint refused the read`;
+}
+function rowsOf(answer) {
+	const facts = isRecord$1(answer.structuredContent) ? answer.structuredContent.facts : void 0;
+	const query = isRecord$1(facts) ? facts.query : void 0;
+	const results = isRecord$1(query) ? query.results : void 0;
+	return Array.isArray(results) ? results.filter(isRecord$1) : null;
+}
+function checkNetwork(args) {
+	const rawNetwork = typeof args.network === "string" ? args.network.trim().toLowerCase() : "";
+	if (!rawNetwork) return { error: "invalid_network: network is required; pass robinhood" };
+	if (rawNetwork !== "robinhood") return { error: `invalid_network: graph_expand reads the robinhood graph only; got "${String(args.network).trim()}"` };
+	return FLOWS_NETWORK;
+}
+/** The address of a node or of one end of a link; `name` says which end in a link refusal. */
+function checkAddress(raw, name) {
+	const address = normalizeFlowsAddress(raw);
+	if (address) return address;
+	return { error: name ? INVALID_ADDRESS_TEXT.replace("invalid_address:", `invalid_address (${name}):`) : INVALID_ADDRESS_TEXT };
+}
+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 checkOffset(value) {
+	if (value === void 0 || value === null) return 0;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0) return { error: OFFSET_NEGATIVE_TEXT };
+	if (value > 1e4) return { error: OFFSET_TOO_LARGE_TEXT };
+	return value;
+}
+/**
+* Read and answer one node page. The reads run one after another: the node
+* first, so an address the graph does not hold costs one read, not three; then
+* the receivers and the senders. The first read that does not answer ends the
+* call.
+*/
+async function runNode(deps, network, address, inOffset, outOffset) {
+	const unavailable = deps.unavailable?.();
+	if (unavailable) return errorResult$1(unavailable);
+	const rows = {};
+	for (const read of flowsReadsFor(address, inOffset, outOffset)) {
+		let answer;
+		try {
+			answer = await deps.graphQuery({
+				network,
+				query: read.query
+			});
+		} catch (err) {
+			return errorResult$1(deps.describeFailure(err));
+		}
+		if (answer.isError === true) return errorResult$1(refusalText(answer));
+		const found = rowsOf(answer);
+		if (!found) return errorResult$1("graph_query_failed: the graph endpoint answered without chain-insights.result.v1 rows");
+		rows[read.id] = found;
+		if (read.id === "node" && found.length === 0) return errorResult$1(`${address} is not in the ${network} topology graph`);
+	}
+	const view = buildFlowView(network, {
+		center: rows.node?.[0] ?? {},
+		senders: rows.in ?? [],
+		receivers: rows.out ?? [],
+		inOffset,
+		outOffset
+	});
+	return {
+		content: [{
+			type: "text",
+			text: flowsSummary(view, deps.now ? deps.now() : /* @__PURE__ */ new Date())
+		}],
+		structuredContent: view,
+		isError: false
+	};
+}
+/** Read and answer the transfers of one link on one day: a single facts read. */
+async function runLink(deps, network, from, to, day) {
+	const unavailable = deps.unavailable?.();
+	if (unavailable) return errorResult$1(unavailable);
+	let answer;
+	try {
+		answer = await deps.graphQuery({
+			network,
+			query: transfersReadFor(from, to, day)
+		});
+	} 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");
+	const view = buildTransfersView(network, from, to, day, rows);
+	return {
+		content: [{
+			type: "text",
+			text: transfersSummary(view)
+		}],
+		structuredContent: view,
+		isError: false
+	};
+}
+function given(record, keys) {
+	return keys.some((key) => record[key] !== void 0 && record[key] !== null);
+}
+/**
+* graph_expand, the node form {network, address, in_offset?, out_offset?} or the
+* link form {network, from, to, day}. Every argument is checked before the
+* first read.
+*/
+async function handleGraphExpand(args, deps) {
+	const record = isRecord$1(args) ? args : {};
+	const network = checkNetwork(record);
+	if (typeof network !== "string") return errorResult$1(network.error);
+	const isLink = given(record, [
+		"from",
+		"to",
+		"day"
+	]);
+	if (isLink && given(record, [
+		"address",
+		"in_offset",
+		"out_offset"
+	])) return errorResult$1(BOTH_FORMS_TEXT);
+	if (isLink) {
+		const from = checkAddress(record.from, "from");
+		if (typeof from !== "string") return errorResult$1(from.error);
+		const to = checkAddress(record.to, "to");
+		if (typeof to !== "string") return errorResult$1(to.error);
+		const day = checkDay(record.day);
+		if (typeof day !== "string") return errorResult$1(day.error);
+		return runLink(deps, network, from, to, day);
+	}
+	const address = checkAddress(record.address);
+	if (typeof address !== "string") return errorResult$1(address.error);
+	const inOffset = checkOffset(record.in_offset);
+	if (typeof inOffset !== "number") return errorResult$1(inOffset.error);
+	const outOffset = checkOffset(record.out_offset);
+	if (typeof outOffset !== "number") return errorResult$1(outOffset.error);
+	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 (12 a side, from the offsets); billed as three 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.";
+//#endregion
+//#region src/mcp/graph-schema-cache.ts
+/** How long a schema with a failed read stays fresh. */
+const PARTIAL_SCHEMA_TTL_MS = 6e5;
+function endpointHash(endpoint) {
+	return createHash("sha256").update(endpoint).digest("hex").slice(0, 12);
+}
+/** The cache file of a network on an endpoint. The network is an identifier already checked by the caller. */
+function graphSchemaCachePath(network, endpoint) {
+	return path.join(chainInsightsHome(), "cache", `schema-${network}-${endpointHash(endpoint)}.json`);
+}
+/**
+* The cached schema, marked cached, or null when there is none, it is stale, or
+* the file cannot be read. A cache is derived data: a damaged file is a miss and
+* the next build replaces it.
+*/
+async function loadGraphSchemaCache(network, endpoint, now) {
+	let parsed;
+	try {
+		parsed = JSON.parse(await readFile(graphSchemaCachePath(network, endpoint), "utf8"));
+	} catch {
+		return null;
+	}
+	const file = parsed;
+	if (!file || typeof file.cached_at !== "number" || file.endpoint !== endpoint || file.document?.schema !== "chain-insights.graph-schema.v1") return null;
+	const lifetime = file.complete === true ? CACHE_TTL_MS : PARTIAL_SCHEMA_TTL_MS;
+	const age = now.getTime() - file.cached_at;
+	if (age < 0 || age > lifetime) return null;
+	return {
+		...file.document,
+		cached: true
+	};
+}
+/** `network` is the name the caller asked for, the same one a later load asks with. */
+async function saveGraphSchemaCache(network, document, endpoint, complete, now) {
+	const target = graphSchemaCachePath(network, endpoint);
+	const file = {
+		cached_at: now.getTime(),
+		complete,
+		endpoint,
+		document: {
+			...document,
+			cached: false
+		}
+	};
+	await mkdir(path.dirname(target), { recursive: true });
+	const scratch = `${target}.${process.pid}.tmp`;
+	await writeFile(scratch, JSON.stringify(file, null, 2) + "\n", { mode: 384 });
+	await rename(scratch, target);
+}
+//#endregion
+//#region src/mcp/graph-schema.ts
+/**
+* meta_schema: the live graph schema of one network, read from the graph
+* endpoint and kept on disk for 24 hours.
+*
+* The graph serves four read-only catalog statements on `USE topology` through
+* the ordinary graph_query tool: `CALL db.labels()`, `CALL db.relationshipTypes()`,
+* `CALL db.propertyKeys()` and `SHOW INDEXES`. They name the labels, the link
+* types, every property key and the indexes. They do not say which keys belong to
+* which kind, so the main kinds are sampled with the two probe forms the server
+* admits (`keys(a)` on addresses, `keys(r)` on a link). The facts relationships
+* and the chain lookups come from the network's published capabilities.
+*
+* One build is one MCP session and runs its reads one after another: the public
+* endpoint allows about 30 requests a minute for each IP address, and opening a
+* session costs three of them. A read that fails leaves its section empty and
+* adds a note. It never fails the tool.
+*/
+var graph_schema_exports = /* @__PURE__ */ __exportAll({
+	ADDRESS_SAMPLE_LIMIT: () => 20,
+	FACTS_TRANSFER_COLUMNS: () => FACTS_TRANSFER_COLUMNS,
+	GRAPH_SCHEMA_ID: () => GRAPH_SCHEMA_ID,
+	GRAPH_SCHEMA_SOURCE: () => GRAPH_SCHEMA_SOURCE,
+	GraphSchemaError: () => GraphSchemaError,
+	LINK_SAMPLE_LIMIT: () => 5,
+	META_SCHEMA_DESCRIPTION: () => META_SCHEMA_DESCRIPTION,
+	META_SCHEMA_TITLE: () => META_SCHEMA_TITLE,
+	SAMPLED_LINK_TYPES: () => SAMPLED_LINK_TYPES,
+	addressSampleQuery: () => addressSampleQuery,
+	buildGraphSchema: () => buildGraphSchema,
+	formatGraphSchemaText: () => formatGraphSchemaText,
+	getGraphSchema: () => getGraphSchema,
+	handleMetaSchema: () => handleMetaSchema,
+	linkSampleQuery: () => linkSampleQuery,
+	normalizeSchemaNetwork: () => normalizeSchemaNetwork
+});
+const GRAPH_SCHEMA_ID = "chain-insights.graph-schema.v1";
+const GRAPH_SCHEMA_SOURCE = "live catalog";
+const META_SCHEMA_TITLE = "Graph schema";
+const META_SCHEMA_DESCRIPTION = "Return the live graph schema of one network: the labels, the link types, the field names of an address and of each main link, the indexes, the USE facts relationships with the TRANSFER columns, and the USE chain lookups. Call it first when you need field names. It is cached for 24 hours; pass refresh=true to rebuild it.";
+/** The link types an agent queries. Each is sampled only when the graph lists it. */
+const SAMPLED_LINK_TYPES = [
+	"FLOWS_TO",
+	"OPERATED_BY",
+	"LINKED",
+	"SWAPPED",
+	"BRIDGED",
+	"ADDED_LIQUIDITY",
+	"REMOVED_LIQUIDITY"
+];
+const FACTS_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",
+	"decimals"
+];
+const CATALOG_READS = {
+	labels: {
+		label: "labels",
+		query: "USE topology CALL db.labels()"
+	},
+	linkTypes: {
+		label: "link types",
+		query: "USE topology CALL db.relationshipTypes()"
+	},
+	propertyKeys: {
+		label: "property keys",
+		query: "USE topology CALL db.propertyKeys()"
+	},
+	indexes: {
+		label: "indexes",
+		query: "USE topology SHOW INDEXES"
+	}
+};
+function addressSampleQuery() {
+	return `USE topology MATCH (a:Address) RETURN keys(a) AS keys LIMIT 20`;
+}
+function linkSampleQuery(linkType) {
+	return `USE topology MATCH ()-[r:${linkType}]->() RETURN keys(r) AS keys LIMIT 5`;
+}
+/** A refusal with its own words for the caller: a bad argument, an unserved network, an endpoint that is down. */
+var GraphSchemaError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "GraphSchemaError";
+	}
+};
+function isRecord(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function sortedUnique(values) {
+	return [...new Set(values)].sort();
+}
+function stringList(value) {
+	return Array.isArray(value) ? value.filter((entry) => typeof entry === "string" && entry !== "") : [];
+}
+const NETWORK_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/**
+* The network as a lower-case identifier. It becomes part of a file name and of
+* every query, so only an identifier passes.
+*/
+function normalizeSchemaNetwork(raw) {
+	const network = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+	if (!network) throw new GraphSchemaError("invalid_network: network is required. Pass the identifier of a served network, for example robinhood.");
+	if (!NETWORK_PATTERN.test(network)) throw new GraphSchemaError(`invalid_network: "${String(raw).trim()}" is not a network identifier. Pass the identifier of a served network, for example robinhood.`);
+	return network;
+}
+function queryBlock(structured) {
+	const facts = isRecord(structured) ? structured.facts : void 0;
+	const query = isRecord(facts) ? facts.query : void 0;
+	return isRecord(query) ? query : null;
+}
+/** The `facts.query` block of one graph_query reply, from structuredContent or from the JSON text. */
+function answerQuery(answer) {
+	const fromStructured = queryBlock(answer.structuredContent);
+	if (fromStructured) return fromStructured;
+	for (const block of answer.content ?? []) {
+		if (block.type !== "text" || typeof block.text !== "string") continue;
+		try {
+			const parsed = queryBlock(JSON.parse(block.text));
+			if (parsed) return parsed;
+		} catch {}
+	}
+	return null;
+}
+function haltOfError(err) {
+	if (err instanceof PaymentRequiredError) return "payment";
+	const code = isRecord(err) ? err.code : void 0;
+	const message = err instanceof Error ? err.message : String(err);
+	if (code === 429 || /\b429\b|too many requests|rate.?limit/i.test(message)) return "rate_limit";
+	if (/\b402\b|payment required/i.test(message)) return "payment";
+}
+function haltOfAnswer(answer) {
+	const detail = isRecord(answer.structuredContent) ? answer.structuredContent.error_detail : void 0;
+	return isRecord(detail) && detail.class === "capacity" ? "rate_limit" : void 0;
+}
+function describeIndex(row) {
+	const name = typeof row.name === "string" ? row.name : "";
+	const entity = row.entityType === "NODE" ? "node" : row.entityType === "RELATIONSHIP" ? "link" : null;
+	const properties = stringList(row.properties);
+	if (!name || !entity || properties.length === 0) return null;
+	return {
+		name,
+		entity,
+		types: stringList(row.labelsOrTypes),
+		properties,
+		state: typeof row.state === "string" && row.state ? row.state : "unknown"
+	};
+}
+async function buildGraphSchema(options) {
+	const { client } = options;
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	const pauseMs = options.pauseMs ?? 0;
+	const sleep = options.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+	const problems = [];
+	const remarks = [];
+	let billed = 0;
+	let calls = 0;
+	let halted = false;
+	async function pace() {
+		if (calls > 0 && pauseMs > 0) await sleep(pauseMs);
+		calls += 1;
+	}
+	function fail(label, reason, halt) {
+		problems.push(`${label} could not be read: ${reason}`);
+		if (halt && !halted) {
+			halted = true;
+			if (halt === "payment") problems.push("The endpoint asks for payment, so the reads after it were not sent. Fix the payment setup, then call again with refresh=true.");
+			else {
+				const wait = /retry after (\d+) seconds?/i.exec(reason)?.[1];
+				problems.push(`The endpoint is limiting requests, so the reads after it were not sent. Call again after ${wait ? `${wait} seconds` : "a minute"} with refresh=true.`);
+			}
+		}
+		return null;
+	}
+	async function graphRead(network, label, query) {
+		if (halted) return null;
+		await pace();
+		let answer;
+		try {
+			answer = await client.callTool({
+				name: "graph_query",
+				arguments: {
+					network,
+					query
+				}
+			});
+		} catch (err) {
+			return fail(label, err instanceof Error ? err.message : String(err), haltOfError(err));
+		}
+		const block = answerQuery(answer ?? {});
+		if (block && typeof block.billable_units === "number") billed += block.billable_units;
+		if (answer?.isError === true) return fail(label, refusalText(answer), haltOfAnswer(answer));
+		if (!block || !Array.isArray(block.results)) return fail(label, "the reply holds no rows");
+		return block.results.filter(isRecord);
+	}
+	let network = options.network;
+	let capability;
+	await pace();
+	try {
+		const answer = await client.callTool({
+			name: "network_capabilities",
+			arguments: {}
+		});
+		if (answer?.isError === true) fail("network capabilities", refusalText(answer), haltOfAnswer(answer));
+		else {
+			const facts = isRecord(answer?.structuredContent) ? answer.structuredContent.facts : void 0;
+			const capabilities = isRecord(facts) ? facts.capabilities : void 0;
+			const networks = isRecord(capabilities) && Array.isArray(capabilities.networks) ? capabilities.networks : null;
+			if (!networks) fail("network capabilities", "the reply lists no networks");
+			else {
+				const document = mirrorGraphNetworkCapabilities({ networks });
+				capability = findNetworkCapability(document, options.network);
+				if (!capability) {
+					const served = document.networks.map((entry) => entry.network).join(", ");
+					throw new GraphSchemaError(`network_not_served: "${options.network}" is not a network this endpoint serves. Served networks: ${served || "none"}.`);
+				}
+				network = capability.network;
+			}
+		}
+	} catch (err) {
+		if (err instanceof GraphSchemaError) throw err;
+		fail("network capabilities", err instanceof Error ? err.message : String(err), haltOfError(err));
+	}
+	const topology = {
+		labels: [],
+		link_types: [],
+		property_keys: [],
+		indexes: [],
+		samples: {}
+	};
+	if (capability?.layers?.topology?.enabled === false) remarks.push("The topology layer is off on this network.");
+	else {
+		const labels = await graphRead(network, CATALOG_READS.labels.label, CATALOG_READS.labels.query);
+		if (labels) topology.labels = sortedUnique(labels.flatMap((row) => stringList([row.label])));
+		const linkTypes = await graphRead(network, CATALOG_READS.linkTypes.label, CATALOG_READS.linkTypes.query);
+		if (linkTypes) topology.link_types = sortedUnique(linkTypes.flatMap((row) => stringList([row.relationshipType])));
+		const keys = await graphRead(network, CATALOG_READS.propertyKeys.label, CATALOG_READS.propertyKeys.query);
+		if (keys) topology.property_keys = sortedUnique(keys.flatMap((row) => stringList([row.propertyKey])));
+		const indexes = await graphRead(network, CATALOG_READS.indexes.label, CATALOG_READS.indexes.query);
+		if (indexes) topology.indexes = indexes.map(describeIndex).filter((index) => index !== null).sort((a, b) => a.name.localeCompare(b.name));
+		if (!(labels !== null) || topology.labels.includes("Address")) {
+			const rows = await graphRead(network, "the Address sample", addressSampleQuery());
+			if (rows) topology.samples["Address"] = unionOfKeys(rows);
+		}
+		const sampled = SAMPLED_LINK_TYPES.filter((type) => topology.link_types.includes(type));
+		if (linkTypes === null && !halted) problems.push("The link samples were skipped: the link types are unknown.");
+		for (const type of sampled) {
+			const rows = await graphRead(network, `the ${type} sample`, linkSampleQuery(type));
+			if (rows) topology.samples[type] = unionOfKeys(rows);
+		}
+		const unsampled = topology.link_types.filter((type) => !SAMPLED_LINK_TYPES.includes(type));
+		if (unsampled.length > 0) remarks.push(`Link types with no sample: ${unsampled.join(", ")}. Read the keys of one with USE topology MATCH ()-[r:<TYPE>]->() RETURN keys(r) AS keys LIMIT 5.`);
+	}
+	const facts = {
+		relationships: [],
+		transfer_columns: []
+	};
+	const chain = { lookups: [] };
+	if (capability) {
+		if (capability.layers?.facts?.enabled === false) remarks.push("The facts layer is off on this network.");
+		else {
+			facts.relationships = stringList(capability.layers?.facts?.relationships);
+			if (facts.relationships.includes("TRANSFER")) facts.transfer_columns = [...FACTS_TRANSFER_COLUMNS];
+		}
+		const admission = capability.chain_admission;
+		if (admission?.enabled === false) remarks.push(`The chain layer is off (status ${admission.status ?? "unknown"}).`);
+		else chain.lookups = stringList(admission?.lookups);
+	}
+	const words = [...topology.property_keys, ...Object.values(topology.samples).flat()];
+	if (words.includes("synced_through_height") || words.includes("pair_key")) remarks.push("synced_through_height and pair_key are sync bookkeeping: never filter or sort on them.");
+	remarks.push("Fields come from a sample of the live graph. A rare field may be missing.");
+	return {
+		complete: problems.length === 0,
+		document: {
+			schema: GRAPH_SCHEMA_ID,
+			network,
+			built_at: now().toISOString(),
+			source: GRAPH_SCHEMA_SOURCE,
+			cached: false,
+			billed_units: billed,
+			layers: {
+				topology,
+				facts,
+				chain
+			},
+			notes: [...problems, ...remarks]
+		}
+	};
+}
+function unionOfKeys(rows) {
+	return sortedUnique(rows.flatMap((row) => stringList(row.keys)));
+}
+const building = /* @__PURE__ */ new Map();
+async function getGraphSchema(options) {
+	const network = normalizeSchemaNetwork(options.network);
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	if (options.refresh !== true) {
+		const cached = await loadGraphSchemaCache(network, options.endpoint, now());
+		if (cached) return cached;
+	}
+	const key = `${options.endpoint}\n${network}`;
+	const running = building.get(key);
+	if (running) return running;
+	const build = (async () => {
+		const { document, complete } = await options.withClient((client) => buildGraphSchema({
+			client,
+			network,
+			now,
+			...options.pauseMs === void 0 ? {} : { pauseMs: options.pauseMs },
+			...options.sleep ? { sleep: options.sleep } : {}
+		}));
+		try {
+			await saveGraphSchemaCache(network, document, options.endpoint, complete, now());
+		} catch (err) {
+			document.notes.push(`The schema could not be saved to the cache: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		return document;
+	})();
+	building.set(key, build);
+	try {
+		return await build;
+	} finally {
+		building.delete(key);
+	}
+}
+function listLine(title, values, empty = "none read") {
+	return `${title}: ${values.length > 0 ? values.join(", ") : empty}`;
+}
+/** The schema as the model and the terminal read it. */
+function formatGraphSchemaText(document) {
+	const { topology, facts, chain } = document.layers;
+	const origin = document.cached ? "from the cache, kept 24 hours; refresh=true rebuilds it" : `read now for ${document.billed_units} billed units and cached for 24 hours`;
+	const lines = [
+		`Graph schema, network ${document.network}`,
+		`Source: ${document.source}, built ${document.built_at} (${origin})`,
+		"",
+		"USE topology",
+		listLine("Labels", topology.labels),
+		listLine("Link types", topology.link_types),
+		listLine(`Property keys (${topology.property_keys.length})`, topology.property_keys)
+	];
+	lines.push(topology.indexes.length > 0 ? "Indexes:" : "Indexes: none read");
+	for (const index of topology.indexes) lines.push(`- ${index.entity} ${index.types.join("|")}(${index.properties.join(", ")}) ${index.state}`);
+	const sampled = Object.entries(topology.samples);
+	lines.push(sampled.length > 0 ? "Fields, from a sample:" : "Fields, from a sample: none read");
+	for (const [kind, fields] of sampled) lines.push(`- ${kind}: ${fields.join(", ")}`);
+	lines.push("", "USE facts", listLine("Relationships", facts.relationships), listLine("TRANSFER columns", facts.transfer_columns), "", "USE chain", listLine("Lookups", chain.lookups));
+	if (document.notes.length > 0) lines.push("", "Notes:", ...document.notes.map((note) => `- ${note}`));
+	return lines.join("\n");
+}
+function errorResult(text) {
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		isError: true
+	};
+}
+/** meta_schema, {network, refresh?}. Every argument is checked before the first read. */
+async function handleMetaSchema(args, deps) {
+	const record = isRecord(args) ? args : {};
+	const refresh = record.refresh;
+	if (refresh !== void 0 && refresh !== null && typeof refresh !== "boolean") return errorResult("invalid_refresh: refresh must be true or false");
+	try {
+		const document = await getGraphSchema({
+			network: record.network,
+			refresh: refresh === true,
+			endpoint: deps.endpoint,
+			withClient: deps.withClient,
+			...deps.now ? { now: deps.now } : {},
+			...deps.pauseMs === void 0 ? {} : { pauseMs: deps.pauseMs },
+			...deps.sleep ? { sleep: deps.sleep } : {}
+		});
+		return {
+			content: [{
+				type: "text",
+				text: formatGraphSchemaText(document)
+			}],
+			structuredContent: document,
+			isError: false
+		};
+	} catch (err) {
+		return errorResult(err instanceof GraphSchemaError ? err.message : deps.describeFailure(err));
+	}
+}
+//#endregion
+export { handleMetaSchema as a, GRAPH_EXPAND_TITLE as c, graph_schema_exports as i, GRAPH_EXPAND_TOOL as l, META_SCHEMA_DESCRIPTION as n, FLOWS_MAX_OFFSET as o, META_SCHEMA_TITLE as r, GRAPH_EXPAND_DESCRIPTION as s, GraphSchemaError as t, handleGraphExpand as u };
+
+//# sourceMappingURL=graph-schema-D1orCe5F.mjs.map