@tokamak-private-dapps/private-state-cli 1.2.1 → 2.1.0

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

@@ -58,7 +58,7 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     type: "text",
     placeholder: "/path/to/wallet-secret",
     valueLabel: "<PATH>",
-    hint: "Source file permissions are not enforced; the imported wallet-local secret is protected.",
+    hint: "Source file permissions are not enforced; the secret is read once for channel-bound spending-key derivation and is not stored in the wallet workspace.",
     option: "--wallet-secret-path",
   },
   wallet: {
@@ -75,26 +75,34 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     valueLabel: "<PATH>",
     option: "--output",
   },
-  input: {
-    label: "Input ZIP",
+  exportEvidence: {
+    label: "Evidence ZIP",
     type: "text",
-    placeholder: "/path/to/wallet-export.zip",
-    valueLabel: "<ZIP>",
-    option: "--input",
+    placeholder: "/path/to/evidence.zip",
+    valueLabel: "<PATH>",
+    hint: "Optional. Export a local full-note evidence bundle as a ZIP for later selective filtering.",
+    option: "--export-evidence",
+    optional: true,
   },
-  all: {
-    label: "All Mainnet Wallets",
+  acknowledgeFullNotePlaintextExport: {
+    label: "Acknowledge Note Plaintext Export",
     type: "checkbox",
-    hint: "Export every local mainnet wallet instead of one selected wallet.",
-    option: "--all",
+    hint: "Required with --export-evidence. Confirms that all locally known note plaintext will be written to the ZIP.",
+    option: "--acknowledge-full-note-plaintext-export",
     optional: true,
   },
-  includeNotes: {
-    label: "Include Immediate-Use Cache",
+  acknowledgeActionImpact: {
+    label: "Acknowledge Action Impact",
     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,
+    hint: "Required for transaction-sending bridge, channel, and note commands. Confirms that the user reviewed the public/private action-impact warning.",
+    option: "--acknowledge-action-impact",
+  },
+  input: {
+    label: "Input File",
+    type: "text",
+    placeholder: "/path/to/wallet-backup.zip",
+    valueLabel: "<PATH>",
+    option: "--input",
   },
   amount: {
     label: "Amount",
@@ -201,6 +209,15 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
   },
 });
 
+const ACTION_IMPACT_HELP = Object.freeze({
+  acknowledgement: "Requires --acknowledge-action-impact after the user reviews the action-impact warning.",
+  illegalUse: "The command must not be used for money laundering, sanctions evasion, terrorist financing, illegal gambling, criminal-proceeds concealment, or regulatory evasion.",
+  secretRecovery: "Losing wallet secrets, viewing keys, or spending keys can prevent note discovery or note use; the CLI cannot recover lost secrets.",
+  cexAddress: "Do not use a centralized-exchange controlled address as a self-custody bridge source or direct bridge withdrawal target.",
+  policy: "The user must review the channel policy snapshot before accepting channel-bound actions.",
+  provenance: "Public observers cannot reconstruct private note counterparty relationships or note provenance from public contract state alone.",
+});
+
 export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
   {
     id: "install",
@@ -268,6 +285,17 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "Reads live fee data from the selected network RPC and live ETH/USD from CoinGecko",
     ],
   },
+  {
+    id: "investigator",
+    description: "Open the local evidence investigator GUI in the default browser.",
+    fields: [],
+    usage: "no options",
+    help: [
+      "Prints the local investigator HTML path and opens it in the default browser",
+      "Use wallet get-notes --export-evidence first, then load the raw ZIP in the investigator GUI",
+      "The raw evidence ZIP contains full locally known note plaintext and should not be submitted as-is unless full wallet-history disclosure is intended",
+    ],
+  },
   {
     id: "account-import",
     display: "account import",
@@ -349,15 +377,29 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+    fields: ["amount", "network", "account", "acknowledgeActionImpact", "rpcUrl"],
+    usage: "--amount, --network, --account, --acknowledge-action-impact, and optional --rpc-url",
+    help: [
+      "Action impact: emits public L1 approval and bridge funding events that expose the local L1 account, bridge vault, amount, and transaction hashes.",
+      "Private note state is not changed by this command.",
+      ACTION_IMPACT_HELP.cexAddress,
+      ACTION_IMPACT_HELP.illegalUse,
+      ACTION_IMPACT_HELP.acknowledgement,
+    ],
   },
   {
     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",
+    fields: ["amount", "network", "account", "acknowledgeActionImpact", "rpcUrl"],
+    usage: "--amount, --network, --account, --acknowledge-action-impact, and optional --rpc-url",
+    help: [
+      "Action impact: emits a public L1 bridge withdrawal event that exposes the local L1 recipient, bridge vault, amount, and transaction hash.",
+      "Private note state is not changed by this command; prior note provenance is not public by default.",
+      ACTION_IMPACT_HELP.cexAddress,
+      ACTION_IMPACT_HELP.illegalUse,
+      ACTION_IMPACT_HELP.acknowledgement,
+    ],
   },
   {
     id: "wallet-recover-workspace",
@@ -366,8 +408,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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 channel join to exist at the canonical secret path",
-      "Does not create or recover the wallet secret itself",
+      "Rebuilds backup metadata from channel state without recreating the spending key",
+      "Derives and stores the viewing key when the local account signer can reproduce the registered viewing public key",
       "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",
       "Use --from-genesis to ignore the recovery index and replay channel logs from channel genesis",
@@ -378,13 +420,19 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+    fields: ["channelName", "network", "account", "walletSecretPath", "acknowledgeActionImpact", "rpcUrl"],
+    usage: "--channel-name, --network, --account, --wallet-secret-path, --acknowledge-action-impact, and optional --rpc-url",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before joining when the scan fits the 10 second pre-command budget",
       "Fails instead of replaying from genesis; run channel recover-workspace --source rpc --from-genesis when a genesis rebuild is required",
-      "--wallet-secret-path imports an existing source secret file into the protected wallet-local secret file",
+      "--wallet-secret-path is read once for channel-bound L2 spending-key derivation and is not stored in the wallet workspace",
       "Prints the immutable policy snapshot before first registration",
+      "Action impact: emits public channel join and token-vault registration events exposing the L1 account, L2 address pair, note-receive public key, join toll, and channel id.",
+      "Private note state is not changed by this command.",
+      ACTION_IMPACT_HELP.policy,
+      ACTION_IMPACT_HELP.secretRecovery,
+      ACTION_IMPACT_HELP.illegalUse,
+      ACTION_IMPACT_HELP.acknowledgement,
     ],
   },
   {
@@ -393,7 +441,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Check whether a wallet matches the on-chain channel registration.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
-    help: ["Refreshes the local channel workspace through the saved recovery index before reading registration metadata when the scan fits the 10 second pre-command budget"],
+    help: [
+      "Refreshes the local channel workspace through the saved recovery index before reading registration metadata when the scan fits the 10 second pre-command budget",
+      "Reports the selected local wallet epoch and lifecycle status when the workspace uses the epoch-aware wallet format",
+    ],
   },
   {
     id: "wallet-list",
@@ -404,44 +455,87 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "optional --network and --channel-name",
   },
   {
-    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",
+    id: "wallet-export-backup",
+    display: "wallet export backup",
+    description: "Export a wallet backup ZIP without spending keys, viewing keys, derivation material, or plaintext note secrets.",
+    fields: ["network", "wallet", "output"],
+    usage: "--network, --wallet, and --output",
     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",
+      "Includes wallet note-tracking metadata, public key metadata, and channel workspace cache",
+      "Excludes L1 private keys, L2 spending keys, viewing private keys, wallet secrets, owner, value, and salt",
     ],
   },
   {
-    id: "wallet-import",
-    display: "wallet import",
-    description: "Import a ZIP created by wallet export into the canonical local wallet workspace.",
+    id: "wallet-export-viewing-key",
+    display: "wallet export viewing-key",
+    description: "Export a secret .key file containing the wallet viewing private key and public viewing-key metadata.",
+    fields: ["network", "wallet", "output"],
+    usage: "--network, --wallet, and --output",
+  },
+  {
+    id: "wallet-export-spending-key",
+    display: "wallet export spending-key",
+    description: "Export a secret .key file containing the wallet L2 spending private key and public spending-key metadata.",
+    fields: ["network", "wallet", "output"],
+    usage: "--network, --wallet, and --output",
+  },
+  {
+    id: "wallet-import-backup",
+    display: "wallet import backup",
+    description: "Import a backup ZIP created by wallet export backup.",
     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",
+      "Refuses to overwrite existing wallet metadata or workspace cache files",
+      "Does not grant viewing or spending authority; import the corresponding key files separately when needed",
     ],
   },
+  {
+    id: "wallet-import-viewing-key",
+    display: "wallet import viewing-key",
+    description: "Import a secret .key file created by wallet export viewing-key.",
+    fields: ["input"],
+    usage: "--input",
+  },
+  {
+    id: "wallet-import-spending-key",
+    display: "wallet import spending-key",
+    description: "Import a secret .key file created by wallet export spending-key.",
+    fields: ["input"],
+    usage: "--input",
+  },
   {
     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",
-    help: ["Refreshes the local channel workspace through the saved recovery index before proving the deposit when the scan fits the 10 second pre-command budget"],
+    fields: ["wallet", "network", "amount", "acknowledgeActionImpact"],
+    usage: "--wallet, --network, --amount, and --acknowledge-action-impact",
+    help: [
+      "Refreshes the local channel workspace through the saved recovery index before proving the deposit when the scan fits the 10 second pre-command budget",
+      "Action impact: emits public proof-backed bridge/channel accounting events exposing the L1 submitter, registered L2 address, amount, channel id, and transaction hash.",
+      "Private note state is not changed by this command.",
+      ACTION_IMPACT_HELP.policy,
+      ACTION_IMPACT_HELP.secretRecovery,
+      ACTION_IMPACT_HELP.illegalUse,
+      ACTION_IMPACT_HELP.acknowledgement,
+    ],
   },
   {
     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",
-    help: ["Refreshes the local channel workspace through the saved recovery index before proving the withdrawal when the scan fits the 10 second pre-command budget"],
+    fields: ["wallet", "network", "amount", "acknowledgeActionImpact"],
+    usage: "--wallet, --network, --amount, and --acknowledge-action-impact",
+    help: [
+      "Refreshes the local channel workspace through the saved recovery index before proving the withdrawal when the scan fits the 10 second pre-command budget",
+      "Action impact: emits public proof-backed bridge/channel accounting events exposing the L1 submitter, registered L2 address, amount, channel id, and transaction hash.",
+      "Private note state is not changed by this command; prior note provenance is not public by default.",
+      ACTION_IMPACT_HELP.provenance,
+      ACTION_IMPACT_HELP.policy,
+      ACTION_IMPACT_HELP.secretRecovery,
+      ACTION_IMPACT_HELP.illegalUse,
+      ACTION_IMPACT_HELP.acknowledgement,
+    ],
   },
   {
     id: "wallet-get-channel-fund",
@@ -457,51 +551,77 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Exit a channel. Both the CLI and bridge contract require a zero channel balance.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
-    help: ["Refreshes the local channel workspace through the saved recovery index before checking the channel balance when the scan fits the 10 second pre-command budget"],
+    help: [
+      "Refreshes the local channel workspace through the saved recovery index before checking the channel balance when the scan fits the 10 second pre-command budget",
+      "Marks the current local wallet epoch as exited and keeps its note metadata available for historical evidence export",
+    ],
   },
   {
     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",
+    fields: ["wallet", "network", "amounts", "acknowledgeActionImpact", "txSubmitter"],
+    usage: "--wallet, --network, --amounts, --acknowledge-action-impact, and optional --tx-submitter",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before proving the mint when the scan fits the 10 second pre-command budget",
       "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
+      "Action impact: emits public accepted-transition, commitment, encrypted note-delivery, root update, and transaction events.",
+      "Private note state changes by creating local note plaintext and public commitments; note owner/value/salt are not public by default.",
+      ACTION_IMPACT_HELP.provenance,
+      ACTION_IMPACT_HELP.policy,
+      ACTION_IMPACT_HELP.secretRecovery,
+      ACTION_IMPACT_HELP.illegalUse,
+      ACTION_IMPACT_HELP.acknowledgement,
     ],
   },
   {
     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",
+    fields: ["wallet", "network", "noteIds", "recipients", "amounts", "acknowledgeActionImpact", "txSubmitter"],
+    usage: "--wallet, --network, --note-ids, --recipients, --amounts, --acknowledge-action-impact, and optional --tx-submitter",
     help: [
       "Refreshes the local channel workspace and received-note logs through saved recovery indexes before proving the transfer when scans fit the 10 second pre-command budget",
       "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
+      "Action impact: emits public accepted-transition, input nullifier, output commitment, encrypted note-delivery, root update, and transaction events.",
+      "Private note state changes by consuming selected input notes and creating output notes; sender-recipient relationship, note plaintext, and note provenance are not public by default.",
+      ACTION_IMPACT_HELP.provenance,
+      ACTION_IMPACT_HELP.policy,
+      ACTION_IMPACT_HELP.secretRecovery,
+      ACTION_IMPACT_HELP.illegalUse,
+      ACTION_IMPACT_HELP.acknowledgement,
     ],
   },
   {
     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",
+    fields: ["wallet", "network", "noteIds", "acknowledgeActionImpact", "txSubmitter"],
+    usage: "--wallet, --network, --note-ids, --acknowledge-action-impact, and optional --tx-submitter",
     help: [
       "Refreshes the local channel workspace and received-note logs through saved recovery indexes before proving the redeem when scans fit the 10 second pre-command budget",
       "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
+      "Action impact: emits public accepted-transition, note nullifier, accounting update, root update, and transaction events.",
+      "Private note state changes by consuming selected notes; prior note provenance is not public by default.",
+      ACTION_IMPACT_HELP.provenance,
+      ACTION_IMPACT_HELP.policy,
+      ACTION_IMPACT_HELP.secretRecovery,
+      ACTION_IMPACT_HELP.illegalUse,
+      ACTION_IMPACT_HELP.acknowledgement,
     ],
   },
   {
     id: "wallet-get-notes",
     display: "wallet get-notes",
     description: "Refresh received notes when the saved recovery index is recent, then show tracked note state.",
-    fields: ["wallet", "network"],
-    usage: "--wallet and --network",
+    fields: ["wallet", "network", "exportEvidence", "acknowledgeFullNotePlaintextExport"],
+    usage: "--wallet, --network, optional --export-evidence, and optional --acknowledge-full-note-plaintext-export",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before reading notes when the scan fits the 10 second pre-command budget",
       "Refreshes received-note logs through the saved wallet note recovery index when the scan fits the 10 second pre-command budget",
       "Fails instead of replaying from genesis; run wallet recover-workspace --from-genesis when a genesis rebuild is required",
+      "Use --export-evidence <PATH> with --acknowledge-full-note-plaintext-export to write a local full-note evidence ZIP for private-state-cli investigator",
+      "Evidence export includes all local epochs for the selected wallet, including exited epochs retained for dispute evidence",
     ],
   },
 ]);

package/lib/private-state-cli-shared.mjs

@@ -88,7 +88,3 @@ export function workspaceWalletsDir(workspaceDir) {
 export function walletDirForName(walletsRoot, walletName) {
   return path.join(walletsRoot, slugifyPathComponent(walletName));
 }
-
-export function walletMetadataPathForDir(walletDir) {
-  return path.join(walletDir, "wallet.metadata.json");
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "1.2.1",
+  "version": "2.1.0",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",
@@ -30,6 +30,7 @@
     "LICENSE",
     "private-state-bridge-cli.mjs",
     "cli-assistant.html",
+    "investigator",
     "assets",
     "lib"
   ],