@stelis/say-ur-intent 0.0.0 → 0.0.2

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_3";
+const protocolActivityPrimaryActionSchema = z.enum(protocolActivityPrimaryActions);
+const protocolActivityConfidenceSchema = 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,
+    confidence: protocolActivityConfidenceSchema,
+    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.confidence === "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 = confidenceRank(a.confidence) - confidenceRank(b.confidence);
+        if (priority !== 0) {
+            return priority;
+        }
+        return compareAscii(a.protocolId, b.protocolId);
+    });
+}
+function matchProtocol(rule, details) {
+    const evidence = [];
+    const limitationSet = new Set();
+    let confidence;
+    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
+        });
+        confidence = strongestConfidence(confidence, "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 })
+            });
+            confidence = strongestConfidence(confidence, "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
+                });
+                confidence = strongestConfidence(confidence, "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
+            });
+            confidence = strongestConfidence(confidence, "shared_object");
+        }
+    }
+    if (evidence.length === 0 || confidence === undefined) {
+        return [];
+    }
+    addTruncationLimitations(details, limitationSet);
+    if (confidence === "shared_object") {
+        limitationSet.add("shared_object_match_does_not_prove_wallet_position");
+    }
+    if (confidence === "event_type" || confidence === "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,
+            confidence,
+            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 strongestConfidence(current, candidate) {
+    return current === undefined || confidenceRank(candidate) < confidenceRank(current)
+        ? candidate
+        : current;
+}
+function confidenceRank(confidence) {
+    switch (confidence) {
+        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;
+}

package/dist/core/activity/transactionActivityDetails.js

@@ -0,0 +1,229 @@
+import { Buffer } from "node:buffer";
+import { MIST_PER_SUI, SUI_DECIMALS } from "@mysten/sui/utils";
+import { z } from "zod";
+import { parseSuiAddress } from "../suiAddress.js";
+import { classifySuiDeFiActivity, protocolActivityClassifierMatchSchema } from "./transactionActivityClassifier.js";
+export const EXTERNAL_ACTIVITY_TRANSACTION_DETAIL_JSON_MAX_BYTES = 64 * 1024;
+export const SUI_GAS_UNIT_SOURCE = "@mysten/sui MIST_PER_SUI";
+export const externalActivityGasCostFactSchema = z.object({
+    netCostRaw: z.string().regex(/^-?\d+$/),
+    rawUnit: z.literal("MIST"),
+    display: z.string().regex(/^-?\d+(?:\.\d+)?$/),
+    displayUnit: z.literal("SUI"),
+    decimals: z.literal(SUI_DECIMALS),
+    unitSource: z.literal(SUI_GAS_UNIT_SOURCE)
+}).strict();
+export const externalActivityTransactionDetailSchema = z.object({
+    transactionKind: z.string().optional(),
+    moveCalls: z.array(z.object({
+        commandIndex: z.number().int().nonnegative(),
+        package: z.string(),
+        module: z.string(),
+        function: z.string(),
+        target: z.string()
+    }).strict()),
+    balanceChanges: z.array(z.object({
+        index: z.number().int().nonnegative(),
+        owner: z.string().optional(),
+        coinType: z.string(),
+        amountRaw: z.string().regex(/^-?\d+$/),
+        direction: z.enum(["increase", "decrease", "zero"])
+    }).strict()),
+    objectChanges: z.array(z.object({
+        index: z.number().int().nonnegative(),
+        objectId: z.string(),
+        changeKind: z.enum(["created", "mutated", "deleted"]),
+        inputType: z.string().optional(),
+        outputType: z.string().optional()
+    }).strict()),
+    events: z.array(z.object({
+        sequenceNumber: z.string().regex(/^\d+$/),
+        sender: z.string().optional(),
+        package: z.string().optional(),
+        module: z.string().optional(),
+        eventType: z.string().optional()
+    }).strict()),
+    gas: z.object({
+        gasObjectId: z.string().optional(),
+        computationCostRaw: z.string().regex(/^\d+$/).optional(),
+        storageCostRaw: z.string().regex(/^\d+$/).optional(),
+        storageRebateRaw: z.string().regex(/^\d+$/).optional(),
+        nonRefundableStorageFeeRaw: z.string().regex(/^\d+$/).optional(),
+        netGasCostRaw: z.string().regex(/^-?\d+$/).optional()
+    }).strict().optional(),
+    executionError: z.object({
+        message: z.string(),
+        abortCodeRaw: z.string().regex(/^\d+$/).optional(),
+        identifier: z.string().optional(),
+        instructionOffset: z.number().int().nonnegative().optional(),
+        sourceLineNumber: z.number().int().nonnegative().optional(),
+        package: z.string().optional(),
+        module: z.string().optional(),
+        function: z.string().optional()
+    }).strict().optional(),
+    truncation: z.object({
+        moveCalls: z.boolean(),
+        balanceChanges: z.boolean(),
+        objectChanges: z.boolean(),
+        events: z.boolean()
+    }).strict()
+}).strict();
+export const externalActivityTransactionCompactFactsSchema = z.object({
+    factScope: z.literal("transaction"),
+    requestedAccountScoped: z.literal(false),
+    moveCallTargets: z.array(z.string()),
+    balanceChanges: z.array(z.object({
+        coinType: z.string(),
+        amountRaw: z.string().regex(/^-?\d+$/),
+        direction: z.enum(["increase", "decrease", "zero"]),
+        count: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional()
+    }).strict()),
+    objectChangeCounts: z.object({
+        created: z.number().int().nonnegative(),
+        mutated: z.number().int().nonnegative(),
+        deleted: z.number().int().nonnegative()
+    }).strict(),
+    eventTypes: z.array(z.string()),
+    gasCost: externalActivityGasCostFactSchema.optional(),
+    gasNetCostRaw: z.string().regex(/^-?\d+$/).optional(),
+    executionError: z.object({
+        message: z.string(),
+        abortCodeRaw: z.string().regex(/^\d+$/).optional(),
+        package: z.string().optional(),
+        module: z.string().optional(),
+        function: z.string().optional()
+    }).strict().optional(),
+    detailTruncated: z.boolean(),
+    protocolMatches: z.array(protocolActivityClassifierMatchSchema).optional()
+}).strict();
+export function externalActivityTransactionDetailJsonByteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+export function sanitizeExternalActivityTransactionDetailsForKnownAccount(details, storageAccount) {
+    return {
+        ...details,
+        balanceChanges: details.balanceChanges.map((change) => {
+            if (addressMatches(change.owner, storageAccount)) {
+                return { ...change, owner: storageAccount };
+            }
+            const { owner: _owner, ...withoutOwner } = change;
+            return withoutOwner;
+        }),
+        events: details.events.map((event) => {
+            if (addressMatches(event.sender, storageAccount)) {
+                return { ...event, sender: storageAccount };
+            }
+            const { sender: _sender, ...withoutSender } = event;
+            return withoutSender;
+        })
+    };
+}
+export function externalActivityTransactionTouchesAccount(transaction, account) {
+    return externalActivityTransactionBalanceOwners(transaction).includes(account);
+}
+export function externalActivityTransactionBalanceOwners(transaction) {
+    const owners = transaction.details?.balanceChanges.flatMap((change) => {
+        const owner = change.owner === undefined ? undefined : parseSuiAddress(change.owner);
+        return owner === undefined ? [] : [owner];
+    }) ?? [];
+    return [...new Set(owners)];
+}
+export function externalActivityTransactionDetailsReferenceOnlyAccount(details, account) {
+    return details.balanceChanges.every((change) => change.owner === undefined || addressMatches(change.owner, account))
+        && details.events.every((event) => event.sender === undefined || addressMatches(event.sender, account));
+}
+export function compactExternalActivityTransactionDetails(details) {
+    const objectChangeCounts = {
+        created: 0,
+        mutated: 0,
+        deleted: 0
+    };
+    for (const change of details.objectChanges) {
+        objectChangeCounts[change.changeKind] += 1;
+    }
+    const executionError = details.executionError === undefined
+        ? undefined
+        : {
+            message: details.executionError.message,
+            ...(details.executionError.abortCodeRaw === undefined ? {} : { abortCodeRaw: details.executionError.abortCodeRaw }),
+            ...(details.executionError.package === undefined ? {} : { package: details.executionError.package }),
+            ...(details.executionError.module === undefined ? {} : { module: details.executionError.module }),
+            ...(details.executionError.function === undefined ? {} : { function: details.executionError.function })
+        };
+    const protocolMatches = classifySuiDeFiActivity(details);
+    return {
+        factScope: "transaction",
+        requestedAccountScoped: false,
+        moveCallTargets: uniqueStrings(details.moveCalls.map((call) => call.target)),
+        balanceChanges: compactBalanceChanges(details.balanceChanges),
+        objectChangeCounts,
+        eventTypes: uniqueStrings(details.events.flatMap((event) => event.eventType === undefined ? [] : [event.eventType])),
+        ...(details.gas?.netGasCostRaw === undefined ? {} : { gasCost: suiGasCostFact(details.gas.netGasCostRaw) }),
+        ...(details.gas?.netGasCostRaw === undefined ? {} : { gasNetCostRaw: details.gas.netGasCostRaw }),
+        ...(executionError === undefined ? {} : { executionError }),
+        detailTruncated: details.truncation.moveCalls
+            || details.truncation.balanceChanges
+            || details.truncation.objectChanges
+            || details.truncation.events,
+        ...(protocolMatches.length === 0 ? {} : { protocolMatches })
+    };
+}
+export function suiGasCostFact(netCostRaw) {
+    return {
+        netCostRaw,
+        rawUnit: "MIST",
+        display: formatSignedMistAsSui(netCostRaw),
+        displayUnit: "SUI",
+        decimals: SUI_DECIMALS,
+        unitSource: SUI_GAS_UNIT_SOURCE
+    };
+}
+function formatSignedMistAsSui(raw) {
+    if (!/^-?\d+$/.test(raw)) {
+        throw new Error("gas raw amount must be a signed integer string");
+    }
+    const negative = raw.startsWith("-");
+    const unsignedRaw = negative ? raw.slice(1) : raw;
+    const amount = BigInt(unsignedRaw);
+    const whole = amount / MIST_PER_SUI;
+    const fractional = amount % MIST_PER_SUI;
+    const sign = negative && amount !== 0n ? "-" : "";
+    if (fractional === 0n) {
+        return `${sign}${whole.toString()}`;
+    }
+    const fractionalText = fractional
+        .toString()
+        .padStart(SUI_DECIMALS, "0")
+        .replace(/0+$/, "");
+    return `${sign}${whole.toString()}.${fractionalText}`;
+}
+function compactBalanceChanges(balanceChanges) {
+    const compacted = new Map();
+    for (const change of balanceChanges) {
+        const key = `${change.coinType}\n${change.amountRaw}\n${change.direction}`;
+        const existing = compacted.get(key);
+        if (existing === undefined) {
+            compacted.set(key, {
+                coinType: change.coinType,
+                amountRaw: change.amountRaw,
+                direction: change.direction,
+                count: 1
+            });
+            continue;
+        }
+        existing.count += 1;
+    }
+    return [...compacted.values()].map((change) => ({
+        coinType: change.coinType,
+        amountRaw: change.amountRaw,
+        direction: change.direction,
+        ...(change.count === 1 ? {} : { count: change.count })
+    }));
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function addressMatches(candidate, account) {
+    const normalized = candidate === undefined ? undefined : parseSuiAddress(candidate);
+    return normalized !== undefined && normalized === account;
+}