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

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 2.3.3 - 2026-05-27
+
+- Changed `help observer` and monitoring references to use the public observer URL
+  `https://observer.tonnel.io`.
+- Clarified CLI help, guide output, and README guidance so channel join tolls are paid directly
+  from the L1 wallet, while `account deposit-bridge` is only for channel liquidity.
+- Clarified README and `help commands` guidance so AI agents answer user gas, fee, and USD cost
+  questions by running `help transaction-fees --json` instead of escalating to developers.
+
+## 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

@@ -131,11 +131,11 @@ and the global CLI npm package when npm reports that it is globally installed.
 
 ## Commands
 
-A common private-state flow is:
+A common note-use flow after channel policy review is:
 
 1. `channel create`
-2. `account deposit-bridge`
-3. `channel join`
+2. `channel join`
+3. `account deposit-bridge`
 4. `wallet deposit-channel`
 5. `wallet mint-notes`
 6. `wallet transfer-notes`
@@ -145,6 +145,8 @@ A common private-state flow is:
 10. `channel exit`
 11. `account withdraw-bridge`
 
+`channel join` pays any join toll directly from the L1 wallet; `account deposit-bridge` funds later channel liquidity and does not pay the join toll.
+
 Use `private-state-cli help commands` for the full command list and required options. `private-state-cli --help`
 continues to print the same command list for shell compatibility.
 
@@ -209,9 +211,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
@@ -310,7 +314,8 @@ private-state-cli help transaction-fees --network mainnet
 `help transaction-fees` uses the measured gas data packaged in `assets/tx-fees.json`, the selected network's live fee data,
 and live ETH/USD pricing to print an ETH/USD fee table for transaction-sending commands. The table separates typical
 cost, based on the RPC `gasPrice`, from worst-case cost, based on `maxFeePerGas` when the network reports EIP-1559 fee
-data.
+data. AI agents answering user questions about gas, transaction fees, transaction cost, or USD cost should run
+`private-state-cli help transaction-fees --network <NETWORK> --json` and answer from the returned table.
 
 Proof-backed note commands can use a separate L1 transaction submitter:
 
@@ -323,6 +328,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,
@@ -510,6 +532,10 @@ Operating rules:
   recovery can be very slow because it scans channel logs from the creation block. If a channel workspace mirror is
   available, try mirror-based recovery first, and use RPC genesis replay only when mirror recovery is unavailable or
   unsuitable.
+- When the user asks about gas use, transaction fees, transaction cost, or USD cost for private-state CLI commands, run
+  `private-state-cli help transaction-fees --network <NETWORK> --json` and answer from the returned `rows`. If the
+  network is unclear, ask which network to use. Do not tell the user to ask the developer unless the command fails after
+  following the CLI's printed corrective guidance.
 - When `channel recover-workspace` or `wallet recover-workspace` is unexpectedly slow, first inspect the RPC provider
   configured by `set rpc`. Explain that recovery speed is dominated by `eth_getLogs` block range cap and log request
   rate. Suggest re-running `set rpc` with a provider that supports a larger block range cap, such as Ankr or Chainnodes
@@ -534,7 +560,7 @@ Operating rules:
   8. prepare a wallet secret source file locally, for example with `openssl rand -hex 32 > ./wallet-secret.txt`
   9. inspect the channel with `channel get-meta` if it already exists, or create it with `channel create` if the user is
      the channel creator
-  10. explain the immutable policy warning printed by the CLI
+  10. explain the immutable policy warning and that the join toll is paid directly from the L1 wallet, not bridge-deposited balance
   11. run `channel join --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH> --acknowledge-action-impact`
 - Before executing any command for a user that requires an `--acknowledge-*` option, strongly warn the user in plain
   language about what that acknowledgement means and ask for explicit confirmation. Do not add
@@ -566,7 +592,7 @@ Operating rules:
 - Do not present one fixed command sequence as universally correct. Some flows start from an existing channel or wallet,
   while others require creating or joining a channel first.
 - When the user asks for a transfer, first determine whether the sender has minted notes available. If not, guide them
-  through funding the bridge, joining or recovering the channel wallet, depositing into the channel, and minting notes.
+  through joining or recovering the channel wallet, funding the bridge for channel liquidity, depositing into the channel, and minting notes.
 - When generating commands, use placeholders for secrets and explicit values for public fields. Show one command at a
   time unless the user asks for a batch.
 
@@ -577,10 +603,10 @@ Suggested interaction flow:
 3. Identify the sender and recipient wallets or local account names.
 4. Run `help doctor`.
 5. Run `wallet list` and relevant metadata or balance checks.
-6. If needed, guide the user through `channel create`, `account deposit-bridge`, `channel join`, `wallet deposit-channel`, and
+6. If needed, guide the user through `channel create`, `channel join`, `account deposit-bridge`, `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/cli-assistant.html

@@ -422,11 +422,12 @@
               <li>
                 <span class="guide-label">Join a channel:</span> <code>channel join</code>
                 <div class="guide-example">
-                  <code>channel join --channel-name 'my-private-channel' --network 'sepolia' --account 'my-account' --wallet-secret-path '/path/to/wallet-secret'</code>
+                  <code>channel join --channel-name 'my-private-channel' --network 'sepolia' --account 'my-account' --wallet-secret-path '/path/to/wallet-secret'</code><br />
+                  Pays the join toll directly from the L1 wallet, not from bridge-deposited balance.
                 </div>
               </li>
               <li>
-                <span class="guide-label">Create notes:</span> <code>account deposit-bridge</code> -&gt; <code>wallet deposit-channel</code> -&gt; <code>wallet mint-notes</code>
+                <span class="guide-label">Fund note balance:</span> <code>account deposit-bridge</code> -&gt; <code>wallet deposit-channel</code> -&gt; <code>wallet mint-notes</code>
                 <div class="guide-example">
                   <code>account deposit-bridge --amount '100' --network 'sepolia' --account 'my-account'</code><br />
                   <code>wallet deposit-channel --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amount '100'</code><br />

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: {
@@ -327,7 +330,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     fields: ["network", "channelName", "account", "wallet"],
     optionalFields: ["network", "channelName", "account", "wallet"],
     usage: "optional --network, --channel-name, --account, and --wallet",
-    help: ["Does not accept --rpc-url and never writes RPC configuration"],
+    help: ["Does not accept --rpc-url and never writes RPC configuration", "Recommends bridge deposits only after a wallet is joined and needs channel liquidity"],
   },
   {
     id: "help-observer",
@@ -349,6 +352,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     help: [
       "Uses packages/apps/private-state/cli/assets/tx-fees.json as the measured gas source packaged with the CLI",
       "Reads live fee data from the selected network RPC and live ETH/USD from CoinGecko",
+      "AI agents should run this command with --json when users ask about gas, transaction fees, transaction cost, or USD cost",
     ],
   },
   {
@@ -458,7 +462,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "--amount, --network, --account, --acknowledge-action-impact",
     help: [
       "Action impact: emits public L1 approval and bridge funding events that expose the local L1 account, bridge vault, amount, and transaction hashes.",
-      "Private note state is not changed by this command.",
+      "Private note state is not changed by this command; it does not pay a channel join toll.",
       ACTION_IMPACT_HELP.exchangeControlledAddress,
       ACTION_IMPACT_HELP.illegalUse,
       ACTION_IMPACT_HELP.acknowledgement,
@@ -508,9 +512,10 @@ 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",
+      "Pays any join toll directly from the L1 wallet, not from bridge-deposited balance",
       "Prints the immutable policy snapshot before first registration",
       "Action impact: emits public channel join and token-vault registration events exposing the L1 account, L2 address pair, note-receive public key, join toll, and channel id.",
       "Private note state is not changed by this command.",
@@ -528,7 +533,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 +603,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 +620,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 +637,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 +647,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 +659,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 +677,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 +703,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 +722,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

@@ -137,7 +137,7 @@ const PRIVATE_STATE_UNINSTALL_CONFIRMATION =
 const ACTION_IMPACT_CONFIRMATION =
   "I understand the public and private impact of this action";
 const PRIVATE_STATE_CLI_PACKAGE_NAME = privateStateCliPackageJson.name;
-const PRIVATE_STATE_OBSERVER_URL = "https://project-scw1r.vercel.app";
+const PRIVATE_STATE_OBSERVER_URL = "https://observer.tonnel.io";
 const GROTH16_PACKAGE_NAME = "@tokamak-private-dapps/groth16";
 const TOKAMAK_ZKEVM_CLI_PACKAGE_NAME = "@tokamak-zk-evm/cli";
 const WALLET_BACKUP_EXPORT_FORMAT = "tokamak-private-state-wallet-backup-export";
@@ -327,7 +327,7 @@ const ACTION_IMPACT_SUMMARIES = Object.freeze({
   },
   "channel-join": {
     display: "channel join",
-    l1PublicEvent: "Yes. Channel join and token-vault registration transactions are public L1 data.",
+    l1PublicEvent: "Yes. Channel join and token-vault registration transactions are public L1 data; any join toll is paid directly from the L1 wallet.",
     privateNoteState: "No. This action registers identity and note-receive metadata; it does not create or spend notes.",
     publicFields: ({ l1Address, l2Address, noteReceivePubKey, joinToll, channelName, channelId }) => [
       `Channel: ${channelName} (${channelId})`,
@@ -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,
@@ -4163,7 +4120,7 @@ function applyGuideNextAction(guide) {
     const account = guide.selectors.account ?? "<ACCOUNT>";
     setGuideNextAction(guide, {
       command: `channel join --channel-name ${channelName} --network ${guide.selectors.network} --account ${account} --wallet-secret-path <PATH> --acknowledge-action-impact`,
-      why: "The selected local wallet does not exist. Join the channel to create the wallet and register the channel L2 identity.",
+      why: "The selected local wallet does not exist. Join the channel to create the wallet, register the channel L2 identity, and pay any join toll directly from the L1 wallet.",
     });
     return;
   }
@@ -4172,7 +4129,7 @@ function applyGuideNextAction(guide) {
     const account = guide.selectors.account ?? "<ACCOUNT>";
     setGuideNextAction(guide, {
       command: `channel join --channel-name ${channelName} --network ${guide.selectors.network} --account ${account} --wallet-secret-path <PATH> --acknowledge-action-impact`,
-      why: "The local wallet exists, but the corresponding L1 address is not registered in the channel.",
+      why: "The local wallet exists, but the corresponding L1 address is not registered in the channel; joining pays any join toll directly from the L1 wallet.",
     });
     return;
   }
@@ -4189,7 +4146,7 @@ function applyGuideNextAction(guide) {
     const account = guide.selectors.account ?? "<ACCOUNT>";
     setGuideNextAction(guide, {
       command: `account deposit-bridge --amount <TOKENS> --network ${guide.selectors.network} --account ${account} --acknowledge-action-impact`,
-      why: "The wallet is joined, but there is no bridge balance, channel balance, or local unused note to spend.",
+      why: "The wallet is joined, but there is no bridge balance, channel balance, or local unused note to spend; bridge deposits fund channel liquidity and do not pay join tolls.",
     });
     return;
   }
@@ -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.3",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",