@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/core/activity/transactionActivityService.js

@@ -0,0 +1,379 @@
+import { randomUUID } from "node:crypto";
+import { isValidTransactionDigest } from "@mysten/sui/utils";
+import { SuiEndpointError } from "../suiEndpoint.js";
+import { parseSuiAddress } from "../suiAddress.js";
+import { REVIEW_ACTIVITY_LIST_DEFAULT_LIMIT } from "./activityStore.js";
+import { externalActivityTransactionBalanceOwners, externalActivityTransactionTouchesAccount, sanitizeExternalActivityTransactionDetailsForKnownAccount } from "./transactionActivityDetails.js";
+import { attachRequestedAccountEffects, buildRequestedAccountActivity, requestedAccountEffectsForTransaction } from "./transactionActivityAccountEffects.js";
+import { assertCheckpointRange, assertTimestampRange, compareActivityFactsDescending, filterTransactionsForRequestedWindow, incompleteReasonForScan, isMonotonicActivityOrder, normalizeActivityLimit, normalizeCheckpointBound, normalizeTimestampBound, transactionMatchesKnownStorageAccount, windowCompletion } from "./transactionActivityScanPolicy.js";
+import { parseSuiFunctionTarget } from "./suiFunctionTarget.js";
+import { TransactionActivityError, TransactionActivitySourceError } from "./transactionActivityTypes.js";
+import { buildSuiActivityAnalysis } from "./transactionActivityAnalysis.js";
+export { TransactionActivityError, TransactionActivitySourceError } from "./transactionActivityTypes.js";
+export class TransactionActivityService {
+    options;
+    now;
+    scanId;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+        this.scanId = options.scanId ?? (() => randomUUID());
+    }
+    async inspectSuiTransaction(input) {
+        const digest = parseTransactionDigest(input.digest);
+        const explicitAccount = input.account === undefined ? undefined : parseAccount(input.account);
+        const source = await this.verifySource();
+        const fetchedAt = this.now().toISOString();
+        const transaction = await this.mapSourceCall(() => this.options.source.getTransaction(digest));
+        if (!transaction) {
+            return {
+                status: "ok",
+                fetchedAt,
+                source: { ...source, method: "Query.transaction" },
+                transaction: { digest, status: "unknown" },
+                persistence: { stored: false, reason: "transaction_not_found" }
+            };
+        }
+        const transactionForExplicitAccount = explicitAccount === undefined
+            ? transaction
+            : {
+                ...transaction,
+                accountEffects: requestedAccountEffectsForTransaction(transaction, explicitAccount)
+            };
+        const known = await this.knownDigestAccountForStorage(explicitAccount, transaction);
+        if (!known) {
+            return {
+                status: "ok",
+                fetchedAt,
+                source: { ...source, method: "Query.transaction" },
+                transaction: transactionForExplicitAccount,
+                persistence: { stored: false, reason: "no_known_wallet_relation" }
+            };
+        }
+        const transactionForKnownAccount = {
+            ...transaction,
+            accountEffects: requestedAccountEffectsForTransaction(transaction, known.account.address)
+        };
+        const scan = await this.options.activityStore.recordExternalActivityScan({
+            scanId: this.scanId(),
+            kind: "digest_lookup",
+            account: known.account.address,
+            relationship: known.relationship,
+            inputDigest: digest,
+            limit: 1,
+            endpointHost: source.endpointHost,
+            chainIdentifier: source.chainIdentifier,
+            fetchedAt,
+            hasMore: false,
+            windowComplete: true,
+            transactions: [await this.transactionInputForKnownAccount(transactionForKnownAccount, known.relationship, known.account.address)]
+        });
+        return {
+            status: "ok",
+            fetchedAt,
+            source: { ...source, method: "Query.transaction" },
+            transaction: transactionForKnownAccount,
+            persistence: {
+                stored: true,
+                account: known.account.address,
+                relationship: known.relationship,
+                scan
+            }
+        };
+    }
+    async scanSuiAccountActivity(input) {
+        const relationship = input.relationship ?? "affected";
+        return this.runActivityScan({
+            request: input,
+            scanKind: "account_scan",
+            relationship,
+            cursorInvalidMessage: "Activity scan cursor was rejected by the provider",
+            sourceCall: ({ account, limit, cursor, fromCheckpoint, toCheckpoint }) => this.options.source.scanAccount({
+                account,
+                relationship,
+                limit,
+                cursor,
+                fromCheckpoint,
+                toCheckpoint
+            })
+        });
+    }
+    async scanSuiFunctionActivity(input) {
+        const functionTarget = parseSuiFunctionTarget(input.function);
+        return this.runActivityScan({
+            request: input,
+            scanKind: "function_scan",
+            relationship: "sent",
+            cursorInvalidMessage: "Function activity scan cursor was rejected by the provider",
+            extraResultFields: { function: functionTarget.target },
+            sourceCall: ({ account, limit, cursor, fromCheckpoint, toCheckpoint }) => this.options.source.scanFunction({
+                functionTarget: functionTarget.target,
+                sentAddress: account,
+                limit,
+                cursor,
+                fromCheckpoint,
+                toCheckpoint
+            })
+        });
+    }
+    async runActivityScan(input) {
+        const limit = normalizeActivityLimit(input.request.limit);
+        const fromCheckpoint = normalizeCheckpointBound(input.request.fromCheckpoint, "fromCheckpoint");
+        const toCheckpoint = normalizeCheckpointBound(input.request.toCheckpoint, "toCheckpoint");
+        assertCheckpointRange(fromCheckpoint, toCheckpoint);
+        const fromTimestamp = normalizeTimestampBound(input.request.fromTimestamp, "fromTimestamp");
+        const toTimestamp = normalizeTimestampBound(input.request.toTimestamp, "toTimestamp");
+        assertTimestampRange(fromTimestamp, toTimestamp);
+        const accountScope = input.request.account === undefined
+            ? await this.resolveActiveAccount()
+            : { account: parseAccount(input.request.account), accountSource: "explicit_filter" };
+        const knownAccount = await this.options.activityStore.getKnownAccount(accountScope.account);
+        const source = await this.verifySource();
+        const fetchedAt = this.now().toISOString();
+        let page;
+        try {
+            page = await input.sourceCall({
+                account: accountScope.account,
+                relationship: input.relationship,
+                limit,
+                cursor: input.request.cursor,
+                fromCheckpoint,
+                toCheckpoint
+            });
+        }
+        catch (error) {
+            if (error instanceof TransactionActivitySourceError && error.reason === "cursor_invalid") {
+                throw new TransactionActivityError("input_invalid", input.cursorInvalidMessage, {
+                    reason: "cursor_invalid"
+                });
+            }
+            throw this.sourceError(error);
+        }
+        const orderingVerified = isMonotonicActivityOrder(page.transactions);
+        const orderedTransactions = [...page.transactions].sort(compareActivityFactsDescending);
+        const orderedPage = { ...page, transactions: orderedTransactions };
+        const windowComplete = windowCompletion({
+            account: input.request.account,
+            relationship: input.relationship,
+            limit: input.request.limit,
+            cursor: input.request.cursor,
+            fromCheckpoint,
+            toCheckpoint,
+            fromTimestamp,
+            toTimestamp
+        }, orderedPage, orderingVerified);
+        const filteredTransactions = filterTransactionsForRequestedWindow(orderedTransactions, {
+            account: accountScope.account,
+            relationship: input.relationship,
+            fromCheckpoint,
+            toCheckpoint,
+            fromTimestamp,
+            toTimestamp
+        });
+        const accountScopedTransactions = attachRequestedAccountEffects(filteredTransactions, accountScope.account);
+        const cursor = page.hasMore ? page.cursor : undefined;
+        const incompleteReason = incompleteReasonForScan({ orderingVerified, windowComplete });
+        const resultBase = {
+            status: "ok",
+            fetchedAt,
+            account: accountScope.account,
+            accountKnown: knownAccount !== undefined,
+            accountSource: accountScope.accountSource,
+            ...(input.extraResultFields ?? {}),
+            relationship: input.relationship,
+            requestedAccount: buildRequestedAccountActivity({
+                account: accountScope.account,
+                relationship: input.relationship,
+                transactions: accountScopedTransactions
+            }),
+            source: { ...source, method: "Query.transactions" },
+            transactions: accountScopedTransactions,
+            hasMore: page.hasMore,
+            ...(cursor === undefined ? {} : { continuationCursor: cursor }),
+            windowComplete,
+            orderingVerified,
+            ...(incompleteReason === undefined ? {} : { incompleteReason })
+        };
+        if (!knownAccount) {
+            return {
+                ...resultBase,
+                persistence: { stored: false, reason: "account_not_known" }
+            };
+        }
+        const storageTransactions = accountScopedTransactions.filter((transaction) => transactionMatchesKnownStorageAccount(transaction, knownAccount.address, input.relationship));
+        const scan = await this.options.activityStore.recordExternalActivityScan({
+            scanId: this.scanId(),
+            kind: input.scanKind,
+            account: knownAccount.address,
+            relationship: input.relationship,
+            fromCheckpoint,
+            toCheckpoint,
+            fromTimestamp,
+            toTimestamp,
+            limit,
+            requestCursor: input.request.cursor,
+            responseCursor: cursor,
+            endpointHost: source.endpointHost,
+            chainIdentifier: source.chainIdentifier,
+            fetchedAt,
+            hasMore: page.hasMore,
+            windowComplete,
+            incompleteReason,
+            skippedCount: page.transactions.length - storageTransactions.length,
+            transactions: await Promise.all(storageTransactions.map((transaction) => this.transactionInputForKnownAccount(transaction, input.relationship, knownAccount.address)))
+        });
+        return {
+            ...resultBase,
+            persistence: { stored: true, scan }
+        };
+    }
+    async summarizeSuiAccountActivity(filter) {
+        const summary = await this.options.activityStore.summarizeExternalActivity({
+            ...filter,
+            limit: filter.limit ?? REVIEW_ACTIVITY_LIST_DEFAULT_LIMIT
+        });
+        return {
+            ...summary,
+            status: "ok",
+            analysis: buildSuiActivityAnalysis(summary.transactions, {
+                truncated: summary.truncated,
+                summary: summary.summary
+            })
+        };
+    }
+    async summarizeSuiActivityScan(input) {
+        const result = await this.scanSuiAccountActivity(input);
+        return {
+            ...result,
+            analysis: buildSuiActivityAnalysis(result.transactions.map((transaction) => ({
+                ...transaction,
+                relationship: result.relationship
+            })), {
+                relationship: result.relationship,
+                windowComplete: result.windowComplete,
+                orderingVerified: result.orderingVerified
+            })
+        };
+    }
+    async summarizeSuiFunctionActivityScan(input) {
+        const result = await this.scanSuiFunctionActivity(input);
+        return {
+            ...result,
+            analysis: buildSuiActivityAnalysis(result.transactions.map((transaction) => ({
+                ...transaction,
+                relationship: result.relationship
+            })), {
+                relationship: result.relationship,
+                windowComplete: result.windowComplete,
+                orderingVerified: result.orderingVerified
+            })
+        };
+    }
+    async verifySource() {
+        try {
+            return await this.options.source.verifyMainnet();
+        }
+        catch (error) {
+            throw this.sourceError(error);
+        }
+    }
+    async resolveActiveAccount() {
+        const active = await this.options.activityStore.getActiveAccount();
+        if (!active) {
+            throw new TransactionActivityError("active_account_not_set", "Active account read context is not set", {
+                action: "connect_wallet_identity"
+            });
+        }
+        return { account: active.address, accountSource: "active_account_context" };
+    }
+    async knownDigestAccountForStorage(explicitAccount, transaction) {
+        const sender = transaction.sender === undefined ? undefined : parseSuiAddress(transaction.sender);
+        if (explicitAccount !== undefined) {
+            const account = await this.options.activityStore.getKnownAccount(explicitAccount);
+            if (!account) {
+                return undefined;
+            }
+            if (explicitAccount === sender) {
+                return { account, relationship: "sent" };
+            }
+            return externalActivityTransactionTouchesAccount(transaction, explicitAccount) ? { account, relationship: "affected" } : undefined;
+        }
+        const active = await this.options.activityStore.getActiveAccount();
+        if (active && active.address === sender) {
+            const account = await this.options.activityStore.getKnownAccount(active.address);
+            return account === undefined ? undefined : { account, relationship: "sent" };
+        }
+        if (active && externalActivityTransactionTouchesAccount(transaction, active.address)) {
+            const account = await this.options.activityStore.getKnownAccount(active.address);
+            return account === undefined ? undefined : { account, relationship: "affected" };
+        }
+        if (sender !== undefined) {
+            const senderAccount = await this.options.activityStore.getKnownAccount(sender);
+            if (senderAccount) {
+                return { account: senderAccount, relationship: "sent" };
+            }
+        }
+        for (const owner of externalActivityTransactionBalanceOwners(transaction)) {
+            const account = await this.options.activityStore.getKnownAccount(owner);
+            if (account) {
+                return { account, relationship: "affected" };
+            }
+        }
+        return undefined;
+    }
+    async transactionInputForKnownAccount(transaction, relationship, storageAccount) {
+        const sender = transaction.sender ? await this.options.activityStore.getKnownAccount(transaction.sender) : undefined;
+        return {
+            digest: transaction.digest,
+            relationship,
+            checkpoint: transaction.checkpoint,
+            timestamp: transaction.timestamp,
+            status: transaction.status,
+            knownSenderAccountId: sender?.id,
+            details: transaction.details === undefined
+                ? undefined
+                : sanitizeExternalActivityTransactionDetailsForKnownAccount(transaction.details, storageAccount)
+        };
+    }
+    async mapSourceCall(call) {
+        try {
+            return await call();
+        }
+        catch (error) {
+            throw this.sourceError(error);
+        }
+    }
+    sourceError(error) {
+        if (error instanceof TransactionActivityError) {
+            return error;
+        }
+        if (error instanceof TransactionActivitySourceError) {
+            return new TransactionActivityError("internal_error", "Sui GraphQL activity source failed", {
+                reason: error.reason,
+                ...error.details
+            });
+        }
+        if (error instanceof SuiEndpointError && error.kind === "chain_identifier_mismatch") {
+            return new TransactionActivityError("network_mismatch", "Sui GraphQL endpoint is not mainnet", {
+                reason: "chain_identifier_mismatch"
+            });
+        }
+        return new TransactionActivityError("internal_error", "Sui GraphQL activity source failed", {
+            message: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+function parseAccount(value) {
+    const normalized = parseSuiAddress(value);
+    if (!normalized) {
+        throw new TransactionActivityError("input_invalid", "Invalid Sui account address", { field: "account" });
+    }
+    return normalized;
+}
+function parseTransactionDigest(value) {
+    const trimmed = value.trim();
+    if (!isValidTransactionDigest(trimmed)) {
+        throw new TransactionActivityError("input_invalid", "Invalid Sui transaction digest", { field: "digest" });
+    }
+    return trimmed;
+}

package/dist/core/activity/transactionActivityTypes.js

@@ -0,0 +1,18 @@
+export class TransactionActivityError extends Error {
+    kind;
+    details;
+    constructor(kind, message, details = {}) {
+        super(message);
+        this.kind = kind;
+        this.details = details;
+    }
+}
+export class TransactionActivitySourceError extends Error {
+    reason;
+    details;
+    constructor(reason, message, details = {}) {
+        super(message);
+        this.reason = reason;
+        this.details = details;
+    }
+}

package/dist/core/eventlog/sink.js

@@ -0,0 +1,35 @@
+import { appendFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+export class NullEventLogSink {
+    async append(_record) { }
+}
+export class NdjsonEventLogSink {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async append(record) {
+        await appendFile(this.filePath, `${JSON.stringify(redactEvent(record))}\n`, "utf8");
+    }
+}
+export function redactEvent(record) {
+    const redacted = {
+        type: record.type,
+        sessionId: record.sessionId,
+        at: record.at
+    };
+    if (record.planId)
+        redacted.planId = record.planId;
+    if (record.walletAddressHash)
+        redacted.walletAddressHash = record.walletAddressHash;
+    if (record.txDigest)
+        redacted.txDigest = record.txDigest;
+    if (record.status)
+        redacted.status = record.status;
+    if (record.reason)
+        redacted.reason = record.reason;
+    return redacted;
+}
+export function hashEventValue(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}

package/dist/core/evidence/settlementFamilies.js

@@ -0,0 +1,87 @@
+import { formatRawAmount, normalizeCoinType } from "../read/coinMetadata.js";
+import { listDeepbookTokenRegistry } from "../read/deepbookRegistry.js";
+import { SUI_USD_SETTLEMENT_ASSET_GROUP_ID } from "../read/readServiceTypes.js";
+const USD_SETTLEMENT_SYMBOLS = new Set(["USDC", "USDT", "WUSDC", "WUSDT", "AUSD", "USDSUI", "SUIUSDE"]);
+export const SUI_USD_SETTLEMENT_ASSETS_ALIASES = [
+    "dollar",
+    "dollars",
+    "usd",
+    "usd-like",
+    "stablecoin",
+    "stablecoins"
+];
+export function normalizeSettlementDenomination(denomination) {
+    const normalized = denomination.trim().toLowerCase();
+    if (normalized === "달러") {
+        return "dollar";
+    }
+    if (SUI_USD_SETTLEMENT_ASSETS_ALIASES.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error("Unsupported settlement denomination");
+}
+export function buildUsdSettlementAssetGroup(coins) {
+    const registry = listDeepbookTokenRegistry(coins);
+    const includedAssets = [];
+    const excludedAssets = [];
+    for (const token of registry) {
+        const coinType = normalizeCoinType(token.type);
+        if (USD_SETTLEMENT_SYMBOLS.has(token.symbol)) {
+            includedAssets.push({
+                symbol: token.symbol,
+                coinType,
+                decimals: token.decimals,
+                unitSource: token.unitSource,
+                poolKeys: [...token.poolKeys]
+            });
+        }
+        else {
+            excludedAssets.push({
+                symbol: token.symbol,
+                coinType,
+                reason: excludedSettlementAssetReason(token.symbol)
+            });
+        }
+    }
+    includedAssets.sort((left, right) => left.symbol.localeCompare(right.symbol));
+    excludedAssets.sort((left, right) => left.symbol.localeCompare(right.symbol));
+    return {
+        id: SUI_USD_SETTLEMENT_ASSET_GROUP_ID,
+        label: "Sui USD-denominated settlement assets",
+        aliases: [...SUI_USD_SETTLEMENT_ASSETS_ALIASES],
+        includedAssets,
+        excludedAssets,
+        evidenceSources: {
+            sdk: "@mysten/deepbook-v3",
+            registry: ["mainnetCoins", "mainnetPools"],
+            network: "mainnet",
+            unitSource: "deepbook_mainnetCoins_scalar"
+        },
+        limitations: [
+            "static_pinned_sdk_registry_not_live_liquidity",
+            "not_fiat_usd_cash_out",
+            "not_payment_execution",
+            "not_route_recommendation",
+            "not_signing_readiness"
+        ]
+    };
+}
+export function commonAssetGroupDecimals(assets) {
+    const decimals = new Set(assets.map((asset) => asset.decimals));
+    return decimals.size === 1 ? assets[0]?.decimals : undefined;
+}
+export function formatSettlementAssetRawAmount(rawAmount, decimals) {
+    return formatRawAmount(rawAmount, decimals);
+}
+function excludedSettlementAssetReason(symbol) {
+    if (symbol === "DEEP") {
+        return "protocol_fee_asset";
+    }
+    if (symbol === "SUI") {
+        return "gas_or_volatile_asset";
+    }
+    if (["BETH", "LZWBTC", "WETH", "WBTC", "XBTC"].includes(symbol)) {
+        return "volatile_or_non_usd_asset";
+    }
+    return "not_in_usd_settlement_asset_group";
+}

package/dist/core/evidence/userAnswerUse.js

@@ -0,0 +1 @@
+export {};

package/dist/core/numeric/rawU64.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+export const MAX_RAW_U64 = (1n << 64n) - 1n;
+const CANONICAL_UNSIGNED_INTEGER_PATTERN = /^(?:0|[1-9][0-9]*)$/;
+const SIGNED_RAW_INTEGER_PATTERN = /^(?:0|-?[1-9][0-9]*)$/;
+export function parseRawU64(value, field, options = {}) {
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`${field} must be an unsigned integer string`);
+    }
+    const amount = BigInt(value);
+    if (options.positive && amount === 0n) {
+        throw new Error(`${field} must be positive`);
+    }
+    if (amount > MAX_RAW_U64) {
+        throw new Error(`${field} must fit u64`);
+    }
+    return amount;
+}
+export function makeRawU64StringSchema(field) {
+    const label = field === "rawAmount" ? "amount" : field;
+    return z.string().min(1).refine((value) => {
+        try {
+            parseRawU64(value, field);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, `Expected a raw u64 ${label} string`);
+}
+export function parseCanonicalRawU64(value, field, options = {}) {
+    if (!CANONICAL_UNSIGNED_INTEGER_PATTERN.test(value)) {
+        throw new Error(`${field} must be a canonical unsigned integer string`);
+    }
+    return parseRawU64(value, field, options);
+}
+export function makeCanonicalRawU64StringSchema(field) {
+    return z.string().min(1).refine((value) => {
+        try {
+            parseCanonicalRawU64(value, field);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, "Expected an unsigned integer string");
+}
+export function parseSignedRawInteger(value, field) {
+    if (!SIGNED_RAW_INTEGER_PATTERN.test(value)) {
+        throw new Error(`${field} must be a signed integer string`);
+    }
+    return BigInt(value);
+}
+export function makeSignedRawIntegerStringSchema(field) {
+    return z.string().min(1).refine((value) => {
+        try {
+            parseSignedRawInteger(value, field);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, "Expected a signed integer string");
+}

package/dist/core/preferences/preferencesStore.js

@@ -0,0 +1,26 @@
+export const LOCAL_SETTING_KEYS = ["suiGrpcUrl", "suiGraphqlUrl"];
+export const SETTINGS_APPLIES_AFTER_RESTART = "mcp_server_restart";
+export class PreferencesStoreError extends Error {
+    kind;
+    details;
+    constructor(kind, message, details = {}) {
+        super(message);
+        this.kind = kind;
+        this.details = details;
+    }
+}
+export class LocalSettingsError extends Error {
+    kind;
+    details;
+    constructor(kind, message, details = {}) {
+        super(message);
+        this.kind = kind;
+        this.details = details;
+    }
+}
+export function assertLocalSettingKey(key) {
+    if (key === "suiGrpcUrl" || key === "suiGraphqlUrl") {
+        return key;
+    }
+    throw new PreferencesStoreError("unknown_key", "Unknown local setting key", { key });
+}