@zktx.io/sui-mcp 0.5.0

package/dist/core/activity/transactionActivityAnalysis.js

@@ -0,0 +1,295 @@
+import { compactExternalActivityTransactionDetails, suiGasCostFact } from "./transactionActivityDetails.js";
+export const SUI_ACTIVITY_ANALYSIS_MOVE_CALL_TARGET_LIMIT = 20;
+export const SUI_ACTIVITY_ANALYSIS_PROTOCOL_LIMIT = 20;
+export const SUI_ACTIVITY_ANALYSIS_COIN_FLOW_LIMIT = 50;
+export const SUI_ACTIVITY_ANALYSIS_EVENT_TYPE_LIMIT = 20;
+export const SUI_ACTIVITY_ANALYSIS_FAILURE_LIMIT = 20;
+export const suiActivityAnalysisLimitations = [
+    "details_missing",
+    "protocol_labels_absent",
+    "failed_without_error_detail",
+    "detail_truncated",
+    "window_incomplete",
+    "window_latest_only",
+    "ordering_unverified",
+    "stored_scan_incomplete",
+    "empty_result",
+    "analysis_rows_truncated",
+    "move_call_targets_truncated",
+    "protocols_truncated",
+    "coin_flows_truncated",
+    "event_types_truncated",
+    "failures_truncated"
+];
+export function buildSuiActivityAnalysis(transactions, context = {}) {
+    const limitations = new Set();
+    if (transactions.length === 0) {
+        limitations.add("empty_result");
+    }
+    if (context.windowComplete === false) {
+        limitations.add("window_incomplete");
+    }
+    else if (context.windowComplete === null) {
+        limitations.add("window_latest_only");
+    }
+    if (context.orderingVerified === false) {
+        limitations.add("ordering_unverified");
+    }
+    if (context.truncated === true) {
+        limitations.add("analysis_rows_truncated");
+    }
+    const statusCounts = zeroStatusCounts();
+    const relationshipCounts = zeroRelationshipCounts();
+    let earliestTimestamp;
+    let latestTimestamp;
+    let earliestCheckpoint;
+    let latestCheckpoint;
+    const moveCallCounts = new Map();
+    const protocolCounts = new Map();
+    const coinFlows = new Map();
+    const objectChanges = { created: 0, mutated: 0, deleted: 0 };
+    const eventTypeCounts = new Map();
+    let gasTransactionCount = 0;
+    let gasNetCostRaw = 0n;
+    const failures = new Map();
+    for (const transaction of transactions) {
+        statusCounts[transaction.status] += 1;
+        const relationship = transaction.relationship ?? context.relationship;
+        if (relationship !== undefined) {
+            relationshipCounts[relationship] += 1;
+        }
+        earliestTimestamp = earlierIso(earliestTimestamp, transaction.timestamp);
+        latestTimestamp = laterIso(latestTimestamp, transaction.timestamp);
+        earliestCheckpoint = earlierCheckpoint(earliestCheckpoint, transaction.checkpoint);
+        latestCheckpoint = laterCheckpoint(latestCheckpoint, transaction.checkpoint);
+        if (transaction.lastScanIncompleteReason !== undefined) {
+            limitations.add("stored_scan_incomplete");
+        }
+        const compact = compactFacts(transaction);
+        if (compact === undefined) {
+            limitations.add("details_missing");
+            if (transaction.status === "failure") {
+                limitations.add("failed_without_error_detail");
+            }
+            continue;
+        }
+        if (compact.protocolMatches === undefined || compact.protocolMatches.length === 0) {
+            limitations.add("protocol_labels_absent");
+        }
+        if (compact.detailTruncated) {
+            limitations.add("detail_truncated");
+        }
+        for (const target of compact.moveCallTargets) {
+            incrementMap(moveCallCounts, target);
+        }
+        const protocolsInTransaction = new Set();
+        for (const match of compact.protocolMatches ?? []) {
+            if (protocolsInTransaction.has(match.protocolId)) {
+                continue;
+            }
+            protocolsInTransaction.add(match.protocolId);
+            const existing = protocolCounts.get(match.protocolId);
+            protocolCounts.set(match.protocolId, {
+                displayName: existing?.displayName ?? match.displayName,
+                count: (existing?.count ?? 0) + 1
+            });
+        }
+        for (const change of compact.balanceChanges) {
+            const entry = coinFlows.get(change.coinType) ?? {
+                increaseRaw: 0n,
+                decreaseRaw: 0n,
+                netRaw: 0n,
+                digests: new Set()
+            };
+            const count = BigInt(change.count ?? 1);
+            const amount = BigInt(change.amountRaw) * count;
+            entry.netRaw += amount;
+            if (change.direction === "increase") {
+                entry.increaseRaw += absBigInt(amount);
+            }
+            else if (change.direction === "decrease") {
+                entry.decreaseRaw += absBigInt(amount);
+            }
+            entry.digests.add(transaction.digest);
+            coinFlows.set(change.coinType, entry);
+        }
+        objectChanges.created += compact.objectChangeCounts.created;
+        objectChanges.mutated += compact.objectChangeCounts.mutated;
+        objectChanges.deleted += compact.objectChangeCounts.deleted;
+        for (const eventType of compact.eventTypes) {
+            incrementMap(eventTypeCounts, eventType);
+        }
+        if (compact.gasNetCostRaw !== undefined) {
+            gasTransactionCount += 1;
+            gasNetCostRaw += BigInt(compact.gasNetCostRaw);
+        }
+        if (transaction.status === "failure" && compact.executionError === undefined) {
+            limitations.add("failed_without_error_detail");
+        }
+        if (compact.executionError !== undefined) {
+            const key = failureKey(compact.executionError);
+            const serialized = JSON.stringify(key);
+            const existing = failures.get(serialized);
+            failures.set(serialized, { key, count: (existing?.count ?? 0) + 1 });
+        }
+    }
+    const moveCallTargets = topCountRows(moveCallCounts, SUI_ACTIVITY_ANALYSIS_MOVE_CALL_TARGET_LIMIT)
+        .map((row) => ({ target: row.key, count: row.count }));
+    if (moveCallCounts.size > SUI_ACTIVITY_ANALYSIS_MOVE_CALL_TARGET_LIMIT) {
+        limitations.add("move_call_targets_truncated");
+    }
+    const protocols = [...protocolCounts.entries()]
+        .map(([protocolId, value]) => ({ protocolId, ...value }))
+        .sort(compareProtocolRows)
+        .slice(0, SUI_ACTIVITY_ANALYSIS_PROTOCOL_LIMIT);
+    if (protocolCounts.size > SUI_ACTIVITY_ANALYSIS_PROTOCOL_LIMIT) {
+        limitations.add("protocols_truncated");
+    }
+    const coinFlowRows = [...coinFlows.entries()]
+        .map(([coinType, value]) => ({
+        coinType,
+        increaseRaw: value.increaseRaw.toString(),
+        decreaseRaw: value.decreaseRaw.toString(),
+        netRaw: value.netRaw.toString(),
+        transactionCount: value.digests.size
+    }))
+        .sort(compareCoinFlowRows)
+        .slice(0, SUI_ACTIVITY_ANALYSIS_COIN_FLOW_LIMIT);
+    if (coinFlows.size > SUI_ACTIVITY_ANALYSIS_COIN_FLOW_LIMIT) {
+        limitations.add("coin_flows_truncated");
+    }
+    const eventTypes = topCountRows(eventTypeCounts, SUI_ACTIVITY_ANALYSIS_EVENT_TYPE_LIMIT)
+        .map((row) => ({ eventType: row.key, count: row.count }));
+    if (eventTypeCounts.size > SUI_ACTIVITY_ANALYSIS_EVENT_TYPE_LIMIT) {
+        limitations.add("event_types_truncated");
+    }
+    const failureRows = [...failures.values()]
+        .sort(compareFailureRows)
+        .slice(0, SUI_ACTIVITY_ANALYSIS_FAILURE_LIMIT)
+        .map(({ key, count }) => ({ ...key, count }));
+    if (failures.size > SUI_ACTIVITY_ANALYSIS_FAILURE_LIMIT) {
+        limitations.add("failures_truncated");
+    }
+    const overviewSummary = context.summary;
+    const overviewEarliestTimestamp = overviewSummary?.earliestTimestamp ?? earliestTimestamp;
+    const overviewLatestTimestamp = overviewSummary?.latestTimestamp ?? latestTimestamp;
+    return {
+        overview: {
+            transactionCount: overviewSummary?.transactionCount ?? transactions.length,
+            analyzedTransactionCount: transactions.length,
+            statusCounts: overviewSummary?.statusCounts ?? statusCounts,
+            relationshipCounts: overviewSummary?.relationshipCounts ?? relationshipCounts,
+            ...(overviewEarliestTimestamp === undefined ? {} : { earliestTimestamp: overviewEarliestTimestamp }),
+            ...(overviewLatestTimestamp === undefined ? {} : { latestTimestamp: overviewLatestTimestamp }),
+            ...(earliestCheckpoint === undefined ? {} : { earliestCheckpoint }),
+            ...(latestCheckpoint === undefined ? {} : { latestCheckpoint })
+        },
+        moveCallTargets,
+        protocols,
+        coinFlows: coinFlowRows,
+        objectChanges,
+        eventTypes,
+        ...(gasTransactionCount === 0
+            ? {}
+            : {
+                gas: {
+                    transactionCount: gasTransactionCount,
+                    netGasCostRaw: gasNetCostRaw.toString(),
+                    netGasCost: suiGasCostFact(gasNetCostRaw.toString())
+                }
+            }),
+        failures: failureRows,
+        limitations: [...limitations].sort()
+    };
+}
+function compactFacts(transaction) {
+    if (transaction.compact !== undefined) {
+        return transaction.compact;
+    }
+    return transaction.details === undefined
+        ? undefined
+        : compactExternalActivityTransactionDetails(transaction.details);
+}
+function zeroStatusCounts() {
+    return { success: 0, failure: 0, unknown: 0 };
+}
+function zeroRelationshipCounts() {
+    return { affected: 0, sent: 0 };
+}
+function incrementMap(map, key) {
+    map.set(key, (map.get(key) ?? 0) + 1);
+}
+function topCountRows(map, limit) {
+    return [...map.entries()]
+        .map(([key, count]) => ({ key, count }))
+        .sort(compareCountRows)
+        .slice(0, limit);
+}
+function compareCountRows(a, b) {
+    return b.count - a.count || compareAscii(a.key, b.key);
+}
+function compareProtocolRows(a, b) {
+    return b.count - a.count || compareAscii(a.protocolId, b.protocolId);
+}
+function compareCoinFlowRows(a, b) {
+    return b.transactionCount - a.transactionCount || compareAscii(a.coinType, b.coinType);
+}
+function compareFailureRows(a, b) {
+    return b.count - a.count || compareAscii(failureSortKey(a.key), failureSortKey(b.key));
+}
+function failureKey(error) {
+    return {
+        message: error.message,
+        ...(error.abortCodeRaw === undefined ? {} : { abortCodeRaw: error.abortCodeRaw }),
+        ...(error.package === undefined ? {} : { package: error.package }),
+        ...(error.module === undefined ? {} : { module: error.module }),
+        ...(error.function === undefined ? {} : { function: error.function })
+    };
+}
+function failureSortKey(key) {
+    return [
+        key.message,
+        key.abortCodeRaw ?? "",
+        key.package ?? "",
+        key.module ?? "",
+        key.function ?? ""
+    ].join("\u0000");
+}
+function earlierIso(current, candidate) {
+    if (candidate === undefined)
+        return current;
+    if (current === undefined)
+        return candidate;
+    return candidate < current ? candidate : current;
+}
+function laterIso(current, candidate) {
+    if (candidate === undefined)
+        return current;
+    if (current === undefined)
+        return candidate;
+    return candidate > current ? candidate : current;
+}
+function earlierCheckpoint(current, candidate) {
+    if (candidate === undefined)
+        return current;
+    if (current === undefined)
+        return candidate;
+    return BigInt(candidate) < BigInt(current) ? candidate : current;
+}
+function laterCheckpoint(current, candidate) {
+    if (candidate === undefined)
+        return current;
+    if (current === undefined)
+        return candidate;
+    return BigInt(candidate) > BigInt(current) ? candidate : current;
+}
+function absBigInt(value) {
+    return value < 0n ? -value : value;
+}
+function compareAscii(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}

package/dist/core/activity/transactionActivityClassifier.js

@@ -0,0 +1,306 @@
+import { z } from "zod";
+import { parseSuiAddress } from "../suiAddress.js";
+import { SUI_DEFI_ACTIVITY_PROTOCOL_RULES, protocolActivityPrimaryActions, protocolPackageRuleAllows } from "./transactionActivityProtocolRules.js";
+export const SUI_DEFI_ACTIVITY_CLASSIFIER_VERSION = "sui_defi_activity_v0_4";
+const protocolActivityPrimaryActionSchema = z.enum(protocolActivityPrimaryActions);
+const protocolMatchBasisSchema = z.enum([
+    "direct_move_call",
+    "event_type",
+    "object_type",
+    "shared_object"
+]);
+const primaryActionPriority = {
+    order: 0,
+    swap: 0,
+    liquidity: 0,
+    lending: 0,
+    fee_or_reward: 1,
+    admin_or_versioning: 2,
+    unknown: 3
+};
+export const protocolActivityClassifierMatchSchema = z.object({
+    classifierVersion: z.literal(SUI_DEFI_ACTIVITY_CLASSIFIER_VERSION),
+    protocolId: z.string(),
+    displayName: z.string(),
+    activityCategory: z.string(),
+    primaryAction: protocolActivityPrimaryActionSchema,
+    matchBasis: protocolMatchBasisSchema,
+    evidence: z.array(z.discriminatedUnion("kind", [
+        z.object({
+            kind: z.literal("moveCall"),
+            package: z.string(),
+            packageSource: z.string().optional(),
+            mvrName: z.string().optional(),
+            module: z.string(),
+            function: z.string(),
+            commandIndex: z.number().int().nonnegative()
+        }).strict(),
+        z.object({
+            kind: z.literal("eventType"),
+            package: z.string().optional(),
+            packageSource: z.string().optional(),
+            mvrName: z.string().optional(),
+            eventType: z.string(),
+            sequenceNumber: z.string().optional()
+        }).strict(),
+        z.object({
+            kind: z.literal("objectType"),
+            objectId: z.string(),
+            changeKind: z.string(),
+            package: z.string().optional(),
+            packageSource: z.string().optional(),
+            mvrName: z.string().optional(),
+            type: z.string()
+        }).strict(),
+        z.object({
+            kind: z.literal("sharedObject"),
+            objectId: z.string(),
+            label: z.string()
+        }).strict()
+    ])).min(1),
+    relatedProtocols: z.array(z.object({
+        protocolId: z.string(),
+        reason: z.string()
+    }).strict()),
+    limitations: z.array(z.string())
+}).strict();
+export function classifySuiDeFiActivity(details) {
+    const matches = SUI_DEFI_ACTIVITY_PROTOCOL_RULES.flatMap((rule) => matchProtocol(rule, details));
+    const deepTradeDirect = matches.some((match) => match.protocolId === "deeptrade-core" && match.matchBasis === "direct_move_call");
+    const deepBookMatch = matches.find((match) => match.protocolId === "deepbook-v3");
+    const resolved = matches
+        .filter((match) => !(deepTradeDirect && match.protocolId === "deepbook-v3"))
+        .map((match) => {
+        if (match.protocolId === "deeptrade-core" && deepTradeDirect && deepBookMatch) {
+            return {
+                ...match,
+                relatedProtocols: [
+                    ...match.relatedProtocols,
+                    {
+                        protocolId: "deepbook-v3",
+                        reason: "deeptrade_wrapper_touched_deepbook_evidence"
+                    }
+                ]
+            };
+        }
+        return match;
+    });
+    return resolved.sort((a, b) => {
+        const priority = matchBasisPriority(a.matchBasis) - matchBasisPriority(b.matchBasis);
+        if (priority !== 0) {
+            return priority;
+        }
+        return compareAscii(a.protocolId, b.protocolId);
+    });
+}
+function matchProtocol(rule, details) {
+    const evidence = [];
+    const limitationSet = new Set();
+    let matchBasis;
+    let primaryAction = "unknown";
+    for (const call of details.moveCalls) {
+        const packageId = normalizedPackageFromMoveCall(call);
+        const packageRule = packageId === undefined ? undefined : rule.packages[packageId];
+        if (packageRule === undefined || !protocolPackageRuleAllows(packageRule, "moveCall")) {
+            continue;
+        }
+        evidence.push({
+            kind: "moveCall",
+            package: call.package,
+            ...packageEvidenceFields(packageRule),
+            module: call.module,
+            function: call.function,
+            commandIndex: call.commandIndex
+        });
+        matchBasis = selectPreferredMatchBasis(matchBasis, "direct_move_call");
+        primaryAction = strongestPrimaryAction(primaryAction, rule.actionForMoveCall?.(call) ?? "unknown");
+        if (packageRule.limitation !== undefined) {
+            limitationSet.add(packageRule.limitation);
+        }
+    }
+    for (const event of details.events) {
+        const packageId = normalizedPackageFromEvent(event);
+        const packageRule = packageId === undefined ? undefined : rule.packages[packageId];
+        if (packageId !== undefined
+            && packageRule !== undefined
+            && protocolPackageRuleAllows(packageRule, "eventType")
+            && event.eventType !== undefined) {
+            evidence.push({
+                kind: "eventType",
+                package: packageId,
+                ...packageEvidenceFields(packageRule),
+                eventType: event.eventType,
+                ...(event.sequenceNumber === undefined ? {} : { sequenceNumber: event.sequenceNumber })
+            });
+            matchBasis = selectPreferredMatchBasis(matchBasis, "event_type");
+        }
+    }
+    for (const change of details.objectChanges) {
+        for (const type of uniqueStrings([change.inputType, change.outputType].flatMap((value) => value === undefined ? [] : [value]))) {
+            const packageId = normalizedPackageFromType(type);
+            const packageRule = packageId === undefined ? undefined : rule.packages[packageId];
+            if (packageId !== undefined
+                && packageRule !== undefined
+                && protocolPackageRuleAllows(packageRule, "objectType")) {
+                evidence.push({
+                    kind: "objectType",
+                    objectId: change.objectId,
+                    changeKind: change.changeKind,
+                    package: packageId,
+                    ...packageEvidenceFields(packageRule),
+                    type
+                });
+                matchBasis = selectPreferredMatchBasis(matchBasis, "object_type");
+            }
+        }
+        const objectId = parseSuiAddress(change.objectId);
+        const sharedObjectLabel = objectId === undefined ? undefined : rule.sharedObjects[objectId];
+        if (sharedObjectLabel !== undefined) {
+            evidence.push({
+                kind: "sharedObject",
+                objectId: change.objectId,
+                label: sharedObjectLabel
+            });
+            matchBasis = selectPreferredMatchBasis(matchBasis, "shared_object");
+        }
+    }
+    if (evidence.length === 0 || matchBasis === undefined) {
+        return [];
+    }
+    addTruncationLimitations(details, limitationSet);
+    if (matchBasis === "shared_object") {
+        limitationSet.add("shared_object_match_does_not_prove_wallet_position");
+    }
+    if (matchBasis === "event_type" || matchBasis === "object_type") {
+        limitationSet.add("no_direct_move_call_match");
+    }
+    limitationSet.add("transaction_activity_label_only");
+    limitationSet.add("not_position_inventory_or_pnl_or_signing");
+    return [{
+            classifierVersion: SUI_DEFI_ACTIVITY_CLASSIFIER_VERSION,
+            protocolId: rule.protocolId,
+            displayName: rule.displayName,
+            activityCategory: rule.activityCategory,
+            primaryAction,
+            matchBasis,
+            evidence: uniqueEvidence(evidence),
+            relatedProtocols: [],
+            limitations: [...limitationSet].sort(compareAscii)
+        }];
+}
+function addTruncationLimitations(details, limitations) {
+    if (details.truncation.moveCalls) {
+        limitations.add("move_call_details_truncated");
+    }
+    if (details.truncation.objectChanges) {
+        limitations.add("object_change_details_truncated");
+    }
+    if (details.truncation.events) {
+        limitations.add("event_details_truncated");
+    }
+}
+function selectPreferredMatchBasis(current, candidate) {
+    return current === undefined || matchBasisPriority(candidate) < matchBasisPriority(current)
+        ? candidate
+        : current;
+}
+function matchBasisPriority(matchBasis) {
+    switch (matchBasis) {
+        case "direct_move_call":
+            return 0;
+        case "event_type":
+            return 1;
+        case "object_type":
+            return 2;
+        case "shared_object":
+            return 3;
+    }
+}
+function strongestPrimaryAction(current, candidate) {
+    const priority = primaryActionPriority[candidate] - primaryActionPriority[current];
+    if (priority !== 0) {
+        return priority < 0 ? candidate : current;
+    }
+    return current === "unknown" ? candidate : current;
+}
+function normalizedPackageFromMoveCall(call) {
+    return parseSuiAddress(call.package) ?? normalizedPackageFromType(call.target);
+}
+function normalizedPackageFromEvent(event) {
+    if (event.package !== undefined) {
+        return parseSuiAddress(event.package);
+    }
+    return event.eventType === undefined ? undefined : normalizedPackageFromType(event.eventType);
+}
+function normalizedPackageFromType(type) {
+    const [packageCandidate] = type.split("::");
+    return packageCandidate === undefined ? undefined : parseSuiAddress(packageCandidate);
+}
+function packageEvidenceFields(packageRule) {
+    return {
+        packageSource: packageRule.source,
+        ...(packageRule.mvrName === undefined ? {} : { mvrName: packageRule.mvrName })
+    };
+}
+function uniqueEvidence(evidence) {
+    const seen = new Set();
+    const unique = [];
+    for (const item of evidence) {
+        const key = evidenceKey(item);
+        if (!seen.has(key)) {
+            seen.add(key);
+            unique.push(item);
+        }
+    }
+    return unique;
+}
+function evidenceKey(evidence) {
+    switch (evidence.kind) {
+        case "moveCall":
+            return keyParts([
+                evidence.kind,
+                evidence.package,
+                evidence.packageSource,
+                evidence.mvrName,
+                evidence.module,
+                evidence.function,
+                String(evidence.commandIndex)
+            ]);
+        case "eventType":
+            return keyParts([
+                evidence.kind,
+                evidence.package,
+                evidence.packageSource,
+                evidence.mvrName,
+                evidence.eventType,
+                evidence.sequenceNumber
+            ]);
+        case "objectType":
+            return keyParts([
+                evidence.kind,
+                evidence.objectId,
+                evidence.changeKind,
+                evidence.package,
+                evidence.packageSource,
+                evidence.mvrName,
+                evidence.type
+            ]);
+        case "sharedObject":
+            return keyParts([evidence.kind, evidence.objectId, evidence.label]);
+    }
+}
+function keyParts(values) {
+    return values.map((value) => value ?? "").join("\u001f");
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function compareAscii(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}