chain-insights 0.2.20 → 0.2.23

package/README.md

@@ -4,12 +4,11 @@
 
 Chain Insights is an open-source AML investigation toolkit for AI agents and
 analysts. Install it from npm to screen blockchain addresses, trace funds,
-expand scam topologies, manage case evidence, and generate graph reports from
-Chain Insights graph intelligence.
+expand scam topologies, manage case evidence, and generate graph reports.
 
-The hosted GraphRAG MCP access path is paid through x402. The CLI and MCP proxy
-handle local wallet status, paid graph calls, approved test access, case files,
-evidence pointers, dossiers, and reports.
+Graph access is configuration-driven. The package defaults to a local GraphRAG
+MCP endpoint for development; hosted endpoints are set explicitly with
+`graphMcpEndpoint` or `CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT`.
 
 ## What You Can Do Today
 
@@ -53,26 +52,32 @@ cd ./chain-insights-investigations
 cia init .
 ```
 
-## Configure MCP server address
+## Configure GraphRAG MCP Endpoint
 
-`cia` uses `graphMcpEndpoint` for all GraphRAG MCP calls. Configure it explicitly per environment.
+`cia` uses `graphMcpEndpoint` for all GraphRAG MCP calls. The npm package does
+not hardcode a hosted endpoint. Configure the endpoint explicitly for the
+environment you intend to use.
 
-1. Local GraphRAG MCP (loopback HTTP allowed):
+Local development endpoint (default):
 
 ```bash
 cia config set graphMcpEndpoint http://127.0.0.1:8012/mcp
 ```
 
-2. Hosted staging/production GraphRAG MCP (HTTPS required):
+Hosted staging endpoint for approved testers:
 
 ```bash
 cia config set graphMcpEndpoint https://staging-mcp.chain-insights.ai/mcp
 ```
 
-3. Optional one-shot override from environment (highest precedence for that process):
+Hosted access also needs an access mode, such as an approved access key or a
+prepared wallet. Keep those credentials out of README examples; setup commands
+live in [MCP proxy](docs/mcp-proxy.md).
+
+Optional one-shot override from the environment:
 
 ```bash
-export CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT=https://prod-mcp.example.com/mcp
+export CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT=https://staging-mcp.chain-insights.ai/mcp
 ```
 
 Validation rules:
@@ -91,15 +96,13 @@ Check the configured endpoint and current GraphRAG MCP capabilities:
 
 ```bash
 cia config get graphMcpEndpoint
-cia wallet balance
 cia mcp networks
 cia mcp tools --refresh
 ```
 
-GraphRAG MCP calls use x402 paid mode by default unless you configure approved
-test access or local debug access. If network or tool discovery fails, fix
-endpoint/auth/payment first; the CLI can still initialize workspaces and manage
-cases without a reachable GraphRAG MCP endpoint.
+If network or tool discovery fails, check the endpoint and access mode first.
+The CLI can still initialize workspaces and manage cases without a reachable
+GraphRAG MCP endpoint.
 
 Open a case and run a small investigation:
 
@@ -175,7 +178,8 @@ Graph queries must choose the right read layer explicitly:
 | `facts` | Labels, features, risk scores, assets, and enrichment |
 
 Use `graph_query_batch` when related reads should share one call and one
-result envelope. Paid hosted calls are settled through x402.
+result envelope. Endpoint access and authentication are configured separately;
+see [MCP proxy](docs/mcp-proxy.md).
 
 ## AML Tools
 
@@ -201,7 +205,7 @@ reports under the workspace instead of embedding large payloads in case notes.
 | --- | --- |
 | [Graph tools](docs/graph-tools.md) | GraphRAG MCP layers, `graph_query`, `graph_query_batch`, AML tool contracts, graph reports, evidence pointers |
 | [Investigation workspaces](docs/investigation-workspaces.md) | `cia init`, case layout, evidence, dossiers, imports, templates, sessions, reports |
-| [MCP proxy](docs/mcp-proxy.md) | Stdio proxy behavior, agent installers, local tools, auth modes, Inspector validation |
+| [MCP proxy](docs/mcp-proxy.md) | Stdio proxy behavior, endpoint configuration, agent installers, local tools, auth modes, Inspector validation |
 | [Architecture](docs/architecture.md) | Product layers, data flow, local storage, security model, config keys |
 | [Development](docs/development.md) | Build, test, and local install commands |
 | [Contributing](docs/contributing.md) | Development workflow, pull requests, release expectations |

package/dist/cli.cjs

@@ -378,7 +378,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 				}));
 				return;
 			}
-			const { addressRisk } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+			const { addressRisk } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 			const result = await addressRisk(client, {
 				address: opts.address,
 				network: opts.network,
@@ -406,7 +406,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 				}));
 				return;
 			}
-			const { trackFunds } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+			const { trackFunds } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 			const caseId = opts.case ? await resolveCaseSelector(opts.case) : void 0;
 			const result = await trackFunds(client, config, {
 				trustedAddresses: opts.trustedAddresses,
@@ -429,7 +429,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 		const { requireWorkspaceRoot } = await Promise.resolve().then(() => require("./output-root-YIbl6PwF.cjs")).then((n) => n.output_root_exports);
 		requireWorkspaceRoot();
 		await withGraphMcpClient("chain-insights-cli-scam-topology", async (client, config) => {
-			const { scamTopology } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+			const { scamTopology } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 			const incidentTimestampMs = optionalNumber(opts.incidentTimestampMs);
 			if (incidentTimestampMs === void 0) throw new Error("incident-timestamp-ms is required");
 			const caseId = opts.case ? await resolveCaseSelector(opts.case) : void 0;
@@ -451,7 +451,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 })).addCommand(new commander.Command("stake-insights").description("Explain Bittensor staking behavior around an address, coldkey, or hotkey").requiredOption("--network <network>", "Network to query. Run `cia mcp networks` for supported networks.").option("--address <address>", "Full Bittensor address to inspect as either coldkey or hotkey").option("--coldkey <address>", "Full Bittensor coldkey address to inspect").option("--hotkey <address>", "Full Bittensor hotkey address to inspect").option("--netuid <number>", "Optional subnet netuid filter").option("--start-timestamp-ms <milliseconds>", "Optional inclusive lower activity timestamp bound").option("--end-timestamp-ms <milliseconds>", "Optional inclusive upper activity timestamp bound").option("--start-block <number>", "Optional start block. Current stake graph parity may require timestamp windows instead.").option("--end-block <number>", "Optional end block. Current stake graph parity may require timestamp windows instead.").option("--depth <number>", "Optional expansion depth limit, default 1, max 3").action(async (opts) => {
 	try {
 		await withGraphMcpClient("chain-insights-cli-stake-insights", async (client) => {
-			const { stakeInsights } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+			const { stakeInsights } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 			const result = await stakeInsights(client, {
 				network: opts.network,
 				address: opts.address,
@@ -479,7 +479,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 		assertPublicMcpToolName(tool);
 		await withGraphMcpClient("chain-insights-cli-call", async (client, config) => {
 			if (tool === "address_risk") {
-				const { addressRisk } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+				const { addressRisk } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 				const result = await addressRisk(client, {
 					address: String(args["address"] ?? ""),
 					network: String(args["network"] ?? ""),
@@ -489,7 +489,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 				return;
 			}
 			if (tool === "track_funds") {
-				const { trackFunds } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+				const { trackFunds } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 				const result = await trackFunds(client, config, {
 					trustedAddresses: args["trusted_addresses"] ?? "",
 					untrustedAddresses: args["untrusted_addresses"],
@@ -504,7 +504,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 				return;
 			}
 			if (tool === "scam_topology") {
-				const { scamTopology } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+				const { scamTopology } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 				const victimAddress = String(args["victim_address"] ?? "").trim();
 				if (!victimAddress) throw new Error("victim_address is required");
 				const incidentTimestampMs = optionalNumberArg(args["incident_timestamp_ms"], "incident_timestamp_ms");
@@ -522,7 +522,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 				return;
 			}
 			if (tool === "stake_insights") {
-				const { stakeInsights } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+				const { stakeInsights } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 				const result = await stakeInsights(client, {
 					network: String(args["network"] ?? ""),
 					address: args["address"] === void 0 ? void 0 : String(args["address"]),

package/dist/cli.mjs

@@ -376,7 +376,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 				}));
 				return;
 			}
-			const { addressRisk } = await import("./public-tools-B13J0MJZ.mjs");
+			const { addressRisk } = await import("./public-tools-w7En2m3q.mjs");
 			const result = await addressRisk(client, {
 				address: opts.address,
 				network: opts.network,
@@ -404,7 +404,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 				}));
 				return;
 			}
-			const { trackFunds } = await import("./public-tools-B13J0MJZ.mjs");
+			const { trackFunds } = await import("./public-tools-w7En2m3q.mjs");
 			const caseId = opts.case ? await resolveCaseSelector(opts.case) : void 0;
 			const result = await trackFunds(client, config, {
 				trustedAddresses: opts.trustedAddresses,
@@ -427,7 +427,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 		const { requireWorkspaceRoot } = await import("./output-root-BRhzhhXZ.mjs").then((n) => n.t);
 		requireWorkspaceRoot();
 		await withGraphMcpClient("chain-insights-cli-scam-topology", async (client, config) => {
-			const { scamTopology } = await import("./public-tools-B13J0MJZ.mjs");
+			const { scamTopology } = await import("./public-tools-w7En2m3q.mjs");
 			const incidentTimestampMs = optionalNumber(opts.incidentTimestampMs);
 			if (incidentTimestampMs === void 0) throw new Error("incident-timestamp-ms is required");
 			const caseId = opts.case ? await resolveCaseSelector(opts.case) : void 0;
@@ -449,7 +449,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 })).addCommand(new Command("stake-insights").description("Explain Bittensor staking behavior around an address, coldkey, or hotkey").requiredOption("--network <network>", "Network to query. Run `cia mcp networks` for supported networks.").option("--address <address>", "Full Bittensor address to inspect as either coldkey or hotkey").option("--coldkey <address>", "Full Bittensor coldkey address to inspect").option("--hotkey <address>", "Full Bittensor hotkey address to inspect").option("--netuid <number>", "Optional subnet netuid filter").option("--start-timestamp-ms <milliseconds>", "Optional inclusive lower activity timestamp bound").option("--end-timestamp-ms <milliseconds>", "Optional inclusive upper activity timestamp bound").option("--start-block <number>", "Optional start block. Current stake graph parity may require timestamp windows instead.").option("--end-block <number>", "Optional end block. Current stake graph parity may require timestamp windows instead.").option("--depth <number>", "Optional expansion depth limit, default 1, max 3").action(async (opts) => {
 	try {
 		await withGraphMcpClient("chain-insights-cli-stake-insights", async (client) => {
-			const { stakeInsights } = await import("./public-tools-B13J0MJZ.mjs");
+			const { stakeInsights } = await import("./public-tools-w7En2m3q.mjs");
 			const result = await stakeInsights(client, {
 				network: opts.network,
 				address: opts.address,
@@ -477,7 +477,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 		assertPublicMcpToolName(tool);
 		await withGraphMcpClient("chain-insights-cli-call", async (client, config) => {
 			if (tool === "address_risk") {
-				const { addressRisk } = await import("./public-tools-B13J0MJZ.mjs");
+				const { addressRisk } = await import("./public-tools-w7En2m3q.mjs");
 				const result = await addressRisk(client, {
 					address: String(args["address"] ?? ""),
 					network: String(args["network"] ?? ""),
@@ -487,7 +487,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 				return;
 			}
 			if (tool === "track_funds") {
-				const { trackFunds } = await import("./public-tools-B13J0MJZ.mjs");
+				const { trackFunds } = await import("./public-tools-w7En2m3q.mjs");
 				const result = await trackFunds(client, config, {
 					trustedAddresses: args["trusted_addresses"] ?? "",
 					untrustedAddresses: args["untrusted_addresses"],
@@ -502,7 +502,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 				return;
 			}
 			if (tool === "scam_topology") {
-				const { scamTopology } = await import("./public-tools-B13J0MJZ.mjs");
+				const { scamTopology } = await import("./public-tools-w7En2m3q.mjs");
 				const victimAddress = String(args["victim_address"] ?? "").trim();
 				if (!victimAddress) throw new Error("victim_address is required");
 				const incidentTimestampMs = optionalNumberArg(args["incident_timestamp_ms"], "incident_timestamp_ms");
@@ -520,7 +520,7 @@ program.command("mcp").description("Interact with the Chain Insights MCP endpoin
 				return;
 			}
 			if (tool === "stake_insights") {
-				const { stakeInsights } = await import("./public-tools-B13J0MJZ.mjs");
+				const { stakeInsights } = await import("./public-tools-w7En2m3q.mjs");
 				const result = await stakeInsights(client, {
 					network: String(args["network"] ?? ""),
 					address: args["address"] === void 0 ? void 0 : String(args["address"]),

package/dist/mcp-proxy.cjs

@@ -995,7 +995,7 @@ async function createProxy() {
 				}],
 				isError: true
 			};
-			const { addressRisk } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+			const { addressRisk } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 			const { writeGraphReport } = await Promise.resolve().then(() => require("./graph-reports-B3mkLP8Z.cjs"));
 			const { ensureArtifactServer } = await Promise.resolve().then(() => require("./artifact-server-XbN16DwU.cjs"));
 			const result = await addressRisk(remoteClient, {
@@ -1066,7 +1066,7 @@ async function createProxy() {
 				}],
 				isError: true
 			};
-			const { trackFunds } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+			const { trackFunds } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 			const { writeGraphReport } = await Promise.resolve().then(() => require("./graph-reports-B3mkLP8Z.cjs"));
 			const { ensureArtifactServer } = await Promise.resolve().then(() => require("./artifact-server-XbN16DwU.cjs"));
 			const result = await trackFunds(remoteClient, config, {
@@ -1139,7 +1139,7 @@ async function createProxy() {
 				}],
 				isError: true
 			};
-			const { scamTopology } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+			const { scamTopology } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 			const { writeGraphReport } = await Promise.resolve().then(() => require("./graph-reports-B3mkLP8Z.cjs"));
 			const { ensureArtifactServer } = await Promise.resolve().then(() => require("./artifact-server-XbN16DwU.cjs"));
 			const result = await scamTopology(remoteClient, config, {
@@ -1216,7 +1216,7 @@ async function createProxy() {
 				}],
 				isError: true
 			};
-			const { stakeInsights } = await Promise.resolve().then(() => require("./public-tools-BC1fi0DV.cjs"));
+			const { stakeInsights } = await Promise.resolve().then(() => require("./public-tools-q4NMdmDX.cjs"));
 			const { writeGraphReport } = await Promise.resolve().then(() => require("./graph-reports-B3mkLP8Z.cjs"));
 			const { ensureArtifactServer } = await Promise.resolve().then(() => require("./artifact-server-XbN16DwU.cjs"));
 			const result = await stakeInsights(remoteClient, {

package/dist/mcp-proxy.mjs

@@ -991,7 +991,7 @@ async function createProxy() {
 				}],
 				isError: true
 			};
-			const { addressRisk } = await import("./public-tools-B13J0MJZ.mjs");
+			const { addressRisk } = await import("./public-tools-w7En2m3q.mjs");
 			const { writeGraphReport } = await import("./graph-reports-BDELxmpi.mjs");
 			const { ensureArtifactServer } = await import("./artifact-server-CP6LXQ9d.mjs");
 			const result = await addressRisk(remoteClient, {
@@ -1062,7 +1062,7 @@ async function createProxy() {
 				}],
 				isError: true
 			};
-			const { trackFunds } = await import("./public-tools-B13J0MJZ.mjs");
+			const { trackFunds } = await import("./public-tools-w7En2m3q.mjs");
 			const { writeGraphReport } = await import("./graph-reports-BDELxmpi.mjs");
 			const { ensureArtifactServer } = await import("./artifact-server-CP6LXQ9d.mjs");
 			const result = await trackFunds(remoteClient, config, {
@@ -1135,7 +1135,7 @@ async function createProxy() {
 				}],
 				isError: true
 			};
-			const { scamTopology } = await import("./public-tools-B13J0MJZ.mjs");
+			const { scamTopology } = await import("./public-tools-w7En2m3q.mjs");
 			const { writeGraphReport } = await import("./graph-reports-BDELxmpi.mjs");
 			const { ensureArtifactServer } = await import("./artifact-server-CP6LXQ9d.mjs");
 			const result = await scamTopology(remoteClient, config, {
@@ -1212,7 +1212,7 @@ async function createProxy() {
 				}],
 				isError: true
 			};
-			const { stakeInsights } = await import("./public-tools-B13J0MJZ.mjs");
+			const { stakeInsights } = await import("./public-tools-w7En2m3q.mjs");
 			const { writeGraphReport } = await import("./graph-reports-BDELxmpi.mjs");
 			const { ensureArtifactServer } = await import("./artifact-server-CP6LXQ9d.mjs");
 			const result = await stakeInsights(remoteClient, {

package/dist/{public-tools-BC1fi0DV.cjs → public-tools-q4NMdmDX.cjs}

@@ -1011,11 +1011,87 @@ function isExchangeFlag(value) {
 	if (typeof value === "number") return value === 1;
 	return false;
 }
+/**
+* Address-type values that mark a node as part of the scam topology itself
+* (a written scam label or the protected victim role). Such nodes must never be
+* read back as exchange infrastructure, even when their label text contains a
+* brand or the word "exchange" — that text is our own output syncing back into
+* the graph, not authoritative exchange signal.
+*/
+const NON_EXCHANGE_ADDRESS_TYPES = new Set(["scam", "victim"]);
+/**
+* Determine whether a node's `address_type` marks it as scam- or victim-typed,
+* which disqualifies it from being treated as an exchange endpoint.
+*
+* @param addressType - The node's `address_type` property, if present.
+* @returns `true` when the type is a scam/victim role.
+*/
+function isScamOrVictimType(addressType) {
+	if (addressType === void 0) return false;
+	return NON_EXCHANGE_ADDRESS_TYPES.has(addressType.trim().toLowerCase());
+}
+/**
+* Detect an authoritative exchange label.
+*
+* Only an exact `exchange` token or a trailing `, exchange` registry suffix
+* (e.g. `"Binance, exchange"`) counts. Loose substring matching such as
+* `includes('exchange')` is deliberately rejected because scam labels written
+* by this tool (e.g. `"... -> Kucoin"`, subtype text containing "exchange")
+* sync back into the graph and would otherwise be mis-read as exchanges.
+*
+* @param labels - Node label strings from the graph.
+* @returns `true` when at least one label is an authoritative exchange marker.
+*/
 function hasExchangeLabel(labels) {
-	return labels.some((label) => label.toLowerCase() === "exchange" || label.toLowerCase().includes("exchange"));
+	return labels.some((label) => {
+		const normalized = label.trim().toLowerCase();
+		return normalized === "exchange" || /(^|,)\s*exchange$/.test(normalized);
+	});
 }
-function isExchangeEndpoint(labels, isExchange, roles) {
-	return isExchangeFlag(isExchange) || hasExchangeLabel(labels) || roles.some((role) => role.toLowerCase().includes("exchange"));
+/**
+* Decide whether a node is an exchange endpoint that terminates traversal.
+*
+* Exchange status keys off the authoritative `is_exchange` flag first, then an
+* exact `exchange` registry label. A node whose `address_type` is SCAM or
+* VICTIM is never an exchange endpoint, regardless of its label or role text,
+* because that signal originates from this tool's own labels rather than from
+* exchange enrichment.
+*
+* @param labels - Destination node label strings.
+* @param isExchange - The node's authoritative `is_exchange` property.
+* @param roles - Enrichment role strings for the node.
+* @param addressType - The node's `address_type` property, if present.
+* @returns `true` when the node should be treated as an exchange endpoint.
+*/
+function isExchangeEndpoint(labels, isExchange, roles, addressType) {
+	if (isScamOrVictimType(addressType)) return false;
+	return isExchangeFlag(isExchange) || hasExchangeLabel(labels) || roles.some((role) => role.trim().toLowerCase() === "exchange");
+}
+/**
+* Transaction-count threshold above which a deposit edge is treated as shared
+* exchange infrastructure rather than a scammer-dedicated cash-out address.
+*/
+const SHARED_EXCHANGE_DEPOSIT_TX_COUNT = 1e3;
+/**
+* USD-volume threshold above which a deposit edge is treated as shared exchange
+* infrastructure rather than a scammer-dedicated cash-out address.
+*/
+const SHARED_EXCHANGE_DEPOSIT_USD_SUM = 5e6;
+/**
+* Decide whether a penultimate-to-exchange edge represents shared exchange
+* deposit infrastructure (an omnibus or routing address many users fund)
+* rather than a scammer-dedicated cash-out address.
+*
+* A single scammer's cash-out deposit for one incident does not aggregate
+* thousands of transfers or tens of millions of USD; an edge that does is
+* exchange-side infrastructure and must not be auto-labeled scam.
+*
+* @param edge - A `terminal_exchange` topology edge (deposit -> exchange).
+* @returns `true` when the edge's `tx_count` or `amount_usd_sum` exceeds the
+*   shared-infrastructure thresholds.
+*/
+function isSharedExchangeDeposit(edge) {
+	return edge.tx_count !== void 0 && edge.tx_count >= SHARED_EXCHANGE_DEPOSIT_TX_COUNT || edge.amount_usd_sum !== void 0 && edge.amount_usd_sum >= SHARED_EXCHANGE_DEPOSIT_USD_SUM;
 }
 function isGenericContextLabel(label) {
 	const normalized = label.trim().toLowerCase();
@@ -1032,6 +1108,10 @@ function traversalProjection() {
 		"dst.labels AS dst_labels",
 		"src.is_exchange AS src_is_exchange",
 		"dst.is_exchange AS dst_is_exchange",
+		"src.address_type AS src_address_type",
+		"dst.address_type AS dst_address_type",
+		"src.address_subtypes AS src_address_subtypes",
+		"dst.address_subtypes AS dst_address_subtypes",
 		"r.amount_sum AS amount_sum",
 		"r.amount_usd_sum AS amount_usd_sum",
 		"r.tx_count AS tx_count",
@@ -1090,9 +1170,14 @@ function edgeFromRow(row, graphScope, hop, context) {
 	const dstLabels = stringArray(row["dst_labels"]);
 	const srcRoles = stringArray(row["src_roles"]);
 	const dstRoles = stringArray(row["dst_roles"]);
-	const srcIsExchange = isExchangeEndpoint(srcLabels, row["src_is_exchange"], srcRoles);
-	const dstIsExchange = isExchangeEndpoint(dstLabels, row["dst_is_exchange"], dstRoles);
-	const genericLabeledBoundary = dstLabels.length > 0 && !dstIsExchange;
+	const srcAddressType = stringValue$1(row["src_address_type"]);
+	const dstAddressType = stringValue$1(row["dst_address_type"]);
+	const srcAddressSubtypes = stringArray(row["src_address_subtypes"]);
+	const dstAddressSubtypes = stringArray(row["dst_address_subtypes"]);
+	const srcIsExchange = isExchangeEndpoint(srcLabels, row["src_is_exchange"], srcRoles, srcAddressType);
+	const dstIsExchange = isExchangeEndpoint(dstLabels, row["dst_is_exchange"], dstRoles, dstAddressType);
+	const dstIsScamTyped = isScamOrVictimType(dstAddressType);
+	const genericLabeledBoundary = dstLabels.length > 0 && !dstIsExchange && !dstIsScamTyped;
 	return {
 		relation: dstIsExchange ? "terminal_exchange" : genericLabeledBoundary ? "context_boundary" : hop === 1 ? "seed_outflow" : "traversal_edge",
 		src,
@@ -1112,7 +1197,11 @@ function edgeFromRow(row, graphScope, hop, context) {
 		src_labels: srcLabels,
 		dst_labels: dstLabels,
 		src_is_exchange: srcIsExchange,
-		dst_is_exchange: dstIsExchange
+		dst_is_exchange: dstIsExchange,
+		...srcAddressType !== void 0 ? { src_address_type: srcAddressType } : {},
+		...dstAddressType !== void 0 ? { dst_address_type: dstAddressType } : {},
+		...srcAddressSubtypes.length > 0 ? { src_address_subtypes: srcAddressSubtypes } : {},
+		...dstAddressSubtypes.length > 0 ? { dst_address_subtypes: dstAddressSubtypes } : {}
 	};
 }
 function edgeKey(edge) {
@@ -1318,6 +1407,126 @@ function labelForSubtype(subtype) {
 		case "exchange_deposit_candidate": return "Scam exchange deposit candidate";
 	}
 }
+/**
+* Per-hop multiplicative decay applied to a candidate's base confidence. Each
+* additional hop from the seed multiplies confidence by this factor, so deeper
+* addresses score strictly lower than closer ones at equal value.
+*/
+const SCAM_TOPOLOGY_HOP_DECAY = .85;
+/**
+* Floor on the hop-decay multiplier so very deep chains do not collapse to
+* zero; keeps confidence bounded and positive while still ranking deep edges
+* below shallow ones.
+*/
+const SCAM_TOPOLOGY_MIN_HOP_FACTOR = .25;
+/**
+* Native/USD value at or above which the value factor saturates to its maximum
+* contribution. Chosen so a large incident-scale transfer earns full value
+* weight while small dust transfers earn little.
+*/
+const SCAM_TOPOLOGY_VALUE_SATURATION = 1e5;
+/**
+* Fraction of confidence governed by carried value (the remainder is the fixed
+* base). A high-value edge keeps near-base confidence; a dust edge is damped.
+*/
+const SCAM_TOPOLOGY_VALUE_WEIGHT = .5;
+/**
+* Confidence threshold at or above which a close-hop candidate is auto-promoted
+* to `promote_confirmed` instead of `review_required`. Tuned so that only a
+* near-full-value, close-hop core reaches it: a hop-1 edge carrying
+* incident-scale value retains its full base confidence (victim-seeded base is
+* 0.72), while dust or deeper edges fall below the bar and stay review-only.
+*/
+const SCAM_TOPOLOGY_PROMOTE_CONFIDENCE = .72;
+/**
+* Maximum hop distance eligible for auto-promotion. Only the close-hop core of
+* a topology can promote automatically; the diluted tail stays review-only.
+*/
+const SCAM_TOPOLOGY_PROMOTE_MAX_HOP = 2;
+/**
+* Choose the value used for confidence scoring.
+*
+* Deep-hop `amount_usd_sum` is frequently inconsistent with the native amount
+* (e.g. hundreds of tokens reported as a few dollars) because price coverage is
+* missing at depth or the price join is wrong. Trusting such USD would deflate
+* confidence for genuinely high-value transfers, so the native `amount_sum` is
+* always preferred when present and positive. USD is used only as a fallback
+* when no usable native amount exists. Native units are consistent within a
+* single asset's topology, so value comparisons across edges remain meaningful.
+*
+* @param amountSum - Native transferred amount on the edge, if present.
+* @param amountUsdSum - Reported USD value on the edge, if present.
+* @returns A positive scoring value, or `undefined` when neither amount is
+*   usable.
+*/
+function reliableScoringValue(amountSum, amountUsdSum) {
+	const native = amountSum !== void 0 && Number.isFinite(amountSum) && amountSum > 0 ? amountSum : void 0;
+	if (native !== void 0) return native;
+	return amountUsdSum !== void 0 && Number.isFinite(amountUsdSum) && amountUsdSum > 0 ? amountUsdSum : void 0;
+}
+/**
+* Compute a bounded [0, 1] value factor from a reliable scoring value using a
+* logarithmic scale, so confidence increases monotonically with carried value
+* and saturates for incident-scale transfers.
+*
+* @param value - A non-negative scoring value, or `undefined`.
+* @returns A factor in [0, 1]; `0` when no value is available.
+*/
+function valueFactor(value) {
+	if (value === void 0 || value <= 0) return 0;
+	return Math.log10(1 + Math.min(value, SCAM_TOPOLOGY_VALUE_SATURATION)) / Math.log10(100001);
+}
+/**
+* Confidence model for a topology edge: a base confidence that decays
+* multiplicatively with hop distance and scales with carried value.
+*
+* The result is `base * hopFactor * (1 - VALUE_WEIGHT + VALUE_WEIGHT * valueFactor)`,
+* where `hopFactor = max(MIN_HOP_FACTOR, HOP_DECAY^(hop - 1))`. It is bounded in
+* `(0, base]`, strictly decreasing in `hop`, and increasing in carried value, so
+* a hop-1 high-value edge always outranks a deeper low-value edge. Carried value
+* is read from the native amount when available (see {@link reliableScoringValue}),
+* so unreliable deep-hop USD pricing cannot distort the score.
+*
+* @param edge - The topology edge being scored.
+* @param baseConfidence - The relation-and-role base confidence in `(0, 1]`.
+* @returns A confidence score in `(0, 1]`.
+*/
+function decayedConfidence(edge, baseConfidence) {
+	const hop = Number.isFinite(edge.hop) && edge.hop > 0 ? edge.hop : 1;
+	const hopFactor = Math.max(SCAM_TOPOLOGY_MIN_HOP_FACTOR, Math.pow(SCAM_TOPOLOGY_HOP_DECAY, hop - 1));
+	const value = reliableScoringValue(edge.amount_sum, edge.amount_usd_sum);
+	const valueScale = 1 - SCAM_TOPOLOGY_VALUE_WEIGHT + SCAM_TOPOLOGY_VALUE_WEIGHT * valueFactor(value);
+	const confidence = baseConfidence * hopFactor * valueScale;
+	return Math.min(baseConfidence, Math.max(0, confidence));
+}
+/**
+* Decide the promotion tier for a scored candidate. Only a close-hop,
+* high-confidence core auto-promotes to `promote_confirmed`; everything else
+* stays `review_required` for human triage.
+*
+* @param edge - The topology edge backing the candidate.
+* @param confidence - The candidate's decayed confidence score.
+* @returns The promotion status for the candidate.
+*/
+function promotionTier(edge, confidence) {
+	const hop = Number.isFinite(edge.hop) && edge.hop > 0 ? edge.hop : 1;
+	return confidence >= SCAM_TOPOLOGY_PROMOTE_CONFIDENCE && hop <= SCAM_TOPOLOGY_PROMOTE_MAX_HOP ? "promote_confirmed" : "review_required";
+}
+/**
+* Build a scam label candidate from a topology edge with hop-and-value decayed
+* confidence and an automatic promotion tier.
+*
+* @param address - The candidate address.
+* @param subtype - The candidate scam subtype.
+* @param evidence - Structured evidence for the candidate.
+* @param edge - The topology edge backing the candidate.
+* @param baseConfidence - The relation-and-role base confidence in `(0, 1]`.
+* @returns A scored label candidate.
+*/
+function makeScoredCandidate(address, subtype, evidence, edge, baseConfidence) {
+	const confidence = decayedConfidence(edge, baseConfidence);
+	return makeCandidate(address, subtype, evidence, confidence, promotionTier(edge, confidence));
+}
 function makeCandidate(address, subtype, evidence, confidence, promotionStatus) {
 	return {
 		address,
@@ -1429,7 +1638,7 @@ function classifyTopology(seeds, edges) {
 				seed_role: edge.seed_role
 			});
 			addRole(rolesByAddress, edge.src, "laundering_intermediate");
-			mergeCandidate(candidates, makeCandidate(edge.src, "laundering_intermediate", edgeEvidence(edge, "Address sends into an exchange-deposit cluster reached from a known scam topology seed."), edge.seed_role === "scammer" ? .78 : .64, "review_required"));
+			mergeCandidate(candidates, makeScoredCandidate(edge.src, "laundering_intermediate", edgeEvidence(edge, "Address sends into an exchange-deposit cluster reached from a known scam topology seed."), edge, edge.seed_role === "scammer" ? .78 : .64));
 			continue;
 		}
 		if (edge.relation === "terminal_exchange") {
@@ -1488,7 +1697,15 @@ function classifyTopology(seeds, edges) {
 					seed_role: edge.seed_role
 				});
 				addRole(rolesByAddress, edge.src, "exchange_deposit_candidate");
-				mergeCandidate(candidates, makeCandidate(edge.src, "exchange_deposit_candidate", edgeEvidence(edge, "Address is the penultimate hop before an exchange endpoint."), edge.seed_role === "scammer" ? .8 : .68, "review_required"));
+				if (isSharedExchangeDeposit(edge)) pushSafetyDecision(safetyDecisions, {
+					address: edge.src,
+					decision: "do_not_label_shared_exchange_deposit",
+					reason: "Penultimate address shows shared exchange-deposit throughput (high tx_count or USD volume); treated as exchange-adjacent context, not an automatic scam candidate.",
+					tx_count: edge.tx_count,
+					amount_usd_sum: edge.amount_usd_sum,
+					seed_address: edge.seed_address
+				});
+				else mergeCandidate(candidates, makeScoredCandidate(edge.src, "exchange_deposit_candidate", edgeEvidence(edge, "Address is the penultimate hop before an exchange endpoint."), edge, edge.seed_role === "scammer" ? .8 : .68));
 			}
 			continue;
 		}
@@ -1533,7 +1750,7 @@ function classifyTopology(seeds, edges) {
 			seed_role: edge.seed_role
 		});
 		addRole(rolesByAddress, edge.dst, "laundering_intermediate");
-		mergeCandidate(candidates, makeCandidate(edge.dst, "laundering_intermediate", edgeEvidence(edge, "Address appears on an outward path from a known scam topology seed."), edge.seed_role === "scammer" ? .85 : .72, "review_required"));
+		mergeCandidate(candidates, makeScoredCandidate(edge.dst, "laundering_intermediate", edgeEvidence(edge, "Address appears on an outward path from a known scam topology seed."), edge, edge.seed_role === "scammer" ? .85 : .72));
 	}
 	return {
 		labelCandidates: [...candidates.values()].sort((a, b) => b.confidence_score - a.confidence_score || a.address.localeCompare(b.address)),