@zktx.io/sui-mcp 0.6.2 → 0.8.0

package/docs/SDK_API.md

@@ -59,7 +59,7 @@ single serialized `CallToolResult` carrier validated with the pinned SDK
 schema. Conflicting payloads or private metadata are rejected. Ordinary data
 does not supply input permission, and saved resource links remain read-only.
 
-`@modelcontextprotocol/ext-apps` is pinned to `2.0.3`, with the MCP client/core/server packages at `2.3.1` and Node transport at `2.1.1`. The server uses `registerAppTool`, `registerAppResource` and `getUiCapability`; the view uses `App` for host-mediated calls and teardown. Account, Receipt, Chart, Connect, Review and Settings are separate self-contained resources, so an account card does not load the PTB or chart renderer. Settings uses scoped app-only inputs for local actions and file transfer. The server keeps app-only permissions out of model content.
+`@modelcontextprotocol/ext-apps` is pinned to `2.0.3`, with the MCP client/core/server packages at `2.3.1` and Node transport at `2.1.1`. The server uses `registerAppTool`, `registerAppResource` and `getUiCapability`; the view uses `App` for host-mediated calls and teardown. Account, Receipt, Chart, Connect, Disconnect, Review and Settings are separate self-contained resources, so an account card does not load the PTB or chart renderer. Settings uses scoped app-only inputs for local actions and file transfer. The server keeps app-only permissions out of model content.
 
 Settings completes a selected upload's verification and restore preparation on
 the backend. The card renders the stored `restoreCheck` result and collects one
@@ -71,9 +71,15 @@ needing a new check, a current confirmation and actual rejection. Definite
 file/mainnet rejection is independent of local-data confirmation revision and
 survives Back until explicit file selection changes. The View's current file-job
 progress describes communication only; it cannot grant restoration authority.
+An operation change that ends use of an upload records invalidation with the
+stored effect/result. Physical cleanup follows without repeating that effect.
+A valid file retained by Back remains eligible for another explicit check.
 
-Recorded backup locations use backend-native folder and file-name fields;
-optional `App.downloadFile` delivery remains separate from local publication.
+Download backup prepares one verified snapshot and calls `App.downloadFile`.
+Only that function's exact method-not-found result selects local publication of
+the same snapshot. A possibly handled earlier attempt requires explicit local-copy
+consent. Host acknowledgment does not prove a save destination or disk storage;
+Folder and File name identify only a verified local backup result.
 
 The shared server uses the pinned MCP SDK Streamable HTTP transport behind authenticated loopback access. Stdio clients forward tool, resource and prompt requests with their original client identity and capabilities. The SDK limits each internal HTTP request body to 4 MiB, including its complete MCP JSON-RPC envelope and metadata. Oversized bodies are refused before tool or card dispatch. Card calls additionally have a 64 KiB envelope budget; ordinary MCP calls do not inherit that smaller limit. Restore uploads retain their 16 MiB file limit and are split into messages within the card budget. The SDK's internal HTTP batch guard does not expose a stdio batch feature. SDK HTTP errors expose the HTTP status separately from their local error code; the stdio forwarding boundary retains that numeric status in the MCP error. Handler cancellation and request identity use `context.mcpReq.signal` and `context.mcpReq.id`. The current private transport uses the SDK's default initialized connection behavior; it does not opt into automatic protocol probes or request retries.
 
@@ -142,7 +148,7 @@ Verified from `node_modules/@mysten/deepbook-v3/src/client.ts` and `node_modules
 
 The `address` is used by the SDK as the transaction simulation sender for read queries. For sender-independent DeepBook orderbook, raw-quantity quote, and display-amount quote reads, Sui MCP supplies an internal mainnet placeholder address. This placeholder is not user identity and must not be represented as wallet authorization.
 
-Account-bound DeepBook reads, such as `read.summarize_deepbook_account_inventory`, use the active account address as the simulation sender. The product filters manager detail reads through on-chain `getBalanceManagerIds(owner)` discovery before calling account-bound detail methods; this is active read context, not signing authorization or custody.
+Account-bound DeepBook reads, such as `read_summarize_deepbook_account_inventory`, use the active account address as the simulation sender. The product filters manager detail reads through on-chain `getBalanceManagerIds(owner)` discovery before calling account-bound detail methods; this is active read context, not signing authorization or custody.
 
 Confirmed methods:
 
@@ -190,12 +196,12 @@ type BaseQuantityOut = {
 };
 ```
 
-The pinned SDK accepts `number | bigint` quote inputs. Its high-level quote query objects include an input echo field (`baseQuantity` or `quoteQuantity`) produced with `Number(inputRaw)`, plus display quote fields (`baseOut`, `quoteOut`, and `deepRequired`) produced after scalar division and `Number(...)` conversion. Sui MCP does not use those high-level query objects as the canonical quote source for adapter preparation. It uses the pinned SDK transaction builder quote functions, requests `client.core.simulateTransaction` command results, and parses raw `u64` return values. The simulated public Move entrypoint is `pool::get_quote_quantity_out` for base-to-quote reads and `pool::get_base_quantity_out` for quote-to-base reads; both delegate to `pool::get_quantity_out`, whose official Move source defines the return order as `base_quantity_out`, `quote_quantity_out`, and `deep_quantity_required`. Public `quote` fields are exact decimal display strings derived from those raw values through pinned DeepBook scalars; `rawQuote` carries the raw evidence. `read.quote_deepbook_action` marks the input as raw `u64`, while `read.quote_deepbook_display_amount` marks the input as a source display amount converted to raw `u64`. Raw quote evidence is not an effective price, price-impact calculation, quote-vs-mid slippage calculation, venue comparison, best-route claim, fiat cash-out estimate, external market lookup, USDC/USD peg assumption, P&L, cost basis, final min-out, signing data, or signing readiness. The account-bound DeepBook review may derive a fresh raw quote policy from this evidence and use that derived policy for local unsigned transaction material build, while keeping bytes private to the backend until a scoped user selection admits a WalletConnect request for that reviewed revision. MCP and ordinary review-status outputs still do not contain transaction bytes, signing data, or signing readiness. When the digest commitment stage completes, it is derived from the locally stored transaction bytes through pinned SDK `Transaction.from(...).getDigest()` and remains an internal binding, not a public signing artifact.
+The pinned SDK accepts `number | bigint` quote inputs. Its high-level quote query objects include an input echo field (`baseQuantity` or `quoteQuantity`) produced with `Number(inputRaw)`, plus display quote fields (`baseOut`, `quoteOut`, and `deepRequired`) produced after scalar division and `Number(...)` conversion. Sui MCP does not use those high-level query objects as the canonical quote source for adapter preparation. It uses the pinned SDK transaction builder quote functions, requests `client.core.simulateTransaction` command results, and parses raw `u64` return values. The simulated public Move entrypoint is `pool::get_quote_quantity_out` for base-to-quote reads and `pool::get_base_quantity_out` for quote-to-base reads; both delegate to `pool::get_quantity_out`, whose official Move source defines the return order as `base_quantity_out`, `quote_quantity_out`, and `deep_quantity_required`. Public `quote` fields are exact decimal display strings derived from those raw values through pinned DeepBook scalars; `rawQuote` carries the raw evidence. `read_quote_deepbook_action` marks the input as raw `u64`, while `read_quote_deepbook_display_amount` marks the input as a source display amount converted to raw `u64`. Raw quote evidence is not an effective price, price-impact calculation, quote-vs-mid slippage calculation, venue comparison, best-route claim, fiat cash-out estimate, external market lookup, USDC/USD peg assumption, P&L, cost basis, final min-out, signing data, or signing readiness. The account-bound DeepBook review may derive a fresh raw quote policy from this evidence and use that derived policy for local unsigned transaction material build, while keeping bytes private to the backend until a scoped user selection admits a WalletConnect request for that reviewed revision. MCP and ordinary review-status outputs still do not contain transaction bytes, signing data, or signing readiness. When the digest commitment stage completes, it is derived from the locally stored transaction bytes through pinned SDK `Transaction.from(...).getDigest()` and remains an internal binding, not a public signing artifact.
 
 ## Runtime Boundary
 
 - JSON-RPC client imports are not used.
-- Sui gRPC and GraphQL endpoints are resolved from local SQLite settings by default. `SUI_GRPC_URL` and `SUI_GRAPHQL_URL` are advanced temporary overrides and do not mutate stored settings.
+- Sui gRPC and GraphQL endpoints are resolved from local SQLite settings by default. `SUI_MCP_GRPC_URL` and `SUI_MCP_GRAPHQL_URL` are advanced temporary overrides and do not mutate stored settings.
 - Sui gRPC URLs must include an explicit port and no credentials, path, query string, or fragment.
 - Sui GraphQL URLs must use `https` and must not include credentials, query string, or fragment.
 - The gRPC endpoint is verified during runtime startup. The GraphQL endpoint is verified when saved, imported, or first used by Sui activity tools.
@@ -207,7 +213,10 @@ The pinned SDK accepts `number | bigint` quote inputs. Its high-level quote quer
 The SDK child initializes pinned SignClient with its public `storage` injection,
 private session persistence, silent SDK logging and telemetry disabled. It uses
 `connect`, `session.getAll`, `session_update/session_delete/session_expire` events,
-and `request` on chain `sui:mainnet`, method `sui_signTransaction`.
+and `request` on chain `sui:mainnet`, method `sui_signTransaction`. Connection
+requests send the saved mainnet chain set as optional namespaces. The pinned SDK
+already treats required namespaces as optional; the product directly supplies
+the intended request shape. Ethereum/Solana requests contain no financial methods.
 Pinned `session_event` does not update approved namespaces itself: account/chain
 selection events explicitly invalidate stored review/submission authority even
 when the approved account set stays unchanged. Requests carry
@@ -235,10 +244,13 @@ not own restart. A new explicit Settings operation can supersede a startup
 still pending; known failure and its first timestamp remain immutable.
 Late callbacks cannot reopen old authority or submit another transaction.
 
-Snapshots and per-session versions distinguish present, absent and unusable
-sessions. Source inspection failure disables the service instead of becoming an
-empty session list. `accountsChanged` and `chainChanged` invalidate selection
-even if namespace values are unchanged. The final pre-submission session check
+Snapshots separate session lifecycle revisions from per-chain grant revisions.
+Presence/status changes affect all grants; an identified chain event affects only
+that chain. Normalized account/method/event scope excludes list order and display
+metadata. Within each SDK run, revisions are monotonic across change-and-revert. Source inspection failure disables the service instead of becoming an
+empty session list. `accountsChanged` and `chainChanged` invalidate their chain
+even if namespace values are unchanged; unknown event scope invalidates the
+connection. The IPC proof and pre/post-signing checks carry the Sui grant revision. The final pre-submission session check
 runs after asynchronous digest/signature/network checks. Responses from another
 SDK run cannot satisfy that check or restore submission authority.
 Actual target-wallet acceptance of the serialization is an integration

package/docs/SIGNABLE_ADAPTER_CONTRACT.md

@@ -278,8 +278,8 @@ relabeled stream produced by `applyContractNamesToMermaid`
 (`@deepbook/core`; the Sui framework `std`/`sui`/`sui_system`) and well-known
 objects (`SuiSystemState`, `Clock`, `Random`, `DenyList`, `CoinRegistry`,
 `AccumulatorRoot`) while keeping the raw addresses available. These names are a
-display label, not a safety, ownership, or trust signal, and the on-chain Move
-Registry name is not yet verified on chain.
+display label, not a safety, ownership, or trust signal, and the renderer does not perform a fresh Move Registry lookup or verify
+current package identity from a display label.
 
 ## Adapter Registration And Stage Vocabulary
 
@@ -390,7 +390,7 @@ Different gas owners, sponsor withdrawals, unsupported reservation formats, and
 unverified funding remain blocked. Supported adapters still require the same quote,
 amount, ownership, human review, simulation, wallet approval, and digest checks.
 
-New review evidence names `client.transactionExecutionService.simulateTransaction`
-as its provider. The previous `client.core.simulateTransaction` provider remains
-parseable in stored public history; it is not a fallback for new reviews. Returned
-BCS is compared privately and is never added to evidence, cards, backups or logs.
+The current review producer uses `client.transactionExecutionService.simulateTransaction`.
+A stored public record identifies the provider that produced its evidence; reading
+that record does not select a simulation fallback or create new funding proof.
+Returned BCS is compared privately and is never added to evidence, cards, backups or logs.

package/docs/TRANSACTION_ACTIVITY_LOG.md

@@ -10,6 +10,10 @@ Sui MCP stores two kinds of local activity evidence:
 - User-requested bounded Sui activity facts that were looked up through GraphQL and matched a known local wallet.
 
 It does not run a background indexer and does not claim complete wallet history.
+Activity reads accept an explicit Sui account or use the saved read address.
+If that address is absent or cleared, the caller supplies an explicit account;
+no wallet connection is required for that read. These filters neither restore
+read context nor change a Review's fixed transaction target.
 
 ## Stored By Default
 
@@ -149,7 +153,7 @@ That analysis aggregates raw integer coin flows, gas totals, Move call targets,
 
 It is not display conversion, P&L, position inventory, route quality, protocol support, transaction-building input, signing data, or signing readiness.
 
-Use `read.inspect_sui_transaction` when a user needs the full normalized facts for a digest.
+Use `read_inspect_sui_transaction` when a user needs the full normalized facts for a digest.
 
 The runtime does not store non-known party account addresses inside persisted transaction rows or normalized detail facts. If a digest lookup or explicit-account scan is not related to a known local wallet, the result can be returned for the current request but is not persisted.
 
@@ -163,19 +167,19 @@ Complete account transaction history is not a product surface of this data.
 
 AI clients may answer questions only from data the listed read tools return.
 
-`read.summarize_sui_activity_scan` summarizes a live bounded scan without full details or transaction-wide balance-change aggregates in row context.
+`read_summarize_sui_activity_scan` summarizes a live bounded scan without full details or transaction-wide balance-change aggregates in row context.
 
-`read.scan_sui_function_activity` and `read.summarize_sui_function_activity_scan` reuse the same requested-account fact, transaction-context, analysis, and protocol label pipeline for transactions the selected account sent that called one full `package::module::function`.
+`read_scan_sui_function_activity` and `read_summarize_sui_function_activity_scan` reuse the same requested-account fact, transaction-context, analysis, and protocol label pipeline for transactions the selected account sent that called one full `package::module::function`.
 
 They do not create a function-specific stored history, global function index, affected-object history, or complete dApp history.
 
-`read.summarize_sui_account_activity` summarizes account-level stored normalized facts only.
+`read_summarize_sui_account_activity` summarizes account-level stored normalized facts only.
 
 It can include rows from account scans, digest lookups, or sent-function scans, and the scan kind remains provenance rather than a user query filter.
 
-`read.get_account_asset_timeline` builds stored account asset net-flow bars from the same local normalized facts. Its requested UTC range is half-open: the start timestamp is included and the end timestamp is excluded.
+`read_get_account_asset_timeline` builds stored account asset net-flow bars from the same local normalized facts. Its requested UTC range is half-open: the start timestamp is included and the end timestamp is excluded.
 
-It first checks stored scan coverage for the requested account and UTC range. If no stored scan can support the requested range for a known account, it returns `scan_needed` and points to `read.scan_sui_account_activity`; it does not start a scan by itself. If an explicit account is not a known local wallet in the activity store, it returns `account_not_known` and does not return `scanNeeded`.
+It first checks stored scan coverage for the requested account and UTC range. If no stored scan can support the requested range for a known account, it returns `scan_needed` and points to `read_scan_sui_account_activity`; it does not start a scan by itself. If an explicit account is not a known local wallet in the activity store, it returns `account_not_known` and does not return `scanNeeded`.
 
 Timeline output uses account-scoped raw balance-change facts only. `netFlowBars` are observed inflow/outflow bars, not held balances. The storage model does not store balance snapshots or balance anchors. The timeline response returns `balanceStatus: "unavailable_no_balance_anchor"` and empty `balanceBars`.
 
@@ -185,7 +189,7 @@ Provider retention and rate-limit behavior are endpoint/operator properties, not
 
 Empty pages, bounded pages, and stored local summaries must not be treated as complete history.
 
-When normalized details are missing or capped, use `transactionDetailAvailability` and the returned digest metadata with `read.inspect_sui_transaction` instead of inventing missing fields.
+When normalized details are missing or capped, use `transactionDetailAvailability` and the returned digest metadata with `read_inspect_sui_transaction` instead of inventing missing fields.
 
 Inspect responses can include live GraphQL detail fields for the current response.
 

package/docs/UTILITY_INDEX.md

@@ -17,33 +17,33 @@ Source-checkout scripts are not packaged product commands, MCP tools, review-tim
 | Utility | Command / Tool | Status | Notes |
 | --- | --- | --- | --- |
 | DeepBook registry generation | `npm run generate:deepbook-registry` | Implemented | Generates ignored mainnet metadata from `@mysten/deepbook-v3@2.6.4` constants. |
-| MCP server status | `read.get_server_status` | Implemented | Reports package version, evidence policy version, runtime, `implementedToolsCount`, resources, prompts, and implementation limits. |
-| Supported protocol list | `read.list_supported_protocols` | Implemented | Reports product support levels. |
-| DeepBook pool list | `read.list_deepbook_pools` | Implemented | Reads pinned SDK mainnet pool metadata. |
-| DeepBook token list | `read.list_deepbook_tokens` | Implemented | Reads pinned SDK mainnet token metadata, registry pool references, and decimals derived from pinned scalar values. |
-| Orderbook inspection | `read.inspect_deepbook_orderbook` | Implemented | Uses pinned DeepBook SDK simulation read methods over Sui gRPC with an internal sender placeholder; `ticks` is capped at 50. |
-| DeepBook mid price | `read.get_deepbook_mid_price` | Implemented | Returns pinned SDK pool mid price snapshots. Not a global market price. |
-| DeepBook USDC price history | `read.get_deepbook_usdc_price_history` | Implemented | Reads DeepBookV3 official Indexer USDC candle data for a requested official interval. Not a utility script, live quote, USD value, P&L, route recommendation, transaction-building input, or signing readiness. |
-| DeepBook USDC price at time | `read.get_deepbook_usdc_price_at_time` | Implemented | Selects the DeepBookV3 official Indexer USDC candle for or nearest to one target UTC time. Not a utility script, live quote, USD value, P&L, route recommendation, transaction-building input, or signing readiness. |
-| DeepBook USDC candle chart card | `ui.open_chart` | Implemented | Internal read-only MCP Apps card displaying official DeepBookV3 Indexer USDC-denominated candles through the shared server. Shows the selected pool, requested UTC range and candle limit with the saved result. Not a utility script, live feed, wallet connection, trading interface, fiat USD value, P&L, route recommendation, transaction-building input, or signing readiness. |
-| Quote calculation | `read.quote_deepbook_action` | Implemented | Quotes raw integer DeepBook quantities with pinned SDK transaction builders and raw `u64` simulation return values. |
-| Display amount quote | `read.quote_deepbook_display_amount` | Implemented | Converts explicit source display amounts through pinned DeepBook token units before quoting; returns exact decimal display quote strings plus raw quote evidence. Quote semantics mark payment coverage and shortfall contribution unavailable. |
-| DeepBook account inventory | `read.summarize_deepbook_account_inventory` | Implemented | Reports display-like BalanceManager inventory. Not raw balance or signing readiness. |
-| Wallet asset summary | `read.summarize_wallet_assets` | Implemented | Reads Sui coin balances for an explicit address or the active account with Sui gRPC `client.core.listBalances`; adds verified unit/display data when available; use `cursor` when `hasNextPage` is true. |
-| Wallet asset classification | `read.classify_wallet_assets` | Implemented | Classifies returned coin balances by balanceStatus and roles. Other asset classes are explicit non-inspected boundaries. |
-| Settlement asset group list | `read.list_settlement_asset_groups` | Implemented | Lists supported natural-language settlement asset groups derived from pinned DeepBook mainnet SDK registries. Not live liquidity, route recommendation, fiat cash-out, payment execution, or signing readiness. |
-| Intent evidence preview | `read.preview_intent_evidence` | Implemented | Builds `responseSummary` for USD-denominated coverage, shortfall, or settlement-asset balance total. |
-| Review activity list | `read.list_review_activity` | Implemented | Lists local Sui MCP review evidence for one account; not complete wallet transaction history. |
-| Review funnel summary | `read.summarize_review_funnel` | Implemented | Summarizes local review lifecycle counts, current statuses, sparse-sample warnings, and review timing. |
-| Review session detail | `read.get_review_session_detail` | Implemented | Returns a capped detail view of one stored review session with plan, state snapshots, transitions, and execution evidence. |
-| Sui transaction digest lookup | `read.inspect_sui_transaction` | Implemented | Looks up one Sui transaction digest and stores normalized facts only when the transaction sender or a returned balance-change owner matches a known local wallet. |
-| Sui account activity scan | `read.scan_sui_account_activity` | Implemented | Runs a bounded recent-to-older GraphQL scan with requested-account facts. Not complete history. |
-| Live Sui activity scan summary | `read.summarize_sui_activity_scan` | Implemented | Summarizes a live bounded scan without full details. Not P&L, position inventory, or complete history. |
-| Sui sent-function activity scan | `read.scan_sui_function_activity` | Implemented | Scans bounded sent transactions for one full `package::module::function`. Not global function history. |
-| Live Sui sent-function activity summary | `read.summarize_sui_function_activity_scan` | Implemented | Summarizes bounded sent-function rows. Not P&L, route recommendation, or signing readiness. |
-| Stored Sui activity summary | `read.summarize_sui_account_activity` | Implemented | Summarizes stored normalized Sui activity facts, including stored Move call, balance change, object/event, gas, execution error details, and optional protocol activity labels when evidence is available. |
-| Stored account asset timeline | `read.get_account_asset_timeline` | Implemented | Builds stored local account asset net-flow bars and optional DeepBook USDC token-denominated candle references. Not held balances, complete wallet history, USD value, P&L, cost basis, route advice, transaction building, or signing readiness. |
-| Local settings | `settings.create_local_settings_session`, `settings.get_local_settings` | Implemented | MCP opens an internal Settings card or reads settings. App-only preparation/confirmation owns changes, files and explicit connection-service recovery. Stored endpoints apply after all participating apps restart. |
+| MCP server status | `read_get_server_status` | Implemented | Reports package version, evidence policy version, runtime, `implementedToolsCount`, resources, prompts, and implementation limits. |
+| Supported protocol list | `read_list_supported_protocols` | Implemented | Reports product support levels. |
+| DeepBook pool list | `read_list_deepbook_pools` | Implemented | Reads pinned SDK mainnet pool metadata. |
+| DeepBook token list | `read_list_deepbook_tokens` | Implemented | Reads pinned SDK mainnet token metadata, registry pool references, and decimals derived from pinned scalar values. |
+| Orderbook inspection | `read_inspect_deepbook_orderbook` | Implemented | Uses pinned DeepBook SDK simulation read methods over Sui gRPC with an internal sender placeholder; `ticks` is capped at 50. |
+| DeepBook mid price | `read_get_deepbook_mid_price` | Implemented | Returns pinned SDK pool mid price snapshots. Not a global market price. |
+| DeepBook USDC price history | `read_get_deepbook_usdc_price_history` | Implemented | Reads DeepBookV3 official Indexer USDC candle data for a requested official interval. Not a utility script, live quote, USD value, P&L, route recommendation, transaction-building input, or signing readiness. |
+| DeepBook USDC price at time | `read_get_deepbook_usdc_price_at_time` | Implemented | Selects the DeepBookV3 official Indexer USDC candle for or nearest to one target UTC time. Not a utility script, live quote, USD value, P&L, route recommendation, transaction-building input, or signing readiness. |
+| DeepBook USDC candle chart card | `ui_open_chart` | Implemented | Internal read-only MCP Apps card displaying official DeepBookV3 Indexer USDC-denominated candles through the shared server. Shows the selected pool, requested UTC range and candle limit with the saved result. Not a utility script, live feed, wallet connection, trading interface, fiat USD value, P&L, route recommendation, transaction-building input, or signing readiness. |
+| Quote calculation | `read_quote_deepbook_action` | Implemented | Quotes raw integer DeepBook quantities with pinned SDK transaction builders and raw `u64` simulation return values. |
+| Display amount quote | `read_quote_deepbook_display_amount` | Implemented | Converts explicit source display amounts through pinned DeepBook token units before quoting; returns exact decimal display quote strings plus raw quote evidence. Quote semantics mark payment coverage and shortfall contribution unavailable. |
+| DeepBook account inventory | `read_summarize_deepbook_account_inventory` | Implemented | Reports display-like BalanceManager inventory. Not raw balance or signing readiness. |
+| Wallet asset summary | `read_summarize_wallet_assets` | Implemented | Reads Sui coin balances for an explicit address or the active account with Sui gRPC `client.core.listBalances`; adds verified unit/display data when available; use `cursor` when `hasNextPage` is true. |
+| Wallet asset classification | `read_classify_wallet_assets` | Implemented | Classifies returned coin balances by balanceStatus and roles. Other asset classes are explicit non-inspected boundaries. |
+| Settlement asset group list | `read_list_settlement_asset_groups` | Implemented | Lists supported natural-language settlement asset groups derived from pinned DeepBook mainnet SDK registries. Not live liquidity, route recommendation, fiat cash-out, payment execution, or signing readiness. |
+| Intent evidence preview | `read_preview_intent_evidence` | Implemented | Builds `responseSummary` for USD-denominated coverage, shortfall, or settlement-asset balance total. |
+| Review activity list | `read_list_review_activity` | Implemented | Lists local Sui MCP review evidence for one account; not complete wallet transaction history. |
+| Review funnel summary | `read_summarize_review_funnel` | Implemented | Summarizes local review lifecycle counts, current statuses, sparse-sample warnings, and review timing. |
+| Review session detail | `read_get_review_session_detail` | Implemented | Returns a capped detail view of one stored review session with plan, state snapshots, transitions, and execution evidence. |
+| Sui transaction digest lookup | `read_inspect_sui_transaction` | Implemented | Looks up one Sui transaction digest and stores normalized facts only when the transaction sender or a returned balance-change owner matches a known local wallet. |
+| Sui account activity scan | `read_scan_sui_account_activity` | Implemented | Runs a bounded recent-to-older GraphQL scan with requested-account facts. Not complete history. |
+| Live Sui activity scan summary | `read_summarize_sui_activity_scan` | Implemented | Summarizes a live bounded scan without full details. Not P&L, position inventory, or complete history. |
+| Sui sent-function activity scan | `read_scan_sui_function_activity` | Implemented | Scans bounded sent transactions for one full `package::module::function`. Not global function history. |
+| Live Sui sent-function activity summary | `read_summarize_sui_function_activity_scan` | Implemented | Summarizes bounded sent-function rows. Not P&L, route recommendation, or signing readiness. |
+| Stored Sui activity summary | `read_summarize_sui_account_activity` | Implemented | Summarizes stored normalized Sui activity facts, including stored Move call, balance change, object/event, gas, execution error details, and optional protocol activity labels when evidence is available. |
+| Stored account asset timeline | `read_get_account_asset_timeline` | Implemented | Builds stored local account asset net-flow bars and optional DeepBook USDC token-denominated candle references. Not held balances, complete wallet history, USD value, P&L, cost basis, route advice, transaction building, or signing readiness. |
+| Local settings | `settings_create_local_settings_session`, `settings_get_local_settings` | Implemented | MCP opens an internal Settings card or reads settings. App-only preparation/confirmation owns changes, files and explicit connection-service recovery. Stored endpoints apply after all participating apps restart. |
 | Release package check | `npm run release:check` | Maintainer, source checkout | Verifies metadata, tests/build, tarball assets/licenses and installed MCP/Settings startup. Requires network and loopback access; no wallet pairing, signing or publishing. |
 | Mainnet read smoke | `npm run smoke:mainnet` | Manual | Runs selected mainnet read paths from built `dist/`. Build first. Not part of CI or `release:check`; see notes below. |
 | Sui GraphQL function filter probe | `npm exec -- tsx scripts/sui-graphql-function-filter-probe.ts [--endpoint <mainnet-graphql-url>] [--sample-size <1-50>] [--timeout-ms <ms>]` | Manual, source evidence only | Runs a read-only Sui mainnet GraphQL source-shape probe for function-filter diagnostics; see notes below. |
@@ -58,15 +58,15 @@ installation, local loopback sockets, and reachable Sui mainnet endpoints are
 required. Native SQLite must work both in the checkout and the installed package.
 The source build and tests use Vite, Rolldown and Vitest's common Node ranges; the
 installed package's Node runtime requirement is documented in MCP Setup.
-The runtime uses its built-in endpoints unless `SUI_GRPC_URL` or `SUI_GRAPHQL_URL`
+The runtime uses its built-in endpoints unless `SUI_MCP_GRPC_URL` or `SUI_MCP_GRAPHQL_URL`
 is supplied; the actual mainnet checks remain enabled.
 
 The command checks metadata, types, tests, builds, package contents and licenses,
 then launches the installed package through stdio MCP with a new data directory
 and an independent port. It reads the registered tools and resources, creates a
-Settings card only in that temporary database, and checks the six internal
+Settings card only in that temporary database, and checks the internal
 HTML resources, app-only tools, scoped status and retired-route rejection. A scoped test card verifies
-that Connect rejects retired restart input and opening manage does not pair. The check
+that Connect rejects unsupported restart input and a model call does not start pairing. The check
 verifies the isolated SDK retains exclusive storage ownership until shutdown. It waits
 for process termination before removing its installation. A termination failure preserves the temporary files for cleanup
 after the process stops. It does not pair, sign, submit, publish, or mutate the
@@ -105,25 +105,25 @@ original workflow revision, so changes to this gate apply to subsequent releases
 This is a manual maintainer check for a specific mainnet provider. Normal quickstart use does not require Sui endpoint setup. Run it for people operating releases or debugging mainnet read shape.
 
 ```bash
-export SUI_GRPC_URL="https://fullnode.mainnet.sui.io:443"
-export SUI_GRAPHQL_URL="https://graphql.mainnet.sui.io/graphql" # optional override; default is the built-in mainnet GraphQL endpoint
-export SMOKE_SUI_ADDRESS="0x..."
-export SMOKE_DEEPBOOK_POOL_KEY="DEEP_SUI"
-export SMOKE_QUOTE_AMOUNT="1000000000" # raw integer units; for SUI, 1000000000 = 1 SUI
-# Optional: export SMOKE_INSPECT_DIGEST="..."
-# Optional: export SMOKE_INSPECT_RANDOM_LATEST="true"
+export SUI_MCP_GRPC_URL="https://fullnode.mainnet.sui.io:443"
+export SUI_MCP_GRAPHQL_URL="https://graphql.mainnet.sui.io/graphql" # optional override; default is the built-in mainnet GraphQL endpoint
+export SUI_MCP_SMOKE_ADDRESS="0x..."
+export SUI_MCP_SMOKE_DEEPBOOK_POOL_KEY="DEEP_SUI"
+export SUI_MCP_SMOKE_QUOTE_AMOUNT="1000000000" # raw integer units; for SUI, 1000000000 = 1 SUI
+# Optional: export SUI_MCP_SMOKE_INSPECT_DIGEST="..."
+# Optional: export SUI_MCP_SMOKE_INSPECT_RANDOM_LATEST="true"
 npm run build
 npm run smoke:mainnet
 ```
 
-`SUI_GRPC_URL` must be only scheme, host, and explicit port. Do not include credentials, a path, query string, or fragment.
-`SMOKE_SUI_ADDRESS` must be a 32-byte hex Sui address, for example `0x` followed by 64 hex characters.
-`SMOKE_INSPECT_DIGEST` is optional. Use a digest whose sender or returned balance-change owner is `SMOKE_SUI_ADDRESS` to exercise the stored digest-lookup path; otherwise the lookup can still return `ok` with `persistence.stored: false`.
-`SMOKE_INSPECT_RANDOM_LATEST=true` is optional and only used when `SMOKE_INSPECT_DIGEST` is unset. It samples one digest from the latest GraphQL transaction page and calls `read.inspect_sui_transaction` without passing the smoke address. This checks current transaction-read shape without pinning a specific user address or exercising the stored relation path.
+`SUI_MCP_GRPC_URL` must be only scheme, host, and explicit port. Do not include credentials, a path, query string, or fragment.
+`SUI_MCP_SMOKE_ADDRESS` must be a 32-byte hex Sui address, for example `0x` followed by 64 hex characters.
+`SUI_MCP_SMOKE_INSPECT_DIGEST` is optional. Use a digest whose sender or returned balance-change owner is `SUI_MCP_SMOKE_ADDRESS` to exercise the stored digest-lookup path; otherwise the lookup can still return `ok` with `persistence.stored: false`.
+`SUI_MCP_SMOKE_INSPECT_RANDOM_LATEST=true` is optional and only used when `SUI_MCP_SMOKE_INSPECT_DIGEST` is unset. It samples one digest from the latest GraphQL transaction page and calls `read_inspect_sui_transaction` without passing the smoke address. This checks current transaction-read shape without pinning a specific user address or exercising the stored relation path.
 
-DeepBook orderbook and raw-quantity quote reads use an internal mainnet SDK simulation sender placeholder, not a user's wallet. The display-amount quote path is covered by automated tests, not by this smoke script. This smoke script does not exercise account-bound DeepBook transaction-material build or digest binding; that path needs a separate funded-account material-build smoke before smoke results are treated as product-grade proof for that review stage.
+DeepBook orderbook and raw-quantity quote reads use an internal mainnet SDK simulation sender placeholder, not a user's wallet. The display-amount quote path is covered by automated tests, not by this smoke script. Without the complete optional swap input group, the script does not run account-bound transaction-material computation or digest binding. See Optional account-bound review smoke for that explicit path; read-only success is not evidence that it ran.
 
-Wallet and activity reads use an explicitly synthetic active-account context in a temporary SQLite database. The script never creates a wallet connection, a review URL or an HTTP wallet result. Wallet approval is checked separately. This smoke script does not record raw GraphQL payloads, transaction bytes, signatures, raw transaction details, or compact transaction aggregates.
+Wallet and activity reads pass `SUI_MCP_SMOKE_ADDRESS` explicitly. All four live activity scan/summary calls require `accountSource: "explicit_filter"`. A temporary SQLite database stores known-account history for persistence and optional review computation, without creating a current wallet row or active read context. The script never creates a wallet connection, a review URL or an HTTP wallet result. Wallet approval is checked separately. This smoke script does not record raw GraphQL payloads, transaction bytes, signatures, raw transaction details, or compact transaction aggregates.
 
 ## Mainnet Read Smoke Notes
 
@@ -134,10 +134,10 @@ The smoke command calls:
 - wallet assets;
 - DeepBook orderbook;
 - raw-quantity DeepBook quote;
-- `read.scan_sui_account_activity` for `SMOKE_SUI_ADDRESS` with limit 5;
-- `read.summarize_sui_activity_scan` through active account context with limit 5;
-- `read.inspect_sui_transaction` when `SMOKE_INSPECT_DIGEST` is set;
-- sent-function activity tools when `SMOKE_FUNCTION_TARGET` is set to a full `package::module::function`.
+- `read_scan_sui_account_activity` for `SUI_MCP_SMOKE_ADDRESS` with limit 5;
+- `read_summarize_sui_activity_scan` with the explicit `SUI_MCP_SMOKE_ADDRESS` and limit 5;
+- `read_inspect_sui_transaction` when `SUI_MCP_SMOKE_INSPECT_DIGEST` is set;
+- sent-function activity tools when `SUI_MCP_SMOKE_FUNCTION_TARGET` is set to a full `package::module::function`.
 
 Empty activity pages are valid smoke outcomes. They are recorded with `rowCount: 0` and `emptyAccepted: true`.
 
@@ -145,15 +145,16 @@ The result file records tool names, environment-variable presence, activity stat
 
 It does not store raw GraphQL payloads, transaction bytes, signatures, raw transaction details, or compact transaction aggregates.
 
-Activity scan and summary smoke paths fail if full transaction details or compact transaction aggregates are returned. The optional digest verifies storage only when its sender or returned balance-change owner is `SMOKE_SUI_ADDRESS`.
+Activity scan and summary smoke paths fail if full transaction details or compact transaction aggregates are returned. The optional digest verifies storage only when its sender or returned balance-change owner is `SUI_MCP_SMOKE_ADDRESS`.
 
-If `SMOKE_INSPECT_RANDOM_LATEST=true` is set and no digest is provided, the script samples one latest GraphQL transaction digest and inspects it without an account argument.
+If `SUI_MCP_SMOKE_INSPECT_RANDOM_LATEST=true` is set and no digest is provided, the script samples one latest GraphQL transaction digest and inspects it without an account argument.
 
-This smoke path does not call display-amount quote, DeepBook account inventory,
-account-bound DeepBook transaction-material build, or internal digest binding. A
-funded-account material-build smoke is a separate operator check before this
-read smoke can be used as product-grade proof for the DeepBook review material
-stage.
+The default read path does not call display-amount quote or DeepBook account
+inventory. Account-bound review computation is separate within the same utility
+and runs only for the complete explicit swap input group. That optional path
+uses the known-account history already prepared in the temporary database; it does not create a live connection, card permission or signing authority. Use its recorded
+status and evidence stages rather than treating read-path success as material
+verification or wallet acceptance.
 
 ## Sui GraphQL Function Filter Probe Notes
 
@@ -228,11 +229,11 @@ It is not an MCP tool, not a CI check, not packaged product functionality, not r
 - DeepBook mid-price outputs are pool snapshots. For `SUI_USDC`, the price is USDC per SUI.
 - DeepBook mid prices are not fiat USD cash-out estimates, external market lookups, USDC/USD peg assumptions, effective quote prices, quote-vs-mid slippage, price-impact calculations, venue comparisons, best-route claims, P&L, cost basis, or route recommendations.
 - DeepBook USDC price-history output reads DeepBookV3 official Indexer candle data for the requested official interval. It is MCP tool evidence, not a source-checkout utility, on-demand chain-history scan, live quote, historical mid price, global market price, USD value, user-account history, P&L, cost basis, route recommendation, transaction-building input, or signing-readiness signal.
-- `ui.open_chart` opens an internal read-only DeepBook USDC candle card. The server queries the official Indexer; the view does not fetch it directly. This is not a utility script, persistent price database, auto-refresh feed, live quote, trading interface, fiat USD value, user-account history, P&L, cost basis, route recommendation, transaction-building input or signing-readiness signal.
+- `ui_open_chart` opens an internal read-only DeepBook USDC candle card. The server queries the official Indexer; the view does not fetch it directly. This is not a utility script, persistent price database, auto-refresh feed, live quote, trading interface, fiat USD value, user-account history, P&L, cost basis, route recommendation, transaction-building input or signing-readiness signal.
 - USDC in DeepBook USDC price-history output is a token-denominated quote asset, not fiat USD and not a USDC/USD peg guarantee.
-- `read.quote_deepbook_action` amounts are raw integer quantities that fit the SDK `u64` quote input, not decimal display amounts. Quote responses include `rawQuote.kind: "deepbook_quote_raw_u64"` from simulated raw `u64` return values.
+- `read_quote_deepbook_action` amounts are raw integer quantities that fit the SDK `u64` quote input, not decimal display amounts. Quote responses include `rawQuote.kind: "deepbook_quote_raw_u64"` from simulated raw `u64` return values.
 - `rawQuote.sourceMoveFunction` names the simulated public entrypoint. `rawQuote.returnValueSourceMoveFunction: "pool::get_quantity_out"` names the official Move function that defines the return-value order.
-- `read.quote_deepbook_display_amount` accepts only source-side display input amounts that convert to SDK `u64` quote inputs.
+- `read_quote_deepbook_display_amount` accepts only source-side display input amounts that convert to SDK `u64` quote inputs.
 - Display quote public `quote` fields are exact decimal display strings derived from raw evidence. `rawQuote.directionalOutput.raw` is the direction-specific quote output before slippage policy.
 - Quote `quantitySemantics` marks payment coverage, shortfall contribution, and route-dependent payment support unavailable and points coverage questions back to intent evidence.
 - DeepBook account inventory quantities are display-like SDK `number` values and must not be used as raw amounts, funding sources, route liquidity, withdrawal readiness, transaction-building inputs, signing data, or signing readiness.
@@ -252,10 +253,10 @@ It is not an MCP tool, not a CI check, not packaged product functionality, not r
 - Gas display facts, when returned, use `@mysten/sui MIST_PER_SUI`.
 - Optional protocol activity labels are derived from normalized detail facts and are not a supported-protocol list or wallet position inventory.
 - Sent-function activity tools are sender-scoped only: they report transactions the selected account sent that called one full `package::module::function`, not recipient-only activity, affected-object history, or global function history.
-- `read.summarize_sui_activity_scan` and `read.summarize_sui_function_activity_scan` summarize live bounded scan results. `read.summarize_sui_account_activity` summarizes stored local SQLite facts only.
+- `read_summarize_sui_activity_scan` and `read_summarize_sui_function_activity_scan` summarize live bounded scan results. `read_summarize_sui_account_activity` summarizes stored local SQLite facts only.
 - Sui GraphQL function filter probe output is source-shape evidence for function-filter diagnostics only.
 - Do not treat the probe as a supported function diagnostics surface, complete dApp history, route quality evidence, wallet position inventory, transaction-building input, signing data, or signing readiness.
-- Sui CLI transaction diagnostics can be compared with `read.inspect_sui_transaction` only at the fact category level.
+- Sui CLI transaction diagnostics can be compared with `read_inspect_sui_transaction` only at the fact category level.
 - Comparable categories include digest/status/checkpoint/timestamp, Move call targets, object ids/types, event type strings, raw gas summary, and optional replay/trace-derived debug artifacts.
 - Sui CLI transaction diagnostics are debug cross-check sources, not replacements for MCP normalized transaction facts and not review-time simulation.
 - Sui CLI transaction diagnostics are source-checkout debug utilities only. They must stay allowlisted and read/debug-only.
@@ -266,13 +267,14 @@ It is not an MCP tool, not a CI check, not packaged product functionality, not r
 
 ### Optional account-bound review smoke
 
-Set `SMOKE_SWAP_PROTOCOL`, `SMOKE_SWAP_FROM_SYMBOL`, `SMOKE_SWAP_TO_SYMBOL` and
-`SMOKE_SWAP_AMOUNT_DISPLAY` together to opt into read-only account-bound review
+Set `SUI_MCP_SMOKE_SWAP_PROTOCOL`, `SUI_MCP_SMOKE_SWAP_FROM_SYMBOL`, `SUI_MCP_SMOKE_SWAP_TO_SYMBOL` and
+`SUI_MCP_SMOKE_SWAP_AMOUNT_DISPLAY` together to opt into read-only account-bound review
 computation. Protocol is explicitly `deep`; the smoke does not silently select a protocol.
-A partially configured group is an error. `SMOKE_SWAP_MAX_SLIPPAGE_BPS` keeps the
+A partially configured group is an error. `SUI_MCP_SMOKE_SWAP_MAX_SLIPPAGE_BPS` keeps the
 existing explicit override. The script uses the same runtime review composition,
 material store and evidence validation as the product, and records whether
 transaction review data was emitted. This can involve mainnet simulation but
-never wallet pairing, signing or submission. The temporary active-account
-fixture is not proof of a wallet connection or ownership. Without the complete
+never wallet pairing, signing or submission. The temporary database supplies
+known-account history for that explicit address; it does not create a current
+wallet connection, saved read context or proof of ownership. Without the complete
 optional group, the result records that review computation was not run.