@zktx.io/sui-mcp 0.7.0 → 0.8.1

package/dist/core/preferences/sqlitePreferencesRepository.js

@@ -1,5 +1,6 @@
 import { PreferencesStoreError, assertLocalSettingKey } from "./preferencesStore.js";
 import { parseGraphqlUrl, parseGrpcUrl } from "../suiEndpoint.js";
+import { DEFAULT_WALLET_CHAINS, parseWalletChains } from "../session/chainAccounts.js";
 export class SqlitePreferencesRepository {
     db;
     constructor(db) {
@@ -11,6 +12,11 @@ export class SqlitePreferencesRepository {
        ON CONFLICT(key) DO NOTHING`);
         insert.run("suiGrpcUrl", encodeSettingValue("suiGrpcUrl", defaults.suiGrpcUrl), now.toISOString());
         insert.run("suiGraphqlUrl", encodeSettingValue("suiGraphqlUrl", defaults.suiGraphqlUrl), now.toISOString());
+        insert.run("walletConnectionChains", encodeSettingValue("walletConnectionChains", DEFAULT_WALLET_CHAINS), now.toISOString());
+    }
+    getWalletConnectionChainsSync() {
+        const record = this.getLocalSettingSync("walletConnectionChains");
+        return record ? parseWalletChains(record.value) : [...DEFAULT_WALLET_CHAINS];
     }
     async getSuiGrpcUrl() {
         const record = await this.getLocalSetting("suiGrpcUrl");
@@ -92,6 +98,8 @@ function rowToLocalSetting(row) {
     };
 }
 function encodeSettingValue(key, value) {
+    if (key === "walletConnectionChains")
+        return JSON.stringify(parseWalletChains(value));
     if (key === "suiGrpcUrl") {
         if (typeof value !== "string") {
             throw new PreferencesStoreError("invalid_value", "suiGrpcUrl setting value must be a string", { key });
@@ -114,6 +122,8 @@ function decodeSettingValue(key, valueJson) {
     catch {
         throw new PreferencesStoreError("malformed_json", "Malformed local setting JSON", { key });
     }
+    if (key === "walletConnectionChains")
+        return parseWalletChains(parsed);
     if (key === "suiGrpcUrl") {
         return asSuiGrpcUrlValue(parsed);
     }

package/dist/core/session/cardResult.js

@@ -0,0 +1,41 @@
+import { assertNoForbiddenMcpFields } from "../action/forbiddenFields.js";
+import { closedWalletCardSchema, closedReviewCardSchema, REVIEW_BOUNDARY } from "./workflowView.js";
+import { fixedReviewTarget } from "./workflowState.js";
+export function walletCardResult(record, at, input) {
+    return closedWalletCardSchema.parse({ kind: record.state.kind, allowedActions: [], observe: false, actionRemainingMs: 0,
+        result: { message: input.message, recordedAt: at.toISOString(), ...(input.pendingWork ? { pendingWork: input.pendingWork } : {}) },
+        ...(input.connection?.walletName ? { walletName: input.connection.walletName } : {}),
+        networks: (input.connection?.chainResults ?? []).map(({ chainId, status }) => ({ chainId, status })) });
+}
+export function reviewCardResult(record, at, input) {
+    const { session, request, state } = input;
+    if (request && request.reviewSessionId !== record.state.input.reviewSessionId)
+        throw new Error("The request does not belong to this card.");
+    const target = session && !session.plans[0]?.reviewModel ? fixedReviewTarget(session, record.state.input) : undefined;
+    const mode = record.scope === "review_manage" ? "review_manage" : "review";
+    const message = record.state.error ?? (request?.execution ? request.execution.status === "success" ? "Transaction succeeded on Sui." : "Transaction failed on Sui."
+        : mode === "review_manage" && record.state.reason === "expired" ? "This result lookup expired. Ask in chat for a new result card for the same transaction."
+            : input.observationStopped && request && request.requestStatus !== "stopped" ? "Result checking was stopped. This does not cancel the transaction. Ask in chat for a new result card for the same transaction."
+                : request ? request.reason ?? "No chain execution result has been confirmed."
+                    : session?.plans[0]?.reviewModel ? "This proposal review has ended. It provided no wallet approval or execution."
+                        : record.state.reason === "cancelled" ? "This review was cancelled. No approval request was sent."
+                            : record.state.reason === "expired" ? "This review expired. Ask in chat for a new transaction review."
+                                : record.state.reason === "server_restarted" ? "This review ended when the server restarted. Ask in chat for a new transaction review."
+                                    : "This review has ended.");
+    const gas = state?.simulation?.gasCostSummary;
+    const result = closedReviewCardSchema.parse({ kind: "review", mode, allowedActions: [], observe: false, actionRemainingMs: 0,
+        result: { message, recordedAt: at.toISOString() }, boundary: REVIEW_BOUNDARY,
+        ...(target ? { reviewTarget: target } : {}),
+        ...(session?.plans[0] ? { review: { reviewSessionId: session.id, plan: session.plans[0], reviewRevision: request?.reviewRevision ?? session.reviewRevision,
+                status: session.status === "expired" ? "expired" : state?.status ?? session.status, account: state?.account ?? session.account, preparing: false,
+                ...(state ? { state } : {}), ...(session.preparationError ? { error: session.preparationError } : {}) } } : {}),
+        ...(request ? { request } : {}), ...(input.observationStopped ? { observationStopped: true } : {}),
+        ...(input.receipt === undefined ? {} : { receipt: input.receipt }),
+        ...(gas ? { netGasMist: (BigInt(gas.computationCostRaw) + BigInt(gas.storageCostRaw) - BigInt(gas.storageRebateRaw)).toString() } : {}) });
+    assertNoForbiddenMcpFields(result);
+    return result;
+}
+export function endedCardMessage(reason) {
+    return reason === "cancelled" ? "This card was cancelled." : reason === "expired" ? "The input period ended."
+        : reason === "server_restarted" ? "This card ended when the server restarted." : "This card has ended.";
+}

package/dist/core/session/cardSession.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 export const walletDisplaySchema = z.object({
     connectionId: z.string().min(1), pairingUri: z.string().startsWith("wc:"), expiresAt: z.string().datetime()
 }).strict();
-export const cardKindSchema = z.enum(["account", "receipt", "chart", "connect", "review", "settings"]);
+export const cardKindSchema = z.enum(["account", "receipt", "chart", "connect", "disconnect", "review", "settings"]);
 export const cardStateSchema = z.object({
     cardId: z.string().min(1), kind: cardKindSchema,
     state: z.enum(["ready", "running", "closed"]),

package/dist/core/session/cardSessionStore.js

@@ -29,11 +29,13 @@ export class CardStore {
     }
     async create(kind, input, execute = false) {
         this.assertCurrent();
-        const business = kind === "connect" || kind === "review";
-        if (kind === "settings" && (!this.options.settings || execute || Object.keys(input).length))
+        const business = kind === "connect" || kind === "disconnect" || kind === "review";
+        if (kind === "settings" && (!this.options.settings || execute))
             throw new CardError("Settings cards are unavailable for this input.");
         if (business && (!this.options.workflow || execute))
             throw new CardError("This type of card is unavailable.");
+        if (kind === "connect" || kind === "disconnect")
+            input = await this.options.workflow.connectionCardInput(kind, input);
         const parsed = execute ? parseCardInput(kind, input) : undefined;
         let preparation = { status: "ready" };
         if (business) {
@@ -51,23 +53,30 @@ export class CardStore {
         }
         assertNoForbiddenMcpFields({ input, preparation });
         const { base, token } = createLocalSessionBase(this.now(), DEFAULT_SESSION_TTL_MS);
-        const record = { ownerId: this.options.ownerId, tokenHash: base.tokenHash,
-            scope: kind === "settings" ? "settings" : kind === "connect" ? "connect" : kind === "review" ? input.mode === "manage" ? "review_manage" : "review" : "read",
-            ...(kind === "settings" ? { operationId: randomUUID() } : {}),
+        const settingsTarget = input.operationStatus ?? input.backupDelivery;
+        const settingsOperationId = settingsTarget && typeof settingsTarget === "object" && "operationId" in settingsTarget ? String(settingsTarget.operationId) : randomUUID();
+        let record = { ownerId: this.options.ownerId, tokenHash: base.tokenHash,
+            scope: kind === "settings" ? "settings" : kind === "connect" || kind === "disconnect" ? kind : kind === "review" ? input.mode === "manage" ? "review_manage" : "review" : "read",
+            ...(kind === "settings" ? { operationId: settingsOperationId } : {}),
+            ...((kind === "connect" || kind === "disconnect") ? { operationId: String(input.operationId) } : {}),
             ...(kind === "review" && input.mode === "manage" && typeof input.attemptId === "string" ? { operationId: input.attemptId } : {}),
-            state: { cardId: base.id, kind, state: preparation.status === "failed" ? "closed" : "ready", revision: 0,
+            state: { cardId: base.id, kind, state: preparation.status !== "ready" ? "closed" : "ready", revision: 0,
                 createdAt: base.createdAt, expiresAt: base.expiresAt, input,
-                ...(preparation.status === "failed" ? { reason: "failed", error: preparation.error } :
+                ...(preparation.status === "failed" ? { reason: "failed", error: preparation.error } : preparation.status === "completed" ? { reason: "completed" } :
                     preparation.data === undefined ? {} : { data: preparation.data }) } };
+        if (business && record.state.state === "closed")
+            record = this.options.workflow.terminalCard(record);
         if (kind === "settings")
-            this.options.settings.create(record);
+            await this.options.settings.create(record);
         else
             this.options.records.create(record);
+        record = this.current(base.id);
         if (preparation.status === "failed")
             this.reportFailure(record, "input_preparation");
-        const result = parsed === undefined ? await this.describe(record, false) : await this.submit({
-            cardId: base.id, permission: token, revision: 0, input: parsed
-        });
+        const result = kind === "connect" || kind === "disconnect" ? { snapshot: (await this.readWalletOperation(base.id)).card }
+            : parsed === undefined ? await this.describe(record, false) : await this.submit({
+                cardId: base.id, permission: token, revision: 0, input: parsed
+            });
         return { ...result, permission: token };
     }
     async read(input) { return this.describe(this.require(input), true); }
@@ -80,16 +89,27 @@ export class CardStore {
         return this.options.settings.readFile(record, input.fileId, input.offset, limit, input.attemptId);
     }
     async readSaved(cardId) { return (await this.describe(this.current(cardId), false)).snapshot; }
+    async readWalletOperation(cardId) {
+        if (!this.options.workflow)
+            throw new CardError("Wallet operations are unavailable.");
+        const result = this.options.workflow.readOperation(this.current(cardId));
+        return { card: this.snapshot(result.data ? { ...result.record, state: { ...result.record.state, data: result.data } } : result.record, result.evaluatedAt), operation: result.operation,
+            walletAvailability: result.walletAvailability, evaluatedAt: result.evaluatedAt };
+    }
     async describe(record, uiObservation) {
+        if (record.state.state === "closed")
+            return this.response(record);
         if (record.state.kind === "settings") {
             if (!this.options.settings)
                 throw new CardError("Settings cards are unavailable.");
             const described = await this.options.settings.describe(record);
+            if (described.record.state.state === "closed")
+                return this.response(described.record);
             return { snapshot: cardSnapshotSchema.parse({ ...described.record.state, data: described.data,
                     inputRemainingMs: described.record.state.state === "ready" ? Math.max(0, Date.parse(described.record.state.expiresAt) - this.now().getTime()) : 0,
                     pollAfterMs: EXECUTION_POLLING_INTERVAL_SECONDS * 1000 }) };
         }
-        if (record.state.kind !== "connect" && record.state.kind !== "review")
+        if (record.state.kind !== "connect" && record.state.kind !== "disconnect" && record.state.kind !== "review")
             return this.response(record);
         if (!this.options.workflow)
             throw new CardError("Wallet actions are unavailable.");
@@ -97,6 +117,8 @@ export class CardStore {
         const current = view.evaluated.record;
         if (!current)
             throw new CardError("Saved card data is unavailable.");
+        if (current.state.state === "closed")
+            return this.response(current);
         const snapshot = cardSnapshotSchema.parse({ ...current.state, data: view.data,
             inputRemainingMs: view.evaluated.inputRemainingMs,
             pollAfterMs: (current.state.kind === "review" ? EXECUTION_POLLING_INTERVAL_SECONDS : WALLET_CONNECTION_POLL_SECONDS) * 1000 });
@@ -106,13 +128,20 @@ export class CardStore {
     }
     async act(input) {
         const record = this.require(input);
+        if (record.state.state === "closed" && input.input.action !== "settings_report_download") {
+            const normalized = record.state.kind === "settings" ? settingsActionSchema.safeParse(input.input) : undefined;
+            if (isDeepStrictEqual(record.acceptedInput, normalized?.success ? normalized.data : input.input) || record.state.reason === "cancelled" &&
+                (input.input.action === "stop_waiting" || input.input.action === "cancel" || input.input.action === "stop_connection" && input.input.operationId === record.operationId))
+                return this.response(record);
+            return { ...this.response(record), error: { code: "card_conflict", message: "This card has ended. Ask in chat for a new request." } };
+        }
         if (record.state.kind === "settings") {
             if (!this.options.settings)
                 throw new CardError("Settings cards are unavailable.");
             const parsed = settingsActionSchema.safeParse(input.input);
             if (!parsed.success)
                 return { ...await this.describe(record, false), error: { code: "invalid_card_input", message: "This Settings action is not valid." } };
-            if ((parsed.data.action === "settings_confirm" || parsed.data.action === "settings_download_backup") && record.acceptedInput !== undefined && isDeepStrictEqual(record.acceptedInput, parsed.data))
+            if ((parsed.data.action === "settings_confirm" || parsed.data.action === "settings_download_backup" || parsed.data.action === "settings_save_wallet_networks" || parsed.data.action === "settings_clear_read_address") && record.acceptedInput !== undefined && isDeepStrictEqual(record.acceptedInput, parsed.data))
                 return this.describe(record, false);
             if (input.revision !== record.state.revision && !isSettingsDownloadFileAction(parsed.data))
                 return { ...await this.describe(record, false), error: { code: "card_conflict", message: "This Settings selection changed. Review the current selection before continuing." } };
@@ -131,7 +160,7 @@ export class CardStore {
             }
             return this.describe(this.current(input.cardId), false);
         }
-        if ((record.state.kind !== "connect" && record.state.kind !== "review") || !this.options.workflow) {
+        if ((record.state.kind !== "connect" && record.state.kind !== "disconnect" && record.state.kind !== "review") || !this.options.workflow) {
             return this.conflict(record, "This card does not accept wallet workflow actions.");
         }
         let parsed;
@@ -156,11 +185,11 @@ export class CardStore {
                     code: error instanceof WalletUnavailableError ? "wallet_unavailable" : "card_conflict", message: error.message
                 } };
         }
-        return this.describe(this.current(input.cardId), false);
+        return this.describe(this.current(input.cardId), true);
     }
     async submit(input) {
         const record = this.require(input);
-        if (record.state.kind === "connect" || record.state.kind === "review" || record.state.kind === "settings")
+        if (record.state.kind === "connect" || record.state.kind === "disconnect" || record.state.kind === "review" || record.state.kind === "settings")
             throw new CardError("This card does not accept data selections.");
         let parsed;
         try {
@@ -198,7 +227,7 @@ export class CardStore {
         const complete = { ...admitted, ...("receiptDisplay" in projected ? { receiptDisplay: projected.receiptDisplay } : {}),
             state: { ...admitted.state, data: projected.data, state: "closed", reason: "completed", revision: admitted.state.revision + 1 } };
         try {
-            this.options.records.replace(admitted, complete);
+            this.options.records.replace(admitted, complete, this.now());
         }
         catch {
             return this.fail(admitted, "result_storage", "The result could not be saved. This request will not be repeated automatically.");
@@ -210,7 +239,7 @@ export class CardStore {
         this.assertCurrent();
         this.reportFailure(record, stage);
         this.options.records.replace(record, { ...record, state: { ...record.state,
-                state: "closed", reason: "failed", error: message, revision: record.state.revision + 1 } });
+                state: "closed", reason: "failed", error: message, revision: record.state.revision + 1 } }, this.now());
         return this.response(this.current(record.state.cardId));
     }
     reportFailure(record, stage) {
@@ -244,8 +273,11 @@ export class CardStore {
         return snapshot;
     }
     response(record) {
+        if (["connect", "disconnect", "review"].includes(record.state.kind) && record.state.state !== "closed")
+            record = this.options.workflow.expireCard(record);
         const evaluated = this.options.records.evaluate(record, () => this.now());
         record = evaluated.record;
-        return { snapshot: this.snapshot(record, evaluated.evaluatedAt), ...(record.receiptDisplay === undefined ? {} : { receiptDisplay: record.receiptDisplay }) };
+        const receipt = record.state.kind === "review" && record.state.state === "closed" ? this.options.workflow?.closedReceiptDisplay(record) : undefined;
+        return { ...(receipt ?? {}), snapshot: this.snapshot(record, evaluated.evaluatedAt), ...(record.receiptDisplay === undefined ? {} : { receiptDisplay: record.receiptDisplay }) };
     }
 }

package/dist/core/session/chainAccounts.js

@@ -0,0 +1,120 @@
+import { fromBase58 } from "@mysten/sui/utils";
+import { z } from "zod";
+import { parseSuiAddress } from "../suiAddress.js";
+export const WALLET_CHAINS = ["sui:mainnet", "eip155:1", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"];
+export const SUI_MAINNET_WALLET_CHAIN = WALLET_CHAINS[0];
+export const walletChainSchema = z.enum(WALLET_CHAINS);
+export const walletGrantRevisionsSchema = z.record(walletChainSchema, z.number().int().nonnegative());
+export function initialGrantRevisions() {
+    return Object.fromEntries(WALLET_CHAINS.map((chain) => [chain, 0]));
+}
+export const walletChainsSchema = z.array(walletChainSchema).refine((chains) => new Set(chains).size === chains.length, "Networks must be distinct");
+export function parseWalletChains(value) {
+    const selected = new Set(walletChainsSchema.parse(value));
+    return WALLET_CHAINS.filter((chain) => selected.has(chain));
+}
+export const DEFAULT_WALLET_CHAINS = [SUI_MAINNET_WALLET_CHAIN];
+export const WALLET_CHAIN_LABELS = {
+    "sui:mainnet": "Sui", "eip155:1": "Ethereum", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "Solana"
+};
+export function normalizeChainAddress(chainId, value) {
+    if (chainId === SUI_MAINNET_WALLET_CHAIN)
+        return parseSuiAddress(value);
+    if (chainId === "eip155:1")
+        return /^0x[0-9a-fA-F]{40}$/.test(value) ? value.toLowerCase() : undefined;
+    try {
+        return fromBase58(value).length === 32 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const chainAccountSchema = z.object({ chainId: walletChainSchema, address: z.string() }).strict()
+    .refine((value) => normalizeChainAddress(value.chainId, value.address) === value.address, "Expected a normalized chain address");
+export const walletGrantAccountSchema = z.object({ address: z.string(), displayAddress: z.string().optional(),
+    methods: z.array(z.string()), events: z.array(z.string()) }).strict();
+export const walletGrantSchema = z.object({ chainId: walletChainSchema, accounts: z.array(walletGrantAccountSchema),
+    invalidAccounts: z.literal(true).optional() }).strict().superRefine((grant, context) => {
+    if (new Set(grant.accounts.map((a) => a.address)).size !== grant.accounts.length ||
+        grant.invalidAccounts && grant.accounts.length || grant.accounts.some((account) => normalizeChainAddress(grant.chainId, account.address) !== account.address ||
+        account.displayAddress !== undefined && normalizeChainAddress(grant.chainId, account.displayAddress) !== account.address)) {
+        context.addIssue({ code: "custom", message: "Wallet grant accounts must match their chain" });
+    }
+});
+export const walletGrantsSchema = z.array(walletGrantSchema).refine((grants) => new Set(grants.map((grant) => grant.chainId)).size === grants.length, "Wallet grants must have distinct chains");
+export const walletChainResultSchema = z.discriminatedUnion("status", [
+    chainAccountSchema.safeExtend({ status: z.literal("bound") }).strict(),
+    z.object({ chainId: walletChainSchema, status: z.enum(["not_approved", "multiple_accounts", "invalid_response"]) }).strict()
+]);
+export const walletChainResultsSchema = z.array(walletChainResultSchema).refine((results) => new Set(results.map((result) => result.chainId)).size === results.length, "One result per requested chain is required");
+export function fixedChainAccount(connection, chainId) {
+    const result = connection.chainResults.find((item) => item.chainId === chainId);
+    return result?.status === "bound" ? result.address : undefined;
+}
+export function approvedChainResults(chains, grants) {
+    return WALLET_CHAINS.filter((chain) => chains.includes(chain)).map((chainId) => {
+        const grant = grants.find((item) => item.chainId === chainId);
+        if (grant?.invalidAccounts)
+            return { chainId, status: "invalid_response" };
+        if (!grant?.accounts.length)
+            return { chainId, status: "not_approved" };
+        if (grant.accounts.length !== 1)
+            return { chainId, status: "multiple_accounts" };
+        return { chainId, status: "bound", address: grant.accounts[0].address };
+    });
+}
+const namespaceSchema = z.object({ accounts: z.array(z.string()), methods: z.array(z.string()), events: z.array(z.string()) });
+export function normalizeWalletGrants(namespaces) {
+    const chains = new Map();
+    for (const [namespace, value] of Object.entries(namespaces)) {
+        const allowed = WALLET_CHAINS.filter((chain) => namespace === chain || namespace === chain.split(":")[0]);
+        if (!allowed.length)
+            continue;
+        const parsed = namespaceSchema.safeParse(value);
+        const entry = (chain) => {
+            let result = chains.get(chain);
+            if (!result) {
+                result = { invalid: false, accounts: new Map() };
+                chains.set(chain, result);
+            }
+            return result;
+        };
+        if (!parsed.success) {
+            for (const chain of allowed)
+                entry(chain).invalid = true;
+            continue;
+        }
+        for (const caipAccount of parsed.data.accounts) {
+            const chain = allowed.find((id) => caipAccount.startsWith(`${id}:`));
+            if (!chain) {
+                if (!/^[^:]+:[^:]+:.+$/.test(caipAccount))
+                    for (const id of allowed)
+                        entry(id).invalid = true;
+                continue;
+            }
+            const rawAddress = caipAccount.slice(chain.length + 1), address = normalizeChainAddress(chain, rawAddress);
+            const grant = entry(chain);
+            if (!address) {
+                grant.invalid = true;
+                continue;
+            }
+            const prior = grant.accounts.get(address);
+            grant.accounts.set(address, { address,
+                ...(rawAddress === address ? prior?.displayAddress ? { displayAddress: prior.displayAddress } : {} : { displayAddress: rawAddress }),
+                methods: [...new Set([...(prior?.methods ?? []), ...parsed.data.methods])].sort(),
+                events: [...new Set([...(prior?.events ?? []), ...parsed.data.events])].sort() });
+        }
+    }
+    return WALLET_CHAINS.flatMap((chainId) => {
+        const grant = chains.get(chainId);
+        return grant ? [{ chainId, accounts: grant.invalid ? [] : [...grant.accounts.values()].sort((a, b) => a.address.localeCompare(b.address)),
+                ...(grant.invalid ? { invalidAccounts: true } : {}) }] : [];
+    });
+}
+export function walletGrantAccount(grants, chainId, address) {
+    return grants.find((grant) => grant.chainId === chainId)?.accounts.find((account) => account.address === address);
+}
+export function comparableGrantScope(grant) {
+    return grant && { chainId: grant.chainId, invalidAccounts: grant.invalidAccounts,
+        accounts: grant.accounts.map(({ address, methods, events }) => ({ address, methods, events })) };
+}

package/dist/core/session/sessionStore.js

@@ -188,17 +188,13 @@ export class LocalSessionStore {
         if (!normalizedAccount) {
             throw new SessionStoreError("input_invalid", "Invalid wallet account address");
         }
-        const activeAccount = await this.activityStore.getActiveAccount();
-        if (!activeAccount) {
-            throw new SessionStoreError("active_account_not_set", "Review account binding requires an active read account");
-        }
-        if (activeAccount.address !== normalizedAccount) {
-            throw new SessionStoreError("invalid_session_transition", `Review account does not match active read account: ${id}`);
-        }
         const nextSession = cloneLocalSession(session);
         if (session.account && session.account !== normalizedAccount) {
             throw new SessionStoreError("invalid_session_transition", `Review session already bound to a different account: ${id}`);
         }
+        const knownAccount = await this.activityStore.getKnownAccount(normalizedAccount);
+        if (!knownAccount)
+            throw new SessionStoreError("active_account_not_set", "Review account binding requires a known Sui account");
         if (nextSession.status === "proposed") {
             transition(nextSession, "awaiting_wallet");
             transition(nextSession, "wallet_connected");
@@ -239,7 +235,7 @@ export class LocalSessionStore {
     async recordReviewStateInternal(id, state, privateArtifacts, now, preparation) {
         const session = await this.requireMutableSession(id, now);
         if (preparation && (session.preparationId !== preparation.id || session.walletConnectionId !== preparation.connectionId ||
-            session.walletConnectionRevision !== preparation.connectionRevision))
+            session.walletGrantRevision !== preparation.grantRevision))
             this.throwStaleReviewSession(id);
         assertSameSessionId(id, state.reviewSessionId, "Review state");
         assertPlanInSession(session, state.planId);

package/dist/core/session/settingsFileStore.js

@@ -42,16 +42,11 @@ export class SettingsFileStore {
     }
     stagingPath(file) {
         this.assertId(file.fileId);
-        return join(this.directory("staging"), `${file.fileId}.${file.role === "upload" ? "upload" : isSettingsDownloadFile(file) ? "download" : "stage"}`);
-    }
-    finalPath(file) {
-        this.assertId(file.operationId);
-        if (file.role !== "export" || file.relativePath !== `backups/${file.operationId}.json`) {
-            throw new SettingsConflict("The backup location does not match this request.");
+        if (file.role === "export" && !isSettingsDownloadFile(file)) {
+            throw new SettingsConflict("The private backup path does not match this request.");
         }
-        return join(this.directory("backups"), `${file.operationId}.json`);
+        return join(this.directory("staging"), `${file.fileId}.${file.role === "upload" ? "upload" : "download"}`);
     }
-    exportPath(file) { return this.finalPath(file); }
     localBackupPath(file) {
         this.assertId(file.operationId);
         if (!isSettingsDownloadFile(file))
@@ -277,28 +272,6 @@ export class SettingsFileStore {
             throw new SettingsConflict("This file is not the private download snapshot.");
         return this.readVerifiedRange(file, this.directory("staging"), this.stagingPath(file), offset, length);
     }
-    async verifyExport(file) {
-        const directory = this.directory("backups");
-        const info = await lstat(directory);
-        if (!info.isDirectory() || info.isSymbolicLink())
-            throw new SettingsConflict("The local backup directory changed.");
-        const handle = await this.handle(this.finalPath(file), constants.O_RDONLY);
-        try {
-            if ((await handle.stat()).size !== file.totalSize)
-                throw new SettingsConflict("The local backup length changed.");
-            const hash = createHash("sha256");
-            for await (const chunk of handle.createReadStream({ autoClose: false }))
-                hash.update(chunk);
-            if (hash.digest("hex") !== file.sha256)
-                throw new SettingsConflict("The local backup content changed.");
-        }
-        finally {
-            await handle.close();
-        }
-    }
-    async readExportRange(file, offset, length) {
-        return this.readVerifiedRange(file, this.directory("backups"), this.finalPath(file), offset, length);
-    }
     async readVerifiedRange(file, directory, path, offset, length) {
         if (!file.sealed || file.invalidated || !Number.isSafeInteger(offset) || !Number.isSafeInteger(length) ||
             offset < 0 || length < 1 || offset + length > file.totalSize)

package/dist/core/session/settingsOperation.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { assetReadAccountSchema, walletAvailabilitySchema } from "./walletConnection.js";
 import { LOCAL_DATA_EXPORT_FORMAT } from "../activity/localDataTypes.js";
-import { suiAddressStringSchema } from "../suiAddress.js";
+import { walletChainsSchema, parseWalletChains } from "./chainAccounts.js";
 export const SETTINGS_IMPORT_MAX_SIZE = 16 * 1024 * 1024;
 const identity = z.string().uuid();
 const size = z.number().int().nonnegative().safe();
@@ -18,12 +18,22 @@ export const restoreCheckSchema = z.discriminatedUnion("status", [
 ]);
 export const storedRestoreCheckSchema = z.object({ fileId: identity, sha256, totalSize: size, dataEpoch: size,
     userDataRevision: size, check: restoreCheckSchema }).strict();
-export const settingsDraftSchema = z.discriminatedUnion("kind", [
+export const settingsSelectionSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("set_endpoint"), endpoint: z.enum(["grpc", "graphql"]), value: z.string().min(1) }).strict(),
     z.object({ kind: z.literal("restore_endpoint"), endpoint: z.enum(["grpc", "graphql"]) }).strict(),
-    z.object({ kind: z.enum(["clear_read_address", "export_local_data", "download_backup", "import_local_data", "reset_local_data", "restart_wallet_service"]) }).strict()
+    z.object({ kind: z.enum(["import_local_data", "reset_local_data", "restart_wallet_service"]) }).strict()
+]);
+export const settingsDraftSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("clear_read_address") }).strict(),
+    ...settingsSelectionSchema.options,
+    z.object({ kind: z.literal("set_wallet_networks"), chains: walletChainsSchema }).strict(),
+    z.object({ kind: z.literal("download_backup") }).strict()
 ]);
-export const settingsDownloadReportSchema = z.enum(["acknowledged", "not_completed", "unconfirmed", "unsupported"]);
+export const settingsCardInputSchema = z.object({
+    operationStatus: z.object({ operationId: z.string().uuid() }).strict().optional(),
+    backupDelivery: z.object({ operationId: z.string().uuid(), fileId: z.string().uuid() }).strict().optional()
+}).strict().refine((input) => !(input.operationStatus && input.backupDelivery), "Choose exactly one card purpose.");
+export const settingsDownloadReportSchema = z.enum(["acknowledged", "not_completed", "unconfirmed", "unsupported", "not_sent"]);
 export const settingsDownloadFailureSchema = z.object({ method: z.literal("ui/download-file"), code: z.literal(-32601) }).strict();
 export const settingsDownloadEndSchema = z.enum(["acknowledged", "cancelled", "expired", "server_restarted", "data_replaced", "source_unavailable", "stored_locally", "local_save_failed"]);
 export const settingsFileIdentitySchema = z.object({ device: z.string().regex(/^\d+$/), inode: z.string().regex(/^\d+$/) }).strict();
@@ -31,7 +41,7 @@ const localSaveFailure = z.enum(["not_published", "target_conflict", "source_una
 const storedLocalSaveSchema = z.object({ status: z.enum(["needs_consent", "saving", "saved", "failed"]),
     attemptId: identity, fileId: identity, sha256, totalSize: size, destination: z.string(), ownerId: z.string().min(1),
     currentSaveAttemptId: identity.optional(),
-    attempts: z.array(z.object({ saveAttemptId: identity, previousSaveAttemptId: identity.optional(),
+    attempts: z.array(z.object({ saveAttemptId: identity, cardId: z.string().min(1), previousSaveAttemptId: identity.optional(),
         admittedAt: z.string().datetime(), allowPossibleCopy: z.boolean() }).strict()),
     sourceIdentity: settingsFileIdentitySchema.optional(), savedAt: z.string().datetime().optional(), failure: localSaveFailure.optional()
 }).strict().superRefine((value, context) => {
@@ -47,7 +57,7 @@ const storedLocalSaveSchema = z.object({ status: z.enum(["needs_consent", "savin
 });
 export const storedSettingsDownloadSchema = z.object({
     currentAttemptId: identity,
-    attempts: z.array(z.object({ attemptId: identity, admittedAt: z.string().datetime(), previousAttemptId: identity.optional(),
+    attempts: z.array(z.object({ attemptId: identity, cardId: z.string().min(1), admittedAt: z.string().datetime(), previousAttemptId: identity.optional(),
         hostReport: settingsDownloadReportSchema.optional(), failure: settingsDownloadFailureSchema.optional() }).strict()).min(1),
     readyAt: z.string().datetime().optional(), expiresAt: z.string().datetime().optional(), endReason: settingsDownloadEndSchema.optional(),
     localSave: storedLocalSaveSchema.optional()
@@ -69,6 +79,9 @@ export const storedSettingsDownloadSchema = z.object({
 });
 export const settingsDownloadFileActionSchema = z.enum(["settings_retry_download", "settings_report_download", "settings_cancel_download", "settings_store_backup"]);
 export const settingsActionSchema = z.discriminatedUnion("action", [
+    z.object({ action: z.literal("settings_clear_read_address"), operationId: identity, connectionId: z.string().min(1), account: z.string().min(1) }).strict(),
+    z.object({ action: z.literal("settings_save_wallet_networks"), operationId: identity,
+        chains: walletChainsSchema.transform(parseWalletChains), expectedChains: walletChainsSchema.transform(parseWalletChains) }).strict(),
     z.object({ action: z.literal("settings_download_backup"), operationId: identity, attemptId: identity }).strict(),
     z.object({ action: z.literal("settings_retry_download"), operationId: identity, fileId: identity,
         previousAttemptId: identity, attemptId: identity }).strict(),
@@ -77,7 +90,7 @@ export const settingsActionSchema = z.discriminatedUnion("action", [
     z.object({ action: z.literal("settings_store_backup"), operationId: identity, fileId: identity, attemptId: identity,
         saveAttemptId: identity, previousSaveAttemptId: identity.optional(), allowPossibleCopy: z.boolean() }).strict(),
     z.object({ action: z.literal("settings_cancel_download"), operationId: identity, fileId: identity, attemptId: identity }).strict(),
-    z.object({ action: z.literal("settings_select"), draft: settingsDraftSchema }).strict(),
+    z.object({ action: z.literal("settings_select"), draft: settingsSelectionSchema }).strict(),
     z.object({ action: z.literal("settings_prepare"), operationId: identity }).strict(),
     z.object({ action: z.literal("settings_begin_upload"), operationId: identity,
         name: z.string().min(1), totalSize: size.max(SETTINGS_IMPORT_MAX_SIZE), sha256 }).strict(),
@@ -107,7 +120,7 @@ export class SettingsConflict extends Error {
 }
 export const settingsResultSchema = z.object({
     outcome: z.enum(["completed", "failed", "interrupted", "superseded"]), recordedAt: z.string().datetime(),
-    message: z.string().min(1), details: z.record(z.string(), z.unknown()).optional(), completionScope: z.literal("backup_snapshot").optional()
+    message: z.string().min(1), details: z.record(z.string(), z.unknown()).optional(), completionScope: z.literal("backup_delivery").optional()
 }).strict();
 const endpointView = z.object({ storedValue: z.string(), effectiveValue: z.string(),
     source: z.enum(["environment", "local_db", "builtin_default"]), pendingStoredValue: z.string().optional(),
@@ -121,8 +134,7 @@ const localDataCounts = z.object({ accounts: count, reviewSessions: count, revie
     externalActivityTransactions: count, localSettings: count }).strict();
 const importPreview = z.object({ status: z.literal("valid"), format: z.literal(LOCAL_DATA_EXPORT_FORMAT), network: z.literal("mainnet"),
     exportedAt: z.string().datetime(), currentCounts: localDataCounts, incomingCounts: localDataCounts, willReplace: z.literal(true),
-    activeAccountChange: z.enum(["unchanged", "set", "cleared"]), currentReadAddress: suiAddressStringSchema.nullable(),
-    incomingReadAddress: suiAddressStringSchema.nullable(), restartRequiredAfterImport: z.boolean() }).strict();
+    restartRequiredAfterImport: z.boolean() }).strict();
 export const settingsViewSchema = z.object({
     kind: z.literal("settings"), operationId: identity,
     phase: z.enum(["draft", "uploading", "sealed", "prepared", "executing", "stopping", "starting", "terminal"]),
@@ -142,13 +154,13 @@ export const settingsViewSchema = z.object({
     priorRunId: identity.optional(), nextRunId: identity.optional(), supersedesOperationId: identity.optional(), supersededByOperationId: identity.optional(),
     allowedActions: z.array(z.enum(settingsActionSchema.options.map((option) => option.shape.action.value))), observe: z.boolean(),
     facts: z.object({ server: z.object({ name: z.string(), version: z.string(), network: z.literal("mainnet") }).strict(),
-        localSettings: z.object({ suiGrpcUrl: endpointView, suiGraphqlUrl: endpointView }).strict(), readAddress: z.string().optional(),
+        localSettings: z.object({ suiGrpcUrl: endpointView, suiGraphqlUrl: endpointView, walletConnectionChains: walletChainsSchema }).strict(), readAddress: z.string().optional(), readConnectionId: z.string().optional(),
         assetReadAccount: assetReadAccountSchema, walletAvailability: walletAvailabilitySchema,
         connectionReconciliationRequired: z.literal(true).optional(), observedAt: z.string().datetime().optional(),
         counts: localDataCounts }).strict().optional()
 }).strict().superRefine((value, context) => {
     if (value.download && (value.draft?.kind !== "download_backup" || !value.file ||
-        value.download.availability === "available" && (!value.file.sealed || !value.result || value.download.endReason || !value.download.expiresAt) ||
+        value.download.availability === "available" && (!value.file.sealed || value.download.endReason || !value.download.expiresAt) ||
         value.download.availability === "ended" && !value.download.endReason)) {
         context.addIssue({ code: "custom", message: "Download delivery must describe its own snapshot and lifetime." });
     }
@@ -174,20 +186,16 @@ export const settingsViewSchema = z.object({
         (value.phase === "prepared" || value.allowedActions.includes("settings_prepare"))) {
         context.addIssue({ code: "custom", message: "A rejected backup requires an explicit new selection." });
     }
-    if (value.backupLocation && !(value.result?.outcome === "completed" && (value.draft?.kind === "export_local_data" ||
-        value.draft?.kind === "download_backup" && value.download?.localSave?.status === "saved" && value.download.endReason === "stored_locally"))) {
+    if (value.backupLocation && !(value.result?.outcome === "completed" &&
+        value.draft?.kind === "download_backup" && value.download?.localSave?.status === "saved" && value.download.endReason === "stored_locally")) {
         context.addIssue({ code: "custom", message: "A backup location requires its recorded successful export." });
     }
     if (value.download?.localSave?.status === "saved" && !value.backupLocation) {
         context.addIssue({ code: "custom", message: "A saved backup must identify its verified location." });
     }
-    if (value.draft?.kind === "export_local_data" && value.result?.outcome === "completed" &&
-        typeof value.result.details?.path === "string" && !value.backupLocation) {
-        context.addIssue({ code: "custom", message: "A recorded backup path must provide its folder and file name." });
-    }
     if (value.temporaryFileCleanup && !value.result)
         context.addIssue({ code: "custom", message: "Cleanup of an applied or ended operation requires its recorded result." });
-    if ((value.phase === "terminal") !== (value.result !== undefined) || value.phase === "terminal" && (value.observe || value.allowedActions.length)) {
+    if ((value.phase === "terminal") !== (value.result !== undefined) || value.phase === "terminal" && (value.observe || value.allowedActions.length || value.download?.allowedFileActions.length)) {
         context.addIssue({ code: "custom", message: "A terminal Settings result cannot grant input or observation." });
     }
     if (value.phase === "prepared" && (!value.preparationId || !value.draft || !value.preparation))