@zktx.io/sui-mcp 0.5.0

package/docs/SDK_API.md

@@ -0,0 +1,206 @@
+# SDK API Verification
+
+This document records the pinned SDK APIs used by the current runtime. The source of truth is the installed package source in `node_modules`, not memory or external summaries.
+
+## Package Versions
+
+- `@modelcontextprotocol/ext-apps`: `1.7.5`
+- `@modelcontextprotocol/sdk`: `1.29.0`
+- `@mysten/sui`: `2.17.0`
+- `@mysten/deepbook-v3`: `1.3.6`
+- `@walletconnect/sign-client`, `@walletconnect/types`, `@walletconnect/utils`: `2.23.10`
+- `qrcode`: `1.5.4`
+- `@zktx.io/ptb-model`: `0.5.0`
+- `mermaid`: `11.12.0`
+
+## MCP Apps
+
+`@modelcontextprotocol/ext-apps` is pinned to `1.7.5`, with MCP SDK `1.29.0`. The server uses `registerAppTool`, `registerAppResource` and `getUiCapability`; the view uses `App` for host-mediated calls and teardown. Account, Receipt, Chart, Connect and Review are separate self-contained resources, so an account card does not load the PTB or chart renderer. The server keeps app-only permissions out of model content.
+
+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. Ordinary MCP input schemas remain unchanged by the transport; the 64 KiB card/HTTP input limit includes the card call envelope.
+
+## WalletConnect Runtime
+
+The backend passes the product identifier from `src/runtime/walletConnectConfig.ts`
+to the pinned `SignClient.init`. The shared runtime's configuration identity uses
+the same value. There is no user project ID setting or environment override.
+Identifier-format validation remains before SDK initialization. Initialization,
+restoration and runtime-state failures remain separate from wallet approval and
+transaction results; public diagnostics do not include raw SDK error bodies.
+
+## Sui gRPC Client
+
+Verified from `node_modules/@mysten/sui/src/grpc/index.ts`, `client.ts`, `core.ts`, and `node_modules/@mysten/sui/src/client/types.ts`.
+
+- Import path: `@mysten/sui/grpc`
+- Client: `SuiGrpcClient`
+- Constructor input includes:
+  - `network`
+  - `baseUrl`
+  - optional `fetchInit`
+  - or custom `transport`
+- Runtime construction:
+
+```ts
+new SuiGrpcClient({
+  baseUrl: "https://fullnode.mainnet.sui.io:443",
+  network: "mainnet"
+});
+```
+
+Confirmed methods:
+
+| Method | Signature Source | Notes |
+| --- | --- | --- |
+| `client.core.getChainIdentifier()` | `GrpcCoreClient.getChainIdentifier(_options?)` | Returns `{ chainIdentifier: string }`. |
+| `client.core.listBalances(options)` | `GrpcCoreClient.listBalances(options)` | `options.owner` is required; `options.cursor` and `options.limit` are available. Returns `{ balances, hasNextPage, cursor }`. |
+| `client.core.getCoinMetadata(options)` | `GrpcCoreClient.getCoinMetadata(options)` | `options.coinType` is required. Returns `{ coinMetadata }`; metadata can be `null`. The gRPC implementation resolves type through MVR before calling `stateService.getCoinInfo`; the pinned gRPC implementation catches `getCoinInfo` failures and returns `coinMetadata: null`, so callers cannot distinguish those failures from missing metadata through this method alone. |
+| `client.core.simulateTransaction(options)` | `GrpcCoreClient.simulateTransaction(options)` | Accepts `transaction`, optional `include`, optional `checksEnabled`. |
+
+`SimulateTransactionOptions.checksEnabled` defaults to enabled and can be set to `false` for debug/read inspection. Read-only DeepBook SDK methods use simulation internally and must not be presented as signing readiness.
+
+For review-time transaction simulation, use the public gRPC `client.transactionExecutionService.simulateTransaction` with validation checks enabled (`checks: ENABLED`), `doGasSelection: true`, and the complete stored BCS transaction. In the pinned core API, `doGasSelection: false` can let the node inject mock gas for an empty gas payment, changing the simulated digest. Require returned BCS to equal the submitted bytes and require the effects digest to match; selection must not change the reviewed material. Decode transaction facts from the identical returned BCS. Request effects, balance changes and object id/type facts, and require the normalized `effects`, `balanceChanges`, `objectTypes` and `transaction` evidence. Missing required fields must fail closed. Returned BCS is only a private equality check and must not enter public or stored review evidence; raw transaction bytes are not an MCP or review-app output. `commandResults` remains scoped to read-only DeepBook raw quote extraction using `client.core.simulateTransaction`, not swap review simulation evidence. Failed simulations are blocked pre-signing review facts, not wallet rejection, transaction submission failure, or automatic transient retry evidence. A thrown simulation call is refreshable only when it is classified as a transport, RPC, timeout, or endpoint availability failure; malformed transaction material, request-shape bugs, incomplete results, and adapter defects remain blocked.
+
+Only an explicit `effects.status.success: false` reports simulation failure. A missing transaction, effects, status, or boolean success value means the response cannot establish an outcome. Incomplete or inconsistent evidence blocks the review with a fixed explanation; internal validation and JavaScript error messages are not public review facts. A `success: true` response still requires all material and evidence checks above.
+
+During transaction building, the SDK's `SimulationError.executionError` does
+not preserve every gRPC error kind. A build error can establish a returned
+simulation rejection without establishing a specific funding shortfall. Build
+error text is not used to infer insufficient gas or coin balance. Explicit
+shortfalls remain available from verified funding reads and the typed error
+kinds returned directly by review-time simulation.
+
+## DeepBook Read Methods
+
+Verified from `node_modules/@mysten/deepbook-v3/src/client.ts` and `node_modules/@mysten/deepbook-v3/src/types/index.ts`.
+
+- Import path: `@mysten/deepbook-v3`
+- Client: `DeepBookClient`
+- Constructor requires:
+  - `client`
+  - `address`
+  - `network`
+- Constructor also accepts optional configured `balanceManagers`; Sui MCP uses this only to register a user-supplied `managerAddress` as an ephemeral SDK BalanceManager key for account-bound inventory detail reads.
+
+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.
+
+Confirmed methods:
+
+| Method | Return Type | Used For |
+| --- | --- | --- |
+| `midPrice(poolKey)` | `Promise<number>` | Orderbook context. |
+| `poolBookParams(poolKey)` | `Promise<PoolBookParams>` | Tick, lot, and min size context. |
+| `getLevel2TicksFromMid(poolKey, ticks)` | `Promise<Level2TicksFromMid>` | Bid/ask levels around mid price. |
+| `deepBook.getQuoteQuantityOut(poolKey, baseQuantity)` | Transaction builder thunk | Base-to-quote quantity quote. Sui MCP passes positive raw input quantities that fit the SDK `u64` argument and parses the simulated raw `u64` return values directly. |
+| `deepBook.getBaseQuantityOut(poolKey, quoteQuantity)` | Transaction builder thunk | Quote-to-base quantity quote. Sui MCP passes positive raw input quantities that fit the SDK `u64` argument and parses the simulated raw `u64` return values directly. |
+| `getBalanceManagerIds(owner)` | `Promise<string[]>` | Active-account BalanceManager discovery. |
+| `accountExists(poolKey, managerKey)` | `Promise<boolean>` | Gate before account-bound detail reads. |
+| `account(poolKey, managerKey)` | `Promise<AccountInfo>` | Display-like account ledger and rebate inventory. Not raw/signable quantity. |
+| `lockedBalance(poolKey, balanceManagerKey)` | `Promise<LockedBalances>` | Display-like balances tied to open orders. Not withdrawable/spendable readiness. |
+| `accountOpenOrders(poolKey, managerKey)` | `Promise<string[]>` | Open order ID inventory; Sui MCP caps returned IDs in its public response. |
+
+Relevant return shapes:
+
+```ts
+type PoolBookParams = {
+  tickSize: number;
+  lotSize: number;
+  minSize: number;
+};
+
+type Level2TicksFromMid = {
+  bid_prices: number[];
+  bid_quantities: number[];
+  ask_prices: number[];
+  ask_quantities: number[];
+};
+
+type QuoteQuantityOut = {
+  baseQuantity: number;
+  baseOut: number;
+  quoteOut: number;
+  deepRequired: number;
+};
+
+type BaseQuantityOut = {
+  quoteQuantity: number;
+  baseOut: number;
+  quoteOut: number;
+  deepRequired: number;
+};
+```
+
+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 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.
+- `fetchedAt` fields are ISO 8601 UTC strings produced by `new Date().toISOString()`.
+- Read-only tools may inspect mainnet state but must not create signable transaction material.
+
+## WalletConnect and signature verification
+
+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`.
+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
+`{ transaction: <stored BCS base64>, address }`; responses require
+`{ transactionBytes: <BCS base64>, signature }`. No SDK source patch or automatic
+sign-and-execute fallback is used.
+
+The backend reconstructs the returned transaction with `Transaction.from`,
+recomputes its digest and calls pinned `verifyTransactionSignature` with the
+admitted address and verified Sui client (including schemes requiring online
+verification). Submission uses `client.core.executeTransaction` exactly once
+per admitted attempt. `waitForTransaction` supplies separately verified chain
+facts; its absence/timeout does not prove execution failure.
+
+SDK session storage persists only the pinned connection namespaces. History,
+requests and unknown queue keys are volatile. The SDK has no supported complete
+in-process disposal; its owner process lifetime bounds callbacks and storage.
+The parent uses a fixed packaged Node child entrypoint and private versioned IPC.
+Only the SDK child owns SDK storage. The supervisor fences a terminating run,
+sends SIGKILL to its owned child and waits for actual exit. Its explicit
+replacement primitive remains private infrastructure; Connect and Settings do
+not expose a restart command. Closing relay transport or receiving an IPC disconnection is not
+evidence that the SDK operation ended. No SDK private teardown, source patch,
+automatic financial retry or overlapping storage writer is used.
+
+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
+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
+requirement, not something inferred from these SDK APIs or a rejected request.
+
+## Funding formats in Sui 2.17.0
+
+The pinned Transaction builder first resolves CoinWithBalance intents. With
+SuiGrpcClient, the SDK's gRPC resolver then asks the node to resolve transaction
+objects, gas payment, and expiration. The common client resolver is a separate
+SDK path; testing it alone does not establish the runtime's gRPC behavior.
+
+The source of truth for address-balance withdrawal and gas reservation formats
+is Sui mainnet-v1.72.5 `sui-types/src/coin_reservation.rs` and
+`transaction.rs`, together with the installed Sui 2.17.0 source. Its
+`utils/coin-reservation.ts` helper is not publicly exported. The local read-only
+funding verifier uses the SDK's public BCS, base58 and dynamic-field primitives
+for the documented reservation format; it does not replace SDK coin selection
+or import private package paths. Reservation epochs cover N and N+1.
+
+Address-balance gas uses an empty payment array with ValidDuring replay
+protection. A reservation reference can also fund a gas coin together with
+actual coin objects. Source reads and checks-enabled review simulation remain
+required; protocol feature availability alone does not prove wallet acceptance
+or execution success.

package/docs/SIGNABLE_ADAPTER_CONTRACT.md

@@ -0,0 +1,396 @@
+# Signable Adapter and PTB Visualization Contract
+
+This document defines the contract boundary for wallet-review adapters.
+It is a product and implementation contract, not a current feature announcement.
+
+The backend builds local account-bound DeepBook transaction material and
+binds its Sui digest to verified review evidence. Only explicit user selection
+and wallet approval allow the backend WalletConnect request. Returned bytes and
+signer must match the admission before submission. No model or card receives
+transaction bytes or signatures.
+
+The source-level schema for this contract lives in
+`src/core/action/signableAdapterContract.ts`.
+
+## Current Status
+
+The contract schema is implemented in TypeScript and Zod, and the runtime
+DeepBook account-bound swap reviews emit it. When an account-bound review
+completes every evidence stage (local unsigned transaction material, internal
+digest commitment, object ownership, quote/policy provenance, human-readable
+review facts, and review-time simulation), the review layer assembles those
+private artifacts into a schema-validated `TransactionReviewData` and
+records it on the public review state as `transactionReviewData` on a
+`ready_for_wallet_review` status. If any required evidence is
+missing or fails contract validation, no contract is emitted and the review
+stays blocked with `blockedReason: "wallet_review_contract_emit_missing"`.
+
+If that stored failure's private evidence later becomes invalid, current state
+retains the failure reason and stage provenance with `evidenceValidity:
+"invalidated"` and removes the material-derived public summaries. Fresh
+computation still validates every required summary; invalidation does not permit
+a ready contract or wallet admission. Earlier recorded snapshots remain history.
+
+`reviewedTransactionDigest` is a hash only. Private bytes travel directly from
+the backend to the wallet through WalletConnect after atomic admission; there
+is no browser handoff endpoint. The adapter contract itself never signs or
+executes. The platform owns request authority and verified chain outcomes.
+
+## Final Acceptance Gate
+
+This contract defines the data checks required before wallet admission; it does
+not authorize a signature request. The current backend WalletConnect workflow
+requires an explicit permitted Review card action and approval in the wallet.
+The term signable adapter identifies this transaction-review contract, not a
+claim that every displayed proposal is eligible for signing.
+
+The gate binds three views of the action to one transaction commitment, so a
+user cannot sign something different from what they reviewed:
+
+- The commitment is a digest (hash) of the exact serialized transaction bytes
+  that will be signed, represented as the Sui transaction digest. The commitment
+  is a hash only; raw transaction bytes remain a prohibited output and must never
+  appear in MCP or review responses.
+- `humanReadableReview` must be derived from the transaction identified by that
+  commitment.
+- The review-time `simulation` must have been run against the transaction with
+  that same commitment.
+- Any bytes handed to the wallet must hash to that same commitment.
+
+The acceptance criterion is strict equality: review-commitment equals
+simulation-commitment equals handoff-commitment. If any is missing or differs,
+the contract is invalid and signing stays blocked.
+
+### Transaction byte lifecycle (closes the handoff loophole)
+
+The signable bytes must have exactly one origin and one handoff path, so an
+adapter cannot display a commitment while signing different bytes through a side
+channel:
+
+- Origin: the bytes are produced only inside Sui MCP's review layer (the
+  signable adapter), from material Sui MCP independently built or verified.
+  They are never accepted from an external MCP or AI-client proposal.
+- Storage: the bytes live only in the local review-server session keyed by
+  `reviewSessionId`. They never appear in an MCP tool response or in the
+  review-API JSON an AI client reads; those surfaces carry the commitment hash
+  only.
+- Transport: the only byte path is the private backend to the wallet through
+  its approved WalletConnect session. No browser signer or MCP response carries
+  bytes or signatures.
+- Binding: before requesting a signature, recompute the stored bytes' digest
+  and require equality with both reviewed producers. Verify the returned bytes'
+  digest and selected account's signature again before one backend submission.
+- Admission: one request per review session/revision, consumed atomically with
+  the card selection and public history. A different card cannot duplicate the
+  request. Recomputing while signature/submission callbacks or initial chain
+  observation remain unsettled is refused. Local timeout or stop does not prove
+  remote cancellation or callback cleanup.
+- Results: request status and chain success/failure are separate. Unknown
+  outcomes retain the known digest and may be read again, never resubmitted.
+  A later explicit reviewed revision has a new attempt while prior facts remain.
+
+DeepBook swap material is built with an explicit fee mode. When the account's
+DEEP balance covers the protocol fee, the swap quotes and builds in DEEP fee
+mode; otherwise it re-quotes through the protocol's input-fee dry run and
+builds with an explicit zero-DEEP coin so the taker fee is paid from the
+source coin at the protocol penalty. The selected fee mode is recorded as
+review evidence and shown as a check. Before building, the producer verifies
+the account holds the source amount plus the explicit gas budget and fails
+closed with the exact required and held amounts.
+
+This gate is enforced at the contract-schema layer. `transactionReviewDataSchema`
+requires a `reviewedTransactionDigest` (the Sui transaction digest of the
+transaction that will be signed, validated with the pinned SDK source of truth
+`isValidTransactionDigest`; a digest only, never raw bytes) and binds
+`humanReadableReview.transactionDigest` and `simulation.transactionDigest` to it
+through a `superRefine` invariant (reusing the `requireEqual` cross-field helper)
+that rejects any contract whose three commitments are missing, malformed, or
+unequal (`src/core/action/signableAdapterContract.ts`,
+`test/signableAdapterContract.test.ts`).
+
+The private `prepareReviewedTransaction` session-store operation verifies stored
+material and the reviewed digest. `WalletWorkflow` and its SQLite owner admit
+the exact account/revision, verify wallet response bytes and signature, submit
+once and record independently read receipt facts. Public output never gains
+signing authority. Internal preparation is distinct from final user admission.
+
+## Adapter Contract
+
+A wallet-review adapter that returns this contract must regenerate or
+independently verify action material inside Sui MCP before any wallet
+handoff exists. External MCP or AI-client proposals remain untrusted structured
+input and cannot become transaction-building authority.
+
+The adapter contract requires these fields:
+
+- `inputProvenance`: where the request came from, when it was captured, and why
+  it remains untrusted until the local review layer regenerates and verifies it.
+- `sourceReferences`: source metadata for pinned SDK registries, verified mainnet
+  onchain metadata, wallet reads, quote evidence, simulation, validated request
+  facts, or explicit user choices. A `sourceReferences` record is not itself a
+  value-bearing fact. It identifies where a typed evidence claim came from.
+- `evidenceClaims`: typed value-bearing claims for every safety-critical fact
+  used by the payload. Each claim has a `factKind`, a `sourceEvidenceId` pointing
+  to `sourceReferences[].id`, and the value fields required for that fact. The
+  schema validates the claim against the safety-critical fact matrix and then
+  validates that payload fields match their referenced claim values.
+- `rawQuantities`: raw integer strings plus normalized Sui coin type, verified
+  decimals, and unit source. `amountClaimId` must point to a
+  `raw_quantity_amount` claim whose role, raw amount, and normalized coin type
+  match the payload. Unit `unitClaimId` must point to a `unit_metadata` claim
+  whose decimals, normalized coin type, and metadata source match the payload.
+  Display amounts remain presentation-only.
+- `gas`: review-time simulation evidence for gas quantities or a concrete
+  unresolved reason. `gasBudgetRaw` and `gasUsedRaw` must point to
+  `raw_quantity_amount` claims with `gas_budget` and `gas_used` roles, the Sui
+  gas coin type, and raw MIST units. An unresolved gas status must point to a
+  `gas_unresolved_status` claim. Gas object ownership must point to
+  `object_ownership` claims whose ownership status is `owned_by_account`.
+  `gasUsedRaw` is the nonnegative net simulation cost. If storage rebates exceed
+  costs, omit this optional unsigned quantity and its claim; do not clamp it to
+  zero. The verified gas budget remains available, and the review simulation
+  retains the exact cost/rebate components and signed balance changes.
+- `expiry`: review-time expiry status. `current` and `expired` require
+  `checkedAt`, `expiresAt`, and `evidenceClaimId`; `current` requires
+  `expiresAt` after `checkedAt`, and `expired` requires `expiresAt` at or before
+  `checkedAt`. The referenced `expiry_status` claim must match the payload and
+  must reference a `sourceReferences` record with `checkedAt` and `expiresAt`.
+  `not_provided` and `not_applicable` must omit `expiresAt`, include
+  `evidenceClaimId` and `reason`, and reference an `expiry_status` claim backed
+  by `checkedAt` and `expiryStatus`.
+- `slippageOrMinOut`: quote-linked max slippage and minimum-output policy when
+  quote evidence is used. `quoteEvidenceClaimId` must point to a `quote_min_out`
+  claim whose `quoteEvidenceId` and `minOutRaw` match the payload.
+  `policySource: "user_explicit"` requires a separate `policyEvidenceClaimId`
+  pointing to a `slippage_policy` claim backed by `user_explicit_choice` fields
+  including `maxSlippageBps` and `userSelection`.
+  `policySource: "adapter_policy_from_quote_evidence"` requires
+  `policyEvidenceClaimId` pointing to a `slippage_policy` claim backed by quote
+  evidence fields including `maxSlippageBps` and `minOutRaw`. If `minOutRaw` or
+  `maxSlippageBps` appears in the payload, it must have the matching typed claim;
+  stale or missing status does not make an unclaimed scalar safe to use.
+  `minOutRaw` must also match a `rawQuantities[]` entry with role
+  `minimum_output` so the raw integer has normalized coin type and verified
+  decimals.
+- `objectOwnership`: account-bound object ownership or shared-object facts. Each
+  object must point to an `object_ownership` claim whose object id, owner account,
+  and ownership status match the payload.
+- `simulation`: the public Sui gRPC `transactionExecutionService.simulateTransaction`
+  with validation checks enabled, identical returned transaction BCS and matching
+  effects digest. The required normalized evidence fields are `effects`,
+  `balanceChanges`, `objectTypes`, and `transaction`. The simulation payload must point to a `simulation_result`
+  claim whose provider, status, required fields, missing fields, and failure
+  reason match the payload.
+- `humanReadableReview`: the fields a human must see before wallet
+  authorization, matching the review-model concepts already exposed for
+  non-signable proposal review.
+- `outputBoundary`: the MCP and review UI exposure limit. Human-readable review,
+  PTB visualization artifacts, diagnostics, and status checks are allowed.
+  The required prohibited set is executable transaction material, serialized
+  transaction material, wallet signature requests, private-key material, wallet
+  authorization, signing data, signing readiness, and payment execution
+  readiness. Each contract must include the whole prohibited set.
+
+## Safety-Critical Fact Matrix
+
+`SAFETY_CRITICAL_FACT_MATRIX` in `src/core/action/signableAdapterContract.ts`
+is the contract's validation source of truth.
+
+It defines the required source kind and source fields for these fact kinds:
+
+- `raw_quantity_amount`, keyed by role: input, expected output, minimum output,
+  gas budget, gas used, fee, and balance delta;
+- `unit_metadata`, keyed by metadata source;
+- `gas_unresolved_status`;
+- `expiry_status`, keyed by status;
+- `quote_min_out`;
+- `slippage_policy`, keyed by policy source;
+- `object_ownership`;
+- `simulation_result`.
+
+Payload fields do not cite `sourceReferences` records directly as proof. They cite
+typed evidence claims, and those claims cite `sourceReferences` records. The schema
+rejects payload values that do not match their typed claims.
+
+## Consumer Invariant Matrix
+
+`CONSUMER_INVARIANT_MATRIX` in
+`src/core/action/signableAdapterContract.ts` defines extra requirements for
+payload fields that consume typed claims. It is separate from
+`SAFETY_CRITICAL_FACT_MATRIX`.
+
+`SAFETY_CRITICAL_FACT_MATRIX` answers whether a typed claim has the required
+source kind and source fields. `CONSUMER_INVARIANT_MATRIX` answers whether that
+claim is valid for a specific payload use.
+
+Current consumer invariants are:
+
+- `gas.gasBudgetClaimId` must reference a `raw_quantity_amount` claim with role
+  `gas_budget`, matching raw amount, and Sui gas coin type. The raw unit is MIST.
+- `gas.gasUsedClaimId` must reference a `raw_quantity_amount` claim with role
+  `gas_used`, matching raw amount, and Sui gas coin type. The raw unit is MIST.
+- `gas.gasObjects[].ownershipClaimId` must reference an `object_ownership` claim
+  with matching object id, matching owner account, and
+  `ownership: "owned_by_account"`.
+
+The current contract does not prove that a gas object is a `Coin<SUI>` object
+type because the object-ownership claim does not carry object type evidence.
+An adapter must not use object ownership alone as gas coin type evidence.
+
+## PTB Visualization Artifact
+
+The PTB visualization contract is for explaining a locally generated
+transaction shape before wallet authorization. It is not wallet handoff.
+
+The artifact may contain:
+
+- `generatedAt`;
+- `source`, including adapter id, plan id when available, source kind, renderer
+  name, package name, and version;
+- Mermaid `flowchart` text;
+- diagnostics from the adapter, renderer, schema, or simulation;
+- `unsupportedUse`, including transaction-building input, wallet authorization,
+  signing data, signing readiness, payment execution readiness, and route
+  recommendation;
+- `executableMaterial.included: false`.
+
+The artifact must not contain executable transaction material. Mermaid text and
+diagnostic messages are screened for executable-material terms and long encoded
+payloads.
+
+## PTB Renderer Status
+
+The pinned renderer dependency is `@zktx.io/ptb-model@0.5.0`. The review layer
+converts the stored local transaction material into a Mermaid `flowchart`
+artifact with `rawTransactionToIR` and `transactionIRToMermaid`, only after the
+stored bytes are recomputed to match the bound transaction material commitment;
+a mismatch declines the artifact. The graph is decoded from the stored transaction bytes with no AI or model input in the rendering path, so it reflects the decoded transaction the wallet will receive, not an AI description of it. The artifact passes
+`ptbVisualizationArtifactSchema` screening before exposure and accompanies the
+emitted wallet review contract as `reviewState.ptbVisualization`. PTB
+visualization stays visualization-only evidence: it is not a runtime
+transaction builder, not wallet handoff, and not a signing-readiness surface.
+
+The producer emits the Mermaid flowchart as two parallel streams. `mermaid.text`
+keeps raw package addresses for audit and copy. `mermaid.namedText` is a second
+relabeled stream produced by `applyContractNamesToMermaid`
+(`src/core/action/ptbVisualizationProducer.ts`,
+`src/core/action/contractNameRegistry.ts`): it labels registered packages
+(`@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.
+
+## Adapter Registration And Stage Vocabulary
+
+Review adapters register through `ReviewAdapterDescriptor` entries in
+`src/adapters/reviewAdapters.ts` (`buildSupportedReviewAdapterDescriptors`).
+A descriptor supplies the adapter id, protocol, action kind, stage catalog id,
+and the evidence computer; action-plan factories live in the adapter module
+and are wired by the MCP layer. The platform keeps the
+safety gates non-delegable: the typed evidence claim matrices, the commitment
+equality gate, the adapter lifecycle validator registry
+(`src/adapters/adapterLifecycleValidators.ts`), and the digest-gated byte
+handoff all run outside adapter code. `src/core` contains no adapter imports;
+a source-policy test enforces that boundary.
+
+Stage vocabulary is a cross-adapter contract. Every stage catalog that reports
+public review evidence must use these stage ids for these concepts, because the
+core review-state schema binds public fields to them:
+
+- `transaction_material_build_or_verify`: local unsigned material exists.
+- `digest_commitment`: the Sui transaction digest is bound to the material.
+- `object_ownership`: object ownership evidence is verified.
+- `human_readable_review`: required before `reviewState.humanReadableReview`.
+- `review_time_simulation`: required before `reviewState.simulation`.
+
+Adapter acceptance gate: a new protocol enters as read-only tools or
+non-signable proposal review first. A signable adapter is accepted only when it
+produces every required evidence stage from independently built or verified
+material, passes `transactionReviewDataSchema` without placeholder
+values, and fails closed when any evidence is missing. Protocol names stay out
+of public docs, runtime guidance, and MCP resources until a concrete
+implementation or support decision exists.
+
+## Verification
+
+Tests must keep this contract in place before any adapter can use it:
+
+- schema tests for required provenance, source-of-truth, raw quantity, gas,
+  expiry, slippage or minimum output, object ownership, simulation, and
+  human-readable review fields;
+- tests that reject duplicate `sourceReferences[].id` and `evidenceClaims[].id`
+  values;
+- tests that reject every payload claim reference that does not resolve to a
+  typed `evidenceClaims[].id`;
+- tests that reject every `evidenceClaims[].sourceEvidenceId` that does not
+  resolve to a `sourceReferences[].id`;
+- tests that reject safety-critical claims whose source references resolve to the
+  wrong source kind or to records missing the required fields for that claim;
+- tests that reject payload values whose raw amounts, decimals, gas quantities,
+  expiry values, minimum output, slippage policy, object ownership, or simulation
+  status do not match their typed evidence claims;
+- tests that reject metadata-only records as raw amount evidence and reject
+  user-explicit slippage policy claims without explicit user-choice evidence;
+- tests that reject raw signable quantity assets without normalized Sui coin
+  types;
+- tests that reject min-out or slippage scalar fields when they do not have typed
+  evidence claims;
+- tests that reject `minOutRaw` when it does not match a `rawQuantities[]` entry
+  with role `minimum_output`;
+- tests that require `gasBudgetRaw` and `gasUsedRaw` to use
+  `raw_quantity_amount` claims with gas roles, the Sui gas coin type, and raw
+  MIST units, or require unresolved gas status to use a `gas_unresolved_status`
+  claim;
+- tests that reject gas object references backed by object-ownership claims whose
+  ownership status is not `owned_by_account`;
+- tests that require every mandatory prohibited output boundary and every
+  mandatory PTB unsupported-use boundary;
+- tests that reject `current` or `expired` expiry status without timestamp
+  evidence, source evidence, matching source fields, and the required
+  `checkedAt`/`expiresAt` time relationship;
+- tests that reject `not_provided` or `not_applicable` expiry status when it
+  includes an `expiresAt` timestamp or omits the reason and source evidence for
+  why timestamp evidence is unavailable;
+- tests that require failed or unavailable simulation evidence to include a
+  concrete `failureReason`;
+- tests that reject display amounts, exponent notation, or floating-point values
+  as raw quantities;
+- tests that reject PTB visualization artifacts containing executable-material
+  terms or long encoded payloads;
+- MCP/review output tests using the shared forbidden-field-name policy;
+- documentation tests that keep PTB visualization described as visualization
+  only, not transaction material, signing readiness, or payment execution
+  readiness.
+
+## Transaction funding and ownership
+
+The supported swap adapters retain the SDK's coin-object and address-balance
+selection. The private ownership evidence verifies the stored transaction's
+sender, gas payer, real object references, address withdrawals, and gas funding
+against the reviewed account and verified mainnet source. The same description
+must match the checks-enabled simulation and the material rechecked for admission.
+
+An empty gas payment array means address-balance gas; it is not missing gas
+evidence. It requires a mainnet-bound ValidDuring epoch window and address SUI
+covering both explicit SUI withdrawals and the gas budget. A gas reservation
+reference is an address-balance reservation, not a Coin<SUI> object. Its account,
+asset, chain, amount and epoch are verified; any real gas coins alongside it
+retain their ownership/type checks. Explicit address withdrawals and reservations
+are summed per coin type without counting the gas budget twice. Observed balances
+are review-time facts, not locked funds or execution guarantees.
+
+Only real gas coins produce `gas.gasObjects` and object-ownership claims. The
+public optional field remains absent when no such objects are used. Private
+funding evidence is required in either case; omitting all funding checks does not
+produce a valid review. The existing human review evidence explains the funding
+form without publishing private artifacts or creating signing authority.
+
+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.