@zktx.io/sui-mcp 0.5.0

package/dist/core/activity/sqliteActivityStoreSchema.js

@@ -0,0 +1,367 @@
+import Database from "better-sqlite3";
+import { EXTERNAL_ACTIVITY_SCAN_MAX_LIMIT } from "./activityStore.js";
+import { DB_USER_VERSION } from "./schemaVersion.js";
+import { ActivityStoreError } from "./sqliteActivityStoreTypes.js";
+import { LIVE_REVIEW_SESSION_INSERT_TRIGGER, LIVE_REVIEW_SESSION_UPDATE_TRIGGER, LIVE_REVIEW_SESSION_WRITE_CONTRACT_VERSION } from "../session/liveReviewSessionContract.js";
+const EXTERNAL_ACTIVITY_SCAN_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_external_activity_scans_account_fetched
+  ON external_activity_scans(account_id, fetched_at)`;
+const CURRENT_SCHEMA_SQL = `
+    CREATE TABLE IF NOT EXISTS accounts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      sui_address TEXT NOT NULL UNIQUE,
+      first_seen_at TEXT NOT NULL,
+      last_used_at TEXT NOT NULL,
+      first_source TEXT NOT NULL CHECK (first_source IN ('wallet_connection', 'review_execution')),
+      last_source TEXT NOT NULL CHECK (last_source IN ('wallet_connection', 'review_execution'))
+    );
+
+    CREATE TABLE IF NOT EXISTS active_account_context (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      account_id INTEGER REFERENCES accounts(id) ON DELETE SET NULL,
+      source TEXT NOT NULL CHECK (source IN ('wallet_connection', 'cleared')),
+      set_at TEXT NOT NULL,
+      wallet_name TEXT,
+      wallet_id TEXT,
+      CHECK (
+        (source = 'cleared' AND account_id IS NULL)
+        OR (source = 'wallet_connection' AND account_id IS NOT NULL)
+      )
+    );
+
+    CREATE TABLE IF NOT EXISTS review_sessions (
+      id TEXT PRIMARY KEY,
+      plan_id TEXT NOT NULL,
+      action_kind TEXT NOT NULL,
+      adapter_id TEXT NOT NULL,
+      protocol TEXT NOT NULL,
+      account_id INTEGER REFERENCES accounts(id) ON DELETE SET NULL,
+      current_status TEXT NOT NULL CHECK (current_status IN ('proposed','awaiting_wallet','wallet_connected','ready_for_wallet_review','refresh_required','blocked','expired')),
+      current_attempt_id TEXT,
+      opened_at TEXT,
+      plan_json TEXT NOT NULL,
+      intent_json TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_review_sessions_account_created
+      ON review_sessions(account_id, created_at);
+
+    CREATE INDEX IF NOT EXISTS idx_review_sessions_status_account
+      ON review_sessions(current_status, account_id, created_at);
+
+    CREATE TABLE IF NOT EXISTS review_state_snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      review_revision INTEGER NOT NULL CHECK (review_revision >= 0),
+      review_session_id TEXT NOT NULL REFERENCES review_sessions(id) ON DELETE RESTRICT,
+      plan_id TEXT NOT NULL,
+      account_id INTEGER NOT NULL REFERENCES accounts(id) ON DELETE RESTRICT,
+      status TEXT NOT NULL CHECK (status IN ('ready_for_wallet_review', 'refresh_required', 'blocked')),
+      blocked_reason TEXT,
+      refresh_reason TEXT,
+      state_json TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      recorded_at TEXT NOT NULL,
+      CHECK (
+        (status = 'blocked' AND blocked_reason IS NOT NULL AND refresh_reason IS NULL)
+        OR (status = 'refresh_required' AND refresh_reason IS NOT NULL AND blocked_reason IS NULL)
+        OR (status = 'ready_for_wallet_review' AND blocked_reason IS NULL AND refresh_reason IS NULL)
+      )
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_review_state_snapshots_session_recorded
+      ON review_state_snapshots(review_session_id, recorded_at);
+
+    CREATE TABLE IF NOT EXISTS review_status_transitions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      review_session_id TEXT NOT NULL REFERENCES review_sessions(id) ON DELETE RESTRICT,
+      event TEXT NOT NULL CHECK (
+        event IN ('created', 'opened', 'wallet_connected', 'state_computed', 'request_admitted', 'request_status_changed', 'signature_verified', 'chain_result_recorded', 'review_update_failed', 'review_invalidated', 'expired')
+      ),
+      attempt_id TEXT,
+      domain TEXT NOT NULL DEFAULT 'review' CHECK (domain IN ('review', 'request')),
+      from_status TEXT,
+      to_status TEXT NOT NULL,
+      account_id INTEGER REFERENCES accounts(id) ON DELETE SET NULL,
+      reason TEXT,
+      transitioned_at TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_review_transitions_session_time
+      ON review_status_transitions(review_session_id, transitioned_at);
+
+    CREATE TABLE IF NOT EXISTS review_requests (
+      attempt_id TEXT PRIMARY KEY,
+      review_session_id TEXT NOT NULL REFERENCES review_sessions(id) ON DELETE RESTRICT,
+      plan_id TEXT NOT NULL,
+      review_revision INTEGER NOT NULL CHECK (review_revision >= 0),
+      account_id INTEGER NOT NULL REFERENCES accounts(id) ON DELETE RESTRICT,
+      transaction_digest TEXT NOT NULL,
+      review_state_json TEXT NOT NULL,
+      request_status TEXT NOT NULL CHECK (request_status IN ('awaiting_signature', 'submitting', 'awaiting_chain_result', 'stopped', 'request_failed', 'outcome_unknown', 'completed')),
+      revision INTEGER NOT NULL CHECK (revision >= 0),
+      reason TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      signature_verified_at TEXT,
+      submitted_at TEXT,
+      UNIQUE (review_session_id, review_revision)
+    );
+    CREATE INDEX IF NOT EXISTS idx_review_requests_session ON review_requests(review_session_id, created_at);
+    CREATE TABLE IF NOT EXISTS review_executions (
+      attempt_id TEXT PRIMARY KEY REFERENCES review_requests(attempt_id) ON DELETE RESTRICT,
+      review_session_id TEXT NOT NULL REFERENCES review_sessions(id) ON DELETE RESTRICT,
+      plan_id TEXT NOT NULL,
+      account_id INTEGER NOT NULL REFERENCES accounts(id) ON DELETE RESTRICT,
+      status TEXT NOT NULL CHECK (status IN ('success', 'failure')),
+      tx_digest TEXT NOT NULL,
+      explorer_url TEXT,
+      failure_reason TEXT CHECK (failure_reason IS NULL OR failure_reason = 'chain_execution_failed'),
+      result_json TEXT NOT NULL,
+      recorded_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      CHECK ((status = 'failure' AND failure_reason IS NOT NULL) OR (status = 'success' AND failure_reason IS NULL))
+    );
+    CREATE INDEX IF NOT EXISTS idx_review_executions_account_updated ON review_executions(account_id, updated_at);
+    CREATE INDEX IF NOT EXISTS idx_review_executions_digest ON review_executions(tx_digest);
+    CREATE TABLE IF NOT EXISTS live_execution_details (
+      attempt_id TEXT PRIMARY KEY REFERENCES review_requests(attempt_id) ON DELETE RESTRICT,
+      model_json TEXT NOT NULL,
+      display_json TEXT
+    );
+    CREATE TABLE IF NOT EXISTS live_wallet_connections (
+      id TEXT PRIMARY KEY,
+      owner_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      revision INTEGER NOT NULL CHECK (revision >= 0),
+      topic TEXT UNIQUE,
+      sdk_pending INTEGER NOT NULL CHECK (sdk_pending IN (0,1)),
+      connection_json TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS live_request_authority (
+      attempt_id TEXT PRIMARY KEY REFERENCES review_requests(attempt_id) ON DELETE RESTRICT,
+      owner_id TEXT NOT NULL,
+      connection_id TEXT NOT NULL REFERENCES live_wallet_connections(id) ON DELETE RESTRICT,
+      connection_revision INTEGER NOT NULL,
+      can_submit INTEGER NOT NULL CHECK (can_submit IN (0,1)),
+      sdk_pending INTEGER NOT NULL CHECK (sdk_pending IN (0,1)),
+      submit_pending INTEGER NOT NULL CHECK (submit_pending IN (0,1)),
+      lookup_pending INTEGER NOT NULL CHECK (lookup_pending IN (0,1)),
+      signature_deadline TEXT NOT NULL,
+      lookup_deadline TEXT,
+      observation_stopped INTEGER NOT NULL DEFAULT 0 CHECK (observation_stopped IN (0,1))
+    );
+
+    ${externalActivityScansTableSql()};
+
+    ${EXTERNAL_ACTIVITY_SCAN_INDEX_SQL};
+
+    CREATE TABLE IF NOT EXISTS external_activity_transactions (
+      account_id INTEGER NOT NULL REFERENCES accounts(id) ON DELETE RESTRICT,
+      digest TEXT NOT NULL,
+      relationship TEXT NOT NULL CHECK (relationship IN ('affected', 'sent')),
+      checkpoint TEXT,
+      timestamp TEXT,
+      status TEXT NOT NULL CHECK (status IN ('success', 'failure', 'unknown')),
+      known_sender_account_id INTEGER REFERENCES accounts(id) ON DELETE SET NULL,
+      first_scan_id TEXT NOT NULL REFERENCES external_activity_scans(scan_id) ON DELETE RESTRICT,
+      last_scan_id TEXT NOT NULL REFERENCES external_activity_scans(scan_id) ON DELETE RESTRICT,
+      first_fetched_at TEXT NOT NULL,
+      last_fetched_at TEXT NOT NULL,
+      detail_json TEXT,
+      PRIMARY KEY (account_id, digest, relationship)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_external_activity_transactions_account_time
+      ON external_activity_transactions(account_id, timestamp);
+
+    CREATE INDEX IF NOT EXISTS idx_external_activity_transactions_digest
+      ON external_activity_transactions(digest);
+
+    CREATE TABLE IF NOT EXISTS local_settings (
+      key TEXT PRIMARY KEY,
+      value_json TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS coin_metadata_cache (
+      coin_type TEXT NOT NULL,
+      chain_identifier TEXT NOT NULL,
+      decimals INTEGER NOT NULL CHECK (decimals >= 0 AND decimals <= 255),
+      symbol TEXT NOT NULL,
+      name TEXT NOT NULL,
+      fetched_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      PRIMARY KEY (coin_type, chain_identifier)
+    );
+
+
+    CREATE TABLE IF NOT EXISTS live_transaction_materials (
+      material_id TEXT PRIMARY KEY,
+      review_session_id TEXT NOT NULL,
+      plan_id TEXT NOT NULL,
+      account TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      source TEXT NOT NULL,
+      transaction_bytes BLOB NOT NULL,
+      redacted_diagnostics_json TEXT,
+      created_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_live_transaction_materials_session
+      ON live_transaction_materials(review_session_id);
+
+    CREATE TABLE IF NOT EXISTS live_review_sessions (
+      id TEXT PRIMARY KEY,
+      token_hash TEXT NOT NULL,
+      status TEXT NOT NULL,
+      account TEXT,
+      owner_id TEXT NOT NULL,
+      review_revision INTEGER NOT NULL DEFAULT 0,
+      preparation_id TEXT,
+      preparation_error TEXT,
+      wallet_connection_id TEXT,
+      wallet_connection_revision INTEGER,
+      current_attempt_id TEXT,
+      plans_json TEXT NOT NULL,
+      review_state_json TEXT,
+      created_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      last_activity_at TEXT NOT NULL,
+      revision INTEGER NOT NULL,
+      write_contract_version TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS live_private_review_artifacts (
+      review_session_id TEXT PRIMARY KEY
+        REFERENCES live_review_sessions(id) ON DELETE CASCADE,
+      artifacts_json TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS live_settings_sessions (
+      id TEXT PRIMARY KEY,
+      session_json TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS live_read_cards (
+      id TEXT PRIMARY KEY,
+      owner_id TEXT NOT NULL,
+      token_hash TEXT NOT NULL,
+      kind TEXT NOT NULL CHECK (kind IN ('account', 'receipt', 'chart', 'connect', 'review')),
+      state TEXT NOT NULL CHECK (state IN ('ready', 'running', 'closed')),
+      reason TEXT CHECK (reason IN ('completed', 'expired', 'failed', 'server_restarted', 'cancelled')),
+      error TEXT,
+      revision INTEGER NOT NULL CHECK (revision >= 0),
+      created_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      input_json TEXT NOT NULL,
+      scope TEXT NOT NULL DEFAULT 'read' CHECK (scope IN ('read', 'connect', 'review', 'review_manage')),
+      operation_id TEXT,
+      accepted_input_json TEXT,
+      result_json TEXT,
+      receipt_display_json TEXT,
+      CHECK ((state = 'closed' AND reason IS NOT NULL) OR (state != 'closed' AND reason IS NULL)),
+      CHECK (state != 'running' OR accepted_input_json IS NOT NULL),
+      CHECK (receipt_display_json IS NULL OR (kind = 'receipt' AND reason = 'completed'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_live_read_cards_owner_state ON live_read_cards(owner_id, state);
+    CREATE TRIGGER IF NOT EXISTS live_read_cards_insert_revision
+    BEFORE INSERT ON live_read_cards WHEN NEW.revision != 0
+    BEGIN SELECT RAISE(ABORT, 'card insert requires revision zero'); END;
+    CREATE TRIGGER IF NOT EXISTS live_read_cards_update_revision
+    BEFORE UPDATE ON live_read_cards WHEN NEW.revision != OLD.revision + 1
+    BEGIN SELECT RAISE(ABORT, 'card update requires the next revision'); END;
+
+    CREATE TRIGGER IF NOT EXISTS ${LIVE_REVIEW_SESSION_INSERT_TRIGGER}
+    BEFORE INSERT ON live_review_sessions
+    FOR EACH ROW
+    WHEN NEW.revision IS NULL
+      OR NEW.revision != 0
+      OR NEW.write_contract_version IS NULL
+      OR NEW.write_contract_version != '${LIVE_REVIEW_SESSION_WRITE_CONTRACT_VERSION}'
+    BEGIN
+      SELECT RAISE(ABORT, 'live review session insert requires the hardened write contract');
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS ${LIVE_REVIEW_SESSION_UPDATE_TRIGGER}
+    BEFORE UPDATE ON live_review_sessions
+    FOR EACH ROW
+    WHEN NEW.revision IS NULL
+      OR OLD.revision IS NULL
+      OR NEW.revision != OLD.revision + 1
+      OR NEW.write_contract_version IS NULL
+      OR NEW.write_contract_version != '${LIVE_REVIEW_SESSION_WRITE_CONTRACT_VERSION}'
+    BEGIN
+      SELECT RAISE(ABORT, 'live review session update requires the hardened write contract');
+    END;
+  `;
+export function configureDatabase(db) {
+    db.exec("PRAGMA journal_mode=WAL");
+    db.exec("PRAGMA synchronous=NORMAL");
+    db.exec("PRAGMA foreign_keys=ON");
+    db.exec("PRAGMA busy_timeout=5000");
+}
+// SQLite normalizes its own DDL. Compare only schema metadata, never user rows.
+// The reference is built once from the single current schema, not from the DB being checked.
+let currentSchemaSignature;
+function schemaSignature(db) {
+    return JSON.stringify(db.prepare("SELECT type, name, tbl_name, sql FROM sqlite_schema WHERE name NOT LIKE 'sqlite_%' ORDER BY type, name").all());
+}
+function expectedSchemaSignature() {
+    if (currentSchemaSignature !== undefined)
+        return currentSchemaSignature;
+    const reference = new Database(":memory:");
+    try {
+        reference.exec(CURRENT_SCHEMA_SQL);
+        currentSchemaSignature = schemaSignature(reference);
+        return currentSchemaSignature;
+    }
+    finally {
+        reference.close();
+    }
+}
+export function assertCurrentDatabaseFormat(db) {
+    const version = db.pragma("user_version", { simple: true });
+    const signature = schemaSignature(db);
+    if (version === 0 && signature === "[]")
+        return "empty";
+    if (version === DB_USER_VERSION && signature === expectedSchemaSignature())
+        return "current";
+    throw new ActivityStoreError("Local database format does not match this runtime. Use a new empty SUI_MCP_DATA_DIR; existing data is not converted or deleted.");
+}
+export function initializeDatabase(db) {
+    if (assertCurrentDatabaseFormat(db) === "current")
+        return;
+    db.transaction(() => {
+        db.exec(CURRENT_SCHEMA_SQL);
+        db.pragma(`user_version = ${DB_USER_VERSION}`);
+    })();
+}
+function externalActivityScansTableSql() {
+    return `CREATE TABLE IF NOT EXISTS external_activity_scans (
+    scan_id TEXT PRIMARY KEY,
+    kind TEXT NOT NULL CHECK (kind IN ('digest_lookup', 'account_scan', 'function_scan')),
+    account_id INTEGER NOT NULL REFERENCES accounts(id) ON DELETE RESTRICT,
+    relationship TEXT NOT NULL CHECK (relationship IN ('affected', 'sent')),
+    input_digest TEXT,
+    from_checkpoint TEXT,
+    to_checkpoint TEXT,
+    from_timestamp TEXT,
+    to_timestamp TEXT,
+    limit_count INTEGER NOT NULL CHECK (limit_count >= 1 AND limit_count <= ${EXTERNAL_ACTIVITY_SCAN_MAX_LIMIT}),
+    request_cursor TEXT,
+    response_cursor TEXT,
+    endpoint_host TEXT NOT NULL,
+    chain_identifier TEXT NOT NULL,
+    fetched_at TEXT NOT NULL,
+    stored_count INTEGER NOT NULL CHECK (stored_count >= 0),
+    skipped_count INTEGER NOT NULL CHECK (skipped_count >= 0),
+    has_more INTEGER NOT NULL CHECK (has_more IN (0, 1)),
+    window_complete INTEGER CHECK (window_complete IN (0, 1)),
+    incomplete_reason TEXT CHECK (
+      incomplete_reason IS NULL
+      OR incomplete_reason IN ('limit_reached', 'ordering_unverified', 'cursor_invalid', 'provider_error')
+    )
+  )`;
+}

package/dist/core/activity/sqliteActivityStoreTypes.js

@@ -0,0 +1,5 @@
+export class ActivityStoreError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}

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,186 @@
+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",
+            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);
+    return {
+        account,
+        scope: "requested_account",
+        role: sentByAccount ? "sender" : "affected_only",
+        sentByAccount,
+        balanceChangeEvidence,
+        accountBalanceChangeInferencePolicy: accountBalanceChangeInferencePolicyFor(balanceChangeEvidence),
+        balanceChangeCompleteness,
+        balanceChanges,
+        coinFlows: coinFlowsForBalanceChanges(balanceChanges),
+        limitations: limitationsForCompleteness(balanceChangeCompleteness)
+    };
+}
+function accountBalanceChangeInferencePolicyFor(evidence) {
+    if (evidence === "account_balance_changes_returned") {
+        return "use_returned_account_balance_changes";
+    }
+    if (evidence === "no_account_balance_changes_returned") {
+        return "no_account_balance_changes_in_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;
+}