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

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 2.3.2 - 2026-05-21
+
+- Clarified `wallet transfer-notes` JSON-array argument formats in CLI help and README guidance.
+- Changed wallet note freshness to use the fresh channel workspace recovery frontier instead of the
+  provider's latest L1 block, so unrelated L1 blocks do not make wallet workspaces stale.
+- Simplified wallet recovery and command-argument validation logic while preserving the channel-frontier
+  recovery model.
+
+## 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

@@ -209,9 +209,11 @@ saved index instead of silently replaying from genesis.
 Wallet commands that need channel state, including `wallet recover-workspace`, `wallet get-meta`,
 `wallet get-channel-fund`, and `wallet get-notes`, refresh stale local channel workspaces through saved recovery
 indexes before reading state. `wallet get-notes` and `wallet recover-workspace` also refresh received-note logs
-through the saved wallet note recovery index. Automatic refresh never replays from channel genesis and only runs when
-the recovery delta fits within the 7,200-block pre-command budget. If a saved index is missing, unusable, or too far
-behind, the command stops and asks the user to run the appropriate recovery command first.
+through the saved wallet note recovery index. Wallet note freshness is measured against the fresh channel workspace
+frontier, not the provider's latest L1 block, so unrelated new L1 blocks do not make a wallet stale by themselves.
+Automatic refresh never replays from channel genesis and only runs when the recovery delta fits within the 7,200-block
+pre-command budget. If a saved index is missing, unusable, or too far behind, the command stops and asks the user to
+run the appropriate recovery command first.
 
 Wallet note-delivery recovery checkpoints after each RPC log chunk by updating
 `noteReceiveLastScannedBlock`. If an ordinary `wallet recover-workspace` run is interrupted during note recovery, the
@@ -323,6 +325,23 @@ note ownership and builds the ZK proof, but the selected local account submits `
 Use this option when a separate imported local account should submit the L1 transaction and pay gas for a proof-backed
 note command.
 
+`wallet transfer-notes` takes JSON arrays for note selection and outputs. `--note-ids` is a JSON array of input note
+commitment IDs from `wallet get-notes`; `--recipients` is a JSON array of recipient L2 addresses; `--amounts` is a JSON
+array of token amounts. Quote decimal amounts to avoid shell or JSON ambiguity. The recipient count must match the
+amount count, only `1->1`, `1->2`, and `2->1` transfer shapes are supported, and the output amount sum must equal the
+selected input note value sum.
+
+```bash
+private-state-cli wallet transfer-notes \
+  --wallet <WALLET> \
+  --network mainnet \
+  --note-ids '["0xNOTE1","0xNOTE2"]' \
+  --recipients '["0xL2RECIPIENT1","0xL2RECIPIENT2"]' \
+  --amounts '["1.5","2"]' \
+  --acknowledge-action-impact \
+  --tx-submitter <ACCOUNT>
+```
+
 Channel policy warning:
 
 - `channel create` commits to an immutable channel policy: verifier bindings, DApp execution metadata, function layout,
@@ -388,6 +407,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 +431,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
@@ -572,7 +599,7 @@ Suggested interaction flow:
 6. If needed, guide the user through `channel create`, `account deposit-bridge`, `channel join`, `wallet deposit-channel`, and
    `wallet mint-notes`.
 7. For a confidential note transfer, select available note IDs from `wallet get-notes`, find the recipient L2 address from
-   `wallet get-meta`, then build `wallet transfer-notes`.
+   `wallet get-meta`, then build `wallet transfer-notes` with JSON arrays for `--note-ids`, `--recipients`, and `--amounts`.
 8. After transfer, guide the recipient to run `wallet get-notes`; it refreshes received notes from the saved recovery index when the delta fits the 7,200-block pre-command budget. If the index is missing or too far behind, explain `wallet recover-workspace`.
 
 Example onboarding explanation for `channel join`:

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

@@ -140,22 +140,25 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
   amounts: {
     label: "Amounts",
     type: "textarea",
-    placeholder: "[1,2,3]",
-    valueLabel: "<A,B,...>",
+    placeholder: "[\"1\",\"2\",\"3\"]",
+    valueLabel: "<JSON_ARRAY>",
+    hint: "JSON array of token amounts. Use quoted strings for decimal amounts, for example [\"1.5\",\"2\"].",
     option: "--amounts",
   },
   noteIds: {
     label: "Note IDs",
     type: "textarea",
     placeholder: "[\"0x...\"]",
-    valueLabel: "<ID,ID,...>",
+    valueLabel: "<JSON_ARRAY>",
+    hint: "JSON array of note commitment IDs from wallet get-notes.",
     option: "--note-ids",
   },
   recipients: {
     label: "Recipients JSON",
     type: "textarea",
     placeholder: "[\"0xRecipientL2Address\"]",
-    valueLabel: "<ADDR,ADDR,...>",
+    valueLabel: "<JSON_ARRAY>",
+    hint: "JSON array of recipient L2 addresses. Its length must match --amounts.",
     option: "--recipients",
   },
   docker: {
@@ -484,11 +487,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",
@@ -504,7 +511,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     fields: ["channelName", "network", "account", "walletSecretPath", "acknowledgeActionImpact"],
     usage: "--channel-name, --network, --account, --wallet-secret-path, --acknowledge-action-impact",
     help: [
-      "Refreshes the local channel workspace through the saved recovery index before joining when the scan fits the 10 second pre-command budget",
+      "Refreshes the local channel workspace through the saved recovery index before joining when the scan fits the 7,200-block 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 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",
@@ -524,7 +531,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+      "Refreshes the local channel workspace through the saved recovery index before reading registration metadata when the scan fits the 7,200-block pre-command budget",
       "Reports the selected local wallet epoch and lifecycle status when the workspace uses the epoch-aware wallet format",
     ],
   },
@@ -594,7 +601,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+      "Refreshes the local channel workspace through the saved recovery index before proving the deposit when the scan fits the 7,200-block 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,
@@ -611,7 +618,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+      "Refreshes the local channel workspace through the saved recovery index before proving the withdrawal when the scan fits the 7,200-block 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,
@@ -628,7 +635,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     installMode: "read-only",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
-    help: ["Refreshes the local channel workspace through the saved recovery index before reading the L2 accounting balance when the scan fits the 10 second pre-command budget"],
+    help: ["Refreshes the local channel workspace through the saved recovery index before reading the L2 accounting balance when the scan fits the 7,200-block pre-command budget"],
   },
   {
     id: "channel-exit",
@@ -638,7 +645,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+      "Refreshes the local channel workspace through the saved recovery index before checking the channel balance when the scan fits the 7,200-block pre-command budget",
       "Marks the current local wallet epoch as exited and keeps its note metadata available for historical evidence export",
     ],
   },
@@ -650,7 +657,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+      "Refreshes the local channel workspace through the saved recovery index before proving the mint when the scan fits the 7,200-block pre-command budget",
       "Requires both viewing and spending key capability so the accepted mint can be recovered through the normal note event path",
       "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.",
@@ -668,9 +675,14 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Spend input notes into the registered 1->1, 1->2, or 2->1 private transfer shapes.",
     installMode: "full",
     fields: ["wallet", "network", "noteIds", "recipients", "amounts", "acknowledgeActionImpact", "txSubmitter"],
-    usage: "--wallet, --network, --note-ids, --recipients, --amounts, --acknowledge-action-impact, and optional --tx-submitter",
+    usage: "--wallet, --network, --note-ids <JSON_ARRAY>, --recipients <JSON_ARRAY>, --amounts <JSON_ARRAY>, --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",
+      "--note-ids must be a JSON array of input note commitment IDs from wallet get-notes, for example '[\"0xNOTE1\",\"0xNOTE2\"]'",
+      "--recipients must be a JSON array of recipient L2 addresses, for example '[\"0xL2RECIPIENT1\",\"0xL2RECIPIENT2\"]'",
+      "--amounts must be a JSON array of token amounts, preferably quoted for decimals, for example '[\"1.5\",\"2\"]'",
+      "--recipients length must equal --amounts length; supported transfer shapes are 1->1, 1->2, and 2->1",
+      "The sum of output amounts must equal the sum of the selected input note values",
+      "Refreshes the local channel workspace and received-note logs through saved recovery indexes before proving the transfer when scans fit the 7,200-block 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.",
@@ -689,7 +701,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+      "Refreshes the local channel workspace and received-note logs through saved recovery indexes before proving the redeem when scans fit the 7,200-block 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.",
@@ -708,8 +720,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+      "Refreshes the local channel workspace through the saved recovery index before reading notes when the scan fits the 7,200-block pre-command budget",
+      "Refreshes received-note logs through the saved wallet note recovery index when the scan fits the 7,200-block pre-command budget",
       "Fails instead of replaying from genesis; run wallet recover-workspace first when explicit wallet recovery 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/runtime.mjs

@@ -2331,10 +2331,19 @@ 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 walletRecoveryTargetBlock = walletNoteReceiveTargetBlock(context);
   const recoveryEventScan = await scanWalletRecoveryEvents({
     context,
     provider,
     l1Address: signer.address,
+    toBlock: walletRecoveryTargetBlock,
     progressAction: "wallet recover-workspace",
   });
   const lifecycleEpoch = selectWalletLifecycleEpoch({
@@ -2358,7 +2367,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),
@@ -2373,57 +2402,8 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
       walletDir,
     })
     : null;
-
-  if (existingWallet) {
-    existingWallet.wallet.noteReceivePrivateKey = noteReceiveKeyMaterial.privateKey;
-    applyWalletLifecycleEpoch(existingWallet.wallet, lifecycleEpoch);
-    persistWalletKeys(existingWallet);
-    persistWallet(existingWallet);
-    persistWalletIndexForContext(existingWallet);
-    const noteScanStartBlock = args.fromGenesis === true
-      ? Number(context.workspace.genesisBlockNumber)
-      : requireUsableWalletNoteReceiveRecoveryIndex({
-        walletContext: existingWallet,
-        context,
-        latestBlock: recoveryEventScan.scanRange.toBlock,
-      });
-    const recoveredDeliveryState = await recoverDeliveredNotesFromCollectedLogs({
-      walletContext: existingWallet,
-      context,
-      noteReceivePrivateKey: noteReceiveKeyMaterial.privateKey,
-      logs: recoveryEventScan.deliveryLogs,
-      storageObservationLogs: recoveryEventScan.storageObservationLogs,
-      scanStartBlock: noteScanStartBlock,
-      latestBlock: recoveryEventScan.scanRange.toBlock,
-    });
-    printJson({
-      action: "wallet recover-workspace",
-      status: "already-recovered",
-      wallet: walletName,
-      walletDir: existingWallet.walletDir,
-      recoveredChannelWorkspace: channelContextResult.recoveredWorkspace,
-      channelAutoRecoveryBlockDelta: channelContextResult.autoRecoveryBlockDelta,
-      workspace: context.workspaceName,
-      channelName: context.workspace.channelName,
-      channelId: context.workspace.channelId,
-      l1Address: signer.address,
-      l2Address: l2Identity.l2Address,
-      l2StorageKey: storageKey,
-      leafIndex: lifecycleEpoch.leafIndex.toString(),
-      epochId: lifecycleEpoch.epochId,
-      lifecycleStatus: lifecycleEpoch.lifecycleStatus,
-      exitedAtTxHash: lifecycleEpoch.exitedAtTxHash,
-      noteReceivePubKey: noteReceiveKeyMaterial.noteReceivePubKey,
-      l2Nonce: existingWallet.wallet.l2Nonce,
-      recoveredFromLogs: recoveredDeliveryState.importedNotes,
-      scannedDeliveryLogs: recoveredDeliveryState.scannedLogs,
-      linkedEvidence: recoveredDeliveryState.linkedEvidence,
-      noteReceiveScanRange: recoveredDeliveryState.scanRange,
-    });
-    return;
-  }
-
-  const walletContext = ensureWallet({
+  const status = existingWallet ? "already-recovered" : "recovered";
+  const walletContext = existingWallet ?? ensureWallet({
     channelContext: context,
     signerAddress: signer.address,
     signerPrivateKey: signer.privateKey,
@@ -2435,16 +2415,29 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     lifecycleEpoch,
     rpcUrl,
   });
-  walletContext.wallet.l2Nonce = 0;
-  persistWallet(walletContext);
+  if (existingWallet) {
+    walletContext.wallet.noteReceivePrivateKey = noteReceiveKeyMaterial.privateKey;
+    applyWalletLifecycleEpoch(walletContext.wallet, lifecycleEpoch);
+    if (recoveredSpendingIdentity) {
+      walletContext.wallet.l2PrivateKey = ethers.hexlify(recoveredSpendingIdentity.l2PrivateKey);
+      walletContext.wallet.l2PublicKey = ethers.hexlify(recoveredSpendingIdentity.l2PublicKey);
+      walletContext.wallet.l2Address = recoveredSpendingIdentity.l2Address;
+      walletContext.wallet.l2DerivationMode = CHANNEL_BOUND_L2_DERIVATION_MODE;
+      walletContext.wallet.l2DerivationChannelName = channelName;
+      walletContext.wallet.l2StorageKey = storageKey;
+    }
+    persistWalletKeys(walletContext);
+    persistWallet(walletContext);
+    persistWalletIndexForContext(walletContext);
+  }
 
   const noteScanStartBlock = args.fromGenesis === true
     ? Number(context.workspace.genesisBlockNumber)
-    : requireUsableWalletNoteReceiveRecoveryIndex({
+    : walletNoteReceiveCursorDelta({
       walletContext,
       context,
-      latestBlock: recoveryEventScan.scanRange.toBlock,
-    });
+      targetNextBlock: recoveryEventScan.scanRange.toBlock + 1,
+    }).localNextBlock;
   const recoveredDeliveryState = await recoverDeliveredNotesFromCollectedLogs({
     walletContext,
     context,
@@ -2457,7 +2450,7 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
 
   printJson({
     action: "wallet recover-workspace",
-    status: "recovered",
+    status,
     wallet: walletName,
     walletDir: walletContext.walletDir,
     recoveredChannelWorkspace: channelContextResult.recoveredWorkspace,
@@ -2468,6 +2461,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 +2475,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
@@ -4130,18 +4159,18 @@ function applyGuideNextAction(guide) {
   }
   if (guide.state.wallet?.exists && channelBalance !== null && channelBalance > 0n && unusedNotes === 0) {
     setGuideNextAction(guide, {
-      command: `wallet mint-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --amounts <A,B> --acknowledge-action-impact [--tx-submitter <ACCOUNT>]`,
+      command: `wallet mint-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --amounts <JSON_ARRAY> --acknowledge-action-impact [--tx-submitter <ACCOUNT>]`,
       why: "The wallet has channel L2 balance and no unused private notes yet. Use --tx-submitter for stronger transaction-submission privacy.",
     });
     return;
   }
   if (guide.state.wallet?.exists && unusedNotes !== null && unusedNotes > 0) {
     setGuideNextAction(guide, {
-      command: `wallet transfer-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID,ID> --recipients <ADDR,ADDR> --amounts <A,B> --acknowledge-action-impact [--tx-submitter <ACCOUNT>]`,
+      command: `wallet transfer-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <JSON_ARRAY> --recipients <JSON_ARRAY> --amounts <JSON_ARRAY> --acknowledge-action-impact [--tx-submitter <ACCOUNT>]`,
       why: "The wallet has unused private notes. It can transfer or redeem those notes. Use --tx-submitter for stronger transaction-submission privacy.",
       candidates: [
         `wallet get-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network}`,
-        `wallet redeem-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID> --acknowledge-action-impact [--tx-submitter <ACCOUNT>]`,
+        `wallet redeem-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <JSON_ARRAY> --acknowledge-action-impact [--tx-submitter <ACCOUNT>]`,
       ],
     });
     return;
@@ -4308,10 +4337,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 +4362,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) => (
@@ -4424,9 +4457,13 @@ async function walletEpochFromJoinReceipt({ receipt, context, provider, l1Addres
   return epoch;
 }
 
-async function scanWalletRecoveryEvents({ context, provider, l1Address, progressAction = null }) {
+async function scanWalletRecoveryEvents({ context, provider, l1Address, toBlock, progressAction = null }) {
   const fromBlock = Number(context.workspace.genesisBlockNumber ?? 0);
-  const toBlock = await fetchFreshBlockNumber(provider);
+  const normalizedToBlock = Number(toBlock);
+  expect(
+    Number.isInteger(normalizedToBlock) && normalizedToBlock >= fromBlock - 1,
+    "Wallet recovery event scan target block is invalid.",
+  );
   const registeredTopic = context.channelManager.interface.getEvent("ChannelTokenVaultIdentityRegistered").topicHash;
   const exitedTopic = context.channelManager.interface.getEvent("ChannelTokenVaultIdentityExited").topicHash;
   const normalizedRegisteredTopic = normalizeBytes32Hex(registeredTopic);
@@ -4443,7 +4480,7 @@ async function scanWalletRecoveryEvents({ context, provider, l1Address, progress
     address: context.workspace.channelManager,
     topics: [[registeredTopic, exitedTopic, NOTE_VALUE_ENCRYPTED_TOPIC, CONTROLLER_STORAGE_KEY_OBSERVED_TOPIC]],
     fromBlock,
-    toBlock,
+    toBlock: normalizedToBlock,
     collectLogs: false,
     onProgress: progressAction
       ? createRpcLogScanProgress({ action: progressAction, label: "wallet-recovery events" })
@@ -4488,7 +4525,7 @@ async function scanWalletRecoveryEvents({ context, provider, l1Address, progress
     storageObservationLogs,
     scanRange: {
       fromBlock,
-      toBlock,
+      toBlock: normalizedToBlock,
     },
   };
 }
@@ -5192,7 +5229,8 @@ async function handleWalletGetNotes({ args, provider }) {
     })
     : {
       nextBlock: wallet.wallet.noteReceiveLastScannedBlock,
-      latestBlock: await provider.getBlockNumber(),
+      targetBlock: walletNoteReceiveTargetBlock(context),
+      targetNextBlock: channelWorkspaceRecoveryTargetNextBlock(context),
       recoveredWalletWorkspace: false,
       recoveredDeliveryState: null,
     };
@@ -5244,7 +5282,8 @@ async function handleWalletGetNotes({ args, provider }) {
     spentTotalTokens: spentTotal === null ? null : ethers.formatUnits(spentTotal, canonicalAssetDecimals),
     bridgeStatusMismatches: [...unusedNotes, ...spentNotes].filter((note) => !note.walletStatusMatchesBridge).length,
     noteReceiveLastScannedBlock: noteReceiveFreshness.nextBlock,
-    latestBlock: noteReceiveFreshness.latestBlock,
+    noteReceiveTargetBlock: noteReceiveFreshness.targetBlock,
+    noteReceiveTargetNextBlock: noteReceiveFreshness.targetNextBlock,
     viewingKeyAvailable: Boolean(wallet.wallet.noteReceivePrivateKey),
     recoveredWalletWorkspace: noteReceiveFreshness.recoveredWalletWorkspace,
     recoveredFromLogs: noteReceiveFreshness.recoveredDeliveryState?.importedNotes ?? 0,
@@ -6505,6 +6544,7 @@ async function recoverWalletReceivedNotes({
   provider,
   signer,
   noteReceiveKeyMaterial = null,
+  toBlock = null,
   progressAction = null,
   fromGenesis = false,
 }) {
@@ -6518,6 +6558,7 @@ async function recoverWalletReceivedNotes({
     context,
     provider,
     noteReceivePrivateKey: resolvedNoteReceiveKeyMaterial.privateKey,
+    toBlock,
     progressAction,
     fromGenesis,
   });
@@ -6532,18 +6573,23 @@ async function recoverDeliveredNotesFromEventLogs({
   context,
   provider,
   noteReceivePrivateKey,
+  toBlock = null,
   storageObservationLogs = null,
   progressAction = null,
   fromGenesis = false,
 }) {
-  const latestBlock = await fetchFreshBlockNumber(provider);
+  const latestBlock = toBlock === null ? await fetchFreshBlockNumber(provider) : Number(toBlock);
+  expect(
+    Number.isInteger(latestBlock) && latestBlock >= Number(context.workspace.genesisBlockNumber) - 1,
+    "Wallet note recovery target block is invalid.",
+  );
   const scanStartBlock = fromGenesis
     ? Number(context.workspace.genesisBlockNumber)
-    : requireUsableWalletNoteReceiveRecoveryIndex({
+    : walletNoteReceiveCursorDelta({
       walletContext,
       context,
-      latestBlock,
-    });
+      targetNextBlock: latestBlock + 1,
+    }).localNextBlock;
   const scanRange = {
     fromBlock: scanStartBlock,
     toBlock: latestBlock,
@@ -6560,7 +6606,10 @@ async function recoverDeliveredNotesFromEventLogs({
       context,
       storageObservationLogs: storageObservationLogs ?? [],
     });
-    walletContext.wallet.noteReceiveLastScannedBlock = latestBlock + 1;
+    walletContext.wallet.noteReceiveLastScannedBlock = Math.max(
+      Number(walletContext.wallet.noteReceiveLastScannedBlock),
+      latestBlock + 1,
+    );
     persistWallet(walletContext);
     return {
       importedNotes: [],
@@ -6670,7 +6719,10 @@ async function recoverDeliveredNotesFromCollectedLogs({
       context,
       storageObservationLogs,
     });
-    walletContext.wallet.noteReceiveLastScannedBlock = latestBlock + 1;
+    walletContext.wallet.noteReceiveLastScannedBlock = Math.max(
+      Number(walletContext.wallet.noteReceiveLastScannedBlock),
+      latestBlock + 1,
+    );
     persistWallet(walletContext);
     return {
       importedNotes: [],
@@ -6797,40 +6849,88 @@ async function recoverDeliveredNoteCandidatesFromLogs({
   return importedCandidates;
 }
 
-function requireUsableWalletNoteReceiveRecoveryIndex({ walletContext, context, latestBlock }) {
-  const nextBlock = Number(walletContext.wallet.noteReceiveLastScannedBlock);
+function channelWorkspaceRecoveryTargetNextBlock(context) {
+  const targetNextBlock = Number(context.workspace.recoveryLastScannedBlock);
   const genesisBlockNumber = Number(context.workspace.genesisBlockNumber);
+  expect(
+    Number.isInteger(targetNextBlock) && targetNextBlock >= genesisBlockNumber,
+    "Channel workspace recovery frontier is missing or unusable.",
+  );
+  return targetNextBlock;
+}
+
+function walletNoteReceiveTargetBlock(context) {
+  return channelWorkspaceRecoveryTargetNextBlock(context) - 1;
+}
+
+function computeRecoveryCursorDelta({
+  localNextBlock,
+  targetNextBlock,
+  genesisBlockNumber,
+  label,
+}) {
+  const normalizedLocalNextBlock = Number(localNextBlock);
+  const normalizedTargetNextBlock = Number(targetNextBlock);
+  const normalizedGenesisBlockNumber = Number(genesisBlockNumber);
   if (
-    !Number.isInteger(nextBlock)
-    || nextBlock < genesisBlockNumber
-    || nextBlock > Number(latestBlock) + 1
+    !Number.isInteger(normalizedLocalNextBlock)
+    || !Number.isInteger(normalizedTargetNextBlock)
+    || !Number.isInteger(normalizedGenesisBlockNumber)
+    || normalizedLocalNextBlock < normalizedGenesisBlockNumber
+    || normalizedTargetNextBlock < normalizedGenesisBlockNumber
   ) {
+    throw new Error([
+      `${label} recovery cursor is missing or unusable.`,
+      `Expected localNextBlock and targetNextBlock to be integers greater than or equal to ${normalizedGenesisBlockNumber}.`,
+    ].join(" "));
+  }
+  const fromBlock = normalizedLocalNextBlock;
+  const toBlock = normalizedTargetNextBlock - 1;
+  const blockDelta = Math.max(0, normalizedTargetNextBlock - normalizedLocalNextBlock);
+  return {
+    fresh: normalizedLocalNextBlock >= normalizedTargetNextBlock,
+    localNextBlock: normalizedLocalNextBlock,
+    targetNextBlock: normalizedTargetNextBlock,
+    fromBlock,
+    toBlock,
+    blockDelta,
+  };
+}
+
+function walletNoteReceiveCursorDelta({ walletContext, context, targetNextBlock = channelWorkspaceRecoveryTargetNextBlock(context) }) {
+  const nextBlock = Number(walletContext.wallet.noteReceiveLastScannedBlock);
+  const genesisBlockNumber = Number(context.workspace.genesisBlockNumber);
+  try {
+    return computeRecoveryCursorDelta({
+      localNextBlock: nextBlock,
+      targetNextBlock,
+      genesisBlockNumber,
+      label: `Wallet note workspace ${walletContext.walletName}`,
+    });
+  } catch (error) {
     throw new Error([
       `Wallet note recovery index is missing or unusable for wallet ${walletContext.walletName}.`,
-      `Expected noteReceiveLastScannedBlock to be an integer between ${genesisBlockNumber} and ${Number(latestBlock) + 1}.`,
+      `Expected noteReceiveLastScannedBlock to be an integer greater than or equal to ${genesisBlockNumber}.`,
       "Run wallet recover-workspace --from-genesis to restart received-note scanning from channel genesis.",
+      `Details: ${error.message}`,
     ].join(" "));
   }
-  return nextBlock;
 }
 
-async function assertWalletNoteReceiveStateFresh({ walletContext, context, provider }) {
-  const latestBlock = await fetchFreshBlockNumber(provider);
-  const nextBlock = requireUsableWalletNoteReceiveRecoveryIndex({
-    walletContext,
-    context,
-    latestBlock,
-  });
-  if (nextBlock !== latestBlock + 1) {
+function assertWalletNoteReceiveStateFresh({ walletContext, context }) {
+  const cursorDelta = walletNoteReceiveCursorDelta({ walletContext, context });
+  if (!cursorDelta.fresh) {
     throw new Error([
       `Wallet note workspace is stale for wallet ${walletContext.walletName}.`,
-      `noteReceiveLastScannedBlock is ${nextBlock}, but latest block requires ${latestBlock + 1}.`,
+      `noteReceiveLastScannedBlock is ${cursorDelta.localNextBlock}, but channel workspace recovery frontier requires ${cursorDelta.targetNextBlock}.`,
       "Run wallet recover-workspace before using commands that read or spend wallet notes.",
     ].join(" "));
   }
   return {
-    latestBlock,
-    nextBlock,
+    targetBlock: cursorDelta.toBlock,
+    targetNextBlock: cursorDelta.targetNextBlock,
+    nextBlock: cursorDelta.localNextBlock,
+    blockDelta: cursorDelta.blockDelta,
   };
 }
 
@@ -6842,14 +6942,9 @@ async function ensureWalletNoteReceiveStateCurrent({
   progressAction = null,
   preConsumedBlockDelta = 0,
 }) {
-  const latestBlock = await fetchFreshBlockNumber(provider);
-  let nextBlock;
+  let cursorDelta;
   try {
-    nextBlock = requireUsableWalletNoteReceiveRecoveryIndex({
-      walletContext,
-      context,
-      latestBlock,
-    });
+    cursorDelta = walletNoteReceiveCursorDelta({ walletContext, context });
   } catch (indexError) {
     throw new Error([
       `Wallet note recovery index is missing or unusable for wallet ${walletContext.walletName}.`,
@@ -6859,10 +6954,11 @@ async function ensureWalletNoteReceiveStateCurrent({
     ].join(" "));
   }
 
-  if (nextBlock === latestBlock + 1) {
+  if (cursorDelta.fresh) {
     return {
-      latestBlock,
-      nextBlock,
+      targetBlock: cursorDelta.toBlock,
+      targetNextBlock: cursorDelta.targetNextBlock,
+      nextBlock: cursorDelta.localNextBlock,
       recoveredWalletWorkspace: false,
       recoveredDeliveryState: null,
       autoRecoveryBlockDelta: 0,
@@ -6871,8 +6967,8 @@ async function ensureWalletNoteReceiveStateCurrent({
   const remainingBlockBudget = AUTO_RECOVERY_BLOCK_BUDGET - Math.max(0, Number(preConsumedBlockDelta));
   const autoRecoveryBlockDelta = assertAutoRecoveryBlockBudget({
     label: `wallet note workspace ${walletContext.walletName}`,
-    fromBlock: nextBlock,
-    toBlock: latestBlock,
+    fromBlock: cursorDelta.fromBlock,
+    toBlock: cursorDelta.toBlock,
     recoveryCommand: `wallet recover-workspace --channel-name ${context.workspace.channelName} --network ${context.workspace.network} --account <ACCOUNT>`,
     blockBudget: remainingBlockBudget,
   });
@@ -6885,6 +6981,7 @@ async function ensureWalletNoteReceiveStateCurrent({
       context,
       provider,
       signer: resolvedSigner,
+      toBlock: cursorDelta.toBlock,
       progressAction,
       fromGenesis: false,
     }));
@@ -6896,22 +6993,12 @@ async function ensureWalletNoteReceiveStateCurrent({
       `Details: ${recoveryError.message}`,
     ].join(" "));
   }
-  try {
-    const freshness = await assertWalletNoteReceiveStateFresh({ walletContext, context, provider });
-    return {
-      ...freshness,
-      recoveredWalletWorkspace: true,
-      recoveredDeliveryState,
-      autoRecoveryBlockDelta,
-    };
-  } catch (postRecoveryError) {
-    throw new Error([
-      `Wallet workspace is still stale after recovery-index sync for wallet ${walletContext.walletName}.`,
-      "Automatic wallet recovery will not replay from genesis.",
-      `Run wallet recover-workspace --channel-name ${context.workspace.channelName} --network ${context.workspace.network} --account <ACCOUNT> --from-genesis if received-note scanning must restart from channel genesis.`,
-      `Details: ${postRecoveryError.message}`,
-    ].join(" "));
-  }
+  return {
+    ...assertWalletNoteReceiveStateFresh({ walletContext, context }),
+    recoveredWalletWorkspace: true,
+    recoveredDeliveryState,
+    autoRecoveryBlockDelta,
+  };
 }
 
 function extractEncryptedNoteValueFromBridgeLog(log) {
@@ -7435,13 +7522,19 @@ async function requireChannelWorkspaceRecoveryIndexForAutoRefresh({
   if (!recoveryIndex) {
     fail(`Channel workspace recovery index is unusable for ${channelName} on ${networkName}.`);
   }
-  if (Number(recoveryIndex.nextBlock) > Number(latestBlock)) {
+  const cursorDelta = computeRecoveryCursorDelta({
+    localNextBlock: recoveryIndex.nextBlock,
+    targetNextBlock: Number(latestBlock) + 1,
+    genesisBlockNumber,
+    label: `Channel workspace ${channelName} on ${networkName}`,
+  });
+  if (cursorDelta.fresh) {
     fail(`Channel workspace recovery index has already scanned through block ${recoveryIndex.nextBlock - 1}, but the local snapshot is not current.`);
   }
   const autoRecoveryBlockDelta = assertAutoRecoveryBlockBudget({
     label: `channel workspace ${channelName} on ${networkName}`,
-    fromBlock: recoveryIndex.nextBlock,
-    toBlock: latestBlock,
+    fromBlock: cursorDelta.fromBlock,
+    toBlock: cursorDelta.toBlock,
     recoveryCommand: `channel recover-workspace --channel-name ${channelName} --network ${networkName}`,
   });
   return { alreadyCurrent: false, autoRecoveryBlockDelta };
@@ -7509,19 +7602,19 @@ async function recoverLocalWorkspacesAfterAcceptedNoteTransaction({
     walletContext: wallet,
     context,
     provider,
+    toBlock: walletNoteReceiveTargetBlock(context),
     progressAction,
     fromGenesis: false,
   });
   const freshness = await assertWalletNoteReceiveStateFresh({
     walletContext: wallet,
     context,
-    provider,
   });
   return {
     channelRecoveryLastScannedBlock: context.workspace.recoveryLastScannedBlock,
     channelRecoveryScanRange: context.workspace.recoveryScanRange,
     walletNoteReceiveNextBlock: freshness.nextBlock,
-    walletLatestBlock: freshness.latestBlock,
+    walletTargetBlock: freshness.targetBlock,
     recoveredFromLogs: recoveredDeliveryState.importedNotes,
     scannedDeliveryLogs: recoveredDeliveryState.scannedLogs,
     linkedEvidence: recoveredDeliveryState.linkedEvidence,
@@ -9735,6 +9828,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");
 }
@@ -10188,15 +10285,19 @@ function assertAllowedCommandKeys(args, commandName, allowedKeys, acceptedUsage)
       `${commandName} only accepts ${acceptedUsage}. Unsupported option(s): ${unsupported.join(", ")}.`,
     );
   }
-  if (args.json !== undefined && args.json !== true) {
-    throw new Error(`${commandName} option --json does not accept a value.`);
-  }
+  assertBooleanFlag(args, "json", `${commandName} option --json`);
   expect(
     (args.positional ?? []).length === 1,
     `${commandName} does not accept positional arguments beyond the command name.`,
   );
 }
 
+function assertBooleanFlag(args, key, label) {
+  if (args[key] !== undefined && args[key] !== true) {
+    throw new Error(`${label} does not accept a value.`);
+  }
+}
+
 function assertWalletChannelMoveArgs(args, commandName) {
   assertAllowedCommandSchema(args, commandName);
   assertActionImpactArg(args, COMMAND_ARG_SCHEMAS[commandName]?.label ?? commandName);
@@ -10204,9 +10305,7 @@ function assertWalletChannelMoveArgs(args, commandName) {
 
 function assertInstallZkEvmArgs(args) {
   assertAllowedCommandSchema(args, "install");
-  if (args.readOnly !== undefined && args.readOnly !== true) {
-    throw new Error("install option --read-only does not accept a value.");
-  }
+  assertBooleanFlag(args, "readOnly", "install option --read-only");
   if (args.readOnly === true && args.docker !== undefined) {
     throw new Error("install --read-only does not accept --docker because proof runtimes are not installed.");
   }
@@ -10247,9 +10346,7 @@ function assertUpdateArgs(args) {
 
 function assertDoctorArgs(args) {
   assertAllowedCommandSchema(args, "help-doctor");
-  if (args.gpu !== undefined && args.gpu !== true) {
-    throw new Error("help doctor option --gpu does not accept a value.");
-  }
+  assertBooleanFlag(args, "gpu", "help doctor option --gpu");
 }
 
 function assertGuideArgs(args) {
@@ -10325,12 +10422,7 @@ function assertTxSubmitterArg(args) {
 }
 
 function assertActionImpactArg(args, commandName) {
-  if (
-    args.acknowledgeActionImpact !== undefined
-    && args.acknowledgeActionImpact !== true
-  ) {
-    throw new Error(`${commandName} option --acknowledge-action-impact does not accept a value.`);
-  }
+  assertBooleanFlag(args, "acknowledgeActionImpact", `${commandName} option --acknowledge-action-impact`);
   if (args.acknowledgeActionImpact !== true && !process.stdin.isTTY) {
     throw new Error(`${commandName} requires --acknowledge-action-impact after reviewing the action-impact warning.`);
   }
@@ -10346,12 +10438,11 @@ function assertWalletGetNotesArgs(args) {
       );
     }
   }
-  if (
-    args.acknowledgeFullNotePlaintextExport !== undefined
-    && args.acknowledgeFullNotePlaintextExport !== true
-  ) {
-    throw new Error("wallet get-notes option --acknowledge-full-note-plaintext-export does not accept a value.");
-  }
+  assertBooleanFlag(
+    args,
+    "acknowledgeFullNotePlaintextExport",
+    "wallet get-notes option --acknowledge-full-note-plaintext-export",
+  );
 }
 
 function assertCreateChannelArgs(args) {
@@ -10361,12 +10452,8 @@ function assertCreateChannelArgs(args) {
 function assertRecoverWorkspaceArgs(args) {
   assertAllowedCommandSchema(args, "channel-recover-workspace");
   const source = resolveWorkspaceRecoverySource(args);
-  if (args.fromGenesis !== undefined && args.fromGenesis !== true) {
-    throw new Error("channel recover-workspace option --from-genesis does not accept a value.");
-  }
-  if (args.outputRaw !== undefined && args.outputRaw !== true) {
-    throw new Error("channel recover-workspace option --output-raw does not accept a value.");
-  }
+  assertBooleanFlag(args, "fromGenesis", "channel recover-workspace option --from-genesis");
+  assertBooleanFlag(args, "outputRaw", "channel recover-workspace option --output-raw");
   if (args.outputRaw === true && source !== "rpc") {
     throw new Error("channel recover-workspace option --output-raw requires --source rpc.");
   }
@@ -10384,9 +10471,7 @@ function assertSetWorkspaceMirrorArgs(args) {
 function assertPublishWorkspaceMirrorArgs(args) {
   assertAllowedCommandSchema(args, "channel-publish-workspace-mirror");
   requireArg(args.output, "--output");
-  if (args.force !== undefined && args.force !== true) {
-    throw new Error("channel publish-workspace-mirror option --force does not accept a value.");
-  }
+  assertBooleanFlag(args, "force", "channel publish-workspace-mirror option --force");
 }
 
 function assertDepositBridgeArgs(args) {
@@ -10400,9 +10485,7 @@ function assertAccountGetBridgeFundArgs(args) {
 
 function assertRecoverWalletArgs(args) {
   assertAllowedCommandSchema(args, "wallet-recover-workspace");
-  if (args.fromGenesis !== undefined && args.fromGenesis !== true) {
-    throw new Error("wallet recover-workspace option --from-genesis does not accept a value.");
-  }
+  assertBooleanFlag(args, "fromGenesis", "wallet recover-workspace option --from-genesis");
 }
 
 function assertJoinChannelArgs(args) {
@@ -11105,7 +11188,14 @@ function getUsableWorkspaceRecoveryIndex({
     return null;
   }
   const recoveryRootVectorHash = normalizeBytes32Hex(workspace.recoveryRootVectorHash);
-  if (!Number.isInteger(nextBlock) || nextBlock < Number(genesisBlockNumber) || nextBlock > Number(latestBlock) + 1) {
+  try {
+    computeRecoveryCursorDelta({
+      localNextBlock: nextBlock,
+      targetNextBlock: Number(latestBlock) + 1,
+      genesisBlockNumber,
+      label: "Channel workspace",
+    });
+  } catch {
     return null;
   }
   if (recoveryRootVectorHash === null) {

package/package.json

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