@tokamak-private-dapps/private-state-cli 2.3.0 → 2.3.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 2.3.1 - 2026-05-20
+
+- Added `wallet recover-workspace --wallet-secret-path` support for rederiving and storing an active
+  wallet spending key from the original L1 account and wallet secret source.
+- Validated recovered spending keys against the current on-chain L2 address and channel token-vault
+  storage key before received-note recovery starts.
+- Documented the active-wallet-only spending-key recovery policy in the CLI README and private-state
+  DApp README.
+
 ## 2.3.0 - 2026-05-20
 
 - Added `help observer` to print the deployed public observer URL for the private-state monitoring

package/README.md

@@ -388,6 +388,13 @@ flow. The spending key needs the same L1 private key, the same channel context,
 spending-key file is lost and the wallet secret source is also lost, the CLI cannot reconstruct the spending key and the
 notes for that wallet cannot be spent, transferred, or redeemed through the normal note flow.
 
+`wallet recover-workspace` restores the viewing key by default. Add `--wallet-secret-path <PATH>` only when the
+account is currently active in the channel and you need to rederive the spending key. In that mode, the CLI checks the
+derived L2 address and channel token-vault storage key against the current on-chain registration before received-note
+recovery starts, then stores the protected spending-key file. Exited or non-active accounts must be recovered without
+`--wallet-secret-path`; that restores viewing/evidence history but not spending authority. The wallet secret source is
+read for derivation and is not stored.
+
 ### Wallet Backup, Viewing, And Spending Authority
 
 The wallet workspace is split so that a backup is not a full-control wallet export. Backup metadata stores the
@@ -405,8 +412,9 @@ 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
-secret source used at `channel join`. Importing `wallet-viewing.key` or `wallet-spending.key` restores the corresponding
-capability without rerunning derivation, but a backup ZIP alone never restores either capability.
+secret source used at `channel join`. `wallet recover-workspace --wallet-secret-path <PATH>` performs this spending-key
+rederivation only for active channel registrations. Importing `wallet-viewing.key` or `wallet-spending.key` restores the
+corresponding capability without rerunning derivation, but a backup ZIP alone never restores either capability.
 
 `wallet get-notes --export-evidence <PATH> --acknowledge-full-note-plaintext-export` writes a local raw evidence ZIP.
 The bundle is not a key export. It includes plaintext note facts for locally known notes so that

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

@@ -484,11 +484,15 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     display: "wallet recover-workspace",
     description: "Rebuild a recoverable local wallet from on-chain channel state.",
     installMode: "read-only",
-    fields: ["channelName", "network", "account", "fromGenesis"],
-    usage: "--channel-name, --network, --account, optional --from-genesis",
+    fields: ["channelName", "network", "account", "walletSecretPath", "fromGenesis"],
+    optionalFields: ["walletSecretPath"],
+    usage: "--channel-name, --network, --account, optional --wallet-secret-path, optional --from-genesis",
     help: [
-      "Rebuilds backup metadata from channel state without recreating the spending key",
+      "Rebuilds backup metadata from channel state without recreating the spending key by default",
       "Derives and stores the viewing key when the local account signer can reproduce the registered viewing public key",
+      "Use --wallet-secret-path only for an active channel registration when you need to rederive and store the spending key",
+      "--wallet-secret-path requires the derived spending key to match the current on-chain L2 address and storage key before note recovery starts",
+      "Exited or non-active accounts can be recovered for viewing/evidence history only; omit --wallet-secret-path for those wallets",
       "Before wallet recovery, refreshes stale channel workspace state only when the saved recovery index delta fits the pre-command budget",
       "Fails and asks for channel recover-workspace first when the channel workspace is missing, unusable, or too stale for automatic recovery",
       "Use --from-genesis to restart received-note scanning from channel genesis; it does not rebuild the channel workspace from genesis",

package/lib/runtime.mjs

@@ -2331,6 +2331,13 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     account: signer.address,
   });
   const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
+  const recoveredSpendingIdentity = await deriveRecoverWalletSpendingIdentity({
+    args,
+    signer,
+    channelName,
+    context,
+    registration,
+  });
   const recoveryEventScan = await scanWalletRecoveryEvents({
     context,
     provider,
@@ -2358,7 +2365,27 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     Number(registeredNoteReceivePubKey.yParity) === Number(noteReceiveKeyMaterial.noteReceivePubKey.yParity),
     "The existing note-receive public key parity does not match the derived note-receive public key.",
   );
-  const l2Identity = {
+  if (recoveredSpendingIdentity) {
+    const expectedRecoveredStorageKey = deriveLiquidBalanceStorageKey(
+      recoveredSpendingIdentity.l2Address,
+      context.workspace.liquidBalancesSlot,
+    );
+    expect(
+      lifecycleEpoch.lifecycleStatus === "active",
+      "--wallet-secret-path can only recover the spending key for an active wallet epoch.",
+    );
+    expect(
+      ethers.toBigInt(getAddress(lifecycleEpoch.l2Address))
+        === ethers.toBigInt(getAddress(recoveredSpendingIdentity.l2Address)),
+      "The recovered spending key does not match the recovered wallet lifecycle L2 address.",
+    );
+    expect(
+      ethers.toBigInt(normalizeBytes32Hex(lifecycleEpoch.channelTokenVaultKey))
+        === ethers.toBigInt(normalizeBytes32Hex(expectedRecoveredStorageKey)),
+      "The recovered spending key does not match the recovered wallet lifecycle storage key.",
+    );
+  }
+  const l2Identity = recoveredSpendingIdentity ?? {
     l2PrivateKey: null,
     l2PublicKey: null,
     l2Address: getAddress(lifecycleEpoch.l2Address),
@@ -2377,6 +2404,14 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
   if (existingWallet) {
     existingWallet.wallet.noteReceivePrivateKey = noteReceiveKeyMaterial.privateKey;
     applyWalletLifecycleEpoch(existingWallet.wallet, lifecycleEpoch);
+    if (recoveredSpendingIdentity) {
+      existingWallet.wallet.l2PrivateKey = ethers.hexlify(recoveredSpendingIdentity.l2PrivateKey);
+      existingWallet.wallet.l2PublicKey = ethers.hexlify(recoveredSpendingIdentity.l2PublicKey);
+      existingWallet.wallet.l2Address = recoveredSpendingIdentity.l2Address;
+      existingWallet.wallet.l2DerivationMode = CHANNEL_BOUND_L2_DERIVATION_MODE;
+      existingWallet.wallet.l2DerivationChannelName = channelName;
+      existingWallet.wallet.l2StorageKey = storageKey;
+    }
     persistWalletKeys(existingWallet);
     persistWallet(existingWallet);
     persistWalletIndexForContext(existingWallet);
@@ -2409,6 +2444,7 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
       l1Address: signer.address,
       l2Address: l2Identity.l2Address,
       l2StorageKey: storageKey,
+      spendingKeyRecovered: Boolean(recoveredSpendingIdentity),
       leafIndex: lifecycleEpoch.leafIndex.toString(),
       epochId: lifecycleEpoch.epochId,
       lifecycleStatus: lifecycleEpoch.lifecycleStatus,
@@ -2468,6 +2504,7 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     l1Address: signer.address,
     l2Address: l2Identity.l2Address,
     l2StorageKey: storageKey,
+    spendingKeyRecovered: Boolean(recoveredSpendingIdentity),
     leafIndex: lifecycleEpoch.leafIndex.toString(),
     epochId: lifecycleEpoch.epochId,
     lifecycleStatus: lifecycleEpoch.lifecycleStatus,
@@ -2481,6 +2518,41 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
   });
 }
 
+async function deriveRecoverWalletSpendingIdentity({
+  args,
+  signer,
+  channelName,
+  context,
+  registration,
+}) {
+  if (args.walletSecretPath === undefined) {
+    return null;
+  }
+  expect(
+    registration.exists,
+    [
+      "--wallet-secret-path can only recover a spending key for an active channel registration.",
+      "This account is not currently registered in the channel.",
+      "Run wallet recover-workspace without --wallet-secret-path to recover viewing/evidence history for exited wallets.",
+    ].join(" "),
+  );
+  const walletSecret = readWalletSecretSourceFile(args);
+  const l2Identity = await deriveParticipantIdentityFromSigner({
+    channelName,
+    walletSecret,
+    signer,
+  });
+  const expectedStorageKey = deriveLiquidBalanceStorageKey(
+    l2Identity.l2Address,
+    context.workspace.liquidBalancesSlot,
+  );
+  expect(
+    walletRegistrationMatchesIdentity({ registration, l2Identity, expectedStorageKey }),
+    "The recovered spending key does not match the current registered L2 address or channel token vault key.",
+  );
+  return l2Identity;
+}
+
 async function handleInstallZkEvm({ args }) {
   const installMode = args.readOnly === true
     ? PRIVATE_STATE_INSTALL_MODES.READ_ONLY
@@ -4308,10 +4380,7 @@ async function loadWalletChannelRegistrationState({
   const l2Identity = restoreParticipantIdentityFromWallet(walletContext.wallet);
   const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
   const expectedStorageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
-  const matchesWallet = registration.exists
-    && ethers.toBigInt(getAddress(registration.l2Address)) === ethers.toBigInt(getAddress(l2Identity.l2Address))
-    && ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
-      === ethers.toBigInt(normalizeBytes32Hex(expectedStorageKey));
+  const matchesWallet = walletRegistrationMatchesIdentity({ registration, l2Identity, expectedStorageKey });
 
   if (requireRegistration) {
     expect(
@@ -4336,6 +4405,13 @@ async function loadWalletChannelRegistrationState({
   };
 }
 
+function walletRegistrationMatchesIdentity({ registration, l2Identity, expectedStorageKey }) {
+  return registration.exists
+    && ethers.toBigInt(getAddress(registration.l2Address)) === ethers.toBigInt(getAddress(l2Identity.l2Address))
+    && ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
+      === ethers.toBigInt(normalizeBytes32Hex(expectedStorageKey));
+}
+
 function selectWalletLifecycleEpoch({ epochs, registration = null }) {
   if (registration?.exists) {
     const active = [...epochs].reverse().find((epoch) => (
@@ -9735,6 +9811,10 @@ function prepareJoinWalletSecretForName({
       `For exited history, keep using wallet recover-workspace --channel-name ${channelName} --network ${networkName} --account ${args.account ?? "<ACCOUNT>"}.`,
     ].join(" "),
   );
+  return readWalletSecretSourceFile(args);
+}
+
+function readWalletSecretSourceFile(args) {
   const sourcePath = path.resolve(String(requireArg(args.walletSecretPath, "--wallet-secret-path")));
   return readImportSecretSourceFile(sourcePath, "--wallet-secret-path");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",