@tokamak-private-dapps/private-state-cli 1.0.2 → 1.1.1

package/cli-assistant.html

@@ -414,31 +414,31 @@
           <div class="box">
             <ol class="guide-list">
               <li>
-                <span class="guide-label">Join a channel:</span> <code>join-channel</code>
+                <span class="guide-label">Join a channel:</span> <code>channel join</code>
                 <div class="guide-example">
-                  <code>join-channel --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' --rpc-url '__RPC_URL__'</code>
                 </div>
               </li>
               <li>
-                <span class="guide-label">Create notes:</span> <code>deposit-bridge</code> -&gt; <code>deposit-channel</code> -&gt; <code>mint-notes</code>
+                <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>deposit-bridge --amount '100' --network 'sepolia' --account 'my-account' --rpc-url '__RPC_URL__'</code><br />
-                  <code>deposit-channel --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amount '100'</code><br />
-                  <code>mint-notes --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amounts '[&quot;50&quot;,&quot;50&quot;,&quot;0&quot;]'</code>
+                  <code>account deposit-bridge --amount '100' --network 'sepolia' --account 'my-account' --rpc-url '__RPC_URL__'</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>
               </li>
               <li>
-                <span class="guide-label">Split, merge, or transfer note ownership:</span> <code>transfer-notes</code>
+                <span class="guide-label">Split, merge, or transfer note ownership:</span> <code>wallet transfer-notes</code>
                 <div class="guide-example">
-                  <code>transfer-notes --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --note-ids '[&quot;0xNoteIdA&quot;]' --recipients '[&quot;0xRecipientL2AddressA&quot;,&quot;0xRecipientL2AddressB&quot;]' --amounts '[&quot;25&quot;,&quot;25&quot;]'</code>
+                  <code>wallet transfer-notes --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --note-ids '[&quot;0xNoteIdA&quot;]' --recipients '[&quot;0xRecipientL2AddressA&quot;,&quot;0xRecipientL2AddressB&quot;]' --amounts '[&quot;25&quot;,&quot;25&quot;]'</code>
                 </div>
               </li>
               <li>
-                <span class="guide-label">Redeem notes back to L1:</span> <code>redeem-notes</code> -&gt; <code>withdraw-channel</code> -&gt; <code>withdraw-bridge</code>
+                <span class="guide-label">Redeem notes back to L1:</span> <code>wallet redeem-notes</code> -&gt; <code>wallet withdraw-channel</code> -&gt; <code>account withdraw-bridge</code>
                 <div class="guide-example">
-                  <code>redeem-notes --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --note-ids '[&quot;0xNoteIdA&quot;]'</code><br />
-                  <code>withdraw-channel --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amount '25'</code><br />
-                  <code>withdraw-bridge --amount '25' --network 'sepolia' --account 'my-account' --rpc-url '__RPC_URL__'</code>
+                  <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>
                 </div>
               </li>
             </ol>
@@ -466,7 +466,7 @@
       }));
 
       const defaultState = {
-        commandId: "join-channel",
+        commandId: "channel-join",
         channelName: "",
         joinToll: "1",
         network: "sepolia",
@@ -612,13 +612,13 @@
       }
 
       function commandNeedsWalletNotes(command = currentCommand()) {
-        return command.id === "transfer-notes" || command.id === "redeem-notes";
+        return command.id === "wallet-transfer-notes" || command.id === "wallet-redeem-notes";
       }
 
       function commandNeedsExistingChannel(command = currentCommand()) {
         return command.fields.includes("channelName")
-          && command.id !== "create-channel"
-          && command.id !== "recover-workspace";
+          && command.id !== "channel-create"
+          && command.id !== "channel-recover-workspace";
       }
 
       function currentWorkspaceOptions() {
@@ -695,7 +695,7 @@
       }
 
       function noteSelectionLimit() {
-        return currentCommand().id === "redeem-notes" ? 1 : 2;
+        return currentCommand().id === "wallet-redeem-notes" ? 1 : 2;
       }
 
       function mintAmountsTotalLabel() {
@@ -814,7 +814,7 @@
           await refreshWalletNoteOptions();
           if (commandNeedsWalletNotes()) {
             rerenderCommandField("noteIds");
-            if (currentCommand().id === "transfer-notes") {
+            if (currentCommand().id === "wallet-transfer-notes") {
               rerenderCommandField("recipients");
             }
           }
@@ -838,7 +838,7 @@
       }
 
       function missingFields(command) {
-        const transferOutputs = command.id === "transfer-notes"
+        const transferOutputs = command.id === "wallet-transfer-notes"
           ? currentTransferOutputs()
           : null;
         const optionalFields = new Set(command.optionalFields ?? []);
@@ -846,10 +846,10 @@
           if (fieldCatalog[fieldKey]?.optional || optionalFields.has(fieldKey)) {
             return false;
           }
-          if (fieldKey === "amounts" && command.id === "mint-notes") {
+          if (fieldKey === "amounts" && command.id === "wallet-mint-notes") {
             return currentMintAmounts().length === 0;
           }
-          if ((fieldKey === "recipients" || fieldKey === "amounts") && command.id === "transfer-notes") {
+          if ((fieldKey === "recipients" || fieldKey === "amounts") && command.id === "wallet-transfer-notes") {
             if (fieldKey === "amounts") {
               return false;
             }
@@ -861,8 +861,8 @@
 
       function buildCommand({ maskSecrets }) {
         const command = currentCommand();
-        const parts = [cliEntry, command.id];
-        const transferOutputs = command.id === "transfer-notes"
+        const parts = [cliEntry, ...(command.display ?? command.id).split(" ")];
+        const transferOutputs = command.id === "wallet-transfer-notes"
           ? currentTransferOutputs()
           : null;
 
@@ -871,13 +871,13 @@
             continue;
           }
 
-          const value = fieldKey === "amounts" && command.id === "mint-notes"
+          const value = fieldKey === "amounts" && command.id === "wallet-mint-notes"
             ? JSON.stringify(currentMintAmounts())
-            : fieldKey === "amounts" && command.id === "transfer-notes"
+            : fieldKey === "amounts" && command.id === "wallet-transfer-notes"
               ? (!transferOutputs.hasPartialPair && transferOutputs.amounts.length > 0
                 ? JSON.stringify(transferOutputs.amounts)
                 : "")
-              : fieldKey === "recipients" && command.id === "transfer-notes"
+              : fieldKey === "recipients" && command.id === "wallet-transfer-notes"
                 ? (!transferOutputs.hasPartialPair && transferOutputs.recipients.length > 0
                   ? JSON.stringify(transferOutputs.recipients)
                   : "")
@@ -990,8 +990,8 @@
         const currentOptions = currentWorkspaceOptions();
         if (
           !currentOptions.channelOptions.includes(state.channelName)
-          && currentCommand().id !== "create-channel"
-          && currentCommand().id !== "recover-workspace"
+          && currentCommand().id !== "channel-create"
+          && currentCommand().id !== "channel-recover-workspace"
         ) {
           state.channelName = currentOptions.channelOptions[0] ?? "";
         }
@@ -1167,7 +1167,7 @@
               state.noteIds = nextSelection.length === 0 ? "" : JSON.stringify(nextSelection);
               persistState();
               rerenderCommandField("noteIds");
-              if (currentCommand().id === "transfer-notes") {
+              if (currentCommand().id === "wallet-transfer-notes") {
                 rerenderCommandField("recipients");
               }
               renderPreview();
@@ -1334,10 +1334,10 @@
         if (fieldKey === "wallet") {
           return createWalletField();
         }
-        if (fieldKey === "amounts" && currentCommand().id === "mint-notes") {
+        if (fieldKey === "amounts" && currentCommand().id === "wallet-mint-notes") {
           return createMintAmountsField();
         }
-        if (fieldKey === "recipients" && currentCommand().id === "transfer-notes") {
+        if (fieldKey === "recipients" && currentCommand().id === "wallet-transfer-notes") {
           return createTransferPairsField();
         }
         if (fieldKey === "noteIds" && commandNeedsWalletNotes()) {
@@ -1345,8 +1345,8 @@
         }
         if (
           fieldKey === "channelName"
-          && currentCommand().id !== "create-channel"
-          && currentCommand().id !== "recover-workspace"
+          && currentCommand().id !== "channel-create"
+          && currentCommand().id !== "channel-recover-workspace"
         ) {
           return createExistingChannelField();
         }
@@ -1423,7 +1423,7 @@
         for (const command of commands) {
           const option = document.createElement("option");
           option.value = command.id;
-          option.textContent = command.id;
+          option.textContent = command.display ?? command.id;
           commandSelectEl.appendChild(option);
         }
         commandSelectEl.value = state.commandId;
@@ -1450,7 +1450,7 @@
           if (fieldKey === "rpcUrl" && !acceptsRpcUrl(command)) {
             continue;
           }
-          if (fieldKey === "amounts" && command.id === "transfer-notes") {
+          if (fieldKey === "amounts" && command.id === "wallet-transfer-notes") {
             continue;
           }
           const fieldElement = createField(fieldKey);

package/lib/private-state-cli-command-registry.mjs

@@ -68,6 +68,34 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     valueLabel: "<NAME>",
     option: "--wallet",
   },
+  output: {
+    label: "Output ZIP",
+    type: "text",
+    placeholder: "/path/to/wallet-export.zip",
+    valueLabel: "<ZIP>",
+    option: "--output",
+  },
+  input: {
+    label: "Input ZIP",
+    type: "text",
+    placeholder: "/path/to/wallet-export.zip",
+    valueLabel: "<ZIP>",
+    option: "--input",
+  },
+  all: {
+    label: "All Mainnet Wallets",
+    type: "checkbox",
+    hint: "Export every local mainnet wallet instead of one selected wallet.",
+    option: "--all",
+    optional: true,
+  },
+  includeNotes: {
+    label: "Include Immediate-Use Cache",
+    type: "checkbox",
+    hint: "Also export the channel workspace cache needed to use note and wallet commands without running recovery first.",
+    option: "--include-notes",
+    optional: true,
+  },
   amount: {
     label: "Amount",
     type: "text",
@@ -168,7 +196,15 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "no options",
   },
   {
-    id: "update",
+    id: "help-commands",
+    display: "help commands",
+    description: "Show the private-state CLI command reference.",
+    fields: [],
+    usage: "no options",
+  },
+  {
+    id: "help-update",
+    display: "help update",
     description: "Check npm registry for the latest private-state CLI package and update global installs when possible.",
     fields: ["json"],
     usage: "optional --json",
@@ -178,7 +214,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     ],
   },
   {
-    id: "doctor",
+    id: "help-doctor",
+    display: "help doctor",
     description: "Check private-state CLI package versions, runtime install state, Docker mode, CUDA mode, and deployment artifacts.",
     fields: ["gpu", "json"],
     usage: "optional --gpu and optional --json",
@@ -188,7 +225,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     ],
   },
   {
-    id: "guide",
+    id: "help-guide",
+    display: "help guide",
     description: "Inspect local CLI state and available on-chain state, then print the next safe command.",
     fields: ["network", "channelName", "account", "wallet"],
     optionalFields: ["network", "channelName", "account", "wallet"],
@@ -196,7 +234,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     help: ["Does not accept --rpc-url and never writes RPC configuration"],
   },
   {
-    id: "transaction-fees",
+    id: "help-transaction-fees",
+    display: "help transaction-fees",
     description: "Estimate ETH and USD fees for transaction-sending commands from packaged measured gas data and live network fee data.",
     fields: ["network", "rpcUrl", "json"],
     usage: "--network, optional --rpc-url, and optional --json",
@@ -213,7 +252,22 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "--account, --network, and --private-key-file",
   },
   {
-    id: "create-channel",
+    id: "account-get-l1-address",
+    display: "account get-l1-address",
+    description: "Derive the L1 address for a local account.",
+    fields: ["account", "network"],
+    usage: "--network and --account",
+  },
+  {
+    id: "account-get-bridge-fund",
+    display: "account get-bridge-fund",
+    description: "Read the local account's current shared bridge vault balance.",
+    fields: ["network", "account", "rpcUrl"],
+    usage: "--network, --account, and optional --rpc-url",
+  },
+  {
+    id: "channel-create",
+    display: "channel create",
     description: "Create a bridge channel and initialize its workspace.",
     fields: ["channelName", "joinToll", "network", "account", "rpcUrl"],
     usage: "--channel-name, --join-toll, --network, --account, and optional --rpc-url",
@@ -223,7 +277,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     ],
   },
   {
-    id: "recover-workspace",
+    id: "channel-recover-workspace",
+    display: "channel recover-workspace",
     description: "Rebuild the local channel workspace from bridge state.",
     fields: ["channelName", "network", "fromGenesis", "rpcUrl"],
     usage: "--channel-name, --network, optional --from-genesis, and optional --rpc-url",
@@ -235,36 +290,34 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     ],
   },
   {
-    id: "get-channel",
+    id: "channel-get-meta",
+    display: "channel get-meta",
     description: "Read channel existence, manager, vault, toll, refund schedule, and immutable policy snapshot.",
     fields: ["channelName", "network", "rpcUrl"],
     usage: "--channel-name, --network, and optional --rpc-url",
   },
   {
-    id: "deposit-bridge",
+    id: "account-deposit-bridge",
+    display: "account deposit-bridge",
     description: "Deposit canonical tokens into the shared bridge vault.",
     fields: ["amount", "network", "account", "rpcUrl"],
     usage: "--amount, --network, --account, and optional --rpc-url",
   },
   {
-    id: "withdraw-bridge",
+    id: "account-withdraw-bridge",
+    display: "account withdraw-bridge",
     description: "Withdraw tokens from the shared bridge vault back to the wallet.",
     fields: ["amount", "network", "account", "rpcUrl"],
     usage: "--amount, --network, --account, and optional --rpc-url",
   },
   {
-    id: "get-my-bridge-fund",
-    description: "Read the current shared bridge vault balance.",
-    fields: ["network", "account", "rpcUrl"],
-    usage: "--network, --account, and optional --rpc-url",
-  },
-  {
-    id: "recover-wallet",
+    id: "wallet-recover-workspace",
+    display: "wallet recover-workspace",
     description: "Rebuild a recoverable local wallet from on-chain channel state.",
     fields: ["channelName", "network", "account", "fromGenesis", "rpcUrl"],
     usage: "--channel-name, --network, --account, optional --from-genesis, and optional --rpc-url",
     help: [
-      "Requires the protected wallet-local secret imported during join-channel to exist at the canonical secret path",
+      "Requires the protected wallet-local secret imported during channel join to exist at the canonical secret path",
       "Does not create or recover the wallet secret itself",
       "By default, resumes RPC log scanning from the workspace recovery index when available",
       "Fails instead of falling back to genesis when no usable recovery index exists",
@@ -273,83 +326,114 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     ],
   },
   {
-    id: "join-channel",
+    id: "channel-join",
+    display: "channel join",
     description: "Pay the channel join toll and bind a wallet to a channel-specific L2 identity.",
     fields: ["channelName", "network", "account", "walletSecretPath", "rpcUrl"],
     usage: "--channel-name, --network, --account, --wallet-secret-path, and optional --rpc-url",
     help: [
+      "Requires a recovered channel workspace and refreshes it through the workspace recovery index before joining",
+      "Run channel recover-workspace --from-genesis once if no usable local recovery index exists",
       "--wallet-secret-path imports an existing source secret file into the protected wallet-local secret file",
       "Prints the immutable policy snapshot before first registration",
     ],
   },
   {
-    id: "get-my-wallet-meta",
+    id: "wallet-get-meta",
+    display: "wallet get-meta",
     description: "Check whether a wallet matches the on-chain channel registration.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
     help: ["Refreshes channel state through the workspace recovery index before reading registration metadata"],
   },
   {
-    id: "get-my-l1-address",
-    description: "Derive the L1 address for a private key.",
-    fields: ["account", "network"],
-    usage: "--network and --account",
-  },
-  {
-    id: "list-local-wallets",
+    id: "wallet-list",
+    display: "wallet list",
     description: "List saved local wallet names that can be reused with --wallet.",
     fields: ["network", "channelName"],
     optionalFields: ["network", "channelName"],
     usage: "optional --network and --channel-name",
   },
   {
-    id: "deposit-channel",
+    id: "wallet-export",
+    display: "wallet export",
+    description: "Export a local wallet backup ZIP that can be imported on another machine.",
+    fields: ["network", "wallet", "output", "all", "includeNotes"],
+    optionalFields: ["network", "wallet"],
+    usage: "--output, plus either --network and --wallet or --all; optional --include-notes",
+    help: [
+      "Default export includes the encrypted wallet, wallet metadata, and wallet-local secret; run channel recover-workspace after import",
+      "--include-notes also includes the channel workspace cache so wallet commands can run immediately when the cache is still chain-aligned",
+      "--all exports every local mainnet wallet and does not accept --network or --wallet",
+    ],
+  },
+  {
+    id: "wallet-import",
+    display: "wallet import",
+    description: "Import a ZIP created by wallet export into the canonical local wallet workspace.",
+    fields: ["input"],
+    usage: "--input",
+    help: [
+      "Refuses to overwrite existing wallet secrets or wallet files",
+      "Default exports require channel recover-workspace after import before wallet commands can use channel state",
+    ],
+  },
+  {
+    id: "wallet-deposit-channel",
+    display: "wallet deposit-channel",
     description: "Move bridged funds into the channel L2 accounting balance.",
     fields: ["wallet", "network", "amount"],
     usage: "--wallet, --network, and --amount",
   },
   {
-    id: "withdraw-channel",
+    id: "wallet-withdraw-channel",
+    display: "wallet withdraw-channel",
     description: "Move channel L2 balance back into the shared bridge vault.",
     fields: ["wallet", "network", "amount"],
     usage: "--wallet, --network, and --amount",
   },
   {
-    id: "get-my-channel-fund",
+    id: "wallet-get-channel-fund",
+    display: "wallet get-channel-fund",
     description: "Read the current channel L2 accounting balance.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
     help: ["Refreshes channel state through the workspace recovery index before reading the L2 accounting balance"],
   },
   {
-    id: "exit-channel",
+    id: "channel-exit",
+    display: "channel exit",
     description: "Exit a channel. Both the CLI and bridge contract require a zero channel balance.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
   },
   {
-    id: "mint-notes",
+    id: "wallet-mint-notes",
+    display: "wallet mint-notes",
     description: "Mint one or two private-state notes from the wallet's channel balance.",
     fields: ["wallet", "network", "amounts", "txSubmitter"],
     usage: "--wallet, --network, --amounts, and optional --tx-submitter",
     help: ["Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy"],
   },
   {
-    id: "transfer-notes",
+    id: "wallet-transfer-notes",
+    display: "wallet transfer-notes",
     description: "Spend input notes into the registered 1->1, 1->2, or 2->1 private transfer shapes.",
     fields: ["wallet", "network", "noteIds", "recipients", "amounts", "txSubmitter"],
     usage: "--wallet, --network, --note-ids, --recipients, --amounts, and optional --tx-submitter",
     help: ["Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy"],
   },
   {
-    id: "redeem-notes",
+    id: "wallet-redeem-notes",
+    display: "wallet redeem-notes",
     description: "Redeem one tracked note back into the wallet's channel balance.",
     fields: ["wallet", "network", "noteIds", "txSubmitter"],
     usage: "--wallet, --network, --note-ids, and optional --tx-submitter",
     help: ["Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy"],
   },
   {
-    id: "get-my-notes",
+    id: "wallet-get-notes",
+    display: "wallet get-notes",
     description: "Show the wallet's tracked note state and refresh received notes.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",

package/lib/private-state-runtime-management.mjs

@@ -143,7 +143,7 @@ function printDoctorHumanReport(report) {
     "",
     formatDoctorTable(rows),
     "",
-    "Run `doctor --json` for the full machine-readable report.",
+    "Run `help doctor --json` for the full machine-readable report.",
   ];
   console.log(lines.join("\n"));
 }
@@ -190,7 +190,7 @@ function buildDoctorHumanRows(report) {
       check: "docker gpu readiness",
       status: report.gpuDockerReadiness.skipped ? "SKIP" : doctorStatus(report.gpuDockerReadiness.ok),
       detail: report.gpuDockerReadiness.skipped
-        ? "live GPU probe skipped; run `doctor --gpu` to check host NVIDIA and Docker GPU access"
+        ? "live GPU probe skipped; run `help doctor --gpu` to check host NVIDIA and Docker GPU access"
         : [
           `expectedUseGpus=${formatDoctorBool(report.gpuDockerReadiness.expectedUseGpus)}`,
           `liveUseGpus=${formatDoctorBool(report.gpuDockerReadiness.liveUseGpus)}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",
@@ -46,6 +46,7 @@
     "@tokamak-private-dapps/common-library": "^0.1.1",
     "@tokamak-private-dapps/groth16": "^0.2.0",
     "@tokamak-zk-evm/cli": "^2.1.0",
+    "adm-zip": "^0.5.17",
     "ethers": "^6.14.1",
     "tokamak-l2js": "^0.1.4"
   },