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

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## 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

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,
@@ -580,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: {
@@ -508,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",
@@ -528,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",
     ],
   },
@@ -598,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,
@@ -615,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,
@@ -632,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",
@@ -642,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",
     ],
   },
@@ -654,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.",
@@ -672,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.",
@@ -693,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.",
@@ -712,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

@@ -2338,10 +2338,12 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     context,
     registration,
   });
+  const walletRecoveryTargetBlock = walletNoteReceiveTargetBlock(context);
   const recoveryEventScan = await scanWalletRecoveryEvents({
     context,
     provider,
     l1Address: signer.address,
+    toBlock: walletRecoveryTargetBlock,
     progressAction: "wallet recover-workspace",
   });
   const lifecycleEpoch = selectWalletLifecycleEpoch({
@@ -2400,66 +2402,8 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
       walletDir,
     })
     : null;
-
-  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);
-    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,
-      spendingKeyRecovered: Boolean(recoveredSpendingIdentity),
-      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,
@@ -2471,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,
@@ -2493,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,
@@ -4202,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;
@@ -4500,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);
@@ -4519,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" })
@@ -4564,7 +4525,7 @@ async function scanWalletRecoveryEvents({ context, provider, l1Address, progress
     storageObservationLogs,
     scanRange: {
       fromBlock,
-      toBlock,
+      toBlock: normalizedToBlock,
     },
   };
 }
@@ -5268,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,
     };
@@ -5320,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,
@@ -6581,6 +6544,7 @@ async function recoverWalletReceivedNotes({
   provider,
   signer,
   noteReceiveKeyMaterial = null,
+  toBlock = null,
   progressAction = null,
   fromGenesis = false,
 }) {
@@ -6594,6 +6558,7 @@ async function recoverWalletReceivedNotes({
     context,
     provider,
     noteReceivePrivateKey: resolvedNoteReceiveKeyMaterial.privateKey,
+    toBlock,
     progressAction,
     fromGenesis,
   });
@@ -6608,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,
@@ -6636,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: [],
@@ -6746,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: [],
@@ -6873,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,
   };
 }
 
@@ -6918,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}.`,
@@ -6935,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,
@@ -6947,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,
   });
@@ -6961,6 +6981,7 @@ async function ensureWalletNoteReceiveStateCurrent({
       context,
       provider,
       signer: resolvedSigner,
+      toBlock: cursorDelta.toBlock,
       progressAction,
       fromGenesis: false,
     }));
@@ -6972,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) {
@@ -7511,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 };
@@ -7585,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,
@@ -10268,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);
@@ -10284,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.");
   }
@@ -10327,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) {
@@ -10405,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.`);
   }
@@ -10426,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) {
@@ -10441,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.");
   }
@@ -10464,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) {
@@ -10480,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) {
@@ -11185,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.1",
+  "version": "2.3.2",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",