@tokamak-private-dapps/private-state-cli 1.0.0 → 1.0.2

package/private-state-bridge-cli.mjs

@@ -68,6 +68,7 @@ import {
   installPrivateStateCliArtifacts,
   installTokamakCliRuntimeForPrivateState,
   inspectGroth16Runtime,
+  parseJsonReport,
   printDoctorHumanReport,
   privateStateCliArtifactPaths,
   readTokamakCliPackageReport,
@@ -77,6 +78,7 @@ import {
   resolveArtifactCacheBaseRoot,
   resolvePrivateStateInstallRuntimeVersions,
   resolveTokamakCliResourceDirForRuntimeRoot,
+  stripAnsi,
   writePrivateStateCliInstallManifest,
 } from "./lib/private-state-runtime-management.mjs";
 import {
@@ -120,12 +122,14 @@ import {
 
 const require = createRequire(import.meta.url);
 const defaultCommandCwd = process.cwd();
+const privateStateCliPackageJson = require("./package.json");
 const privateStateCliPackageRoot = path.dirname(require.resolve("./package.json"));
 const workspaceRoot = path.resolve(os.homedir(), "tokamak-private-channels", "workspace");
 const secretRoot = path.resolve(os.homedir(), "tokamak-private-channels", "secrets");
 const flatDeploymentArtifactPathsByChainId = new Map();
 const PRIVATE_STATE_UNINSTALL_CONFIRMATION =
   "I understand that the wallet secrets deleted due to this decision cannot be recovered";
+const PRIVATE_STATE_CLI_PACKAGE_NAME = privateStateCliPackageJson.name;
 const GROTH16_PACKAGE_NAME = "@tokamak-private-dapps/groth16";
 const TOKAMAK_ZKEVM_CLI_PACKAGE_NAME = "@tokamak-zk-evm/cli";
 let jsonOutputRequested = false;
@@ -314,6 +318,12 @@ async function main() {
   activeCliArgs = args;
   configureOutput(args);
 
+  if (args.version !== undefined) {
+    assertVersionArgs(args);
+    printVersion();
+    return;
+  }
+
   if (args.help || !args.command) {
     printHelp();
     return;
@@ -331,6 +341,12 @@ async function main() {
     return;
   }
 
+  if (args.command === "update") {
+    assertUpdateArgs(args);
+    await handleUpdate();
+    return;
+  }
+
   if (args.command === "doctor") {
     assertDoctorArgs(args);
     await handleDoctor({ args });
@@ -343,6 +359,13 @@ async function main() {
     return;
   }
 
+  if (args.command === "transaction-fees") {
+    assertTransactionFeesArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args);
+    await handleTransactionFees({ network, provider, rpcUrl });
+    return;
+  }
+
   if (args.command === "get-my-l1-address") {
     assertGetMyL1AddressArgs(args);
     handleGetMyL1Address({ args });
@@ -511,6 +534,8 @@ async function handleChannelCreate({ args, network, provider }) {
     provider,
     bridgeResources,
     persist: true,
+    fromGenesis: true,
+    progressAction: "create-channel",
   });
 
   printJson({
@@ -622,6 +647,7 @@ async function handleWorkspaceInit({ args, network, provider }) {
     allowExistingWorkspaceSync: true,
     useWorkspaceRecoveryIndex: true,
     fromGenesis: args.fromGenesis === true,
+    progressAction: "recover-workspace",
   });
 
   printJson({
@@ -729,6 +755,7 @@ async function initializeChannelWorkspace({
   allowExistingWorkspaceSync = false,
   useWorkspaceRecoveryIndex = false,
   fromGenesis = false,
+  progressAction = null,
 }) {
   const workspaceDir = channelWorkspacePath(networkNameFromChainId(network.chainId), workspaceName);
   const channelDir = channelDataPath(workspaceDir);
@@ -806,6 +833,13 @@ async function initializeChannelWorkspace({
       managedStorageAddresses,
     })
     : null;
+  if (useWorkspaceRecoveryIndex && !fromGenesis && !localSnapshotReusable && !recoveryIndex) {
+    throw new Error([
+      `Workspace recovery index is missing or unusable for channel ${channelName} on ${networkNameFromChainId(network.chainId)}.`,
+      "The CLI will not fall back to replaying channel logs from genesis unless explicitly requested.",
+      "Run recover-workspace --from-genesis or recover-wallet --from-genesis to rebuild from channel genesis.",
+    ].join(" "));
+  }
   const reconstruction = localSnapshotReusable
     ? {
       currentSnapshot: existingArtifacts.stateSnapshot,
@@ -831,6 +865,7 @@ async function initializeChannelWorkspace({
       baseSnapshot: recoveryIndex?.stateSnapshot ?? null,
       fromBlock: recoveryIndex?.nextBlock ?? genesisBlockNumber,
       toBlock: latestBlock,
+      progressAction,
     });
   const currentSnapshot = reconstruction.currentSnapshot;
   const recoveryRootVectorHash = normalizeBytes32Hex(hashRootVector(currentSnapshot.stateRoots));
@@ -975,6 +1010,9 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     bridgeResources,
     persist: true,
     allowExistingWorkspaceSync: true,
+    useWorkspaceRecoveryIndex: true,
+    fromGenesis: args.fromGenesis === true,
+    progressAction: "recover-wallet",
   });
   const context = {
     workspaceName: channelName,
@@ -1056,6 +1094,14 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
   });
 
   if (existingWallet) {
+    const { recoveredDeliveryState } = await recoverWalletReceivedNotes({
+      walletContext: existingWallet,
+      context,
+      provider,
+      signer,
+      noteReceiveKeyMaterial,
+      progressAction: "recover-wallet",
+    });
     printJson({
       action: "recover-wallet",
       status: "already-recovered",
@@ -1071,6 +1117,10 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
       l2StorageKey: storageKey,
       leafIndex: registration.leafIndex.toString(),
       noteReceivePubKey: noteReceiveKeyMaterial.noteReceivePubKey,
+      l2Nonce: existingWallet.wallet.l2Nonce,
+      recoveredFromLogs: recoveredDeliveryState.importedNotes,
+      scannedDeliveryLogs: recoveredDeliveryState.scannedLogs,
+      noteReceiveScanRange: recoveredDeliveryState.scanRange,
     });
     return;
   }
@@ -1091,11 +1141,13 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
   walletContext.wallet.l2Nonce = 0;
   persistWallet(walletContext);
 
-  const recoveredDeliveryState = await recoverDeliveredNotesFromEventLogs({
+  const { recoveredDeliveryState } = await recoverWalletReceivedNotes({
     walletContext,
     context,
     provider,
-    noteReceivePrivateKey: noteReceiveKeyMaterial.privateKey,
+    signer,
+    noteReceiveKeyMaterial,
+    progressAction: "recover-wallet",
   });
 
   printJson({
@@ -1390,31 +1442,44 @@ function assertSafeManagedRoot(rootPath, label) {
   }
 }
 
-function uninstallGlobalPrivateStateCliPackage() {
-  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
-  const list = runCaptured(npmCommand, ["ls", "-g", "@tokamak-private-dapps/private-state-cli", "--depth=0", "--json"]);
-  if (list.status !== 0) {
-    const listReport = parseJsonReport(list.stdout);
+function npmCommandName() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function inspectGlobalPrivateStateCliPackage() {
+  const list = runCaptured(npmCommandName(), ["ls", "-g", PRIVATE_STATE_CLI_PACKAGE_NAME, "--depth=0", "--json"]);
+  const report = parseJsonReport(list.stdout);
+  const packageReport = report?.dependencies?.[PRIVATE_STATE_CLI_PACKAGE_NAME] ?? null;
+  const installed = Boolean(packageReport);
+  if (!installed) {
     const missing = /empty|missing|not found|not installed/iu.test(`${list.stdout}\n${list.stderr}`);
     return {
-      attempted: false,
       installed: false,
-      reason: missing || listReport ? "global package is not installed" : "unable to inspect global npm package",
+      version: null,
       status: list.status,
+      reason: missing || report ? "global package is not installed" : "unable to inspect global npm package",
       stderr: stripAnsi(list.stderr).trim(),
     };
   }
-  const report = parseJsonReport(list.stdout);
-  const installed = Boolean(report?.dependencies?.["@tokamak-private-dapps/private-state-cli"]);
-  if (!installed) {
+  return {
+    installed: true,
+    version: packageReport.version ?? null,
+    status: list.status,
+  };
+}
+
+function uninstallGlobalPrivateStateCliPackage() {
+  const inspection = inspectGlobalPrivateStateCliPackage();
+  if (!inspection.installed) {
     return {
       attempted: false,
       installed: false,
-      reason: "global package is not installed",
-      status: list.status,
+      reason: inspection.reason,
+      status: inspection.status,
+      stderr: inspection.stderr,
     };
   }
-  const uninstall = runCaptured(npmCommand, ["uninstall", "-g", "@tokamak-private-dapps/private-state-cli"]);
+  const uninstall = runCaptured(npmCommandName(), ["uninstall", "-g", PRIVATE_STATE_CLI_PACKAGE_NAME]);
   return {
     attempted: true,
     installed: true,
@@ -1425,6 +1490,106 @@ function uninstallGlobalPrivateStateCliPackage() {
   };
 }
 
+async function handleUpdate() {
+  const currentVersion = privateStateCliPackageJson.version;
+  const latestVersion = await fetchLatestPrivateStateCliVersion();
+  const registryComparison = compareSemver(currentVersion, latestVersion);
+  const globalPackage = inspectGlobalPrivateStateCliPackage();
+  const runningFromRepositoryCheckout = isRepositoryCliPackageRoot(privateStateCliPackageRoot);
+  const updateAvailable = registryComparison < 0;
+
+  const result = {
+    action: "update",
+    packageName: PRIVATE_STATE_CLI_PACKAGE_NAME,
+    currentVersion,
+    latestVersion,
+    updateAvailable,
+    registryState: registryComparison > 0 ? "local-version-ahead-of-registry" : "normal",
+    runningFromRepositoryCheckout,
+    globalPackage,
+    attempted: false,
+    updated: false,
+    command: `npm install -g ${PRIVATE_STATE_CLI_PACKAGE_NAME}@latest`,
+  };
+
+  if (!updateAvailable) {
+    printJson(result);
+    return;
+  }
+
+  if (runningFromRepositoryCheckout) {
+    printJson({
+      ...result,
+      reason: "running from a repository checkout; update the checkout with git/npm instead of mutating source files",
+    });
+    return;
+  }
+
+  if (!globalPackage.installed) {
+    printJson({
+      ...result,
+      reason: "global npm package is not installed; install or update the CLI with the printed command",
+    });
+    return;
+  }
+
+  const install = runCaptured(npmCommandName(), ["install", "-g", `${PRIVATE_STATE_CLI_PACKAGE_NAME}@latest`]);
+  if (install.status !== 0) {
+    throw new Error([
+      `Unable to update ${PRIVATE_STATE_CLI_PACKAGE_NAME} to ${latestVersion}.`,
+      stripAnsi(install.stderr || install.stdout).trim(),
+    ].filter(Boolean).join(" "));
+  }
+  printJson({
+    ...result,
+    attempted: true,
+    updated: true,
+    installedVersion: latestVersion,
+    stdout: stripAnsi(install.stdout).trim(),
+    stderr: stripAnsi(install.stderr).trim(),
+  });
+}
+
+async function fetchLatestPrivateStateCliVersion() {
+  const url = `https://registry.npmjs.org/${encodeURIComponent(PRIVATE_STATE_CLI_PACKAGE_NAME)}/latest`;
+  const response = await fetch(url, {
+    redirect: "follow",
+    signal: typeof globalThis.AbortSignal?.timeout === "function" ? globalThis.AbortSignal.timeout(10_000) : undefined,
+  });
+  if (!response.ok) {
+    throw new Error(`Unable to fetch ${PRIVATE_STATE_CLI_PACKAGE_NAME} latest version from npm registry: HTTP ${response.status}.`);
+  }
+  const metadata = await response.json();
+  const version = metadata?.version;
+  if (typeof version !== "string" || version.trim() === "") {
+    throw new Error(`npm registry response for ${PRIVATE_STATE_CLI_PACKAGE_NAME} did not include a version.`);
+  }
+  return version;
+}
+
+function compareSemver(left, right) {
+  const parse = (value) => String(value).split("-", 1)[0].split(".").map((part) => {
+    const parsed = Number.parseInt(part, 10);
+    return Number.isFinite(parsed) ? parsed : 0;
+  });
+  const leftParts = parse(left);
+  const rightParts = parse(right);
+  const length = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0; index < length; index += 1) {
+    const delta = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+    if (delta !== 0) {
+      return delta < 0 ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+function isRepositoryCliPackageRoot(packageRoot) {
+  const segments = path.resolve(packageRoot).split(path.sep);
+  const suffix = ["packages", "apps", "private-state", "cli"];
+  return suffix.every((segment, index) => segments[segments.length - suffix.length + index] === segment);
+}
+
 async function handleDoctor({ args }) {
   const report = buildDoctorReport({ probeGpu: args.gpu === true });
   if (isJsonOutputRequested()) {
@@ -1437,6 +1602,144 @@ async function handleDoctor({ args }) {
   }
 }
 
+async function handleTransactionFees({ network, provider, rpcUrl }) {
+  const feeAsset = loadTransactionFeeAsset();
+  const feeData = await provider.getFeeData();
+  const gasPrices = requireTransactionFeeGasPrices(feeData);
+  const ethUsd = await fetchEthUsdPrice();
+  const rows = buildTransactionFeeRows({
+    commands: feeAsset.commands,
+    typicalGasPriceWei: gasPrices.typical,
+    worstCaseGasPriceWei: gasPrices.worstCase,
+    ethUsd,
+  });
+
+  printJson({
+    action: "transaction-fees",
+    generatedAt: new Date().toISOString(),
+    network: network.name,
+    chainId: Number(network.chainId),
+    rpcUrl,
+    asset: {
+      schema: feeAsset.schema,
+      measuredAt: feeAsset.measuredAt,
+      measurementBasis: feeAsset.measurementBasis,
+      notes: feeAsset.notes,
+    },
+    livePricing: {
+      typicalGasPriceWei: gasPrices.typical.toString(),
+      typicalGasPriceGwei: formatGwei(gasPrices.typical),
+      typicalGasPriceSource: gasPrices.typicalSource,
+      worstCaseGasPriceWei: gasPrices.worstCase.toString(),
+      worstCaseGasPriceGwei: formatGwei(gasPrices.worstCase),
+      worstCaseGasPriceSource: gasPrices.worstCaseSource,
+      maxFeePerGasWei: feeData.maxFeePerGas?.toString() ?? null,
+      maxPriorityFeePerGasWei: feeData.maxPriorityFeePerGas?.toString() ?? null,
+      gasPriceWei: feeData.gasPrice?.toString() ?? null,
+      ethUsd,
+      ethUsdSource: "CoinGecko simple price API",
+    },
+    rows,
+  });
+}
+
+function loadTransactionFeeAsset() {
+  const assetPath = path.join(privateStateCliPackageRoot, "assets", "tx-fees.json");
+  const asset = readJson(assetPath);
+  expect(asset.schema === "tokamak-private-state-cli-tx-fees.v1", `Unsupported transaction fee asset schema: ${assetPath}`);
+  expect(Array.isArray(asset.commands), `Transaction fee asset is missing commands: ${assetPath}`);
+  return asset;
+}
+
+function requireTransactionFeeGasPrices(feeData) {
+  const typical = feeData.gasPrice ?? feeData.maxFeePerGas;
+  const worstCase = feeData.maxFeePerGas ?? feeData.gasPrice;
+  if (typical === null || typical === undefined || worstCase === null || worstCase === undefined) {
+    throw new Error("RPC provider did not return gasPrice or maxFeePerGas.");
+  }
+  return {
+    typical: ethers.toBigInt(typical),
+    typicalSource: feeData.gasPrice ? "gasPrice" : "maxFeePerGas",
+    worstCase: ethers.toBigInt(worstCase),
+    worstCaseSource: feeData.maxFeePerGas ? "maxFeePerGas" : "gasPrice",
+  };
+}
+
+async function fetchEthUsdPrice() {
+  const url = "https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd";
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      "user-agent": `${privateStateCliPackageJson.name}/${privateStateCliPackageJson.version}`,
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`Unable to fetch live ETH/USD price from CoinGecko: HTTP ${response.status}.`);
+  }
+  const payload = await response.json();
+  const value = Number(payload?.ethereum?.usd);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error("CoinGecko response did not include a valid ethereum.usd price.");
+  }
+  return value;
+}
+
+function buildTransactionFeeRows({ commands, typicalGasPriceWei, worstCaseGasPriceWei, ethUsd }) {
+  return commands.map((entry) => {
+    const transactions = expectTransactionFeeTransactions(entry);
+    const gasUsed = transactions.reduce((sum, transaction) => sum + Number(transaction.gasUsed), 0);
+    const typicalEth = ethers.formatEther(BigInt(gasUsed) * typicalGasPriceWei);
+    const worstCaseEth = ethers.formatEther(BigInt(gasUsed) * worstCaseGasPriceWei);
+    return {
+      command: entry.command,
+      description: entry.description,
+      transactions: transactions.map((transaction) => transaction.label).join(" + "),
+      gasUsed,
+      typicalGasPriceGwei: formatGwei(typicalGasPriceWei),
+      typicalEth: formatEthForDisplay(typicalEth),
+      typicalUsd: formatUsdForDisplay(Number(typicalEth) * ethUsd),
+      worstCaseGasPriceGwei: formatGwei(worstCaseGasPriceWei),
+      worstCaseEth: formatEthForDisplay(worstCaseEth),
+      worstCaseUsd: formatUsdForDisplay(Number(worstCaseEth) * ethUsd),
+      sources: [...new Set(transactions.map((transaction) => transaction.source))].join(", "),
+      sourceDetails: transactions.map((transaction) => transaction.sourceDetail),
+    };
+  });
+}
+
+function expectTransactionFeeTransactions(entry) {
+  expect(typeof entry?.command === "string" && entry.command.length > 0, "Transaction fee asset contains a command without command name.");
+  expect(Array.isArray(entry.transactions) && entry.transactions.length > 0, `Transaction fee asset command ${entry.command} has no transactions.`);
+  for (const transaction of entry.transactions) {
+    expect(Number.isInteger(transaction.gasUsed) && transaction.gasUsed > 0, `Transaction fee asset command ${entry.command} has invalid gasUsed.`);
+  }
+  return entry.transactions;
+}
+
+function formatGwei(wei) {
+  return trimFixedNumber(ethers.formatUnits(wei, "gwei"), 6);
+}
+
+function formatEthForDisplay(value) {
+  return trimFixedNumber(value, 8);
+}
+
+function formatUsdForDisplay(value) {
+  if (value > 0 && value < 0.01) {
+    return "<0.01";
+  }
+  return value.toFixed(2);
+}
+
+function trimFixedNumber(value, maxDecimals) {
+  const [integer, decimals = ""] = String(value).split(".");
+  if (!decimals || maxDecimals <= 0) {
+    return integer;
+  }
+  const trimmed = decimals.slice(0, maxDecimals).replace(/0+$/u, "");
+  return trimmed ? `${integer}.${trimmed}` : integer;
+}
+
 function handleGetMyL1Address({ args }) {
   const signer = requireL1Signer(args);
   printJson({
@@ -1513,6 +1816,7 @@ async function handleGuide({ args }) {
     nextSafeAction: null,
     why: null,
     candidateCommands: [],
+    privacyTip: "For mint-notes, transfer-notes, and redeem-notes, add --tx-submitter <ACCOUNT> to let a separate local L1 account submit executeChannelTransaction and pay gas.",
   };
 
   guide.state.local = inspectGuideLocalState(args);
@@ -1957,8 +2261,8 @@ function applyGuideNextAction(guide) {
   }
   if (guide.selectors.channelName && guide.state.channel?.onchain?.exists && !guide.state.channel?.local?.workspaceExists) {
     setGuideNextAction(guide, {
-      command: `recover-workspace --channel-name ${guide.selectors.channelName} --network ${guide.selectors.network}`,
-      why: "The channel exists on-chain, but the local channel workspace has not been recovered yet.",
+      command: `recover-workspace --channel-name ${guide.selectors.channelName} --network ${guide.selectors.network} --from-genesis`,
+      why: "The channel exists on-chain, but the local channel workspace has not been recovered yet, so there is no local recovery index to resume from.",
     });
     return;
   }
@@ -2006,18 +2310,18 @@ function applyGuideNextAction(guide) {
   }
   if (guide.state.wallet?.exists && channelBalance !== null && channelBalance > 0n && unusedNotes === 0) {
     setGuideNextAction(guide, {
-      command: `mint-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --amounts <A,B>`,
-      why: "The wallet has channel L2 balance and no unused private notes yet.",
+      command: `mint-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --amounts <A,B> [--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: `transfer-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID,ID> --recipients <ADDR,ADDR> --amounts <A,B>`,
-      why: "The wallet has unused private notes. It can transfer or redeem those notes.",
+      command: `transfer-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID,ID> --recipients <ADDR,ADDR> --amounts <A,B> [--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: [
         `get-my-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network}`,
-        `redeem-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID>`,
+        `redeem-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID> [--tx-submitter <ACCOUNT>]`,
       ],
     });
     return;
@@ -2097,21 +2401,24 @@ function redactRpcUrl(rpcUrl) {
 
 async function handleGetMyWalletMeta({ args, provider }) {
   const { wallet, walletMetadata } = loadUnlockedWalletWithMetadata(args);
-  const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
-  const context = await loadChannelContext({
-    args,
-    networkName: walletMetadata.network,
+  const contextResult = await loadPreferredWalletChannelContext({
+    walletContext: wallet,
     provider,
+    progressAction: "get-my-wallet-meta",
+  });
+  const context = contextResult.context;
+  const {
+    signer,
+    l2Identity,
+    registration,
+    expectedStorageKey,
+    matchesWallet,
+  } = await loadWalletChannelRegistrationState({
     walletContext: wallet,
+    context,
+    provider,
   });
 
-  const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
-  const expectedStorageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
-  const matchesWallet = registration.exists
-    && ethers.toBigInt(getAddress(registration.l2Address)) === ethers.toBigInt(getAddress(l2Identity.l2Address))
-    && ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
-      === ethers.toBigInt(normalizeBytes32Hex(expectedStorageKey));
-
   printJson({
     action: "get-my-wallet-meta",
     wallet: wallet.walletName,
@@ -2128,28 +2435,24 @@ async function handleGetMyWalletMeta({ args, provider }) {
   });
 }
 
-async function loadWalletChannelFundState({ walletContext, provider }) {
-  const { signer, l2Identity } = restoreWalletParticipant(walletContext, provider);
-  const contextResult = await loadPreferredWalletChannelContext({ walletContext, provider });
+async function loadWalletChannelFundState({ walletContext, provider, progressAction = null }) {
+  const contextResult = await loadPreferredWalletChannelContext({
+    walletContext,
+    provider,
+    progressAction,
+  });
   const context = contextResult.context;
-  const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
-  expect(
-    registration.exists,
-    cliError(
-      CLI_ERROR_CODES.MISSING_CHANNEL_REGISTRATION,
-      `No channelTokenVault registration exists for ${signer.address}. Run join-channel first.`,
-    ),
-  );
-  const expectedStorageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
-  expect(
-    ethers.toBigInt(getAddress(registration.l2Address)) === ethers.toBigInt(getAddress(l2Identity.l2Address)),
-    "The local wallet L2 address does not match the registered channel L2 address.",
-  );
-  expect(
-    ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
-      === ethers.toBigInt(normalizeBytes32Hex(expectedStorageKey)),
-    "The local wallet L2 storage key does not match the registered channelTokenVault key.",
-  );
+  const {
+    signer,
+    l2Identity,
+    registration,
+    expectedStorageKey,
+  } = await loadWalletChannelRegistrationState({
+    walletContext,
+    context,
+    provider,
+    requireRegistration: true,
+  });
 
   const stateManager = await buildStateManager(context.currentSnapshot, context.contractCodes);
   const channelDeposit = await currentStorageBigInt(
@@ -2168,6 +2471,43 @@ async function loadWalletChannelFundState({ walletContext, provider }) {
   };
 }
 
+async function loadWalletChannelRegistrationState({
+  walletContext,
+  context,
+  provider,
+  requireRegistration = false,
+}) {
+  const { signer, l2Identity } = restoreWalletParticipant(walletContext, provider);
+  const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
+  const expectedStorageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
+  const matchesWallet = registration.exists
+    && ethers.toBigInt(getAddress(registration.l2Address)) === ethers.toBigInt(getAddress(l2Identity.l2Address))
+    && ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
+      === ethers.toBigInt(normalizeBytes32Hex(expectedStorageKey));
+
+  if (requireRegistration) {
+    expect(
+      registration.exists,
+      cliError(
+        CLI_ERROR_CODES.MISSING_CHANNEL_REGISTRATION,
+        `No channelTokenVault registration exists for ${signer.address}. Run join-channel first.`,
+      ),
+    );
+    expect(
+      matchesWallet,
+      "The local wallet L2 address or storage key does not match the registered channelTokenVault state.",
+    );
+  }
+
+  return {
+    signer,
+    l2Identity,
+    registration,
+    expectedStorageKey,
+    matchesWallet,
+  };
+}
+
 async function handleGetMyChannelFund({ args, provider }) {
   const { wallet, walletMetadata } = loadUnlockedWalletWithMetadata(args);
   const {
@@ -2177,7 +2517,11 @@ async function handleGetMyChannelFund({ args, provider }) {
     registration,
     expectedStorageKey,
     channelFund,
-  } = await loadWalletChannelFundState({ walletContext: wallet, provider });
+  } = await loadWalletChannelFundState({
+    walletContext: wallet,
+    provider,
+    progressAction: "get-my-channel-fund",
+  });
 
   printJson({
     action: "get-my-channel-fund",
@@ -2200,9 +2544,9 @@ async function handleGetMyChannelFund({ args, provider }) {
 }
 
 async function handleJoinChannel({ args, network, provider, rpcUrl }) {
-  const context = await loadChannelContext({
+  const context = await loadJoinChannelContext({
     args,
-    networkName: network.name,
+    network,
     provider,
   });
   const signer = requireL1Signer(args, provider);
@@ -2357,7 +2701,11 @@ async function handleGrothVaultMove({ args, provider, direction }) {
       : "withdraw";
   emitProgress(operationName, "loading");
   const { wallet: walletContext } = loadUnlockedWalletWithMetadata(args);
-  const contextResult = await loadPreferredWalletChannelContext({ walletContext, provider });
+  const contextResult = await loadPreferredWalletChannelContext({
+    walletContext,
+    provider,
+    progressAction: operationName,
+  });
   const context = contextResult.context;
   const network = contextResult.network;
   expect(
@@ -2403,6 +2751,7 @@ async function handleGrothVaultMove({ args, provider, direction }) {
     "The derived L2 address does not match the registered channel L2 address.",
   );
 
+  await assertWorkspaceAlignedWithChain(context);
   const stateManager = await buildStateManager(context.currentSnapshot, context.contractCodes);
   const keyHex = storageKey;
   const currentValue = await currentStorageBigInt(stateManager, context.workspace.l2AccountingVault, keyHex);
@@ -2578,6 +2927,7 @@ async function handleMintNotes({ args, provider }) {
   const { channelFund } = await loadWalletChannelFundState({
     walletContext: wallet,
     provider,
+    progressAction: "mint-notes",
   });
   expect(
     totalMintAmount <= channelFund,
@@ -2591,6 +2941,7 @@ async function handleMintNotes({ args, provider }) {
     baseUnitAmounts: baseUnitAmounts.map(({ amountBaseUnits }) => amountBaseUnits),
   });
   const { execution, contextResult, recoveredWorkspace } = await executeWalletDirectTemplateCommand({
+    args,
     wallet,
     provider,
     operationName: "mint-notes",
@@ -2602,7 +2953,10 @@ async function handleMintNotes({ args, provider }) {
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
     operationDir: execution.operationDir,
-    l1Submitter: execution.signer.address,
+    l1Submitter: execution.txSubmitter.address,
+    l1WalletOwner: execution.signer.address,
+    txSubmitterSource: execution.txSubmitterSource,
+    txSubmitterAccount: execution.txSubmitterAccount,
     l2Address: execution.l2Identity.l2Address,
     underlyingMethod: templatePayload.method,
     nonce: execution.nonce,
@@ -2631,6 +2985,7 @@ async function handleRedeemNotes({ args, provider }) {
     inputNotes,
   });
   const { execution, contextResult, recoveredWorkspace } = await executeWalletDirectTemplateCommand({
+    args,
     wallet,
     provider,
     operationName: "redeem-notes",
@@ -2642,7 +2997,10 @@ async function handleRedeemNotes({ args, provider }) {
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
     operationDir: execution.operationDir,
-    l1Submitter: execution.signer.address,
+    l1Submitter: execution.txSubmitter.address,
+    l1WalletOwner: execution.signer.address,
+    txSubmitterSource: execution.txSubmitterSource,
+    txSubmitterAccount: execution.txSubmitterAccount,
     l2Address: execution.l2Identity.l2Address,
     receiver: wallet.wallet.l2Address,
     underlyingMethod: templatePayload.method,
@@ -2669,20 +3027,18 @@ async function handleGetMyNotes({ args, provider }) {
     `Wallet ${wallet.walletName} is missing the stored controller address.`,
   );
   const canonicalAssetDecimals = Number(wallet.wallet.canonicalAssetDecimals);
-  const { context } = await loadPreferredWalletChannelContext({ walletContext: wallet, provider });
-  const signer = restoreWalletSigner(wallet, provider);
-  const noteReceiveKeyMaterial = await deriveNoteReceiveKeyMaterial({
-    signer,
-    chainId: context.workspace.chainId,
-    channelId: context.workspace.channelId,
-    channelName: context.workspace.channelName,
-    account: signer.address,
+  const { context } = await loadPreferredWalletChannelContext({
+    walletContext: wallet,
+    provider,
+    progressAction: "get-my-notes",
   });
-  const recoveredDeliveryState = await recoverDeliveredNotesFromEventLogs({
+  const signer = restoreWalletSigner(wallet, provider);
+  const { recoveredDeliveryState } = await recoverWalletReceivedNotes({
     walletContext: wallet,
     context,
     provider,
-    noteReceivePrivateKey: noteReceiveKeyMaterial.privateKey,
+    signer,
+    progressAction: "get-my-notes",
   });
 
   const unusedTrackedNotes = wallet.wallet.notes.unusedOrder
@@ -2728,7 +3084,11 @@ async function handleGetMyNotes({ args, provider }) {
 async function handleTransferNotes({ args, provider }) {
   const { wallet } = loadUnlockedWalletWithMetadata(args);
   const { signer } = restoreWalletParticipant(wallet, provider);
-  const preparedContextResult = await loadPreferredWalletChannelContext({ walletContext: wallet, provider });
+  const preparedContextResult = await loadPreferredWalletChannelContext({
+    walletContext: wallet,
+    provider,
+    progressAction: "transfer-notes",
+  });
   const context = preparedContextResult.context;
   const canonicalAssetDecimals = Number(wallet.wallet.canonicalAssetDecimals);
   const noteIds = parseNoteIdVector(requireArg(args.noteIds, "--note-ids"));
@@ -2760,6 +3120,7 @@ async function handleTransferNotes({ args, provider }) {
     outputAmounts,
   });
   const { execution, contextResult, recoveredWorkspace } = await executeWalletDirectTemplateCommand({
+    args,
     wallet,
     provider,
     operationName: "transfer-notes",
@@ -2777,7 +3138,10 @@ async function handleTransferNotes({ args, provider }) {
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
     operationDir: execution.operationDir,
-    l1Submitter: execution.signer.address,
+    l1Submitter: execution.txSubmitter.address,
+    l1WalletOwner: execution.signer.address,
+    txSubmitterSource: execution.txSubmitterSource,
+    txSubmitterAccount: execution.txSubmitterAccount,
     l2Address: execution.l2Identity.l2Address,
     underlyingMethod: templatePayload.method,
     nonce: execution.nonce,
@@ -3092,17 +3456,47 @@ function buildLifecycleTrackedOutputs({
   }));
 }
 
+async function recoverWalletReceivedNotes({
+  walletContext,
+  context,
+  provider,
+  signer,
+  noteReceiveKeyMaterial = null,
+  progressAction = null,
+}) {
+  const resolvedNoteReceiveKeyMaterial = noteReceiveKeyMaterial ?? await deriveNoteReceiveKeyMaterial({
+    signer,
+    chainId: context.workspace.chainId,
+    channelId: context.workspace.channelId,
+    channelName: context.workspace.channelName,
+    account: signer.address,
+  });
+  const recoveredDeliveryState = await recoverDeliveredNotesFromEventLogs({
+    walletContext,
+    context,
+    provider,
+    noteReceivePrivateKey: resolvedNoteReceiveKeyMaterial.privateKey,
+    progressAction,
+  });
+  return {
+    noteReceiveKeyMaterial: resolvedNoteReceiveKeyMaterial,
+    recoveredDeliveryState,
+  };
+}
+
 async function recoverDeliveredNotesFromEventLogs({
   walletContext,
   context,
   provider,
   noteReceivePrivateKey,
+  progressAction = null,
 }) {
-  const scanStartBlock = Math.max(
-    Number(walletContext.wallet.noteReceiveLastScannedBlock),
-    Number(context.workspace.genesisBlockNumber),
-  );
   const latestBlock = await provider.getBlockNumber();
+  const scanStartBlock = requireUsableWalletNoteReceiveRecoveryIndex({
+    walletContext,
+    context,
+    latestBlock,
+  });
   const scanRange = {
     fromBlock: scanStartBlock,
     toBlock: latestBlock,
@@ -3128,6 +3522,9 @@ async function recoverDeliveredNotesFromEventLogs({
     topics: [NOTE_VALUE_ENCRYPTED_TOPIC],
     fromBlock: scanStartBlock,
     toBlock: latestBlock,
+    onProgress: progressAction
+      ? createRpcLogScanProgress({ action: progressAction, label: "note-delivery events" })
+      : null,
   });
 
   const importedCandidates = [];
@@ -3203,6 +3600,23 @@ async function recoverDeliveredNotesFromEventLogs({
   };
 }
 
+function requireUsableWalletNoteReceiveRecoveryIndex({ walletContext, context, latestBlock }) {
+  const nextBlock = Number(walletContext.wallet.noteReceiveLastScannedBlock);
+  const genesisBlockNumber = Number(context.workspace.genesisBlockNumber);
+  if (
+    !Number.isInteger(nextBlock)
+    || nextBlock < genesisBlockNumber
+    || nextBlock > Number(latestBlock) + 1
+  ) {
+    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}.`,
+      "Run recover-wallet --from-genesis to rebuild wallet note state from channel genesis.",
+    ].join(" "));
+  }
+  return nextBlock;
+}
+
 function extractEncryptedNoteValueFromBridgeLog(log) {
   if (!Array.isArray(log?.topics) || log.topics.length !== 1) {
     return null;
@@ -3666,10 +4080,15 @@ function walletChannelWorkspaceIsReady(walletContext) {
     && fs.existsSync(path.join(channelWorkspaceCurrentPath(workspaceDir), "contract_codes.json"));
 }
 
-async function loadPreferredWalletChannelContext({ walletContext, provider, forceRecover = false }) {
+async function loadPreferredWalletChannelContext({
+  walletContext,
+  provider,
+  forceRecover = false,
+  progressAction = null,
+}) {
   let recoveredWorkspace = false;
   if (forceRecover || !walletChannelWorkspaceIsReady(walletContext)) {
-    await recoverWalletChannelWorkspace({ walletContext, provider });
+    await recoverWalletChannelWorkspace({ walletContext, provider, progressAction });
     recoveredWorkspace = true;
   }
   let context = await loadWorkspaceContext(walletContext.wallet.channelName, walletContext.wallet.network, provider);
@@ -3679,7 +4098,7 @@ async function loadPreferredWalletChannelContext({ walletContext, provider, forc
     if (!isRecoverableWalletWorkspaceFailure(error)) {
       throw error;
     }
-    await recoverWalletChannelWorkspace({ walletContext, provider });
+    await recoverWalletChannelWorkspace({ walletContext, provider, progressAction });
     recoveredWorkspace = true;
     context = await loadWorkspaceContext(walletContext.wallet.channelName, walletContext.wallet.network, provider);
     await assertWorkspaceAlignedWithChain(context);
@@ -3692,7 +4111,7 @@ async function loadPreferredWalletChannelContext({ walletContext, provider, forc
   };
 }
 
-async function recoverWalletChannelWorkspace({ walletContext, provider }) {
+async function recoverWalletChannelWorkspace({ walletContext, provider, progressAction = null }) {
   const networkName = walletContext.wallet.network ?? networkNameFromChainId(Number(walletContext.wallet.chainId));
   const network = resolveCliNetwork(networkName);
   const bridgeResources = loadBridgeResources({ chainId: network.chainId });
@@ -3704,6 +4123,8 @@ async function recoverWalletChannelWorkspace({ walletContext, provider }) {
     bridgeResources,
     persist: true,
     allowExistingWorkspaceSync: true,
+    useWorkspaceRecoveryIndex: true,
+    progressAction,
   });
 }
 
@@ -3725,6 +4146,7 @@ function assertWalletMatchesChannelContext(walletContext, l2Identity, context) {
 }
 
 async function executeWalletDirectTemplateCommand({
+  args,
   wallet,
   provider,
   operationName,
@@ -3732,13 +4154,29 @@ async function executeWalletDirectTemplateCommand({
 }) {
   emitProgress(operationName, "loading");
   const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
-  let contextResult = await loadPreferredWalletChannelContext({ walletContext: wallet, provider });
+  const {
+    txSubmitter,
+    source: txSubmitterSource,
+    account: txSubmitterAccount,
+  } = resolveTxSubmitterSigner({
+    args,
+    ownerSigner: signer,
+    provider,
+  });
+  let contextResult = await loadPreferredWalletChannelContext({
+    walletContext: wallet,
+    provider,
+    progressAction: operationName,
+  });
   let recoveredWorkspace = contextResult.recoveredWorkspace;
 
   try {
     const execution = await executeWalletTemplateSend({
       wallet,
       signer,
+      txSubmitter,
+      txSubmitterSource,
+      txSubmitterAccount,
       l2Identity,
       context: contextResult.context,
       operationName,
@@ -3761,11 +4199,15 @@ async function executeWalletDirectTemplateCommand({
     walletContext: wallet,
     provider,
     forceRecover: true,
+    progressAction: operationName,
   });
   recoveredWorkspace = contextResult.recoveredWorkspace;
   const execution = await executeWalletTemplateSend({
     wallet,
     signer,
+    txSubmitter,
+    txSubmitterSource,
+    txSubmitterAccount,
     l2Identity,
     context: contextResult.context,
     operationName,
@@ -3783,6 +4225,9 @@ async function executeWalletDirectTemplateCommand({
 async function executeWalletTemplateSend({
   wallet,
   signer,
+  txSubmitter,
+  txSubmitterSource,
+  txSubmitterAccount,
   l2Identity,
   context,
   operationName,
@@ -3860,7 +4305,7 @@ async function executeWalletTemplateSend({
   emitProgress(operationName, "submitting");
   const receipt =
     await waitForReceipt(
-      await context.channelManager.connect(signer).executeChannelTransaction(payload, functionProof),
+      await context.channelManager.connect(txSubmitter).executeChannelTransaction(payload, functionProof),
     );
 
   const onchainRootVectorHash = normalizeBytes32Hex(await context.channelManager.currentRootVectorHash());
@@ -3884,6 +4329,9 @@ async function executeWalletTemplateSend({
   return {
     wallet,
     signer,
+    txSubmitter,
+    txSubmitterSource,
+    txSubmitterAccount,
     l2Identity,
     context,
     noteLifecycle,
@@ -3929,24 +4377,10 @@ async function loadWorkspaceContext(workspaceName, networkName, provider) {
   };
 }
 
-async function loadChannelContext({ args, networkName, provider, walletContext = null }) {
+async function loadJoinChannelContext({ args, network, provider }) {
   const chainId = Number((await provider.getNetwork()).chainId);
-  const resolvedNetworkName = networkName ?? networkNameFromChainId(chainId);
-  const channelName = args.channelName ?? walletContext?.wallet.channelName;
-  if (args.channelName && walletContext) {
-    expect(
-      args.channelName === walletContext.wallet.channelName,
-      [
-        `The provided --channel-name (${args.channelName}) does not match the wallet channel`,
-        `(${walletContext.wallet.channelName}).`,
-      ].join(" "),
-    );
-  }
-  if (!channelName) {
-    throw new Error(
-      "Missing channel selector. Provide either --channel-name or --wallet bound to a channel.",
-    );
-  }
+  const resolvedNetworkName = network?.name ?? networkNameFromChainId(chainId);
+  const channelName = requireArg(args.channelName, "--channel-name");
 
   const bridgeResources = loadBridgeResources({ chainId });
   const initialized = await initializeChannelWorkspace({
@@ -4732,6 +5166,7 @@ async function reconstructChannelSnapshot({
   baseSnapshot = null,
   fromBlock = genesisBlockNumber,
   toBlock = null,
+  progressAction = null,
 }) {
   let startingSnapshot = baseSnapshot;
   if (!startingSnapshot) {
@@ -4763,6 +5198,9 @@ async function reconstructChannelSnapshot({
     ]],
     fromBlock: scanFromBlock,
     toBlock: latestBlock,
+    onProgress: progressAction
+      ? createRpcLogScanProgress({ action: progressAction, label: "channel-manager events" })
+      : null,
   });
   const channelManagerEvents = channelManagerLogs.map((log) => {
     const topic0 = log.topics[0] ? normalizeBytes32Hex(log.topics[0]) : null;
@@ -4781,6 +5219,9 @@ async function reconstructChannelSnapshot({
     eventName: "StorageWriteObserved",
     fromBlock: scanFromBlock,
     toBlock: latestBlock,
+    onProgress: progressAction
+      ? createRpcLogScanProgress({ action: progressAction, label: "bridge-vault events" })
+      : null,
   });
 
   const groupedEvents = new Map();
@@ -4900,15 +5341,34 @@ async function fetchLogsChunked(provider, {
   fromBlock,
   toBlock,
   initialChunkSize = DEFAULT_LOG_CHUNK_SIZE,
+  onProgress = null,
 }) {
   const normalizedFromBlock = Number(fromBlock);
   const resolvedToBlock = toBlock === "latest" ? await provider.getBlockNumber() : Number(toBlock);
   const aggregatedLogs = [];
 
   if (normalizedFromBlock > resolvedToBlock) {
+    onProgress?.({
+      status: "skipped",
+      fromBlock: normalizedFromBlock,
+      toBlock: resolvedToBlock,
+      scannedBlocks: 0,
+      totalBlocks: 0,
+      logsFound: 0,
+    });
     return aggregatedLogs;
   }
 
+  const totalBlocks = resolvedToBlock - normalizedFromBlock + 1;
+  onProgress?.({
+    status: "start",
+    fromBlock: normalizedFromBlock,
+    toBlock: resolvedToBlock,
+    scannedBlocks: 0,
+    totalBlocks,
+    logsFound: 0,
+  });
+
   let chunkSize = Math.max(1, Number(initialChunkSize));
   let cursor = normalizedFromBlock;
   while (cursor <= resolvedToBlock) {
@@ -4922,6 +5382,17 @@ async function fetchLogsChunked(provider, {
         toBlock: chunkToBlock,
       });
       aggregatedLogs.push(...logs);
+      onProgress?.({
+        status: "progress",
+        fromBlock: normalizedFromBlock,
+        toBlock: resolvedToBlock,
+        chunkFromBlock: cursor,
+        chunkToBlock,
+        scannedBlocks: chunkToBlock - normalizedFromBlock + 1,
+        totalBlocks,
+        logsFound: aggregatedLogs.length,
+        chunkLogs: logs.length,
+      });
       cursor = chunkToBlock + 1;
     } catch (error) {
       if (isRateLimitError(error)) {
@@ -4938,6 +5409,15 @@ async function fetchLogsChunked(provider, {
     }
   }
 
+  onProgress?.({
+    status: "done",
+    fromBlock: normalizedFromBlock,
+    toBlock: resolvedToBlock,
+    scannedBlocks: totalBlocks,
+    totalBlocks,
+    logsFound: aggregatedLogs.length,
+  });
+
   return aggregatedLogs;
 }
 
@@ -4995,6 +5475,7 @@ async function queryContractEventsChunked({
   eventName,
   fromBlock,
   toBlock,
+  onProgress = null,
 }) {
   const eventFragment = contract.interface.getEvent(eventName);
   const eventTopic = contract.interface.getEvent(eventName).topicHash;
@@ -5006,6 +5487,7 @@ async function queryContractEventsChunked({
     topics: [eventTopic],
     fromBlock,
     toBlock,
+    onProgress,
   });
 
   return logs.map((log) => {
@@ -5278,6 +5760,33 @@ function requireArg(value, label) {
   return value;
 }
 
+function assertVersionArgs(args) {
+  if (args.version !== true) {
+    throw new Error("--version does not accept a value.");
+  }
+  if (args.command) {
+    throw new Error("--version must be used without a command.");
+  }
+  const allowedKeys = new Set(["version", "json"]);
+  const unknownKeys = Object.keys(args)
+    .filter((key) => key !== "positional" && key !== "command" && !allowedKeys.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(`Unsupported --version option(s): ${unknownKeys.map(toKebabCase).join(", ")}.`);
+  }
+}
+
+function printVersion() {
+  if (isJsonOutputRequested()) {
+    printJson({
+      action: "version",
+      packageName: privateStateCliPackageJson.name,
+      version: privateStateCliPackageJson.version,
+    });
+    return;
+  }
+  console.log(privateStateCliPackageJson.version);
+}
+
 function requireWorkspaceName(args) {
   const value = typeof args === "string" ? args : args.workspace;
   if (!value) {
@@ -5306,6 +5815,29 @@ function requireL1Signer(args, provider) {
   return new Wallet(resolvePrivateKeySource(args), provider);
 }
 
+function resolveTxSubmitterSigner({ args, ownerSigner, provider }) {
+  if (args.txSubmitter === undefined) {
+    return {
+      txSubmitter: ownerSigner,
+      source: "wallet-owner",
+      account: null,
+    };
+  }
+  if (args.txSubmitter === true || String(args.txSubmitter).trim() === "") {
+    throw new Error("--tx-submitter requires a local account name.");
+  }
+  const networkName = requireNetworkName(args);
+  const account = String(args.txSubmitter).trim();
+  return {
+    txSubmitter: new Wallet(
+      normalizePrivateKey(readSecretFile(accountPrivateKeyPath(networkName, account), "--tx-submitter")),
+      provider,
+    ),
+    source: "tx-submitter-account",
+    account,
+  };
+}
+
 function resolvePrivateKeySource(args) {
   const networkName = requireNetworkName(args);
   const account = requireAccountName(args);
@@ -5593,6 +6125,10 @@ function assertUninstallArgs(args) {
   assertAllowedCommandSchema(args, "uninstall");
 }
 
+function assertUpdateArgs(args) {
+  assertAllowedCommandSchema(args, "update");
+}
+
 function assertDoctorArgs(args) {
   assertAllowedCommandSchema(args, "doctor");
   if (args.gpu !== undefined && args.gpu !== true) {
@@ -5616,12 +6152,17 @@ function assertGuideArgs(args) {
   assertAllowedCommandSchema(args, "guide");
 }
 
+function assertTransactionFeesArgs(args) {
+  assertAllowedCommandSchema(args, "transaction-fees");
+}
+
 function assertAccountImportArgs(args) {
   assertAllowedCommandSchema(args, "account-import");
 }
 
 function assertMintNotesArgs(args) {
   assertAllowedCommandSchema(args, "mint-notes");
+  assertTxSubmitterArg(args);
   parseAmountVector(args.amounts, {
     allowZeroEntries: true,
     requireAnyPositive: true,
@@ -5630,11 +6171,13 @@ function assertMintNotesArgs(args) {
 
 function assertRedeemNotesArgs(args) {
   assertAllowedCommandSchema(args, "redeem-notes");
+  assertTxSubmitterArg(args);
   selectRedeemNotesMethod(parseNoteIdVector(args.noteIds).length);
 }
 
 function assertTransferNotesArgs(args) {
   assertAllowedCommandSchema(args, "transfer-notes");
+  assertTxSubmitterArg(args);
   const noteIds = parseNoteIdVector(args.noteIds);
   const recipients = parseRecipientVector(args.recipients);
   const amounts = parseAmountVector(args.amounts);
@@ -5645,6 +6188,15 @@ function assertTransferNotesArgs(args) {
   selectTransferNotesMethod(noteIds.length, recipients.length);
 }
 
+function assertTxSubmitterArg(args) {
+  if (args.txSubmitter === undefined) {
+    return;
+  }
+  if (args.txSubmitter === true || String(args.txSubmitter).trim() === "") {
+    throw new Error("--tx-submitter requires a local account name.");
+  }
+}
+
 function assertGetMyNotesArgs(args) {
   assertWalletSecretArgs(args, "get-my-notes");
 }
@@ -5675,6 +6227,9 @@ function assertExplicitSignerCommandArgs(args, commandName) {
 
 function assertRecoverWalletArgs(args) {
   assertExplicitSignerCommandArgs(args, "recover-wallet");
+  if (args.fromGenesis !== undefined && args.fromGenesis !== true) {
+    throw new Error("recover-wallet option --from-genesis does not accept a value.");
+  }
 }
 
 function assertJoinChannelArgs(args) {
@@ -5769,6 +6324,9 @@ Secret source options:
   canonical CLI secret files remain protected. On macOS/Linux this means 0600; on Windows the CLI repairs ACLs when possible.
 
 Options:
+  --version
+      Print the private-state CLI package version and exit.
+
   --json
       Print the command result as JSON. Without --json, commands print human-readable output.
 
@@ -6197,6 +6755,8 @@ function loadWalletCommandRuntime(args) {
 
 const HUMAN_RESULT_RENDERERS = Object.freeze({
   guide: printGuideHumanResult,
+  "transaction-fees": printTransactionFeesHumanResult,
+  update: printUpdateHumanResult,
 });
 
 function normalizePrivateKey(value) {
@@ -6246,9 +6806,90 @@ function printGuideHumanResult(guide) {
   }
 
   lines.push("", "Run with --json to inspect the full guide state.");
+  lines.push(
+    "",
+    "Privacy Tip",
+    formatHumanValue(guide.privacyTip),
+  );
+  console.log(lines.join("\n"));
+}
+
+function printTransactionFeesHumanResult(report) {
+  const lines = [
+    "Transaction Fees",
+    `Generated: ${formatHumanValue(report.generatedAt)}`,
+    `Network: ${formatHumanValue(report.network)} (${formatHumanValue(report.chainId)})`,
+    `Typical gas price: ${formatHumanValue(report.livePricing?.typicalGasPriceGwei)} gwei (${formatHumanValue(report.livePricing?.typicalGasPriceSource)})`,
+    `Worst-case gas price: ${formatHumanValue(report.livePricing?.worstCaseGasPriceGwei)} gwei (${formatHumanValue(report.livePricing?.worstCaseGasPriceSource)})`,
+    `ETH/USD: $${formatHumanValue(report.livePricing?.ethUsd)} (${formatHumanValue(report.livePricing?.ethUsdSource)})`,
+    `Measured gas asset: ${formatHumanValue(report.asset?.schema)}, measured ${formatHumanValue(report.asset?.measuredAt)}`,
+    "",
+    formatHumanTable(
+      ["Command", "Transactions", "Gas", "Typical ETH", "Typical USD", "Worst ETH", "Worst USD", "Source"],
+      (report.rows ?? []).map((row) => [
+        row.command,
+        row.transactions,
+        String(row.gasUsed),
+        row.typicalEth,
+        `$${row.typicalUsd}`,
+        row.worstCaseEth,
+        `$${row.worstCaseUsd}`,
+        row.sources,
+      ]),
+    ),
+  ];
+  if (Array.isArray(report.asset?.notes) && report.asset.notes.length > 0) {
+    lines.push(
+      "",
+      "Notes",
+      ...report.asset.notes.map((note) => `- ${note}`),
+    );
+  }
   console.log(lines.join("\n"));
 }
 
+function printUpdateHumanResult(report) {
+  const lines = [
+    "Private-State CLI Update",
+    `Package: ${formatHumanValue(report.packageName)}`,
+    `Current version: ${formatHumanValue(report.currentVersion)}`,
+    `Latest registry version: ${formatHumanValue(report.latestVersion)}`,
+  ];
+  if (report.registryState === "local-version-ahead-of-registry") {
+    lines.push("Status: local version is newer than the npm registry latest tag.");
+  } else if (!report.updateAvailable) {
+    lines.push("Status: up to date.");
+  } else if (report.updated) {
+    lines.push("Status: updated global npm install.");
+  } else {
+    lines.push(
+      "Status: update available.",
+      `Reason: ${formatHumanValue(report.reason)}`,
+      `Command: ${formatHumanValue(report.command)}`,
+    );
+  }
+  lines.push(
+    `Global install: ${report.globalPackage?.installed ? `yes (${formatHumanValue(report.globalPackage.version)})` : "no"}`,
+    `Repository checkout: ${report.runningFromRepositoryCheckout ? "yes" : "no"}`,
+    "",
+    "Run with --json to inspect the full update report.",
+  );
+  console.log(lines.join("\n"));
+}
+
+function formatHumanTable(headers, rows) {
+  const values = [headers, ...rows].map((row) => row.map((value) => String(value ?? "")));
+  const widths = headers.map((_header, columnIndex) =>
+    Math.max(...values.map((row) => row[columnIndex].length)),
+  );
+  const formatRow = (row) => `| ${row.map((value, index) => value.padEnd(widths[index])).join(" | ")} |`;
+  return [
+    formatRow(values[0]),
+    formatRow(widths.map((width) => "-".repeat(width))),
+    ...values.slice(1).map(formatRow),
+  ].join("\n");
+}
+
 function formatGuideSelector(value) {
   return value === null || value === undefined || value === "" ? "not selected" : String(value);
 }
@@ -6327,6 +6968,51 @@ function emitProgress(action, phase) {
   }
 }
 
+function createRpcLogScanProgress({ action, label }) {
+  let lastBucket = -1;
+  return (event) => {
+    const totalBlocks = Number(event.totalBlocks ?? 0);
+    const scannedBlocks = Number(event.scannedBlocks ?? 0);
+    const logsFound = Number(event.logsFound ?? 0);
+    if (event.status === "skipped") {
+      emitProgress(action, `rpc-log-scan ${label}: skipped (no blocks to scan, ${logsFound} logs)`);
+      return;
+    }
+    if (event.status === "start") {
+      lastBucket = 0;
+      emitProgress(
+        action,
+        `rpc-log-scan ${label}: 0% (0/${totalBlocks} blocks, ${logsFound} logs, blocks ${event.fromBlock}-${event.toBlock})`,
+      );
+      return;
+    }
+    if (event.status === "done") {
+      emitProgress(
+        action,
+        `rpc-log-scan ${label}: 100% (${totalBlocks}/${totalBlocks} blocks, ${logsFound} logs, done)`,
+      );
+      return;
+    }
+    if (event.status !== "progress" || totalBlocks <= 0) {
+      return;
+    }
+
+    const percent = Math.min(100, Math.floor((scannedBlocks * 100) / totalBlocks));
+    if (percent >= 100) {
+      return;
+    }
+    const bucket = Math.floor(percent / 10) * 10;
+    if (bucket <= lastBucket) {
+      return;
+    }
+    lastBucket = bucket;
+    emitProgress(
+      action,
+      `rpc-log-scan ${label}: ${percent}% (${scannedBlocks}/${totalBlocks} blocks, ${logsFound} logs)`,
+    );
+  };
+}
+
 function formatCliErrorForDisplay(error, args = {}) {
   const message = String(error?.message ?? error);
   const hints = buildRecoveryHints(error, args);
@@ -6411,6 +7097,15 @@ function buildRecoveryHints(error, args = {}) {
     hints.push(`private-state-cli guide --network ${networkName} --channel-name ${channelName}`);
   }
 
+  if (message.includes("Workspace recovery index is missing or unusable")) {
+    hints.push(`private-state-cli recover-workspace --channel-name ${channelName} --network ${networkName} --from-genesis`);
+    hints.push(`private-state-cli recover-wallet --channel-name ${channelName} --network ${networkName} --account ${accountName} --from-genesis`);
+  }
+
+  if (message.includes("Wallet note recovery index is missing or unusable")) {
+    hints.push(`private-state-cli recover-wallet --channel-name ${channelName} --network ${networkName} --account ${accountName} --from-genesis`);
+  }
+
   if (message.includes("Missing channel selector")) {
     hints.push(`private-state-cli list-local-wallets --network ${networkName}`);
     hints.push(`private-state-cli guide --network ${networkName} --channel-name <CHANNEL> --wallet <WALLET>`);