@tokamak-private-dapps/private-state-cli 2.1.1 → 2.1.2

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+## 2.1.2 - 2026-05-15
+
+- Fixed wallet lifecycle recovery log lookups so account-specific registration and exit event scans
+  use the same chunked `eth_getLogs` path as the rest of RPC workspace recovery.
+- Removed synthetic wallet lifecycle epoch fallback creation; wallet recovery now requires
+  lifecycle registration events to be found in RPC log history instead of fabricating epochs from
+  current registration state.
+- Fixed RPC log request pacing so every `eth_getLogs` call passes through a shared async limiter
+  instead of relying on a race-prone timestamp throttle during concurrent scans.
+- Added progress output for the wallet lifecycle registered/exited event scans that run before
+  note-delivery recovery in `wallet recover-workspace`.
+- Added `set rpc` for per-network RPC configuration with built-in `eth_getLogs` scan-limit tables
+  for Ankr, Chainstack, Chainnodes, QuickNode, and Alchemy, using 90% of the provider reference
+  request-rate values.
+- Simplified note-mutating command post-processing so accepted note transactions wait for the
+  receipt block, then refresh channel and wallet workspaces from their recovery indexes instead of
+  manually applying note lifecycle metadata.
+- Extended wallet recovery to persist public creation/spend linkage from commitment and
+  nullifier storage observations so raw evidence export can package stored metadata without
+  running its own log scan.
+- Fixed raw evidence spend linkage so nullifier observation transactions are used as the spend
+  transition references and included with their transaction, receipt, and event evidence.
+- Redesigned the bundled investigator GUI around purpose-first disclosure requests, an interactive
+  SVG note-linkage graph, node detail overlays, and Markdown ASCII-art linkage report export.
+- Updated private-state documentation to reflect `set rpc` as the only CLI RPC configuration path
+  for ordinary bridge-facing and wallet commands.
+- Split the CLI entrypoint into command dispatch modules and moved the shared runtime implementation
+  under `lib/runtime.mjs`; the published package now includes the `commands/` modules.
+- Removed the `channel get-meta` workspace mirror lookup fallback so contract lookup errors surface
+  directly instead of being hidden behind `null` metadata.
+- Changed `channel join` to derive the wallet lifecycle epoch from the accepted join receipt instead
+  of rescanning full account registration and exit history.
+- Changed investigator numeric block filters to reject invalid values instead of silently treating
+  them as absent filters.
+
 ## 2.1.1 - 2026-05-14
 
 - Changed `channel recover-workspace --from-genesis` to move any existing local channel workspace

package/README.md

@@ -264,8 +264,11 @@ private-state-cli investigator
 ```
 
 The command prints the bundled investigator HTML path and file URL, then opens the static browser GUI. Load the raw
-evidence ZIP in that GUI, apply the requested filters, and export a narrower user-consent disclosure ZIP. The GUI runs
-locally in the browser and does not send files over the network.
+evidence ZIP in that GUI, choose the disclosure request type, inspect the interactive note-linkage graph, and export a
+narrower user-consent disclosure ZIP. The graph view renders every matched note as a node and shows creation, spend,
+and local note-to-note linkage edges when the raw bundle contains enough local evidence. The GUI can also export a
+Markdown ASCII-art linkage report with a compact graph section and per-note detail sections. The GUI runs locally in the
+browser and does not send files over the network.
 
 The investigator accepts current epoch-aware evidence bundles only. If a bundle was generated by an older CLI, rebuild
 the wallet workspace with `wallet recover-workspace` and export a new bundle with `wallet get-notes --export-evidence`.
@@ -273,7 +276,7 @@ the wallet workspace with `wallet recover-workspace` and export a new bundle wit
 Estimate live transaction costs before sending commands with:
 
 ```bash
-private-state-cli help transaction-fees --network mainnet --rpc-url <RPC_URL>
+private-state-cli help transaction-fees --network mainnet
 ```
 
 `help transaction-fees` uses the measured gas data packaged in `assets/tx-fees.json`, the selected network's live fee data,
@@ -366,8 +369,9 @@ note-delivery events and rebuild the user's readable note view. Sharing it gives
 registered note-receive public key, but not spending authority.
 
 The spending key is the channel-bound L2 private key. It authorizes proof-backed use of the wallet identity. Commands
-that consume existing notes, such as `wallet transfer-notes` and `wallet redeem-notes`, need both the viewing key and
-the spending key because the CLI must first reconstruct the plaintext notes and then prove authorized use of them.
+that create or consume notes, such as `wallet mint-notes`, `wallet transfer-notes`, and `wallet redeem-notes`, need both
+the viewing key and the spending key because the CLI refreshes the readable note workspace after accepted note
+transactions and then proves authorized note use when inputs are consumed.
 
 Key recovery is intentionally split. Recreating the viewing key requires the original L1 private key and the same channel
 context. Recreating the spending key requires the original L1 private key, the same channel context, and the same wallet
@@ -390,11 +394,40 @@ The CLI stores user workspaces under:
 Wallet backup metadata lives under the channel workspace. Viewing and spending private keys live as separate protected
 key files under `~/tokamak-private-channels/secrets/<network>/wallets/<wallet>/`.
 
-Bridge-facing commands accept optional `--rpc-url <URL>`. When `--rpc-url` is provided, the CLI stores it in
-`~/tokamak-private-channels/secrets/<network>/.env` as `RPC_URL=<URL>` with protected canonical secret permissions.
-When `--rpc-url` is omitted, the CLI reads `RPC_URL` from that file. The `anvil` network falls back to
-`http://127.0.0.1:8545` when no saved RPC URL exists. Canonical CLI secrets are checked on read: macOS/Linux uses
-`0600`, while Windows uses ACL repair and inspection when possible.
+Configure the network RPC endpoint before bridge-facing or wallet recovery commands:
+
+```bash
+private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --provider alchemy
+```
+
+The CLI writes `~/tokamak-private-channels/workspace/<network>/rpc-config.env` and later commands read `RPC_URL`,
+`LOG_CHUNK_SIZE`, `LOG_REQUESTS_PER_SECOND`, and `RPC_BLOCK_RANGE_CAP` from that file. Built-in provider limits are
+set to 90% of the provider reference values: Ankr `27 calls/s, 3000 blocks`; Chainstack `22.5 calls/s, 100 blocks`;
+Chainnodes `22.5 calls/s, 20000 blocks`; QuickNode `13.5 calls/s, 5 blocks`; Alchemy `7.497 calls/s, 10 blocks`.
+If the provider is not listed, use
+`--log-requests-per-second <N>` and `--block-range-cap <N>` instead of `--provider`.
+
+### Slow Workspace Recovery
+
+`channel recover-workspace` and `wallet recover-workspace` scan on-chain logs with `eth_getLogs`. If recovery is
+unexpectedly slow, first check the RPC scan limits saved by `set rpc`. The main speed factors are the provider's
+`eth_getLogs` block range cap and the allowed log request rate. A small block range cap can turn the same channel scan
+into thousands of RPC calls.
+
+For example, an Alchemy free-tier-style cap of `10` blocks is much slower for long recovery scans than Ankr's built-in
+`3000` block setting or Chainnodes' built-in `20000` block setting. When recovery is too slow, re-run `set rpc` with a
+provider that supports a larger `eth_getLogs` block range cap, or provide explicit values:
+
+```bash
+private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --provider ankr
+private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --log-requests-per-second <N> --block-range-cap <N>
+```
+
+If an RPC provider rejects the configured range or rate during recovery, run `set rpc` again with limits that match the
+provider's documented `eth_getLogs` policy, then retry the recovery command.
+
+Canonical CLI secrets are checked on read: macOS/Linux uses `0600`, while Windows uses ACL repair and inspection when
+possible.
 
 ## LLM Agent Guidance
 
@@ -429,8 +462,9 @@ Operating rules:
   - A viewing key decrypts encrypted note-delivery events for the registered note-receive public key. A spending key is
     the channel-bound L2 private key used to authorize note use. Do not describe either key as interchangeable with the
     other.
-  - The network RPC URL is the endpoint used to read and write chain state. It can be supplied once with `--rpc-url`
-    on a bridge-facing command, after which the CLI saves it under the selected network.
+  - The network RPC URL is the endpoint used to read and write chain state. It must be configured once with
+    `private-state-cli set rpc --network <NETWORK> --rpc-url <URL> --provider <PROVIDER>`, or with explicit
+    `--log-requests-per-second` and `--block-range-cap` values when the provider is not built in.
   - A workspace recovery index is the saved block pointer and state-root hash that lets the CLI resume log scanning
     without replaying the channel from its creation block. If it is missing, explain `--from-genesis` before using it
     because genesis replay can take much longer.
@@ -438,25 +472,32 @@ Operating rules:
   recovery can be very slow because it scans channel logs from the creation block. If a channel workspace mirror is
   available, try mirror-based recovery first, and use RPC genesis replay only when mirror recovery is unavailable or
   unsuitable.
+- When `channel recover-workspace` or `wallet recover-workspace` is unexpectedly slow, first inspect the RPC provider
+  configured by `set rpc`. Explain that recovery speed is dominated by `eth_getLogs` block range cap and log request
+  rate. Suggest re-running `set rpc` with a provider that supports a larger block range cap, such as Ankr or Chainnodes
+  when appropriate, or with explicit `--log-requests-per-second` and `--block-range-cap` values from the provider's
+  documentation.
 - When a CLI command fails, read the error message and any printed `Try:` hints first. Prefer the corrective action
   suggested by the CLI before inventing a different recovery sequence.
 - When the user does not have a network RPC URL yet, explain that they need an Ethereum JSON-RPC endpoint for the
-  selected network. They can obtain one from an infrastructure provider such as Alchemy, Infura, QuickNode, or from
-  their own node. Ask the user to create or select the endpoint in that provider's UI, then paste only the endpoint URL
-  into the CLI command that accepts `--rpc-url`; do not ask for provider account passwords, API dashboards, seed phrases,
-  private keys, or wallet secrets.
+  selected network. They can obtain one from an infrastructure provider such as Alchemy, Ankr, Chainstack, Chainnodes,
+  QuickNode, or from their own node. Ask the user to create or select the endpoint in that provider's UI, then paste only
+  the endpoint URL into `private-state-cli set rpc`; do not ask for provider account passwords, API dashboards, seed
+  phrases, private keys, or wallet secrets.
 - When a user wants to join a channel, do not jump straight to `channel join`. Walk them through:
   1. choose the network and channel name
   2. run `private-state-cli install`
   3. run `private-state-cli help doctor`
   4. obtain or confirm a network RPC URL for the selected network
-  5. prepare a private key source file locally, without pasting the key into chat
-  6. run `account import --account <NAME> --network <NETWORK> --private-key-file <PATH>`
-  7. prepare a wallet secret source file locally, for example with `openssl rand -hex 32 > ./wallet-secret.txt`
-  8. inspect the channel with `channel get-meta` if it already exists, or create it with `channel create` if the user is
+  5. run `set rpc --network <NETWORK> --rpc-url <URL> --provider <PROVIDER>`, or use explicit scan limits for an
+     unlisted provider
+  6. prepare a private key source file locally, without pasting the key into chat
+  7. run `account import --account <NAME> --network <NETWORK> --private-key-file <PATH>`
+  8. prepare a wallet secret source file locally, for example with `openssl rand -hex 32 > ./wallet-secret.txt`
+  9. inspect the channel with `channel get-meta` if it already exists, or create it with `channel create` if the user is
      the channel creator
-  9. explain the immutable policy warning printed by the CLI
-  10. run `channel join --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH> --acknowledge-action-impact`
+  10. explain the immutable policy warning printed by the CLI
+  11. run `channel join --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH> --acknowledge-action-impact`
 - Before executing any command for a user that requires an `--acknowledge-*` option, strongly warn the user in plain
   language about what that acknowledgement means and ask for explicit confirmation. Do not add
   `--acknowledge-action-impact` or `--acknowledge-full-note-plaintext-export` on the user's behalf until they confirm.

package/cli-assistant.html

@@ -413,16 +413,22 @@
           <h2>Command Guide</h2>
           <div class="box">
             <ol class="guide-list">
+              <li>
+                <span class="guide-label">Configure RPC:</span> <code>set rpc</code>
+                <div class="guide-example">
+                  <code>set rpc --network 'sepolia' --rpc-url '__RPC_URL__' --provider 'alchemy'</code>
+                </div>
+              </li>
               <li>
                 <span class="guide-label">Join a channel:</span> <code>channel join</code>
                 <div class="guide-example">
-                  <code>channel join --channel-name 'my-private-channel' --network 'sepolia' --account 'my-account' --wallet-secret-path '/path/to/wallet-secret' --rpc-url '__RPC_URL__'</code>
+                  <code>channel join --channel-name 'my-private-channel' --network 'sepolia' --account 'my-account' --wallet-secret-path '/path/to/wallet-secret'</code>
                 </div>
               </li>
               <li>
                 <span class="guide-label">Create notes:</span> <code>account deposit-bridge</code> -&gt; <code>wallet deposit-channel</code> -&gt; <code>wallet mint-notes</code>
                 <div class="guide-example">
-                  <code>account deposit-bridge --amount '100' --network 'sepolia' --account 'my-account' --rpc-url '__RPC_URL__'</code><br />
+                  <code>account deposit-bridge --amount '100' --network 'sepolia' --account 'my-account'</code><br />
                   <code>wallet deposit-channel --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amount '100'</code><br />
                   <code>wallet mint-notes --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amounts '[&quot;50&quot;,&quot;50&quot;,&quot;0&quot;]'</code>
                 </div>
@@ -438,7 +444,7 @@
                 <div class="guide-example">
                   <code>wallet redeem-notes --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --note-ids '[&quot;0xNoteIdA&quot;]'</code><br />
                   <code>wallet withdraw-channel --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amount '25'</code><br />
-                  <code>account withdraw-bridge --amount '25' --network 'sepolia' --account 'my-account' --rpc-url '__RPC_URL__'</code>
+                  <code>account withdraw-bridge --amount '25' --network 'sepolia' --account 'my-account'</code>
                 </div>
               </li>
             </ol>
@@ -1420,7 +1426,7 @@
         ].forEach((fieldKey) => {
           memoryFieldsEl.appendChild(createField(fieldKey));
         });
-        memoryStatusEl.textContent = "Use account import --private-key-file before signing commands. Optional --rpc-url is saved as the network RPC_URL for later commands.";
+        memoryStatusEl.textContent = "Use set rpc once before bridge-facing commands, then use account import --private-key-file before signing commands.";
       }
 
       function renderCommandSelect() {
@@ -1480,7 +1486,7 @@
             : "",
         ].join("");
         warningEl.textContent = missing.length === 0
-          ? `Ready. If --rpc-url is omitted, the CLI uses the saved network RPC_URL.${workspaceWarnings}`
+          ? `Ready. Bridge-facing commands use the saved network RPC configuration.${workspaceWarnings}`
           : `Missing inputs: ${missing.map((fieldKey) => fieldCatalog[fieldKey].label).join(", ")}.${workspaceWarnings}`;
       }
 

package/commands/account.mjs

@@ -0,0 +1,43 @@
+import {
+  assertAccountGetBridgeFundArgs,
+  assertAccountGetL1AddressArgs,
+  assertAccountImportArgs,
+  assertDepositBridgeArgs,
+  assertWithdrawBridgeArgs,
+  handleAccountGetBridgeFund,
+  handleAccountGetL1Address,
+  handleAccountImport,
+  handleDepositBridge,
+  handleWithdrawBridge,
+  loadExplicitCommandRuntime,
+  prepareDeploymentArtifacts,
+} from "../lib/runtime.mjs";
+
+export const accountCommands = Object.freeze({
+  "account-get-l1-address": async (args) => {
+    assertAccountGetL1AddressArgs(args);
+    handleAccountGetL1Address({ args });
+  },
+  "account-import": async (args) => {
+    assertAccountImportArgs(args);
+    handleAccountImport({ args });
+  },
+  "account-get-bridge-fund": async (args) => {
+    assertAccountGetBridgeFundArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleAccountGetBridgeFund({ args, provider });
+  },
+  "account-deposit-bridge": async (args) => {
+    assertDepositBridgeArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleDepositBridge({ args, network, provider });
+  },
+  "account-withdraw-bridge": async (args) => {
+    assertWithdrawBridgeArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleWithdrawBridge({ args, network, provider });
+  },
+});

package/commands/channel.mjs

@@ -0,0 +1,66 @@
+import {
+  assertCreateChannelArgs,
+  assertExitChannelArgs,
+  assertGetChannelArgs,
+  assertJoinChannelArgs,
+  assertProviderChainIdMatchesNetwork,
+  assertPublishWorkspaceMirrorArgs,
+  assertRecoverWorkspaceArgs,
+  assertSetWorkspaceMirrorArgs,
+  handleChannelCreate,
+  handleExitChannel,
+  handleGetChannel,
+  handleJoinChannel,
+  handlePublishChannelWorkspaceMirror,
+  handleSetChannelWorkspaceMirror,
+  handleWorkspaceInit,
+  loadExplicitCommandRuntime,
+  loadWalletCommandRuntime,
+  prepareDeploymentArtifacts,
+} from "../lib/runtime.mjs";
+
+export const channelCommands = Object.freeze({
+  "channel-create": async (args) => {
+    assertCreateChannelArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleChannelCreate({ args, network, provider });
+  },
+  "channel-recover-workspace": async (args) => {
+    assertRecoverWorkspaceArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { staticNetwork: true });
+    await assertProviderChainIdMatchesNetwork({ provider, network, rpcUrl });
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleWorkspaceInit({ args, network, provider });
+  },
+  "channel-get-meta": async (args) => {
+    assertGetChannelArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleGetChannel({ args, network, provider });
+  },
+  "channel-set-workspace-mirror": async (args) => {
+    assertSetWorkspaceMirrorArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleSetChannelWorkspaceMirror({ args, network, provider });
+  },
+  "channel-publish-workspace-mirror": async (args) => {
+    assertPublishWorkspaceMirrorArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handlePublishChannelWorkspaceMirror({ args, network, provider });
+  },
+  "channel-join": async (args) => {
+    assertJoinChannelArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleJoinChannel({ args, network, provider, rpcUrl });
+  },
+  "channel-exit": async (args) => {
+    assertExitChannelArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleExitChannel({ args, provider });
+  },
+});

package/commands/index.mjs

@@ -0,0 +1,62 @@
+import {
+  assertHelpCommandsArgs,
+  assertVersionArgs,
+  configureOutput,
+  formatCliErrorForDisplay,
+  parseArgs,
+  printHelp,
+  printVersion,
+} from "../lib/runtime.mjs";
+import { accountCommands } from "./account.mjs";
+import { channelCommands } from "./channel.mjs";
+import { investigatorCommands } from "./investigator.mjs";
+import { notesCommands } from "./notes.mjs";
+import { systemCommands } from "./system.mjs";
+import { walletCommands } from "./wallet.mjs";
+
+const COMMANDS = Object.freeze({
+  ...systemCommands,
+  ...investigatorCommands,
+  ...accountCommands,
+  ...channelCommands,
+  ...walletCommands,
+  ...notesCommands,
+});
+
+export async function runPrivateStateCli(argv) {
+  let args = {};
+  try {
+    args = parseArgs(argv);
+    configureOutput(args);
+
+    if (args.version !== undefined) {
+      assertVersionArgs(args);
+      printVersion();
+      return;
+    }
+
+    if (args.help || !args.command) {
+      printHelp();
+      return;
+    }
+
+    if (args.command === "help-commands") {
+      assertHelpCommandsArgs(args);
+      printHelp();
+      return;
+    }
+
+    const command = COMMANDS[args.command];
+    if (!command) {
+      throw new Error(`Unsupported command: ${args.command}`);
+    }
+    await command(args);
+  } catch (error) {
+    console.error(formatCliErrorForDisplay(error, args));
+    process.exitCode = 1;
+  }
+}
+
+export function privateStateCliDispatchTable() {
+  return COMMANDS;
+}

package/commands/investigator.mjs

@@ -0,0 +1,11 @@
+import {
+  assertInvestigatorArgs,
+  handleInvestigator,
+} from "../lib/runtime.mjs";
+
+export const investigatorCommands = Object.freeze({
+  investigator: async (args) => {
+    assertInvestigatorArgs(args);
+    handleInvestigator();
+  },
+});

package/commands/notes.mjs

@@ -0,0 +1,39 @@
+import {
+  assertMintNotesArgs,
+  assertRedeemNotesArgs,
+  assertTransferNotesArgs,
+  assertWalletGetNotesArgs,
+  handleMintNotes,
+  handleRedeemNotes,
+  handleTransferNotes,
+  handleWalletGetNotes,
+  loadWalletCommandRuntime,
+  prepareDeploymentArtifacts,
+} from "../lib/runtime.mjs";
+
+export const notesCommands = Object.freeze({
+  "wallet-mint-notes": async (args) => {
+    assertMintNotesArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleMintNotes({ args, provider });
+  },
+  "wallet-redeem-notes": async (args) => {
+    assertRedeemNotesArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleRedeemNotes({ args, provider });
+  },
+  "wallet-get-notes": async (args) => {
+    assertWalletGetNotesArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleWalletGetNotes({ args, provider });
+  },
+  "wallet-transfer-notes": async (args) => {
+    assertTransferNotesArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleTransferNotes({ args, provider });
+  },
+});

package/commands/system.mjs

@@ -0,0 +1,49 @@
+import {
+  assertDoctorArgs,
+  assertGuideArgs,
+  assertInstallZkEvmArgs,
+  assertSetRpcArgs,
+  assertTransactionFeesArgs,
+  assertUninstallArgs,
+  assertUpdateArgs,
+  handleDoctor,
+  handleGuide,
+  handleInstallZkEvm,
+  handleSetRpc,
+  handleTransactionFees,
+  handleUninstall,
+  handleUpdate,
+  loadExplicitCommandRuntime,
+} from "../lib/runtime.mjs";
+
+export const systemCommands = Object.freeze({
+  install: async (args) => {
+    assertInstallZkEvmArgs(args);
+    await handleInstallZkEvm({ args });
+  },
+  uninstall: async (args) => {
+    assertUninstallArgs(args);
+    await handleUninstall();
+  },
+  "set-rpc": async (args) => {
+    assertSetRpcArgs(args);
+    await handleSetRpc({ args });
+  },
+  "help-update": async (args) => {
+    assertUpdateArgs(args);
+    await handleUpdate();
+  },
+  "help-doctor": async (args) => {
+    assertDoctorArgs(args);
+    await handleDoctor({ args });
+  },
+  "help-guide": async (args) => {
+    assertGuideArgs(args);
+    await handleGuide({ args });
+  },
+  "help-transaction-fees": async (args) => {
+    assertTransactionFeesArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args);
+    await handleTransactionFees({ network, provider, rpcUrl });
+  },
+});

package/commands/wallet.mjs

@@ -0,0 +1,86 @@
+import {
+  assertProviderChainIdMatchesNetwork,
+  assertListLocalWalletsArgs,
+  assertRecoverWalletArgs,
+  assertWalletChannelMoveArgs,
+  assertWalletExportBackupArgs,
+  assertWalletExportKeyArgs,
+  assertWalletGetChannelFundArgs,
+  assertWalletGetMetaArgs,
+  assertWalletImportBackupArgs,
+  assertWalletImportKeyArgs,
+  handleGrothVaultMove,
+  handleListLocalWallets,
+  handleRecoverWallet,
+  handleWalletExportBackup,
+  handleWalletExportKey,
+  handleWalletGetChannelFund,
+  handleWalletGetMeta,
+  handleWalletImportBackup,
+  handleWalletImportKey,
+  loadExplicitCommandRuntime,
+  loadWalletCommandRuntime,
+  prepareDeploymentArtifacts,
+} from "../lib/runtime.mjs";
+
+export const walletCommands = Object.freeze({
+  "wallet-list": async (args) => {
+    assertListLocalWalletsArgs(args);
+    handleListLocalWallets({ args });
+  },
+  "wallet-export-backup": async (args) => {
+    assertWalletExportBackupArgs(args);
+    handleWalletExportBackup({ args });
+  },
+  "wallet-export-viewing-key": async (args) => {
+    assertWalletExportKeyArgs(args, "wallet-export-viewing-key");
+    handleWalletExportKey({ args, keyKind: "viewing" });
+  },
+  "wallet-export-spending-key": async (args) => {
+    assertWalletExportKeyArgs(args, "wallet-export-spending-key");
+    handleWalletExportKey({ args, keyKind: "spending" });
+  },
+  "wallet-import-backup": async (args) => {
+    assertWalletImportBackupArgs(args);
+    handleWalletImportBackup({ args });
+  },
+  "wallet-import-viewing-key": async (args) => {
+    assertWalletImportKeyArgs(args, "wallet-import-viewing-key");
+    handleWalletImportKey({ args, keyKind: "viewing" });
+  },
+  "wallet-import-spending-key": async (args) => {
+    assertWalletImportKeyArgs(args, "wallet-import-spending-key");
+    handleWalletImportKey({ args, keyKind: "spending" });
+  },
+  "wallet-recover-workspace": async (args) => {
+    assertRecoverWalletArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { staticNetwork: true });
+    await assertProviderChainIdMatchesNetwork({ provider, network, rpcUrl });
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleRecoverWallet({ args, network, provider, rpcUrl });
+  },
+  "wallet-get-meta": async (args) => {
+    assertWalletGetMetaArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleWalletGetMeta({ args, provider });
+  },
+  "wallet-get-channel-fund": async (args) => {
+    assertWalletGetChannelFundArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleWalletGetChannelFund({ args, provider });
+  },
+  "wallet-deposit-channel": async (args) => {
+    assertWalletChannelMoveArgs(args, "wallet-deposit-channel");
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleGrothVaultMove({ args, provider, direction: "deposit" });
+  },
+  "wallet-withdraw-channel": async (args) => {
+    assertWalletChannelMoveArgs(args, "wallet-withdraw-channel");
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleGrothVaultMove({ args, provider, direction: "withdraw" });
+  },
+});

package/investigator/README.md

@@ -10,13 +10,13 @@ private-state-cli wallet get-notes \
   --acknowledge-full-note-plaintext-export
 ```
 
-Open `index.html` in a modern browser, load the raw ZIP, select a filter scope, and build a narrower
-user-consent disclosure ZIP. From an installed CLI package, `private-state-cli investigator` prints the bundled
-HTML path and opens it in the default browser.
+Open `index.html` in a modern browser, load the raw ZIP, choose the disclosure request type, inspect the graph, and
+build a narrower user-consent disclosure ZIP. From an installed CLI package, `private-state-cli investigator` prints
+the bundled HTML path and opens it in the default browser.
 
 The tool does not run a server and does not send files over the network. It reads the selected ZIP in
-the browser and writes a new ZIP with selected note records plus directly referenced transaction,
-receipt, and event files.
+the browser. It can write a new ZIP with selected note records plus directly referenced transaction,
+receipt, and event files, and it can export a Markdown ASCII-art linkage report.
 
 The raw evidence bundle contains plaintext for all locally known notes. Do not submit the raw bundle
 as an exchange or auditor package unless full wallet-history disclosure is intended. Use the
@@ -26,7 +26,17 @@ The investigator accepts current epoch-aware evidence bundles only. Supported no
 `wallets/<wallet>/epochs/<epoch-id>/notes/` inside the ZIP. If a bundle uses an older layout, rebuild the local wallet
 workspace with `wallet recover-workspace` and export a new evidence ZIP with `wallet get-notes --export-evidence`.
 
-## Supported Filtering
+## Supported Investigation Views
+
+- purpose-first request presets for full graph view, specific note receipt, specific note use, transaction linkage,
+  period receipts, and counterparty subsets
+- an interactive SVG note-linkage graph where every matched note is a node
+- graph edges for external note creation, external note spend, and locally recoverable note-to-note linkage
+- node detail overlays showing commitment, nullifier, value, status, creation reference, spend reference, direction, and
+  available counterparty metadata
+- a Markdown ASCII-art report with a compact graph section and separate note detail sections
+
+## Supported Filtering Inputs
 
 - note commitment or nullifier
 - creation transaction or spend transaction