@zktx.io/sui-mcp 0.6.2 → 0.8.0

package/README.md

@@ -16,7 +16,7 @@ cause another signing or submission request. Request failures and unknown
 outcomes are separate from independently observed chain success/failure.
 
 Account, Receipt and Chart cards provide read-only evidence independently of
-signing. Connect, Review and Settings also run inside the MCP host. Settings
+signing. Connect, Disconnect, Review and Settings also run inside the MCP host. Settings
 provides local data controls and explicit connection-service recovery. Human-readable review is not a guarantee of safety or
 of complete interpretation of every transaction detail; the raw PTB structure
 and addresses remain inspectable.
@@ -27,14 +27,72 @@ Users can ask ordinary questions:
 - "How much are my USD-denominated assets together?"
 - "What is the shortfall?"
 
-This document describes `@zktx.io/sui-mcp@0.6.2`. Confirm that version is
-published before using npm installation commands. For a local build, follow
-[Developer Checkout Setup](docs/MCP_SETUP.md#developer-checkout-setup).
+## Install
+
+Install once with npm, then register the command in each AI app. You need [Node.js 22 or newer](https://nodejs.org/en/download), including npm. No Git checkout, build, custom installation folder, database server, Sui API key or endpoint setup is required for the normal path.
+
+This guide describes **0.8.0**. First confirm it is published, then install that exact version:
+
+```sh
+npm view @zktx.io/sui-mcp@0.8.0 version
+npm install -g @zktx.io/sui-mcp@0.8.0
+```
+
+The first command must return `0.8.0`. If it is unavailable, follow the [version availability guidance](docs/MCP_SETUP.md#npm-command-returns-404); do not drop the version and assume an older release matches this guide. Contributors can use the optional [developer checkout](docs/MCP_SETUP.md#developer-checkout-setup).
+
+Register the installed command in your app. This is the complete default configuration for Claude Desktop; Cursor's example is in the setup guide:
+
+```json
+{
+  "mcpServers": {
+    "sui-mcp": {
+      "command": "sui-mcp"
+    }
+  }
+}
+```
+
+Codex uses TOML in `~/.codex/config.toml` instead:
+
+```toml
+[mcp_servers.sui-mcp]
+command = "sui-mcp"
+```
+
+Keep existing settings and other servers when adding these entries. Choose your app's walkthrough for the file location, registration and startup confirmation:
+
+- [Codex Desktop / CLI](docs/MCP_SETUP.md#codex)
+- [Claude Desktop](docs/MCP_SETUP.md#claude-desktop)
+- [Claude Code](docs/MCP_SETUP.md#claude-code)
+- [Cursor](docs/MCP_SETUP.md#cursor)
+
+After the app loads the registration, ask: **"Use Sui MCP to show its package name, server name, version and network."** Expect `@zktx.io/sui-mcp`, `sui-mcp`, `0.8.0` and `mainnet`. Then ask: **"Use Sui MCP to list the available DeepBook pools on Sui mainnet."** This first read needs no wallet or transaction. The [first-use tutorial](docs/MCP_SETUP.md#first-use-flow) explains expected results, optional cards and wallet connection. If the app cannot find `sui-mcp`, use [Command not found](docs/MCP_SETUP.md#command-not-found).
+
+### Using several apps at once
+
+Codex, Claude Desktop and other local MCP apps can use the same installation at the same time on one computer under the same OS user. Register `sui-mcp` in each app. With defaults, they share the local backend, settings, records and **one current wallet connection**; no separate wallet pairing per app is needed. Changing that connection in one app affects the others, while completed cards keep their original results.
+
+All apps must use the same package release and configuration. Updates require stopping all participating Sui MCP connections before restarting the shared backend. See [Using Multiple Apps](docs/MCP_SETUP.md#using-multiple-apps) for sharing and update conditions. Interactive wallet, Review and Settings workflows require MCP Apps card support; ordinary reads can be used without it.
+
+### Package identity and local data
+
+The npm package is `@zktx.io/sui-mcp`, and its repository is
+`zktx-mcp/sui-mcp`. Confirm the requested version is available before changing
+your client registration.
+
+Use the full scoped package name: the unscoped `sui-mcp` package is a different
+project. Use `sui-mcp` as the default MCP registration name. A client-defined registration
+alias is a local label, not server identity or authorization. Compatible
+updates preserve the current data directory. Incompatible databases and backups
+are rejected without conversion, and files are left in place. Data from a
+different package is not discovered or imported. See the
+[setup guide](docs/MCP_SETUP.md#switching-the-installed-package) for installation
+and shared-server restart instructions.
 
 ## Product Scope in Two Layers
 
-- **Implemented:** Sui mainnet read evidence, non-signable external proposal review, and account-bound DeepBook swap review using protocol-agnostic adapters. Six internal cards use the same SQLite state and permission model. The backend verifies stored material, ownership, quote/policy provenance, human-readable facts, simulation and PTB evidence before an explicit user request. WalletConnect carries bytes only between the backend and wallet; ordinary MCP responses expose facts, request status and observed execution results. Settings owns endpoint and read-address controls, local backup/import/reset, and explicit connection-service recovery. Settings operations require scoped user confirmation; ordinary MCP calls only create the card or read settings.
-- **Never (permanently unsupported at every layer):** no private-key custody, no MCP or AI autonomous execution, no forwarding of opaque external transaction bytes to a wallet, no silent settlement-token or route choice, no fiat cash-out, no P&L, no peg guarantee.
+- **Implemented:** Sui mainnet read evidence, non-signable external proposal review, and account-bound DeepBook swap review using protocol-agnostic adapters. Account, Receipt, Chart, Connect, Disconnect, Review and Settings cards use the same SQLite state and scoped permission model. The backend verifies stored material, ownership, quote/policy provenance, human-readable facts, simulation and PTB evidence before an explicit user request. WalletConnect carries bytes only between the backend and wallet; ordinary MCP responses expose facts, request status and observed execution results. Settings owns endpoint and read-address controls, local backup/import/reset, and explicit connection-service recovery. Settings operations require scoped user confirmation; ordinary MCP calls only create the card or read settings.
+- **Safety boundaries:** no private-key custody, no MCP or AI autonomous execution, no forwarding of opaque external transaction bytes to a wallet, and no peg guarantee. The current product does not silently choose settlement tokens or routes. It does not provide fiat cash-out, P&L, tax or cost-basis support.
 
 DeepBook provides the current scoped Sui conversion, price, and orderbook
 evidence through the shared protocol adapter contracts. Wallet and Sui balance reads
@@ -92,22 +150,33 @@ The current release can run as a local stdio MCP server and expose mainnet Sui D
 It also includes:
 
 - a local review server bound to `127.0.0.1`;
-- a local SQLite store for active account read context and review evidence;
+- a local SQLite store for chain-qualified address history and review evidence;
 - MCP output checks that reject forbidden executable, signing, token, seed, and
   key-material field names from responses.
 
 ## Screens
 
-**Wallet connection.** Connect one Sui mainnet wallet and use one of its approved
-addresses. A manage card shows Connect wallet when no connection is active;
-opening it alone does not pair. A connect-intent card starts pairing after its
-View confirms permission and current state. Each disconnection requires the
-user to confirm its exact target. Connection is not transaction approval.
-
-
-**Review and result.** The internal Review card automatically prepares and renews verified conditions for one selected wallet/account. Users inspect its transaction graph, amounts and costs, then choose Request wallet approval and approve in their wallet. One wallet connection is used at a time; choose among its approved addresses when needed. Conflicting saved connections must be resolved through targeted disconnection. Failed preparation has an explicit retry. Receipt and completed Review show the executed transaction graph, actual asset changes and net network fee. Supplementary facts are in one Details slide; earlier estimates in Review remain distinct from actual chain results. Missing graph or receipt data is marked unavailable. Cards use a single document layout without nested card panels.
-
-**DeepBook USDC chart.** `ui.open_chart` opens an internal MCP Apps card with
+**Wallet connection.** One WalletConnect connection provides one fixed address
+per approved chain. Settings chooses networks for the next connection, defaulting
+to Sui. The wallet may return a subset. Sui, Ethereum and Solana mainnet addresses
+are supported; financial actions remain Sui-only. A chain returning multiple
+addresses is unavailable for that connection; there is no account selector.
+Changing the wallet, address or network scope requires disconnecting and connecting
+again. Connect and Disconnect are separate purpose cards. Connect starts one
+pairing after authenticated View confirmation; Disconnect asks for one exact-target
+confirmation. Ended cards show a fixed address-free result and accept no further
+operation. Current addresses are available through read-only connection status.
+Connection is not transaction approval.
+
+**Review and result.** The Review card prepares and renews verified conditions for
+its fixed Sui account and connection. Disconnecting and reconnecting cannot retarget an
+existing review. A replacement connection requires a new review. Users inspect the graph,
+amounts and costs, then choose Request wallet approval and approve in their wallet.
+Failed preparation has an explicit retry. Receipt and completed Review show the
+executed graph, observed asset changes and net network fee. Details supplements
+the same facts. Missing graph or receipt data is marked unavailable.
+
+**DeepBook USDC chart.** `ui_open_chart` opens an internal MCP Apps card with
 official DeepBookV3 Indexer candles and volume for one selected USDC pool.
 The saved result shows the selected pair, interval, UTC period and source time. Limited and empty results are identified.
 
@@ -156,11 +225,11 @@ These product behaviors are out of scope in the current release by design:
 
 ### Quote Response Limits
 
-Quote tools such as `read.quote_deepbook_action` and
-`read.quote_deepbook_display_amount` return scoped quote facts and raw quote
+Quote tools such as `read_quote_deepbook_action` and
+`read_quote_deepbook_display_amount` return scoped quote facts and raw quote
 evidence only.
 
-Their semantics mark quote output as price evidence, not payment coverage or shortfall evidence. Coverage and shortfall answers come from `read.preview_intent_evidence.responseSummary`.
+Their semantics mark quote output as price evidence, not payment coverage or shortfall evidence. Coverage and shortfall answers come from `read_preview_intent_evidence.responseSummary`.
 
 For quote responses alone, these conclusions are unsupported:
 
@@ -180,33 +249,6 @@ For quote responses alone, these conclusions are unsupported:
 - cost basis is not available;
 - actionable signing data is not available.
 
-## Install
-
-Use the checkout setup above for unpublished changes. A local commit or successful
-package check does not publish a release.
-
-This release uses npm package `@zktx.io/sui-mcp` and MCP Registry name
-`io.github.zktx-mcp/sui-mcp`. Once the requested version is published,
-install through your client's registry support or run `npx -y @zktx.io/sui-mcp`.
-For per-client configuration (Claude Code, Claude Desktop, Codex, Cursor) and
-running from a local checkout, see [docs/MCP_SETUP.md](docs/MCP_SETUP.md).
-
-### Package identity and local data
-
-The npm package is `@zktx.io/sui-mcp`, and its repository is
-`zktx-mcp/sui-mcp`. Confirm the requested version is available before changing
-your client registration.
-
-Use the full scoped package name: the unscoped `sui-mcp` package is a different
-project. Keep the MCP registration name `sui-mcp`, without a suffix. Compatible
-updates preserve the current data directory. Incompatible databases and backups
-are rejected without conversion, and files are left in place. Data from a
-different package is not discovered or imported. See the
-[setup guide](docs/MCP_SETUP.md#switching-the-installed-package) for installation
-and shared-server restart instructions.
-
-After the MCP server is connected, use [docs/MCP_SETUP.md](docs/MCP_SETUP.md#first-use-flow) for first-use setup, [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) for API fields and statuses, and [docs/AGENT_BEHAVIOR.md](docs/AGENT_BEHAVIOR.md) for user-question flow and response wording.
-
 ## Mainnet-Only Product Surface
 
 Product docs, registry, AI responses, UX copy, and signable actions are mainnet-only.
@@ -217,11 +259,11 @@ Unsupported protocol experiments are not product functionality and are not inclu
 
 The canonical MCP API reference lives in [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).
 
-The server also exposes `read.get_server_status`. It returns the package version, evidence policy version, `implementedToolsCount`, and implemented tool list at runtime.
+The server also exposes `read_get_server_status`. It returns the package version, evidence policy version, `implementedToolsCount`, and implemented tool list at runtime.
 
-DeepBook pool-price context is exposed through `read.get_deepbook_mid_price`. Use `docs/MCP_TOOLS.md` for the response fields and unsupported conclusions.
+DeepBook pool-price context is exposed through `read_get_deepbook_mid_price`. Use `docs/MCP_TOOLS.md` for the response fields and unsupported conclusions.
 
-Tool names use dot prefixes because the MCP spec recommends ASCII letters, digits, underscore, hyphen, and dot for tool names. `action.prepare_sui_action_review` returns a `reviewSessionId` and an internal `card`; it does not return executable transaction bytes.
+Tool names use `domain_verb_object`. Names identify an operation; its schema, card visibility and permission checks define its authority. `action_start_review` returns a `reviewSessionId` and an internal `card`; it does not request a signature, submit a transaction or return executable transaction bytes.
 
 ## Documentation Map
 
@@ -237,7 +279,7 @@ Runtime-facing MCP resources currently include:
 - `protocols/deepbook-v3.md`;
 - `protocols/deepbook-margin.md`.
 
-Protocol resources are explanatory references. Current support is declared by `read.get_server_status`, `read.list_supported_protocols`, concrete tool schemas, and concrete tool responses, not by protocol Markdown alone.
+Protocol resources are explanatory references. Current support is declared by `read_get_server_status`, `read_list_supported_protocols`, concrete tool schemas, and concrete tool responses, not by protocol Markdown alone.
 
 Development-only or release-review documents can define contributor rules and checks.
 
@@ -248,7 +290,7 @@ AI client answer behavior must be mirrored in runtime-facing instructions, resou
 - `docs/MCP_TOOLS.md`: API reference: tool contracts, response fields, statuses, follow-up fields, and output boundaries.
 - `docs/AGENT_BEHAVIOR.md`: Answer playbook: user-question flows, tool selection, and response wording boundaries.
 - `docs/WALLET_CONNECTION.md`: Wallet connection reference: active read context, private SDK ownership and user-approved transaction requests.
-- `protocols/deepbook-v3.md`: Protocol reference only; use MCP tool responses and read.list_supported_protocols for current support.
+- `protocols/deepbook-v3.md`: Protocol reference only; use MCP tool responses and read_list_supported_protocols for current support.
 - `protocols/deepbook-margin.md`: Protocol reference only; no margin MCP read tools or signable actions are exposed in this release.
 - `docs/TRANSACTION_ACTIVITY_LOG.md`: transaction activity evidence, storage, scan, and summary boundaries.
 - `docs/UTILITY_INDEX.md`: manual maintainer and developer utilities. Utility rows are not MCP tools unless they explicitly name an MCP tool, and source-checkout scripts are not packaged product commands.

package/dist/adapters/adapterPromptSurfaces.js

@@ -35,6 +35,6 @@ export const ADAPTER_PROMPT_SURFACES = [
         description: 'Prepare a reviewable DeepBook mainnet swap from a one-line intent, e.g. "10 sui to usdc".',
         intentArgDescription: 'Swap intent in one line, any language, e.g. "10 sui to usdc" or "10 수이 usdc로 환전"',
         exampleIntents: ["10 sui to usdc", "10 수이 usdc로 환전"],
-        toolName: "action.prepare_sui_action_review"
+        toolName: "action_start_review"
     }
 ];

package/dist/core/activity/localDataService.js

@@ -1,8 +1,9 @@
+import { DEFAULT_WALLET_CHAINS } from "../session/chainAccounts.js";
 import { SETTINGS_DOWNLOAD_FILE_SQL, SETTINGS_FILE_CLEANUP_SQL } from "../session/settingsFileIdentity.js";
 import { hasUnsettledWalletWork } from "../session/sqliteWalletWorkflowStore.js";
 import { SuiEndpointError, parseGraphqlUrl, parseGrpcUrl } from "../suiEndpoint.js";
 import { LOCAL_DATA_EXPORT_FORMAT, LOCAL_DATA_NETWORK, LocalDataError } from "./localDataTypes.js";
-import { activeAccountChange, activeAccountAddress, countsForPayload, invalidBackup, maxNumber, parseLocalDataEnvelope, suiGraphqlUrlFromPayload, suiGrpcUrlFromPayload } from "./localDataValidation.js";
+import { countsForPayload, invalidBackup, maxNumber, parseLocalDataEnvelope, suiGraphqlUrlFromPayload, suiGrpcUrlFromPayload } from "./localDataValidation.js";
 export * from "./localDataTypes.js";
 export class SqliteLocalDataService {
     db;
@@ -32,7 +33,6 @@ export class SqliteLocalDataService {
                 exportedAt: now.toISOString(),
                 data: {
                     accounts: this.selectAll("accounts"),
-                    activeAccountContext: this.selectAll("active_account_context"),
                     reviewSessions: this.selectAll("review_sessions"),
                     reviewStateSnapshots: this.selectAll("review_state_snapshots"),
                     reviewStatusTransitions: this.selectAll("review_status_transitions"),
@@ -55,8 +55,6 @@ export class SqliteLocalDataService {
         });
         return this.db.transaction(() => {
             this.options.advanceRequestDeadlines(now);
-            const currentAccounts = this.selectAll("accounts");
-            const currentContext = this.selectAll("active_account_context");
             return {
                 status: "valid",
                 format: envelope.format,
@@ -65,9 +63,6 @@ export class SqliteLocalDataService {
                 currentCounts: this.getDataCountsSync(),
                 incomingCounts: countsForPayload(envelope.data),
                 willReplace: true,
-                activeAccountChange: activeAccountChange(currentAccounts, currentContext, envelope.data.accounts, envelope.data.activeAccountContext),
-                currentReadAddress: activeAccountAddress(currentAccounts, currentContext),
-                incomingReadAddress: activeAccountAddress(envelope.data.accounts, envelope.data.activeAccountContext),
                 restartRequiredAfterImport: true,
             };
         }).immediate();
@@ -89,7 +84,6 @@ export class SqliteLocalDataService {
         this.resetLocalDataTables(preserveCardId);
         if (envelope) {
             this.insertAccounts(envelope.data.accounts);
-            this.insertActiveAccountContext(envelope.data.activeAccountContext);
             this.insertReviewSessions(envelope.data.reviewSessions);
             this.insertReviewStateSnapshots(envelope.data.reviewStateSnapshots);
             this.insertReviewRequests(envelope.data.reviewRequests);
@@ -121,6 +115,7 @@ export class SqliteLocalDataService {
         }
         else
             this.db.prepare("DELETE FROM live_read_cards").run();
+        this.db.prepare("DELETE FROM wallet_connection_operations WHERE sdk_pending=0 AND status!='running' AND card_id NOT IN (SELECT id FROM live_read_cards)").run();
         for (const table of [
             "live_execution_details",
             "live_request_authority",
@@ -135,7 +130,6 @@ export class SqliteLocalDataService {
             "review_requests",
             "review_sessions",
             "coin_metadata_cache",
-            "active_account_context",
             "accounts",
             "local_settings"
         ]) {
@@ -148,6 +142,7 @@ export class SqliteLocalDataService {
        VALUES (?, ?, ?)`);
         statement.run("suiGrpcUrl", JSON.stringify(parseGrpcUrl(this.options.suiGrpcUrl)), now.toISOString());
         statement.run("suiGraphqlUrl", JSON.stringify(parseGraphqlUrl(this.options.suiGraphqlUrl)), now.toISOString());
+        statement.run("walletConnectionChains", JSON.stringify(DEFAULT_WALLET_CHAINS), now.toISOString());
     }
     getDataCountsSync() {
         return {
@@ -170,18 +165,10 @@ export class SqliteLocalDataService {
         return this.db.prepare(`SELECT * FROM ${table} ORDER BY rowid ASC`).all();
     }
     insertAccounts(rows) {
-        const statement = this.db.prepare(`INSERT INTO accounts (id, sui_address, first_seen_at, last_used_at, first_source, last_source)
-       VALUES (?, ?, ?, ?, ?, ?)`);
-        for (const row of rows) {
-            statement.run(row.id, row.sui_address, row.first_seen_at, row.last_used_at, row.first_source, row.last_source);
-        }
-    }
-    insertActiveAccountContext(rows) {
-        const statement = this.db.prepare(`INSERT INTO active_account_context (id, account_id, source, set_at, wallet_name, wallet_id)
-       VALUES (?, ?, ?, ?, ?, ?)`);
-        for (const row of rows) {
-            statement.run(row.id, row.account_id, row.source, row.set_at, row.wallet_name ?? null, row.wallet_id ?? null);
-        }
+        const statement = this.db.prepare(`INSERT INTO accounts (id,chain_id,address,first_seen_at,last_used_at,first_source,last_source)
+      VALUES (?,?,?,?,?,?,?)`);
+        for (const row of rows)
+            statement.run(row.id, row.chain_id, row.address, row.first_seen_at, row.last_used_at, row.first_source, row.last_source);
     }
     insertReviewSessions(rows) {
         const statement = this.db.prepare(`INSERT INTO review_sessions

package/dist/core/activity/localDataValidation.js

@@ -1,10 +1,11 @@
+import { walletChainSchema, walletChainsSchema, normalizeChainAddress, SUI_MAINNET_WALLET_CHAIN } from "../session/chainAccounts.js";
+import { LOCAL_SETTING_KEYS } from "../preferences/preferencesStore.js";
 import { transactionRequestStatusSchema, transactionRequestSchema } from "../session/transactionRequest.js";
 import { REVIEW_TRANSITION_EVENTS } from "./sqliteActivityStoreRows.js";
 import { z } from "zod";
 import { assertNoForbiddenMcpFields } from "../action/forbiddenFields.js";
 import { parseLifecycleValidatedReviewState } from "../action/reviewStateValidation.js";
 import { actionPlanSchema, transactionExecutionSummarySchema, internalSessionStatusSchema } from "../action/schemas.js";
-import { parseSuiAddress } from "../suiAddress.js";
 import { parseGraphqlUrl, parseGrpcUrl } from "../suiEndpoint.js";
 import { EXTERNAL_ACTIVITY_TRANSACTION_DETAIL_JSON_MAX_BYTES, externalActivityTransactionDetailJsonByteLength, externalActivityTransactionDetailSchema, externalActivityTransactionDetailsReferenceOnlyAccount } from "./transactionActivityDetails.js";
 import { LOCAL_DATA_EXPORT_FORMAT, LOCAL_DATA_NETWORK, LocalDataError } from "./localDataTypes.js";
@@ -15,20 +16,14 @@ const isoTimestamp = z.string().refine((value) => {
 const nullableString = z.string().nullable();
 const accountRowSchema = z.object({
     id: z.number().int().positive(),
-    sui_address: z.string().refine((value) => parseSuiAddress(value) === value, "must be a normalized Sui address"),
+    chain_id: walletChainSchema,
+    address: z.string(),
     first_seen_at: isoTimestamp,
     last_used_at: isoTimestamp,
     first_source: z.enum(["wallet_connection", "review_execution"]),
     last_source: z.enum(["wallet_connection", "review_execution"])
-}).strict();
-const activeAccountContextRowSchema = z.object({
-    id: z.literal(1),
-    account_id: z.number().int().positive().nullable(),
-    source: z.enum(["wallet_connection", "cleared"]),
-    set_at: isoTimestamp,
-    wallet_name: z.string().min(1).max(200).nullish(),
-    wallet_id: z.string().min(1).max(200).nullish()
-}).strict();
+}).strict().refine((row) => normalizeChainAddress(row.chain_id, row.address) === row.address &&
+    (row.chain_id === SUI_MAINNET_WALLET_CHAIN || row.first_source !== "review_execution" && row.last_source !== "review_execution"), "Account identity and source must match the supported chain");
 const reviewSessionRowSchema = z.object({
     id: z.string().min(1),
     plan_id: z.string().min(1),
@@ -126,13 +121,12 @@ const externalActivityTransactionRowSchema = z.object({
     detail_json: z.string().nullable()
 }).strict();
 const localSettingRowSchema = z.object({
-    key: z.enum(["suiGrpcUrl", "suiGraphqlUrl"]),
+    key: z.enum(LOCAL_SETTING_KEYS),
     value_json: z.string(),
     updated_at: isoTimestamp
 }).strict();
 const payloadSchema = z.object({
     accounts: z.array(accountRowSchema),
-    activeAccountContext: z.array(activeAccountContextRowSchema).max(1),
     reviewSessions: z.array(reviewSessionRowSchema),
     reviewStateSnapshots: z.array(reviewStateSnapshotRowSchema),
     reviewStatusTransitions: z.array(reviewStatusTransitionRowSchema),
@@ -140,7 +134,7 @@ const payloadSchema = z.object({
     reviewRequests: z.array(reviewRequestRowSchema),
     externalActivityScans: z.array(externalActivityScanRowSchema),
     externalActivityTransactions: z.array(externalActivityTransactionRowSchema),
-    localSettings: z.array(localSettingRowSchema).length(2)
+    localSettings: z.array(localSettingRowSchema).length(LOCAL_SETTING_KEYS.length)
 }).strict();
 const envelopeSchema = z.object({
     format: z.literal(LOCAL_DATA_EXPORT_FORMAT),
@@ -160,7 +154,7 @@ export function parseLocalDataEnvelope(input, options) {
 }
 function validatePayloadSemantics(data, validateAdapterLifecycle) {
     ensureUnique(data.accounts.map((row) => row.id), "duplicate_account_id");
-    ensureUnique(data.accounts.map((row) => row.sui_address), "duplicate_account_address");
+    ensureUnique(data.accounts.map((row) => `${row.chain_id}:${row.address}`), "duplicate_account_address");
     ensureUnique(data.reviewSessions.map((row) => row.id), "duplicate_review_session_id");
     ensureUnique(data.reviewStateSnapshots.map((row) => row.id), "duplicate_review_state_snapshot_id");
     ensureUnique(data.reviewStatusTransitions.map((row) => row.id), "duplicate_review_transition_id");
@@ -170,26 +164,18 @@ function validatePayloadSemantics(data, validateAdapterLifecycle) {
     ensureUnique(data.localSettings.map((row) => row.key), "duplicate_local_setting_key");
     ensureUnique(data.reviewRequests.map((row) => row.attempt_id), "duplicate_review_request_id");
     ensureUnique(data.reviewRequests.map((row) => `${row.review_session_id}:${row.review_revision}`), "duplicate_review_request_revision");
-    const accountIds = new Set(data.accounts.map((row) => row.id));
-    const accountAddressesById = new Map(data.accounts.map((row) => [row.id, row.sui_address]));
-    for (const row of data.activeAccountContext) {
-        if (row.source === "cleared" && row.account_id !== null) {
-            throw invalidBackup("invalid_active_account_context");
-        }
-        if (row.source === "wallet_connection" && (row.account_id === null || !accountIds.has(row.account_id))) {
-            throw invalidBackup("invalid_active_account_context");
-        }
-    }
+    const suiAccountIds = new Set(data.accounts.filter((row) => row.chain_id === SUI_MAINNET_WALLET_CHAIN).map((row) => row.id));
+    const accountAddressesById = new Map(data.accounts.map((row) => [row.id, row.address]));
     for (const row of data.reviewSessions) {
         validateJsonColumn(row.plan_json, "plan_json", actionPlanSchema);
         validateOptionalJsonColumn(row.intent_json, "intent_json");
-        if (row.account_id !== null && !accountIds.has(row.account_id)) {
+        if (row.account_id !== null && !suiAccountIds.has(row.account_id)) {
             throw invalidBackup("invalid_review_session_account");
         }
     }
     const reviewSessionIds = new Set(data.reviewSessions.map((row) => row.id));
     for (const row of data.reviewStateSnapshots) {
-        if (!reviewSessionIds.has(row.review_session_id) || !accountIds.has(row.account_id)) {
+        if (!reviewSessionIds.has(row.review_session_id) || !suiAccountIds.has(row.account_id)) {
             throw invalidBackup("invalid_review_state_snapshot_reference");
         }
         if (row.status === "blocked" && (row.blocked_reason === null || row.refresh_reason !== null)) {
@@ -242,7 +228,7 @@ function validatePayloadSemantics(data, validateAdapterLifecycle) {
             throw invalidBackup("invalid_review_open_time");
     }
     for (const row of data.reviewStatusTransitions) {
-        if (!reviewSessionIds.has(row.review_session_id) || (row.account_id !== null && !accountIds.has(row.account_id)))
+        if (!reviewSessionIds.has(row.review_session_id) || (row.account_id !== null && !suiAccountIds.has(row.account_id)))
             throw invalidBackup("invalid_review_transition_reference");
         const requestEvent = ["request_admitted", "request_status_changed", "signature_verified", "chain_result_recorded"].includes(row.event);
         if ((row.domain === "request") !== requestEvent)
@@ -270,7 +256,7 @@ function validatePayloadSemantics(data, validateAdapterLifecycle) {
     }
     const scanIds = new Set(data.externalActivityScans.map((row) => row.scan_id));
     for (const row of data.externalActivityScans) {
-        if (!accountIds.has(row.account_id)) {
+        if (!suiAccountIds.has(row.account_id)) {
             throw invalidBackup("invalid_external_activity_scan_account");
         }
         if (row.from_timestamp !== null && row.to_timestamp !== null && row.from_timestamp > row.to_timestamp) {
@@ -281,10 +267,10 @@ function validatePayloadSemantics(data, validateAdapterLifecycle) {
         }
     }
     for (const row of data.externalActivityTransactions) {
-        if (!accountIds.has(row.account_id) || !scanIds.has(row.first_scan_id) || !scanIds.has(row.last_scan_id)) {
+        if (!suiAccountIds.has(row.account_id) || !scanIds.has(row.first_scan_id) || !scanIds.has(row.last_scan_id)) {
             throw invalidBackup("invalid_external_activity_transaction_reference");
         }
-        if (row.known_sender_account_id !== null && !accountIds.has(row.known_sender_account_id)) {
+        if (row.known_sender_account_id !== null && !suiAccountIds.has(row.known_sender_account_id)) {
             throw invalidBackup("invalid_external_activity_sender_reference");
         }
         if (row.detail_json !== null) {
@@ -310,6 +296,11 @@ function validatePayloadSemantics(data, validateAdapterLifecycle) {
     }
     for (const row of data.localSettings) {
         const value = validateJsonColumn(row.value_json, "local_settings.value_json");
+        if (row.key === "walletConnectionChains") {
+            if (!walletChainsSchema.safeParse(value).success)
+                throw invalidBackup("invalid_wallet_connection_chains");
+            continue;
+        }
         if (typeof value !== "string") {
             throw invalidBackup(row.key === "suiGrpcUrl" ? "invalid_sui_grpc_url" : "invalid_sui_graphql_url");
         }
@@ -417,21 +408,6 @@ export function countsForPayload(data) {
         localSettings: data.localSettings.length
     };
 }
-export function activeAccountChange(currentAccounts, current, incomingAccounts, incoming) {
-    const currentAccount = activeAccountAddress(currentAccounts, current);
-    const incomingAccount = activeAccountAddress(incomingAccounts, incoming);
-    if (currentAccount === incomingAccount) {
-        return "unchanged";
-    }
-    return incomingAccount === null ? "cleared" : "set";
-}
-export function activeAccountAddress(accounts, context) {
-    const accountId = context[0]?.account_id ?? null;
-    if (accountId === null) {
-        return null;
-    }
-    return accounts.find((account) => account.id === accountId)?.sui_address ?? null;
-}
 export function maxNumber(values) {
     return values.reduce((max, value) => Math.max(max, value), 0);
 }

package/dist/core/activity/sqliteAccountStore.js

@@ -0,0 +1,46 @@
+import { normalizeChainAddress, fixedChainAccount } from "../session/chainAccounts.js";
+import { walletConnectionSchema } from "../session/walletConnection.js";
+import { ActivityStoreError } from "./sqliteActivityStoreTypes.js";
+export class SqliteAccountStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    get(chainId, address) {
+        const normalized = normalizeChainAddress(chainId, address);
+        if (!normalized)
+            throw new ActivityStoreError("Invalid chain account address");
+        const row = this.db.prepare("SELECT * FROM accounts WHERE chain_id=? AND address=?").get(chainId, normalized);
+        return row && this.account(row);
+    }
+    upsert(chainId, address, source, timestamp) {
+        const normalized = normalizeChainAddress(chainId, address);
+        if (!normalized)
+            throw new ActivityStoreError("Invalid chain account address");
+        this.db.prepare(`INSERT INTO accounts (chain_id,address,first_seen_at,last_used_at,first_source,last_source)
+      VALUES (?,?,?,?,?,?) ON CONFLICT(chain_id,address) DO UPDATE SET last_used_at=excluded.last_used_at,last_source=excluded.last_source`)
+            .run(chainId, normalized, timestamp, timestamp, source, source);
+        return this.get(chainId, normalized);
+    }
+    currentReadAccount(chainId) {
+        const row = this.db.prepare(`SELECT connection_json FROM live_wallet_connections
+      WHERE current_slot=1 AND read_address_cleared=0 AND data_epoch=(SELECT data_epoch FROM settings_control WHERE id=1)`)
+            .get();
+        if (!row)
+            return undefined;
+        const connection = walletConnectionSchema.parse(JSON.parse(row.connection_json));
+        const address = fixedChainAccount(connection, chainId);
+        if (!address)
+            return undefined;
+        const account = this.get(chainId, address);
+        if (!account)
+            return undefined;
+        return { accountId: account.id, chainId, address, revision: connection.revision, source: "wallet_connection",
+            setAt: connection.approvedAt, connectionId: connection.connectionId,
+            ...(connection.walletName ? { walletName: connection.walletName } : {}) };
+    }
+    account(row) {
+        return { id: row.id, chainId: row.chain_id, address: row.address, firstSeenAt: row.first_seen_at,
+            lastUsedAt: row.last_used_at, firstSource: row.first_source, lastSource: row.last_source };
+    }
+}