chain-insights 0.2.20 → 0.2.23

package/dist/{public-tools-B13J0MJZ.mjs → public-tools-w7En2m3q.mjs}

@@ -1009,11 +1009,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();
@@ -1030,6 +1106,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",
@@ -1088,9 +1168,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,
@@ -1110,7 +1195,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) {
@@ -1316,6 +1405,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,
@@ -1427,7 +1636,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") {
@@ -1486,7 +1695,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;
 		}
@@ -1531,7 +1748,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)),
@@ -2946,4 +3163,4 @@ async function trackFunds(remoteClient, config, options) {
 //#endregion
 export { addressRisk, scamTopology, stakeInsights, trackFunds };
 
-//# sourceMappingURL=public-tools-B13J0MJZ.mjs.map
+//# sourceMappingURL=public-tools-w7En2m3q.mjs.map