@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/core/activity/suiFunctionTarget.js

@@ -0,0 +1,43 @@
+import { isValidSuiAddress, normalizeSuiAddress } from "@mysten/sui/utils";
+import { parseSuiAddress } from "../suiAddress.js";
+import { TransactionActivityError } from "./transactionActivityTypes.js";
+const MOVE_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function parseSuiFunctionTarget(value) {
+    if (value.length === 0 || value.trim() !== value || value.includes("<") || value.includes(">")) {
+        throw invalidFunctionTarget();
+    }
+    const parts = value.split("::");
+    if (parts.length !== 3) {
+        throw invalidFunctionTarget();
+    }
+    const [packageId, moduleName, functionName] = parts;
+    const normalizedPackage = parseFunctionPackageAddress(packageId);
+    if (normalizedPackage === undefined ||
+        !MOVE_IDENTIFIER_PATTERN.test(moduleName) ||
+        !MOVE_IDENTIFIER_PATTERN.test(functionName)) {
+        throw invalidFunctionTarget();
+    }
+    return {
+        package: normalizedPackage,
+        module: moduleName,
+        function: functionName,
+        target: `${normalizedPackage}::${moduleName}::${functionName}`
+    };
+}
+function parseFunctionPackageAddress(value) {
+    const normalized = parseSuiAddress(value);
+    if (normalized !== undefined) {
+        return normalized;
+    }
+    if (!/^0x[0-9a-fA-F]+$/.test(value)) {
+        return undefined;
+    }
+    const normalizedShort = normalizeSuiAddress(value);
+    return isValidSuiAddress(normalizedShort) ? normalizedShort : undefined;
+}
+function invalidFunctionTarget() {
+    return new TransactionActivityError("input_invalid", "Invalid Sui function target", {
+        field: "function",
+        reason: "invalid_function_target"
+    });
+}

package/dist/core/activity/transactionActivityAccountEffects.js

@@ -0,0 +1,189 @@
+import { parseSuiAddress } from "../suiAddress.js";
+export function attachRequestedAccountEffects(transactions, account) {
+    return transactions.map((transaction) => ({
+        ...transaction,
+        accountEffects: requestedAccountEffectsForTransaction(transaction, account)
+    }));
+}
+export function buildRequestedAccountActivity(input) {
+    const coinFlows = new Map();
+    let sentCount = 0;
+    let affectedOnlyCount = 0;
+    let completeness = "complete";
+    for (const transaction of input.transactions) {
+        const effects = transaction.accountEffects ?? requestedAccountEffectsForTransaction(transaction, input.account);
+        if (effects.sentByAccount) {
+            sentCount += 1;
+        }
+        else {
+            affectedOnlyCount += 1;
+        }
+        completeness = mergeCompleteness(completeness, effects.balanceChangeCompleteness);
+        for (const change of effects.balanceChanges) {
+            const entry = coinFlows.get(change.coinType) ?? {
+                increaseRaw: 0n,
+                decreaseRaw: 0n,
+                netRaw: 0n,
+                digests: new Set()
+            };
+            const amount = BigInt(change.amountRaw);
+            entry.netRaw += amount;
+            if (amount > 0n) {
+                entry.increaseRaw += amount;
+            }
+            else if (amount < 0n) {
+                entry.decreaseRaw += -amount;
+            }
+            entry.digests.add(transaction.digest);
+            coinFlows.set(change.coinType, entry);
+        }
+    }
+    return {
+        account: input.account,
+        relationship: input.relationship,
+        sentCount,
+        affectedOnlyCount,
+        balanceChangeCompleteness: completeness,
+        coinFlows: [...coinFlows.entries()]
+            .map(([coinType, value]) => ({
+            coinType,
+            increaseRaw: value.increaseRaw.toString(),
+            decreaseRaw: value.decreaseRaw.toString(),
+            netRaw: value.netRaw.toString(),
+            transactionCount: value.digests.size
+        }))
+            .sort(compareCoinFlowRows)
+    };
+}
+export function requestedAccountEffectsForTransaction(transaction, account) {
+    const sentByAccount = addressMatches(transaction.sender, account);
+    if (transaction.details === undefined) {
+        return {
+            account,
+            scope: "requested_account",
+            role: sentByAccount ? "sender" : "affected_only",
+            sentByAccount,
+            balanceChangeEvidence: "account_balance_changes_unavailable",
+            accountBalanceChangeAbsenceProven: false,
+            accountBalanceChangeInferencePolicy: "do_not_infer_from_transaction_context",
+            balanceChangeCompleteness: "unavailable",
+            balanceChanges: [],
+            coinFlows: [],
+            limitations: ["transaction_details_unavailable"]
+        };
+    }
+    const balanceChanges = transaction.details.balanceChanges
+        .filter((change) => addressMatches(change.owner, account))
+        .map((change) => ({
+        index: change.index,
+        coinType: change.coinType,
+        amountRaw: change.amountRaw,
+        direction: change.direction
+    }));
+    const balanceChangeCompleteness = transaction.details.truncation.balanceChanges ? "truncated" : "complete";
+    const balanceChangeEvidence = balanceChangeEvidenceFor(balanceChangeCompleteness, balanceChanges);
+    const accountBalanceChangeAbsenceProven = balanceChangeCompleteness === "complete" && balanceChanges.length === 0;
+    return {
+        account,
+        scope: "requested_account",
+        role: sentByAccount ? "sender" : "affected_only",
+        sentByAccount,
+        balanceChangeEvidence,
+        accountBalanceChangeAbsenceProven,
+        accountBalanceChangeInferencePolicy: accountBalanceChangeInferencePolicyFor(balanceChangeEvidence, accountBalanceChangeAbsenceProven),
+        balanceChangeCompleteness,
+        balanceChanges,
+        coinFlows: coinFlowsForBalanceChanges(balanceChanges),
+        limitations: limitationsForCompleteness(balanceChangeCompleteness)
+    };
+}
+function accountBalanceChangeInferencePolicyFor(evidence, absenceProven) {
+    if (evidence === "account_balance_changes_returned") {
+        return "use_returned_account_balance_changes";
+    }
+    if (evidence === "no_account_balance_changes_returned" && absenceProven) {
+        return "account_absence_proven_by_complete_details";
+    }
+    return "do_not_infer_from_transaction_context";
+}
+function balanceChangeEvidenceFor(completeness, balanceChanges) {
+    if (completeness === "truncated") {
+        return "incomplete_account_balance_changes";
+    }
+    if (completeness === "unavailable") {
+        return "account_balance_changes_unavailable";
+    }
+    return balanceChanges.length === 0
+        ? "no_account_balance_changes_returned"
+        : "account_balance_changes_returned";
+}
+function coinFlowsForBalanceChanges(balanceChanges) {
+    const flows = new Map();
+    for (const change of balanceChanges) {
+        const amount = BigInt(change.amountRaw);
+        const entry = flows.get(change.coinType) ?? {
+            increaseRaw: "0",
+            decreaseRaw: "0",
+            netRaw: "0",
+            increaseRawBigInt: 0n,
+            decreaseRawBigInt: 0n,
+            netRawBigInt: 0n
+        };
+        entry.netRawBigInt += amount;
+        if (amount > 0n) {
+            entry.increaseRawBigInt += amount;
+        }
+        else if (amount < 0n) {
+            entry.decreaseRawBigInt += -amount;
+        }
+        flows.set(change.coinType, entry);
+    }
+    return [...flows.entries()]
+        .map(([coinType, value]) => ({
+        coinType,
+        increaseRaw: value.increaseRawBigInt.toString(),
+        decreaseRaw: value.decreaseRawBigInt.toString(),
+        netRaw: value.netRawBigInt.toString()
+    }))
+        .sort((a, b) => {
+        const absoluteNetA = absBigInt(BigInt(a.netRaw));
+        const absoluteNetB = absBigInt(BigInt(b.netRaw));
+        if (absoluteNetA !== absoluteNetB) {
+            return absoluteNetA > absoluteNetB ? -1 : 1;
+        }
+        return a.coinType.localeCompare(b.coinType);
+    });
+}
+function limitationsForCompleteness(completeness) {
+    if (completeness === "truncated") {
+        return ["provider_balance_changes_truncated"];
+    }
+    if (completeness === "unavailable") {
+        return ["transaction_details_unavailable"];
+    }
+    return [];
+}
+function mergeCompleteness(current, next) {
+    if (current === "truncated" || next === "truncated") {
+        return "truncated";
+    }
+    if (current === "unavailable" || next === "unavailable") {
+        return "unavailable";
+    }
+    return "complete";
+}
+function compareCoinFlowRows(a, b) {
+    const absoluteNetA = absBigInt(BigInt(a.netRaw));
+    const absoluteNetB = absBigInt(BigInt(b.netRaw));
+    if (absoluteNetA !== absoluteNetB) {
+        return absoluteNetA > absoluteNetB ? -1 : 1;
+    }
+    return a.coinType.localeCompare(b.coinType);
+}
+function absBigInt(value) {
+    return value < 0n ? -value : value;
+}
+function addressMatches(candidate, account) {
+    const normalized = candidate === undefined ? undefined : parseSuiAddress(candidate);
+    return normalized !== undefined && normalized === account;
+}

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;
+}