@tokamak-private-dapps/private-state-cli 1.2.1 → 2.1.0

package/private-state-bridge-cli.mjs

@@ -7,11 +7,11 @@ import process from "node:process";
 import readline from "node:readline/promises";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
 import AdmZip from "adm-zip";
 import {
   createHash,
   createCipheriv,
-  createDecipheriv,
   randomBytes,
   scryptSync,
 } from "node:crypto";
@@ -61,7 +61,6 @@ import {
   workspaceDirForName,
   workspaceWalletsDir,
   walletDirForName,
-  walletMetadataPathForDir,
   walletNameForChannelAndAddress,
 } from "./lib/private-state-cli-shared.mjs";
 import {
@@ -131,11 +130,19 @@ const secretRoot = path.resolve(os.homedir(), "tokamak-private-channels", "secre
 const flatDeploymentArtifactPathsByChainId = new Map();
 const PRIVATE_STATE_UNINSTALL_CONFIRMATION =
   "I understand that the wallet secrets deleted due to this decision cannot be recovered";
+const ACTION_IMPACT_CONFIRMATION =
+  "I understand the public and private impact of this action";
 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";
-const WALLET_EXPORT_FORMAT = "tokamak-private-state-wallet-export";
-const WALLET_EXPORT_FORMAT_VERSION = 1;
+const WALLET_BACKUP_EXPORT_FORMAT = "tokamak-private-state-wallet-backup-export";
+const WALLET_KEY_EXPORT_FORMAT = "tokamak-private-state-wallet-key-export";
+const WALLET_INDEX_FORMAT = "tokamak-private-state-wallet-index";
+const WALLET_EVIDENCE_BUNDLE_FORMAT = "tokamak-private-state-raw-evidence-bundle";
+const WALLET_EXPORT_FORMAT_VERSION = 2;
+const WALLET_INDEX_FORMAT_VERSION = 1;
+const WALLET_EVIDENCE_BUNDLE_FORMAT_VERSION = 2;
+const WALLET_WORKSPACE_FORMAT_VERSION = 2;
 const CHANNEL_WORKSPACE_MIRROR_PROTOCOL_VERSION = 2;
 const CHANNEL_WORKSPACE_MIRROR_MANIFEST_PATH_PREFIX =
   ".well-known/tokamak-private-state/channel-workspace";
@@ -151,8 +158,6 @@ let activeCliArgs = {};
 const CLI_ERROR_CODES = Object.freeze({
   MISSING_RPC_URL: "MISSING_RPC_URL",
   UNKNOWN_WALLET: "UNKNOWN_WALLET",
-  MISSING_WALLET_SECRET: "MISSING_WALLET_SECRET",
-  WALLET_DECRYPT_FAILED: "WALLET_DECRYPT_FAILED",
   MISSING_DEPLOYMENT_ARTIFACTS: "MISSING_DEPLOYMENT_ARTIFACTS",
   MISSING_CHANNEL_REGISTRATION: "MISSING_CHANNEL_REGISTRATION",
   STALE_WORKSPACE: "STALE_WORKSPACE",
@@ -247,6 +252,206 @@ function printImmutableChannelPolicyWarning({
   console.error(details.join("\n"));
 }
 
+const ACTION_IMPACT_SUMMARIES = Object.freeze({
+  "account-deposit-bridge": {
+    display: "account deposit-bridge",
+    l1PublicEvent: "Yes. ERC-20 approval and bridge vault funding transactions are public L1 events.",
+    privateNoteState: "No. This action only moves canonical tokens into the shared bridge vault.",
+    publicFields: ({ l1Address, amountInput, bridgeTokenVault }) => [
+      `L1 account: ${l1Address}`,
+      `Bridge token vault: ${bridgeTokenVault}`,
+      `Amount: ${amountInput}`,
+      "Approval and funding transaction hashes, block numbers, and event logs.",
+    ],
+    notPublic: [
+      "No private note owner, value, salt, counterparty, or note provenance is created by this action.",
+    ],
+    noteProvenance: "Not applicable for this bridge-edge action.",
+    cexWarning: "Do not use a centralized-exchange controlled address as a self-custody bridge source.",
+    policy: "No channel policy is accepted by this action.",
+  },
+  "account-withdraw-bridge": {
+    display: "account withdraw-bridge",
+    l1PublicEvent: "Yes. The bridge withdrawal transaction and claim event are public L1 data.",
+    privateNoteState: "No. This action claims shared bridge-vault balance to the local L1 account.",
+    publicFields: ({ l1Address, amountInput, bridgeTokenVault }) => [
+      `L1 recipient/account: ${l1Address}`,
+      `Bridge token vault: ${bridgeTokenVault}`,
+      `Amount: ${amountInput}`,
+      "Withdrawal transaction hash, block number, and event log.",
+    ],
+    notPublic: [
+      "The private note path that produced any prior channel balance is not reconstructed from this event alone.",
+    ],
+    noteProvenance: "Public observers cannot reconstruct prior internal note provenance from this withdrawal alone.",
+    cexWarning: "Do not use a centralized-exchange deposit address as the direct bridge withdrawal target unless the user has explicitly accepted the compliance implications. Prefer a self-custody L1 wallet.",
+    policy: "No channel policy is accepted by this action.",
+  },
+  "channel-join": {
+    display: "channel join",
+    l1PublicEvent: "Yes. Channel join and token-vault registration transactions are public L1 data.",
+    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})`,
+      `L1 account: ${l1Address}`,
+      `L2 address: ${l2Address}`,
+      `Note-receive public key: ${noteReceivePubKey}`,
+      `Join toll: ${joinToll}`,
+    ],
+    notPublic: [
+      "Wallet secret, L2 spending private key, note-receive private key, and future note plaintext.",
+    ],
+    noteProvenance: "Future note provenance is not made public by joining.",
+    policy: "Joining accepts the displayed immutable channel policy snapshot.",
+  },
+  "wallet-deposit-channel": {
+    display: "wallet deposit-channel",
+    l1PublicEvent: "Yes. The proof-backed channel accounting transaction is public L1 data.",
+    privateNoteState: "No. This action increases liquid channel accounting balance; it does not create notes.",
+    publicFields: ({ l1Address, l2Address, amountInput, channelName, channelId }) => [
+      `Channel: ${channelName} (${channelId})`,
+      `L1 submitter/account: ${l1Address}`,
+      `Registered L2 address: ${l2Address}`,
+      `Amount: ${amountInput}`,
+      "Transaction hash, accepted proof surface, and accounting root update.",
+    ],
+    notPublic: [
+      "No note owner, value, salt, counterparty, or note provenance is created by this action.",
+    ],
+    noteProvenance: "Not applicable; this action does not transfer note ownership.",
+    policy: "This action uses the channel policy snapshot accepted by the registered wallet.",
+  },
+  "wallet-withdraw-channel": {
+    display: "wallet withdraw-channel",
+    l1PublicEvent: "Yes. The proof-backed channel accounting transaction is public L1 data.",
+    privateNoteState: "No. This action decreases liquid channel accounting balance; it does not spend notes directly.",
+    publicFields: ({ l1Address, l2Address, amountInput, channelName, channelId }) => [
+      `Channel: ${channelName} (${channelId})`,
+      `L1 submitter/account: ${l1Address}`,
+      `Registered L2 address: ${l2Address}`,
+      `Amount: ${amountInput}`,
+      "Transaction hash, accepted proof surface, and accounting root update.",
+    ],
+    notPublic: [
+      "Any prior private note path that produced the liquid balance is not reconstructed from this action alone.",
+    ],
+    noteProvenance: "Public observers cannot reconstruct prior internal note provenance from this withdrawal-channel action alone.",
+    policy: "This action uses the channel policy snapshot accepted by the registered wallet.",
+  },
+  "wallet-mint-notes": {
+    display: "wallet mint-notes",
+    l1PublicEvent: "Yes. executeChannelTransaction, accepted transition, commitments, encrypted note events, and root updates are public L1 data.",
+    privateNoteState: "Yes. This action creates private-state notes tracked by the local wallet.",
+    publicFields: ({ l1Address, l2Address, amounts, channelName, channelId }) => [
+      `Channel: ${channelName} (${channelId})`,
+      `L1 submitter/account: ${l1Address}`,
+      `Registered L2 address: ${l2Address}`,
+      `Requested note amounts: ${amounts}`,
+      "New commitments, encrypted note-delivery events, transaction hash, and root updates.",
+    ],
+    notPublic: [
+      "Note owner, value, salt, plaintext note contents, and later note provenance are not public by default.",
+    ],
+    noteProvenance: "Public observers cannot reconstruct later note provenance without user-controlled disclosure.",
+    policy: "This action uses the channel policy snapshot accepted by the registered wallet.",
+  },
+  "wallet-transfer-notes": {
+    display: "wallet transfer-notes",
+    l1PublicEvent: "Yes. executeChannelTransaction, nullifiers, output commitments, encrypted note events, and root updates are public L1 data.",
+    privateNoteState: "Yes. This action spends selected input notes and creates output notes.",
+    publicFields: ({ l1Address, l2Address, noteIds, amounts, channelName, channelId }) => [
+      `Channel: ${channelName} (${channelId})`,
+      `L1 submitter/account: ${l1Address}`,
+      `Registered L2 address: ${l2Address}`,
+      `Input note commitments: ${noteIds}`,
+      `Output amounts supplied to the CLI: ${amounts}`,
+      "Input nullifiers, output commitments, encrypted note-delivery events, transaction hash, and root updates.",
+    ],
+    notPublic: [
+      "Sender-recipient relationship, recipient note plaintext, and note provenance are not public by default.",
+    ],
+    noteProvenance: "Public observers cannot reconstruct private note counterparty relationships or provenance from public contract state alone.",
+    policy: "This action uses the channel policy snapshot accepted by the registered wallet.",
+  },
+  "wallet-redeem-notes": {
+    display: "wallet redeem-notes",
+    l1PublicEvent: "Yes. executeChannelTransaction, nullifier usage, accounting update, and root updates are public L1 data.",
+    privateNoteState: "Yes. This action consumes selected notes and credits liquid channel accounting balance.",
+    publicFields: ({ l1Address, l2Address, noteIds, channelName, channelId }) => [
+      `Channel: ${channelName} (${channelId})`,
+      `L1 submitter/account: ${l1Address}`,
+      `Registered L2 address: ${l2Address}`,
+      `Input note commitments: ${noteIds}`,
+      "Input nullifiers, accounting update, transaction hash, and root updates.",
+    ],
+    notPublic: [
+      "The prior path by which the redeemed note was received is not public by default.",
+    ],
+    noteProvenance: "Public observers cannot reconstruct prior internal note provenance from this redeem action alone.",
+    policy: "This action uses the channel policy snapshot accepted by the registered wallet.",
+  },
+});
+
+async function requireActionImpactAcknowledgement(commandId, args, details = {}) {
+  const summary = ACTION_IMPACT_SUMMARIES[commandId];
+  if (!summary) {
+    throw new Error(`Missing action-impact summary for ${commandId}.`);
+  }
+  printActionImpactSummary(summary, details);
+  if (args.acknowledgeActionImpact === true) {
+    return;
+  }
+  if (args.acknowledgeActionImpact !== undefined) {
+    throw new Error(`${summary.display} option --acknowledge-action-impact does not accept a value.`);
+  }
+  if (!process.stdin.isTTY) {
+    throw new Error(`${summary.display} requires --acknowledge-action-impact after reviewing the action-impact warning.`);
+  }
+  const prompt = [
+    `Type exactly: ${ACTION_IMPACT_CONFIRMATION}`,
+    "> ",
+  ].join("\n");
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+    terminal: process.stdin.isTTY && process.stderr.isTTY,
+  });
+  try {
+    const answer = await rl.question(prompt);
+    if (answer !== ACTION_IMPACT_CONFIRMATION) {
+      throw new Error(`${summary.display} action-impact confirmation did not match. No transaction was submitted.`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function printActionImpactSummary(summary, details) {
+  const lines = [
+    `ACTION IMPACT SUMMARY: ${summary.display}`,
+    `- L1 public event: ${summary.l1PublicEvent}`,
+    `- Private note state change: ${summary.privateNoteState}`,
+    "- Public addresses and amounts:",
+    ...normalizeImpactLines(summary.publicFields, details).map((line) => `  - ${line}`),
+    "- Not public by default:",
+    ...normalizeImpactLines(summary.notPublic, details).map((line) => `  - ${line}`),
+    `- Note provenance: ${summary.noteProvenance}`,
+    `- Illegal-use prohibition: Do not use this command for money laundering, sanctions evasion, terrorist financing, illegal gambling, criminal-proceeds concealment, or regulatory evasion.`,
+    `- Secret recovery: Losing wallet secrets, viewing keys, or spending keys can prevent note discovery or note use. The CLI cannot recover lost secrets.`,
+    `- Channel policy: ${summary.policy}`,
+  ];
+  if (summary.cexWarning) {
+    lines.push(`- CEX address warning: ${summary.cexWarning}`);
+  }
+  lines.push(`- Confirmation: pass --acknowledge-action-impact or type the exact confirmation phrase when prompted.`);
+  console.error(lines.join("\n"));
+}
+
+function normalizeImpactLines(value, details) {
+  const resolved = typeof value === "function" ? value(details) : value;
+  return Array.isArray(resolved) ? resolved : [resolved];
+}
+
 function normalizeDAppPolicySnapshot({
   dappId,
   metadataDigest,
@@ -386,6 +591,12 @@ async function main() {
     return;
   }
 
+  if (args.command === "investigator") {
+    assertInvestigatorArgs(args);
+    handleInvestigator();
+    return;
+  }
+
   if (args.command === "account-get-l1-address") {
     assertAccountGetL1AddressArgs(args);
     handleAccountGetL1Address({ args });
@@ -404,15 +615,39 @@ async function main() {
     return;
   }
 
-  if (args.command === "wallet-export") {
-    assertWalletExportArgs(args);
-    handleWalletExport({ args });
+  if (args.command === "wallet-export-backup") {
+    assertWalletExportBackupArgs(args);
+    handleWalletExportBackup({ args });
+    return;
+  }
+
+  if (args.command === "wallet-export-viewing-key") {
+    assertWalletExportKeyArgs(args, "wallet-export-viewing-key");
+    handleWalletExportKey({ args, keyKind: "viewing" });
+    return;
+  }
+
+  if (args.command === "wallet-export-spending-key") {
+    assertWalletExportKeyArgs(args, "wallet-export-spending-key");
+    handleWalletExportKey({ args, keyKind: "spending" });
+    return;
+  }
+
+  if (args.command === "wallet-import-backup") {
+    assertWalletImportBackupArgs(args);
+    handleWalletImportBackup({ args });
+    return;
+  }
+
+  if (args.command === "wallet-import-viewing-key") {
+    assertWalletImportKeyArgs(args, "wallet-import-viewing-key");
+    handleWalletImportKey({ args, keyKind: "viewing" });
     return;
   }
 
-  if (args.command === "wallet-import") {
-    assertWalletImportArgs(args);
-    handleWalletImport({ args });
+  if (args.command === "wallet-import-spending-key") {
+    assertWalletImportKeyArgs(args, "wallet-import-spending-key");
+    handleWalletImportKey({ args, keyKind: "spending" });
     return;
   }
 
@@ -2161,6 +2396,11 @@ async function handleDepositBridge({ args, network, provider }) {
   const bridgeVaultContext = await loadBridgeVaultContext({ provider, chainId: network.chainId });
   const amountInput = requireArg(args.amount, "--amount");
   const amount = parseTokenAmount(amountInput, Number(bridgeVaultContext.canonicalAssetDecimals));
+  await requireActionImpactAcknowledgement("account-deposit-bridge", args, {
+    l1Address: signer.address,
+    amountInput,
+    bridgeTokenVault: bridgeVaultContext.bridgeTokenVaultAddress,
+  });
   const bridgeTokenVault = new Contract(
     bridgeVaultContext.bridgeTokenVaultAddress,
     bridgeVaultContext.bridgeAbiManifest.contracts.bridgeTokenVault.abi,
@@ -2223,10 +2463,6 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
   const channelName = requireArg(args.channelName, "--channel-name");
   const signer = requireL1Signer(args, provider);
   const walletName = walletNameForChannelAndAddress(channelName, signer.address);
-  const walletSecret = resolveWalletSecretForName({
-    networkName: network.name,
-    walletName,
-  });
   const bridgeResources = loadBridgeResources({ chainId: network.chainId });
   const initialized = await syncChannelWorkspace({
     workspaceName: channelName,
@@ -2260,11 +2496,6 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
       provider,
     ),
   };
-  const l2Identity = await deriveParticipantIdentityFromSigner({
-    channelName,
-    walletSecret,
-    signer,
-  });
   const noteReceiveKeyMaterial = await deriveNoteReceiveKeyMaterial({
     signer,
     chainId: network.chainId,
@@ -2272,82 +2503,52 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     channelName,
     account: signer.address,
   });
-  const storageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
-  const leafIndex = deriveChannelTokenVaultLeafIndex(storageKey);
   const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
-
-  if (!registration.exists) {
-    const cleanup = removeLocalWalletArtifacts(walletName, context.workspace.network);
-    if (cleanup.removed) {
-      printJson({
-        action: "wallet recover-workspace",
-        status: "stale-wallet-removed",
-        wallet: walletName,
-        removedWalletDir: cleanup.removedWalletDir ? cleanup.walletDir : null,
-        removedWalletSecretFile: cleanup.removedWalletSecret ? cleanup.walletSecretFile : null,
-        walletSecretSource: resolvedWalletSecretSource(args),
-        walletSecretFile: resolvedWalletSecretFile(network.name, walletName),
-        workspace: context.workspaceName,
-        channelName: context.workspace.channelName,
-        channelId: context.workspace.channelId,
-        l1Address: signer.address,
-        l2Address: l2Identity.l2Address,
-        l2StorageKey: storageKey,
-        leafIndex: leafIndex.toString(),
-        reason: "The local wallet existed, but the L1 address is no longer registered in the channel.",
-        nextAction: buildRecoverWalletRemovedNextAction({
-          channelName,
-          networkName: network.name,
-          accountName: args.account,
-        }),
-      });
-      return;
-    }
-    expect(
-      false,
-      cliError(
-        CLI_ERROR_CODES.MISSING_CHANNEL_REGISTRATION,
-        `No channelTokenVault registration exists for ${signer.address}. Run channel join first.`,
-      ),
-    );
-  }
-  expect(
-    ethers.toBigInt(getAddress(registration.l2Address)) === ethers.toBigInt(getAddress(l2Identity.l2Address)),
-    "The existing channel registration L2 address does not match the derived L2 address.",
-  );
-  expect(
-    ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
-      === ethers.toBigInt(normalizeBytes32Hex(storageKey)),
-    "The existing channel registration key does not match the derived channelTokenVault key.",
-  );
+  const lifecycleEpoch = await resolveWalletLifecycleEpoch({
+    context,
+    provider,
+    l1Address: signer.address,
+    registration,
+  });
   expect(
-    ethers.toBigInt(registration.leafIndex) === ethers.toBigInt(leafIndex),
-    "The existing channel registration leaf index does not match the derived leaf index.",
+    lifecycleEpoch,
+    cliError(
+      CLI_ERROR_CODES.MISSING_CHANNEL_REGISTRATION,
+      `No channelTokenVault registration history exists for ${signer.address}. Run channel join first.`,
+    ),
   );
+  const registeredNoteReceivePubKey = lifecycleEpoch.noteReceivePubKey;
   expect(
-    ethers.toBigInt(normalizeBytes32Hex(registration.noteReceivePubKey.x))
+    ethers.toBigInt(normalizeBytes32Hex(registeredNoteReceivePubKey.x))
       === ethers.toBigInt(normalizeBytes32Hex(noteReceiveKeyMaterial.noteReceivePubKey.x)),
     "The existing note-receive public key X does not match the derived note-receive public key.",
   );
   expect(
-    Number(registration.noteReceivePubKey.yParity) === Number(noteReceiveKeyMaterial.noteReceivePubKey.yParity),
+    Number(registeredNoteReceivePubKey.yParity) === Number(noteReceiveKeyMaterial.noteReceivePubKey.yParity),
     "The existing note-receive public key parity does not match the derived note-receive public key.",
   );
-
-  const existingWallet = tryLoadRecoverableWallet({
-    walletName,
-    walletSecret,
-    signerAddress: signer.address,
-    signerPrivateKey: signer.privateKey,
-    l2Identity,
-    storageKey,
-    leafIndex,
-    rpcUrl,
-    channelContext: context,
-    noteReceiveKeyMaterial,
-  });
+  const l2Identity = {
+    l2PrivateKey: null,
+    l2PublicKey: null,
+    l2Address: getAddress(lifecycleEpoch.l2Address),
+  };
+  const storageKey = normalizeBytes32Hex(lifecycleEpoch.channelTokenVaultKey);
+
+  const walletDir = walletEpochPath(walletName, context.workspace.network, lifecycleEpoch.epochId);
+  const existingWallet = walletConfigExists(walletDir)
+    ? loadWalletFromDir({
+      walletName,
+      networkName: context.workspace.network,
+      walletDir,
+    })
+    : null;
 
   if (existingWallet) {
+    existingWallet.wallet.noteReceivePrivateKey = noteReceiveKeyMaterial.privateKey;
+    applyWalletLifecycleEpoch(existingWallet.wallet, lifecycleEpoch);
+    persistWalletKeys(existingWallet);
+    persistWallet(existingWallet);
+    persistWalletIndexForContext(existingWallet);
     const { recoveredDeliveryState } = await recoverWalletReceivedNotes({
       walletContext: existingWallet,
       context,
@@ -2362,15 +2563,16 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
       status: "already-recovered",
       wallet: walletName,
       walletDir: existingWallet.walletDir,
-      walletSecretSource: resolvedWalletSecretSource(args),
-      walletSecretFile: resolvedWalletSecretFile(network.name, walletName),
       workspace: context.workspaceName,
       channelName: context.workspace.channelName,
       channelId: context.workspace.channelId,
       l1Address: signer.address,
       l2Address: l2Identity.l2Address,
       l2StorageKey: storageKey,
-      leafIndex: registration.leafIndex.toString(),
+      leafIndex: lifecycleEpoch.leafIndex.toString(),
+      epochId: lifecycleEpoch.epochId,
+      lifecycleStatus: lifecycleEpoch.lifecycleStatus,
+      exitedAtTxHash: lifecycleEpoch.exitedAtTxHash,
       noteReceivePubKey: noteReceiveKeyMaterial.noteReceivePubKey,
       l2Nonce: existingWallet.wallet.l2Nonce,
       recoveredFromLogs: recoveredDeliveryState.importedNotes,
@@ -2380,17 +2582,16 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     return;
   }
 
-  fs.rmSync(walletPath(walletName, context.workspace.network), { recursive: true, force: true });
-
   const walletContext = ensureWallet({
     channelContext: context,
     signerAddress: signer.address,
     signerPrivateKey: signer.privateKey,
     l2Identity,
-    walletSecret,
+    walletSecret: noteReceiveKeyMaterial.privateKey,
     storageKey,
-    leafIndex: registration.leafIndex,
+    leafIndex: lifecycleEpoch.leafIndex,
     noteReceiveKeyMaterial,
+    lifecycleEpoch,
     rpcUrl,
   });
   walletContext.wallet.l2Nonce = 0;
@@ -2411,15 +2612,16 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     status: "recovered",
     wallet: walletName,
     walletDir: walletContext.walletDir,
-    walletSecretSource: resolvedWalletSecretSource(args),
-    walletSecretFile: resolvedWalletSecretFile(network.name, walletName),
     workspace: context.workspaceName,
     channelName: context.workspace.channelName,
     channelId: context.workspace.channelId,
     l1Address: signer.address,
     l2Address: l2Identity.l2Address,
     l2StorageKey: storageKey,
-    leafIndex: registration.leafIndex.toString(),
+    leafIndex: lifecycleEpoch.leafIndex.toString(),
+    epochId: lifecycleEpoch.epochId,
+    lifecycleStatus: lifecycleEpoch.lifecycleStatus,
+    exitedAtTxHash: lifecycleEpoch.exitedAtTxHash,
     noteReceivePubKey: noteReceiveKeyMaterial.noteReceivePubKey,
     l2Nonce: walletContext.wallet.l2Nonce,
     recoveredFromLogs: recoveredDeliveryState.importedNotes,
@@ -2428,161 +2630,6 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
   });
 }
 
-function tryLoadRecoverableWallet({
-  walletName,
-  walletSecret,
-  signerAddress,
-  signerPrivateKey,
-  l2Identity,
-  storageKey,
-  leafIndex,
-  rpcUrl,
-  channelContext,
-  noteReceiveKeyMaterial,
-}) {
-  const walletDir = walletPath(walletName, channelContext.workspace.network);
-  if (!walletConfigExists(walletDir)) {
-    return null;
-  }
-
-  try {
-    const walletMetadata = loadWalletMetadata(walletName, channelContext.workspace.network);
-    const walletContext = loadWallet(walletName, walletSecret, channelContext.workspace.network);
-    assertWalletMatchesMetadata(walletContext, walletMetadata);
-    assertExistingRecoverableWallet({
-      walletContext,
-      walletMetadata,
-      signerAddress,
-      signerPrivateKey,
-      l2Identity,
-      storageKey,
-      leafIndex,
-      rpcUrl,
-      channelContext,
-      noteReceiveKeyMaterial,
-    });
-    return walletContext;
-  } catch {
-    return null;
-  }
-}
-
-function assertExistingRecoverableWallet({
-  walletContext,
-  walletMetadata,
-  signerAddress,
-  signerPrivateKey,
-  l2Identity,
-  storageKey,
-  leafIndex,
-  rpcUrl,
-  channelContext,
-  noteReceiveKeyMaterial,
-}) {
-  const wallet = walletContext.wallet;
-  expect(
-    walletMetadata.network === channelContext.workspace.network,
-    `Wallet ${walletContext.walletName} metadata network does not match the requested network.`,
-  );
-  expect(
-    walletMetadata.channelName === channelContext.workspace.channelName,
-    `Wallet ${walletContext.walletName} metadata channel does not match the requested channel.`,
-  );
-  expect(
-    walletMetadata.rpcUrl === rpcUrl,
-    `Wallet ${walletContext.walletName} metadata rpcUrl does not match the requested runtime RPC URL.`,
-  );
-  expect(
-    normalizePrivateKey(wallet.l1PrivateKey) === normalizePrivateKey(signerPrivateKey),
-    `Wallet ${walletContext.walletName} does not decrypt to the requested L1 private key.`,
-  );
-  expect(
-    ethers.toBigInt(getAddress(wallet.l1Address)) === ethers.toBigInt(getAddress(signerAddress)),
-    `Wallet ${walletContext.walletName} L1 address does not match the requested signer.`,
-  );
-  expect(
-    ethers.toBigInt(getAddress(wallet.l2Address)) === ethers.toBigInt(getAddress(l2Identity.l2Address)),
-    `Wallet ${walletContext.walletName} L2 address does not match the derived channel identity.`,
-  );
-  expect(
-    ethers.toBigInt(normalizeBytes32Hex(wallet.l2StorageKey))
-      === ethers.toBigInt(normalizeBytes32Hex(storageKey)),
-    `Wallet ${walletContext.walletName} storage key does not match the derived registration key.`,
-  );
-  expect(
-    ethers.toBigInt(wallet.leafIndex) === ethers.toBigInt(leafIndex),
-    `Wallet ${walletContext.walletName} leaf index does not match the derived registration leaf index.`,
-  );
-  expect(
-    ethers.toBigInt(wallet.channelId) === ethers.toBigInt(channelContext.workspace.channelId),
-    `Wallet ${walletContext.walletName} channel ID does not match the requested channel.`,
-  );
-  expect(
-    wallet.channelName === channelContext.workspace.channelName,
-    `Wallet ${walletContext.walletName} channel name does not match the requested channel.`,
-  );
-  expect(
-    wallet.network === channelContext.workspace.network,
-    `Wallet ${walletContext.walletName} network does not match the requested network.`,
-  );
-  expect(
-    wallet.rpcUrl === rpcUrl,
-    `Wallet ${walletContext.walletName} rpcUrl does not match the requested runtime RPC URL.`,
-  );
-  expect(
-    ethers.toBigInt(getAddress(wallet.channelManager)) === ethers.toBigInt(getAddress(channelContext.workspace.channelManager)),
-    `Wallet ${walletContext.walletName} channel manager does not match the recovered workspace.`,
-  );
-  expect(
-    ethers.toBigInt(getAddress(wallet.bridgeTokenVault)) === ethers.toBigInt(getAddress(channelContext.workspace.bridgeTokenVault)),
-    `Wallet ${walletContext.walletName} bridge token vault does not match the recovered workspace.`,
-  );
-  expect(
-    ethers.toBigInt(getAddress(wallet.controller)) === ethers.toBigInt(getAddress(channelContext.workspace.controller)),
-    `Wallet ${walletContext.walletName} controller does not match the recovered workspace.`,
-  );
-  expect(
-    ethers.toBigInt(getAddress(wallet.l2AccountingVault))
-      === ethers.toBigInt(getAddress(channelContext.workspace.l2AccountingVault)),
-    `Wallet ${walletContext.walletName} L2 accounting vault does not match the recovered workspace.`,
-  );
-  expect(
-    ethers.toBigInt(normalizeBytes32Hex(wallet.noteReceivePubKeyX))
-      === ethers.toBigInt(normalizeBytes32Hex(noteReceiveKeyMaterial.noteReceivePubKey.x)),
-    `Wallet ${walletContext.walletName} note-receive public key X does not match the derived key.`,
-  );
-  expect(
-    Number(wallet.noteReceivePubKeyYParity) === Number(noteReceiveKeyMaterial.noteReceivePubKey.yParity),
-    `Wallet ${walletContext.walletName} note-receive public key parity does not match the derived key.`,
-  );
-}
-
-function removeLocalWalletArtifacts(walletName, networkName) {
-  const walletDir = walletPath(walletName, networkName);
-  const walletSecretFile = walletSecretPath(networkName, walletName);
-  const walletSecretDir = path.dirname(walletSecretFile);
-  const removedWalletDir = fs.existsSync(walletDir);
-  const removedWalletSecret = fs.existsSync(walletSecretFile) || fs.existsSync(walletSecretDir);
-  if (removedWalletDir) {
-    fs.rmSync(walletDir, { recursive: true, force: true });
-  }
-  if (removedWalletSecret) {
-    fs.rmSync(walletSecretDir, { recursive: true, force: true });
-  }
-  return {
-    walletDir,
-    walletSecretFile,
-    removed: removedWalletDir || removedWalletSecret,
-    removedWalletDir,
-    removedWalletSecret,
-  };
-}
-
-function buildRecoverWalletRemovedNextAction({ channelName, networkName, accountName }) {
-  const account = accountName ? String(accountName) : "<ACCOUNT>";
-  return `channel join --channel-name ${channelName} --network ${networkName} --account ${account} --wallet-secret-path <PATH>`;
-}
-
 async function handleInstallZkEvm({ args }) {
   const selectedVersions = await resolvePrivateStateInstallRuntimeVersions(args);
   const tokamakCliRuntime = await installTokamakCliRuntimeForPrivateState({
@@ -2880,6 +2927,68 @@ async function handleDoctor({ args }) {
   }
 }
 
+function handleInvestigator() {
+  const htmlPath = resolveInvestigatorIndexPath();
+  const fileUrl = pathToFileURL(htmlPath).href;
+  const browser = openFileInDefaultBrowser(fileUrl);
+  printJson({
+    action: "investigator",
+    htmlPath,
+    fileUrl,
+    browserOpened: browser.opened,
+    browserOpenCommand: browser.command,
+    browserOpenError: browser.error,
+    nextSteps: [
+      "Create a raw evidence ZIP with wallet get-notes --export-evidence and --acknowledge-full-note-plaintext-export.",
+      "Load the raw evidence ZIP in the browser investigator.",
+      "Filter the raw bundle and export a user-consent disclosure ZIP.",
+      "Do not submit the raw evidence ZIP unless full wallet-history disclosure is intended.",
+    ],
+  });
+}
+
+function resolveInvestigatorIndexPath() {
+  const candidates = [
+    path.join(privateStateCliPackageRoot, "investigator", "index.html"),
+    path.resolve(privateStateCliPackageRoot, "..", "investigator", "index.html"),
+  ];
+  const htmlPath = candidates.find((candidate) => fs.existsSync(candidate));
+  if (!htmlPath) {
+    throw new Error(
+      [
+        "Missing investigator HTML asset.",
+        `Checked: ${candidates.join(", ")}`,
+        "Reinstall the private-state CLI package or run from a complete repository checkout.",
+      ].join(" "),
+    );
+  }
+  return htmlPath;
+}
+
+function openFileInDefaultBrowser(fileUrl) {
+  const opener = defaultBrowserOpenCommand(fileUrl);
+  const result = spawnSync(opener.command, opener.args, {
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  return {
+    command: [opener.command, ...opener.args].join(" "),
+    opened: result.status === 0,
+    status: result.status,
+    error: result.error?.message ?? null,
+  };
+}
+
+function defaultBrowserOpenCommand(fileUrl) {
+  if (process.platform === "darwin") {
+    return { command: "open", args: [fileUrl] };
+  }
+  if (process.platform === "win32") {
+    return { command: "cmd", args: ["/c", "start", "", fileUrl] };
+  }
+  return { command: "xdg-open", args: [fileUrl] };
+}
+
 async function handleTransactionFees({ network, provider, rpcUrl }) {
   const feeAsset = loadTransactionFeeAsset();
   const feeData = await provider.getFeeData();
@@ -3079,24 +3188,19 @@ function handleListLocalWallets({ args }) {
   });
 }
 
-function handleWalletExport({ args }) {
+function handleWalletExportBackup({ args }) {
   const outputPath = path.resolve(String(requireArg(args.output, "--output")));
   expect(!fs.existsSync(outputPath), `Export output already exists: ${outputPath}.`);
   ensureDir(path.dirname(outputPath));
 
-  const includeNotes = args.includeNotes === true;
-  const wallets = args.all === true
-    ? listLocalWallets({ networkFilter: "mainnet" }).filter((wallet) => wallet.hasEncryptedWallet)
-    : [resolveExportWalletInfo({
-      networkName: requireNetworkName(args),
-      walletName: requireWalletName(args),
-    })];
+  const wallets = [resolveExportWalletInfo({
+    networkName: requireNetworkName(args),
+    walletName: requireWalletName(args),
+  })];
 
   expect(
     wallets.length > 0,
-    args.all === true
-      ? "No local mainnet wallets are available to export."
-      : "No local wallet is available to export.",
+    "No local wallet is available to export.",
   );
 
   const archive = new AdmZip();
@@ -3109,7 +3213,7 @@ function handleWalletExport({ args }) {
       channelName: normalized.channelName,
       wallet: normalized.wallet,
     });
-    for (const filePath of walletExportFilePaths(normalized, { includeNotes })) {
+    for (const filePath of walletBackupExportFilePaths(normalized)) {
       const archivePath = archivePathForLocalCliFile(filePath);
       if (!files.has(archivePath)) {
         files.set(archivePath, filePath);
@@ -3118,44 +3222,65 @@ function handleWalletExport({ args }) {
   }
 
   const manifest = {
-    format: WALLET_EXPORT_FORMAT,
+    format: WALLET_BACKUP_EXPORT_FORMAT,
     formatVersion: WALLET_EXPORT_FORMAT_VERSION,
     createdAt: new Date().toISOString(),
     cliPackage: PRIVATE_STATE_CLI_PACKAGE_NAME,
     cliVersion: privateStateCliPackageJson.version,
-    exportMode: args.all === true ? "all-mainnet" : "single-wallet",
-    includeNotes,
-    notes: includeNotes
-      ? [
-        "Includes the channel workspace cache required for immediate wallet command use when the cache is still chain-aligned.",
-      ]
-      : [
-        "Includes wallet identity, encrypted wallet state, metadata, and wallet-local secret only.",
-        "Run channel recover-workspace after import before wallet commands need channel state.",
-      ],
+    exportMode: "backup",
+    notes: [
+      "Includes wallet note-tracking metadata, public key metadata, and channel workspace cache.",
+      "Excludes spending keys, viewing keys, key derivation material, owner, value, and salt.",
+    ],
     wallets: exportedWallets,
     files: [...files.keys()].sort(),
   };
 
   archive.addFile("manifest.json", Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, "utf8"));
   for (const archivePath of manifest.files) {
-    archive.addFile(archivePath, fs.readFileSync(files.get(archivePath)));
+    const filePath = files.get(archivePath);
+    validateBackupExportFile(filePath);
+    archive.addFile(archivePath, fs.readFileSync(filePath));
   }
   archive.writeZip(outputPath);
   protectSecretFile(outputPath, "wallet export ZIP");
 
   printJson({
-    action: "wallet export",
+    action: "wallet export backup",
     output: outputPath,
     exportMode: manifest.exportMode,
-    includeNotes,
     walletCount: exportedWallets.length,
     fileCount: manifest.files.length,
     wallets: exportedWallets.map(({ network, channelName, wallet }) => ({ network, channelName, wallet })),
   });
 }
 
-function handleWalletImport({ args }) {
+function handleWalletExportKey({ args, keyKind }) {
+  const outputPath = path.resolve(String(requireArg(args.output, "--output")));
+  expect(!fs.existsSync(outputPath), `Export output already exists: ${outputPath}.`);
+  ensureDir(path.dirname(outputPath));
+  const networkName = requireNetworkName(args);
+  const walletName = requireWalletName(args);
+  const wallet = loadWallet(walletName, networkName);
+  const secretPath = keyKind === "spending"
+    ? walletSpendingKeySecretPath(networkName, walletName)
+    : walletViewingKeySecretPath(networkName, walletName);
+  expect(fs.existsSync(secretPath), `Wallet ${walletName} is missing its ${keyKind} key.`);
+  const payload = JSON.parse(readSecretFile(secretPath, `${keyKind} key`));
+  validateWalletKeyPayload(payload, keyKind);
+  fs.writeFileSync(outputPath, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  protectSecretFile(outputPath, `${keyKind} key export`);
+  printJson({
+    action: `wallet export ${keyKind}-key`,
+    wallet: wallet.walletName,
+    network: networkName,
+    output: outputPath,
+    keyKind,
+    metadata: payload.metadata,
+  });
+}
+
+function handleWalletImportBackup({ args }) {
   const inputPath = path.resolve(String(requireArg(args.input, "--input")));
   expect(fs.existsSync(inputPath), `Import ZIP does not exist: ${inputPath}.`);
 
@@ -3191,16 +3316,55 @@ function handleWalletImport({ args }) {
   commitWalletImportFiles({ targetRoot, plannedWrites });
 
   printJson({
-    action: "wallet import",
+    action: "wallet import backup",
     input: inputPath,
     exportMode: manifest.exportMode,
-    includeNotes: Boolean(manifest.includeNotes),
     walletCount: manifest.wallets.length,
     fileCount: plannedWrites.length,
     wallets: manifest.wallets.map(({ network, channelName, wallet }) => ({ network, channelName, wallet })),
-    nextStep: manifest.includeNotes
-      ? "Wallet commands can run immediately if the imported channel workspace cache is still chain-aligned."
-      : "Run channel recover-workspace before wallet commands need channel state.",
+    nextStep: "Import viewing-key and spending-key files separately when the wallet needs those capabilities.",
+  });
+}
+
+function handleWalletImportKey({ args, keyKind }) {
+  const inputPath = path.resolve(String(requireArg(args.input, "--input")));
+  expect(fs.existsSync(inputPath), `Key import file does not exist: ${inputPath}.`);
+  const payload = JSON.parse(readImportSecretSourceFile(inputPath, "--input"));
+  validateWalletKeyPayload(payload, keyKind);
+  const metadata = payload.metadata;
+  const networkName = requireNetworkName({ network: metadata.network });
+  const walletName = requireWalletName({ wallet: metadata.wallet });
+  const targetPath = keyKind === "spending"
+    ? walletSpendingKeySecretPath(networkName, walletName)
+    : walletViewingKeySecretPath(networkName, walletName);
+  expect(!fs.existsSync(targetPath), `Refusing to overwrite existing ${keyKind} key: ${targetPath}.`);
+  writeSecretFile(targetPath, JSON.stringify(payload, null, 2));
+  const walletRoot = walletRootPath(walletName, networkName);
+  const walletIndex = fs.existsSync(walletRoot)
+    ? requireWalletIndex({ walletRoot, walletName, networkName })
+    : null;
+  const selectedEpoch = walletIndex ? selectedWalletEpoch(walletIndex, walletName, networkName) : null;
+  if (selectedEpoch) {
+    const walletDir = walletEpochPathFromRoot(walletRoot, selectedEpoch.epochId);
+    const metadataPath = keyKind === "spending"
+      ? walletSpendingKeyMetadataPath(walletDir)
+      : walletViewingKeyMetadataPath(walletDir);
+    if (fs.existsSync(metadataPath)) {
+      expect(
+        JSON.stringify(readJson(metadataPath)) === JSON.stringify(normalizeCliOutput(metadata)),
+        `Refusing to overwrite mismatched ${keyKind} key metadata: ${metadataPath}.`,
+      );
+    } else {
+      writeJson(metadataPath, metadata);
+    }
+  }
+  printJson({
+    action: `wallet import ${keyKind}-key`,
+    input: inputPath,
+    network: networkName,
+    wallet: walletName,
+    keyKind,
+    metadata,
   });
 }
 
@@ -3217,17 +3381,58 @@ function readWalletImportArchive(inputPath) {
   }
 }
 
-function commitWalletImportFiles({ targetRoot, plannedWrites }) {
-  const stagingRoot = fs.mkdtempSync(path.join(targetRoot, ".wallet-import-"));
-  const committedPaths = [];
-  try {
-    for (const write of plannedWrites) {
-      write.stagingPath = path.resolve(stagingRoot, write.archivePath);
-      expectPathWithinRoot(write.stagingPath, stagingRoot, `Unsafe staging target for ${write.archivePath}.`);
-      ensureDir(path.dirname(write.stagingPath));
-      fs.writeFileSync(write.stagingPath, write.data);
-      applyImportedWalletFileMode(write.archivePath, write.stagingPath);
-    }
+function validateBackupExportFile(filePath) {
+  if (path.basename(filePath) !== "wallet-notes.metadata.json") {
+    return;
+  }
+  const metadata = readJson(filePath);
+  const forbidden = findForbiddenBackupMetadataPaths(metadata);
+  expect(
+    forbidden.length === 0,
+    `wallet export backup refuses to export plaintext note secrets or key material: ${forbidden.join(", ")}.`,
+  );
+}
+
+function findForbiddenBackupMetadataPaths(value, pathParts = []) {
+  const forbiddenNames = new Set([
+    "owner",
+    "value",
+    "salt",
+    "l1PrivateKey",
+    "l2PrivateKey",
+    "noteReceivePrivateKey",
+    "walletSecret",
+    "seedSignature",
+  ]);
+  if (Array.isArray(value)) {
+    return value.flatMap((entry, index) => findForbiddenBackupMetadataPaths(entry, [...pathParts, String(index)]));
+  }
+  if (!value || typeof value !== "object") {
+    return [];
+  }
+  const found = [];
+  for (const [key, entry] of Object.entries(value)) {
+    const nextPath = [...pathParts, key];
+    if (forbiddenNames.has(key) && entry !== undefined && entry !== null) {
+      found.push(nextPath.join("."));
+      continue;
+    }
+    found.push(...findForbiddenBackupMetadataPaths(entry, nextPath));
+  }
+  return found;
+}
+
+function commitWalletImportFiles({ targetRoot, plannedWrites }) {
+  const stagingRoot = fs.mkdtempSync(path.join(targetRoot, ".wallet-import-"));
+  const committedPaths = [];
+  try {
+    for (const write of plannedWrites) {
+      write.stagingPath = path.resolve(stagingRoot, write.archivePath);
+      expectPathWithinRoot(write.stagingPath, stagingRoot, `Unsafe staging target for ${write.archivePath}.`);
+      ensureDir(path.dirname(write.stagingPath));
+      fs.writeFileSync(write.stagingPath, write.data);
+      applyImportedWalletFileMode(write.archivePath, write.stagingPath);
+    }
 
     for (const write of plannedWrites) {
       expect(!fs.existsSync(write.targetPath), `Refusing to overwrite existing file: ${write.targetPath}.`);
@@ -3609,15 +3814,25 @@ async function inspectGuideAccount({ account, networkName, network, provider, ar
 }
 
 async function inspectGuideWallet({ walletName, networkName, provider, artifactsInstalled }) {
-  const walletDir = walletPath(walletName, networkName);
+  let walletDir = walletRootPath(walletName, networkName);
+  let workspaceError = null;
+  try {
+    walletDir = selectedWalletEpochDir(walletName, networkName);
+  } catch (error) {
+    workspaceError = error.message;
+  }
+  const viewingKeyFile = walletViewingKeySecretPath(networkName, walletName);
+  const spendingKeyFile = walletSpendingKeySecretPath(networkName, walletName);
   const result = {
     wallet: walletName,
     network: networkName,
     walletDir,
     exists: walletConfigExists(walletDir),
-    metadataExists: fs.existsSync(walletMetadataPath(walletDir)),
-    secretFile: walletSecretPath(networkName, walletName),
-    secretFileExists: fs.existsSync(walletSecretPath(networkName, walletName)),
+    metadataExists: fs.existsSync(walletNotesMetadataPath(walletDir)),
+    viewingKeyFile,
+    viewingKeyFileExists: fs.existsSync(viewingKeyFile),
+    spendingKeyFile,
+    spendingKeyFileExists: fs.existsSync(spendingKeyFile),
     channelName: null,
     l1Address: null,
     l2Address: null,
@@ -3628,14 +3843,14 @@ async function inspectGuideWallet({ walletName, networkName, provider, artifacts
     unusedNoteBalanceBaseUnits: null,
     unusedNoteBalanceTokens: null,
     spentNoteCount: null,
-    error: null,
+    error: workspaceError,
   };
-  if (!result.exists) {
+  if (workspaceError || !result.exists) {
     return result;
   }
 
   try {
-    const walletContext = loadWallet(walletName, resolveWalletDefaultSecret(networkName, walletName), networkName);
+    const walletContext = loadWallet(walletName, networkName);
     const walletMetadata = loadWalletMetadata(walletName, networkName);
     assertWalletMatchesMetadata(walletContext, walletMetadata);
     result.channelName = walletContext.wallet.channelName;
@@ -3643,10 +3858,13 @@ async function inspectGuideWallet({ walletName, networkName, provider, artifacts
     result.l2Address = getAddress(walletContext.wallet.l2Address);
     result.unusedNoteCount = Object.keys(walletContext.wallet.notes.unused).length;
     result.spentNoteCount = Object.keys(walletContext.wallet.notes.spent).length;
-    const unusedNoteBalance = Object.values(walletContext.wallet.notes.unused)
-      .reduce((sum, note) => sum + ethers.toBigInt(note.value), 0n);
-    result.unusedNoteBalanceBaseUnits = unusedNoteBalance.toString();
-    result.unusedNoteBalanceTokens = ethers.formatUnits(unusedNoteBalance, Number(walletContext.wallet.canonicalAssetDecimals));
+    const unusedValues = Object.values(walletContext.wallet.notes.unused).map((note) => note.value);
+    if (unusedValues.every((value) => value !== null)) {
+      const unusedNoteBalance = Object.values(walletContext.wallet.notes.unused)
+        .reduce((sum, note) => sum + ethers.toBigInt(note.value), 0n);
+      result.unusedNoteBalanceBaseUnits = unusedNoteBalance.toString();
+      result.unusedNoteBalanceTokens = ethers.formatUnits(unusedNoteBalance, Number(walletContext.wallet.canonicalAssetDecimals));
+    }
 
     if (provider && artifactsInstalled && walletChannelWorkspaceIsReady(walletContext)) {
       const context = await loadWorkspaceContext(walletContext.wallet.channelName, networkName, provider);
@@ -3717,7 +3935,7 @@ function applyGuideNextAction(guide) {
     const channelName = guide.selectors.channelName ?? guide.state.channel?.channelName ?? "<CHANNEL>";
     const account = guide.selectors.account ?? "<ACCOUNT>";
     setGuideNextAction(guide, {
-      command: `channel join --channel-name ${channelName} --network ${guide.selectors.network} --account ${account} --wallet-secret-path <PATH>`,
+      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.",
     });
     return;
@@ -3726,7 +3944,7 @@ function applyGuideNextAction(guide) {
     const channelName = guide.state.wallet.channelName ?? guide.selectors.channelName ?? "<CHANNEL>";
     const account = guide.selectors.account ?? "<ACCOUNT>";
     setGuideNextAction(guide, {
-      command: `channel join --channel-name ${channelName} --network ${guide.selectors.network} --account ${account} --wallet-secret-path <PATH>`,
+      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.",
     });
     return;
@@ -3743,32 +3961,32 @@ function applyGuideNextAction(guide) {
   if (guide.state.wallet?.exists && bridgeBalance === 0n && (channelBalance === null || channelBalance === 0n) && unusedNotes === 0) {
     const account = guide.selectors.account ?? "<ACCOUNT>";
     setGuideNextAction(guide, {
-      command: `account deposit-bridge --amount <TOKENS> --network ${guide.selectors.network} --account ${account}`,
+      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.",
     });
     return;
   }
   if (guide.state.wallet?.exists && bridgeBalance !== null && bridgeBalance > 0n && channelBalance === 0n) {
     setGuideNextAction(guide, {
-      command: `wallet deposit-channel --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --amount <TOKENS>`,
+      command: `wallet deposit-channel --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --amount <TOKENS> --acknowledge-action-impact`,
       why: "The account has funds in the shared bridge vault, but the wallet has no channel L2 accounting balance.",
     });
     return;
   }
   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> [--tx-submitter <ACCOUNT>]`,
+      command: `wallet mint-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --amounts <A,B> --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> [--tx-submitter <ACCOUNT>]`,
+      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>]`,
       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> [--tx-submitter <ACCOUNT>]`,
+        `wallet redeem-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID> --acknowledge-action-impact [--tx-submitter <ACCOUNT>]`,
       ],
     });
     return;
@@ -3869,6 +4087,7 @@ async function handleWalletGetMeta({ args, provider }) {
   printJson({
     action: "wallet get-meta",
     wallet: wallet.walletName,
+    ...walletLifecycleMetadata(wallet.wallet),
     network: walletMetadata.network,
     channelName: walletMetadata.channelName,
     l1Address: signer.address,
@@ -3879,6 +4098,12 @@ async function handleWalletGetMeta({ args, provider }) {
     registeredL2Address: registration.exists ? getAddress(registration.l2Address) : null,
     registeredL2StorageKey: registration.exists ? normalizeBytes32Hex(registration.channelTokenVaultKey) : null,
     registeredLeafIndex: registration.exists ? registration.leafIndex.toString() : null,
+    registeredNoteReceivePubKey: registration.exists
+      ? {
+        x: normalizeBytes32Hex(registration.noteReceivePubKey.x),
+        yParity: Number(registration.noteReceivePubKey.yParity),
+      }
+      : null,
   });
 }
 
@@ -3924,7 +4149,8 @@ async function loadWalletChannelRegistrationState({
   provider,
   requireRegistration = false,
 }) {
-  const { signer, l2Identity } = restoreWalletParticipant(walletContext, provider);
+  const signer = requireWalletOwnerSigner(walletContext, provider);
+  const l2Identity = restoreParticipantIdentityFromWallet(walletContext.wallet);
   const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
   const expectedStorageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
   const matchesWallet = registration.exists
@@ -3955,6 +4181,156 @@ async function loadWalletChannelRegistrationState({
   };
 }
 
+async function resolveWalletLifecycleEpoch({
+  context,
+  provider,
+  l1Address,
+  registration = null,
+}) {
+  const epochs = await readWalletLifecycleEpochs({
+    context,
+    provider,
+    l1Address,
+  });
+  if (epochs.length === 0 && registration?.exists) {
+    const block = await provider.getBlock("latest").catch(() => null);
+    return {
+      epochId: `join-registered-${String(registration.joinedAt)}-${String(registration.leafIndex)}`,
+      lifecycleStatus: "active",
+      joinedAtTxHash: null,
+      joinedAtBlockNumber: null,
+      joinedAtLogIndex: null,
+      joinedAtBlockTimestamp: Number(registration.joinedAt),
+      joinedAtBlockTimestampIso: Number(registration.joinedAt) > 0
+        ? new Date(Number(registration.joinedAt) * 1000).toISOString()
+        : null,
+      exitedAtTxHash: null,
+      exitedAtBlockNumber: null,
+      exitedAtLogIndex: null,
+      exitedAtBlockTimestamp: null,
+      exitedAtBlockTimestampIso: null,
+      l2Address: getAddress(registration.l2Address),
+      channelTokenVaultKey: normalizeBytes32Hex(registration.channelTokenVaultKey),
+      leafIndex: registration.leafIndex,
+      noteReceivePubKey: {
+        x: normalizeBytes32Hex(registration.noteReceivePubKey.x),
+        yParity: Number(registration.noteReceivePubKey.yParity),
+      },
+      observedAtBlockNumber: block?.number ?? null,
+    };
+  }
+  if (registration?.exists) {
+    const active = [...epochs].reverse().find((epoch) => (
+      epoch.lifecycleStatus === "active"
+      && ethers.toBigInt(getAddress(epoch.l2Address)) === ethers.toBigInt(getAddress(registration.l2Address))
+      && ethers.toBigInt(normalizeBytes32Hex(epoch.channelTokenVaultKey))
+        === ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
+    ));
+    if (active) {
+      return active;
+    }
+  }
+  return epochs[epochs.length - 1] ?? null;
+}
+
+async function readWalletLifecycleEpochs({ context, provider, l1Address }) {
+  const fromBlock = Number(context.workspace.genesisBlockNumber ?? 0);
+  const [registeredLogs, exitedLogs] = await Promise.all([
+    context.channelManager.queryFilter(
+      context.channelManager.filters.ChannelTokenVaultIdentityRegistered(l1Address),
+      fromBlock,
+      "latest",
+    ),
+    context.channelManager.queryFilter(
+      context.channelManager.filters.ChannelTokenVaultIdentityExited(l1Address),
+      fromBlock,
+      "latest",
+    ),
+  ]);
+  const exits = await Promise.all(exitedLogs.map((log) => walletExitFromLog({ log, provider })));
+  const epochs = [];
+  for (const log of registeredLogs.sort(compareLogsByPosition)) {
+    const registered = await walletEpochFromRegisteredLog({ log, provider });
+    const exit = exits.find((entry) => (
+      compareLogPosition(entry, registered) > 0
+      && ethers.toBigInt(entry.leafIndex) === ethers.toBigInt(registered.leafIndex)
+      && !epochs.some((epoch) => epoch.exitedAtTxHash === entry.exitedAtTxHash)
+    ));
+    if (exit) {
+      epochs.push({
+        ...registered,
+        lifecycleStatus: "exited",
+        exitedAtTxHash: exit.exitedAtTxHash,
+        exitedAtBlockNumber: exit.exitedAtBlockNumber,
+        exitedAtLogIndex: exit.exitedAtLogIndex,
+        exitedAtBlockTimestamp: exit.exitedAtBlockTimestamp,
+        exitedAtBlockTimestampIso: exit.exitedAtBlockTimestampIso,
+      });
+    } else {
+      epochs.push(registered);
+    }
+  }
+  return epochs.sort(compareWalletEpochs);
+}
+
+async function walletEpochFromRegisteredLog({ log, provider }) {
+  const block = await provider.getBlock(log.blockNumber).catch(() => null);
+  const args = log.args;
+  return {
+    epochId: walletEpochIdFromLog(log),
+    lifecycleStatus: "active",
+    joinedAtTxHash: log.transactionHash,
+    joinedAtBlockNumber: log.blockNumber,
+    joinedAtLogIndex: log.index ?? log.logIndex ?? null,
+    joinedAtBlockTimestamp: block?.timestamp ?? Number(args.joinedAt ?? 0) ?? null,
+    joinedAtBlockTimestampIso: block?.timestamp
+      ? new Date(Number(block.timestamp) * 1000).toISOString()
+      : Number(args.joinedAt ?? 0) > 0
+        ? new Date(Number(args.joinedAt) * 1000).toISOString()
+        : null,
+    exitedAtTxHash: null,
+    exitedAtBlockNumber: null,
+    exitedAtLogIndex: null,
+    exitedAtBlockTimestamp: null,
+    exitedAtBlockTimestampIso: null,
+    l2Address: getAddress(args.l2Address),
+    channelTokenVaultKey: normalizeBytes32Hex(args.channelTokenVaultKey),
+    leafIndex: args.leafIndex,
+    noteReceivePubKey: {
+      x: normalizeBytes32Hex(args.noteReceivePubKeyX),
+      yParity: Number(args.noteReceivePubKeyYParity),
+    },
+  };
+}
+
+async function walletExitFromLog({ log, provider }) {
+  const block = await provider.getBlock(log.blockNumber).catch(() => null);
+  return {
+    exitedAtTxHash: log.transactionHash,
+    exitedAtBlockNumber: log.blockNumber,
+    exitedAtLogIndex: log.index ?? log.logIndex ?? null,
+    exitedAtBlockTimestamp: block?.timestamp ?? null,
+    exitedAtBlockTimestampIso: block?.timestamp ? new Date(Number(block.timestamp) * 1000).toISOString() : null,
+    leafIndex: log.args.leafIndex,
+  };
+}
+
+function walletEpochIdFromLog(log) {
+  return `join-${String(log.transactionHash).toLowerCase()}-${Number(log.index ?? log.logIndex ?? 0)}`;
+}
+
+function compareLogPosition(left, right) {
+  return Number(left.exitedAtBlockNumber ?? left.blockNumber ?? 0) - Number(right.joinedAtBlockNumber ?? right.blockNumber ?? 0)
+    || Number((left.exitedAtLogIndex ?? left.index ?? left.logIndex) ?? 0)
+      - Number((right.joinedAtLogIndex ?? right.index ?? right.logIndex) ?? 0);
+}
+
+function compareWalletEpochs(left, right) {
+  return Number(left.joinedAtBlockNumber ?? 0) - Number(right.joinedAtBlockNumber ?? 0)
+    || Number(left.joinedAtLogIndex ?? 0) - Number(right.joinedAtLogIndex ?? 0)
+    || String(left.epochId).localeCompare(String(right.epochId));
+}
+
 async function handleWalletGetChannelFund({ args, provider }) {
   const { wallet, walletMetadata } = loadUnlockedWalletWithMetadata(args);
   const {
@@ -4025,13 +4401,9 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
   const storageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
   const leafIndex = deriveChannelTokenVaultLeafIndex(storageKey);
 
-  const resolvedLeafIndex = leafIndex;
   let approveReceipt = null;
   let receipt = null;
-  let joinToll = 0n;
-  let status = null;
-
-  joinToll = ethers.toBigInt(await context.channelManager.joinToll());
+  const joinToll = ethers.toBigInt(await context.channelManager.joinToll());
   const asset = new Contract(
     context.workspace.canonicalAsset,
     context.bridgeAbiManifest.contracts.erc20.abi,
@@ -4045,6 +4417,14 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
     channelManager: context.workspace.channelManager,
     policySnapshot: context.workspace.policySnapshot,
   });
+  await requireActionImpactAcknowledgement("channel-join", args, {
+    l1Address: signer.address,
+    l2Address: l2Identity.l2Address,
+    noteReceivePubKey: JSON.stringify(noteReceiveKeyMaterial.noteReceivePubKey),
+    joinToll: ethers.formatUnits(joinToll, Number(context.workspace.canonicalAssetDecimals)),
+    channelName: context.workspace.channelName,
+    channelId: context.workspace.channelId,
+  });
   if (joinToll !== 0n) {
     approveReceipt = await waitForReceipt(
       await asset.approve(context.workspace.bridgeTokenVault, joinToll, { nonce: nextNonce++ }),
@@ -4060,8 +4440,14 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
       { nonce: nextNonce++ },
     ),
   );
-  status = "joined";
-
+  const registered = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
+  const lifecycleEpoch = await resolveWalletLifecycleEpoch({
+    context,
+    provider,
+    l1Address: signer.address,
+    registration: registered,
+  });
+  expect(lifecycleEpoch, "Unable to resolve the channel join epoch from emitted registration logs.");
   await refreshPersistedWorkspaceAfterLocalTransaction({
     context,
     provider,
@@ -4076,8 +4462,9 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
     l2Identity,
     walletSecret,
     storageKey,
-    leafIndex: resolvedLeafIndex,
+    leafIndex,
     noteReceiveKeyMaterial,
+    lifecycleEpoch,
     rpcUrl,
   });
 
@@ -4085,14 +4472,19 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
     action: "channel join",
     workspace: context.workspaceName,
     wallet: walletContext.walletName,
-    walletSecretSource: resolvedWalletSecretSource(args),
-    walletSecretFile: resolvedWalletSecretFile(network.name, walletContext.walletName),
+    walletSecretSource: "wallet-secret-path-one-time-derivation",
+    walletSecretStored: false,
+    walletSecretRecoveryWarning: "Keep the wallet secret source backed up. If the spending-key file is lost and this wallet secret source is also lost, the CLI cannot rederive the spending key; notes for this wallet cannot be spent, transferred, or redeemed through the normal note flow.",
     channelName: context.workspace.channelName,
     channelId: context.workspace.channelId,
     l1Address: signer.address,
     l2Address: l2Identity.l2Address,
     l2StorageKey: storageKey,
-    leafIndex: resolvedLeafIndex.toString(),
+    leafIndex: leafIndex.toString(),
+    epochId: lifecycleEpoch.epochId,
+    lifecycleStatus: lifecycleEpoch.lifecycleStatus,
+    joinedAtTxHash: lifecycleEpoch.joinedAtTxHash,
+    joinedAtBlockNumber: lifecycleEpoch.joinedAtBlockNumber,
     joinTollBaseUnits: joinToll.toString(),
     joinTollTokens: ethers.formatUnits(joinToll, Number(context.workspace.canonicalAssetDecimals)),
     noteReceivePubKey: noteReceiveKeyMaterial.noteReceivePubKey,
@@ -4103,31 +4495,37 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
     txUrl: receipt ? explorerTxUrl(network, receipt.hash) : null,
     approveReceipt: approveReceipt ? sanitizeReceipt(approveReceipt) : null,
     receipt: receipt ? sanitizeReceipt(receipt) : null,
-    status,
+    status: "joined",
   });
 }
 
 async function handleExitChannel({ args, provider }) {
   const { wallet: walletContext, walletMetadata } = loadUnlockedWalletWithMetadata(args);
+  requireActiveWalletLifecycle(walletContext, "channel exit");
   const { signer, context, channelFund, contextResult } = await loadWalletChannelFundState({
     walletContext,
     provider,
     progressAction: "channel exit",
   });
+  const ownerSigner = requireWalletOwnerSigner(walletContext, provider);
   const network = contextResult.network;
   expect(
     channelFund === 0n,
     [
-      `The current channel fund for ${signer.address} is ${channelFund.toString()}.`,
+      `The current channel fund for ${ownerSigner.address} is ${channelFund.toString()}.`,
       "channel exit requires a zero channel balance.",
       "Run wallet withdraw-channel first, then retry channel exit.",
     ].join(" "),
   );
-  const [refundAmount, refundBps] = await context.channelManager.getExitTollRefundQuote(signer.address);
+  const [refundAmount, refundBps] = await context.channelManager.getExitTollRefundQuote(ownerSigner.address);
   const receipt = await waitForReceipt(
-    await context.bridgeTokenVault.connect(signer).exitChannel(ethers.toBigInt(context.workspace.channelId)),
+    await context.bridgeTokenVault.connect(ownerSigner).exitChannel(ethers.toBigInt(context.workspace.channelId)),
   );
-  const cleanup = removeLocalWalletArtifacts(walletContext.walletName, walletMetadata.network);
+  const lifecycleEpoch = await markWalletEpochExited({
+    walletContext,
+    receipt,
+    provider,
+  });
 
   printJson({
     action: "channel exit",
@@ -4135,7 +4533,7 @@ async function handleExitChannel({ args, provider }) {
     network: walletMetadata.network,
     channelName: walletMetadata.channelName,
     channelId: context.workspace.channelId,
-    l1Address: signer.address,
+    l1Address: ownerSigner.address,
     currentUserValue: channelFund.toString(),
     refundAmountBaseUnits: refundAmount.toString(),
     refundAmountTokens: ethers.formatUnits(refundAmount, Number(context.workspace.canonicalAssetDecimals)),
@@ -4145,8 +4543,12 @@ async function handleExitChannel({ args, provider }) {
     gasUsed: receiptGasUsed(receipt),
     txUrl: explorerTxUrl(network, receipt.hash),
     receipt: sanitizeReceipt(receipt),
-    removedWalletDir: cleanup.removedWalletDir ? cleanup.walletDir : null,
-    removedWalletSecretFile: cleanup.removedWalletSecret ? cleanup.walletSecretFile : null,
+    epochId: lifecycleEpoch.epochId,
+    lifecycleStatus: lifecycleEpoch.lifecycleStatus,
+    exitedAtTxHash: lifecycleEpoch.exitedAtTxHash,
+    exitedAtBlockNumber: lifecycleEpoch.exitedAtBlockNumber,
+    exitedAtBlockTimestampIso: lifecycleEpoch.exitedAtBlockTimestampIso,
+    archivedWalletDir: walletContext.walletDir,
   });
 }
 
@@ -4158,6 +4560,7 @@ async function handleGrothVaultMove({ args, provider, direction }) {
       : "wallet withdraw-channel";
   emitProgress(operationName, "loading");
   const { wallet: walletContext } = loadUnlockedWalletWithMetadata(args);
+  requireActiveWalletLifecycle(walletContext, operationName);
   const contextResult = await loadFreshWalletChannelContext({
     walletContext,
     provider,
@@ -4174,6 +4577,13 @@ async function handleGrothVaultMove({ args, provider, direction }) {
   const { signer, l2Identity } = restoreWalletParticipant(walletContext, provider);
   const amountInput = requireArg(args.amount, "--amount");
   const amount = parseTokenAmount(amountInput, Number(context.workspace.canonicalAssetDecimals));
+  await requireActionImpactAcknowledgement(args.command, args, {
+    l1Address: signer.address,
+    l2Address: l2Identity.l2Address,
+    amountInput,
+    channelName: context.workspace.channelName,
+    channelId: context.workspace.channelId,
+  });
   const storageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
   const bridgeTokenVault = new Contract(
     context.workspace.bridgeTokenVault,
@@ -4256,7 +4666,7 @@ async function handleGrothVaultMove({ args, provider, direction }) {
   writeJson(path.join(operationDir, `${operationName}-receipt.json`), sanitizeReceipt(receipt));
   writeJson(path.join(operationDir, "state_snapshot.json"), transition.nextSnapshot);
   writeJson(path.join(operationDir, "state_snapshot.normalized.json"), transition.nextSnapshot);
-  sealWalletOperationDir(operationDir, walletContext.walletSecret);
+  sealWalletOperationDir(operationDir, walletOperationSealSecret(walletContext));
 
   context.currentSnapshot = transition.nextSnapshot;
   await refreshPersistedWorkspaceAfterLocalTransaction({
@@ -4291,6 +4701,11 @@ async function handleWithdrawBridge({ args, network, provider }) {
   const bridgeVaultContext = await loadBridgeVaultContext({ provider, chainId });
   const amountInput = requireArg(args.amount, "--amount");
   const amount = parseTokenAmount(amountInput, Number(bridgeVaultContext.canonicalAssetDecimals));
+  await requireActionImpactAcknowledgement("account-withdraw-bridge", args, {
+    l1Address: signer.address,
+    amountInput,
+    bridgeTokenVault: bridgeVaultContext.bridgeTokenVaultAddress,
+  });
   const bridgeTokenVault = new Contract(
     bridgeVaultContext.bridgeTokenVaultAddress,
     bridgeVaultContext.bridgeAbiManifest.contracts.bridgeTokenVault.abi,
@@ -4371,6 +4786,8 @@ function resolveFunctionMetadataProofForExecution({
 
 async function handleMintNotes({ args, provider }) {
   const { wallet } = loadUnlockedWalletWithMetadata(args);
+  requireActiveWalletLifecycle(wallet, "wallet mint-notes");
+  requireWalletSpendingCapability(wallet);
   const canonicalAssetDecimals = Number(wallet.wallet.canonicalAssetDecimals);
   const amountInputs = parseAmountVector(requireArg(args.amounts, "--amounts"), {
     allowZeroEntries: true,
@@ -4400,6 +4817,19 @@ async function handleMintNotes({ args, provider }) {
       `${channelFund.toString()}. Run wallet get-channel-fund to inspect the available balance.`,
     ].join(" "),
   );
+  const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
+  const { txSubmitter } = resolveTxSubmitterSigner({
+    args,
+    ownerSigner: signer,
+    provider,
+  });
+  await requireActionImpactAcknowledgement("wallet-mint-notes", args, {
+    l1Address: txSubmitter.address,
+    l2Address: l2Identity.l2Address,
+    amounts: baseUnitAmounts.map(({ amountInput }) => amountInput).join(", "),
+    channelName: wallet.wallet.channelName,
+    channelId: wallet.wallet.channelId,
+  });
   const templatePayload = buildMintNotesTemplatePayload({
     wallet,
     baseUnitAmounts: baseUnitAmounts.map(({ amountBaseUnits }) => amountBaseUnits),
@@ -4432,6 +4862,7 @@ async function handleMintNotes({ args, provider }) {
       sourceFunction: templatePayload.method,
       sourceTxHash: execution.receipt.hash,
       bridgeCommitmentKeys: execution.noteLifecycle.outputCommitmentKeys,
+      sourceBlockNumber: execution.receipt.blockNumber,
     }),
     gasUsed: receiptGasUsed(execution.receipt),
     txUrl: explorerTxUrl(contextResult.network, execution.receipt.hash),
@@ -4444,6 +4875,9 @@ async function handleMintNotes({ args, provider }) {
 
 async function handleRedeemNotes({ args, provider }) {
   const { wallet } = loadUnlockedWalletWithMetadata(args);
+  requireActiveWalletLifecycle(wallet, "wallet redeem-notes");
+  requireWalletViewingCapability(wallet);
+  requireWalletSpendingCapability(wallet);
   const noteIds = parseNoteIdVector(requireArg(args.noteIds, "--note-ids"));
   const preparedContextResult = await loadFreshWalletChannelContext({
     walletContext: wallet,
@@ -4458,6 +4892,19 @@ async function handleRedeemNotes({ args, provider }) {
     preConsumedBlockDelta: preparedContextResult.autoRecoveryBlockDelta,
   });
   const inputNotes = loadWalletUnusedInputNotes(wallet, noteIds);
+  const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
+  const { txSubmitter } = resolveTxSubmitterSigner({
+    args,
+    ownerSigner: signer,
+    provider,
+  });
+  await requireActionImpactAcknowledgement("wallet-redeem-notes", args, {
+    l1Address: txSubmitter.address,
+    l2Address: l2Identity.l2Address,
+    noteIds: noteIds.join(", "),
+    channelName: wallet.wallet.channelName,
+    channelId: wallet.wallet.channelId,
+  });
   const templatePayload = buildRedeemNotesTemplatePayload({
     wallet,
     inputNotes,
@@ -4513,13 +4960,20 @@ async function handleWalletGetNotes({ args, provider }) {
     progressAction: "wallet get-notes",
   });
   const context = contextResult.context;
-  const noteReceiveFreshness = await ensureWalletNoteReceiveStateCurrent({
-    walletContext: wallet,
-    context,
-    provider,
-    progressAction: "wallet get-notes",
-    preConsumedBlockDelta: contextResult.autoRecoveryBlockDelta,
-  });
+  const noteReceiveFreshness = wallet.wallet.noteReceivePrivateKey
+    ? await ensureWalletNoteReceiveStateCurrent({
+      walletContext: wallet,
+      context,
+      provider,
+      progressAction: "wallet get-notes",
+      preConsumedBlockDelta: contextResult.autoRecoveryBlockDelta,
+    })
+    : {
+      nextBlock: wallet.wallet.noteReceiveLastScannedBlock,
+      latestBlock: await provider.getBlockNumber(),
+      recoveredWalletWorkspace: false,
+      recoveredDeliveryState: null,
+    };
 
   const unusedTrackedNotes = wallet.wallet.notes.unusedOrder
     .map((commitment) => wallet.wallet.notes.unused[commitment])
@@ -4539,8 +4993,20 @@ async function handleWalletGetNotes({ args, provider }) {
     canonicalAssetDecimals,
   })));
 
-  const unusedTotal = unusedTrackedNotes.reduce((sum, note) => sum + ethers.toBigInt(note.value), 0n);
-  const spentTotal = spentTrackedNotes.reduce((sum, note) => sum + ethers.toBigInt(note.value), 0n);
+  const canComputeTotals = [...unusedTrackedNotes, ...spentTrackedNotes].every((note) => note.value !== null);
+  const unusedTotal = canComputeTotals ? unusedTrackedNotes.reduce((sum, note) => sum + ethers.toBigInt(note.value), 0n) : null;
+  const spentTotal = canComputeTotals ? spentTrackedNotes.reduce((sum, note) => sum + ethers.toBigInt(note.value), 0n) : null;
+  const evidenceExport = args.exportEvidence
+    ? await exportWalletGetNotesEvidenceBundle({
+      args,
+      provider,
+      walletContext: wallet,
+      walletMetadata,
+      context,
+      unusedTrackedNotes,
+      spentTrackedNotes,
+    })
+    : null;
 
   printJson({
     action: "wallet get-notes",
@@ -4550,22 +5016,517 @@ async function handleWalletGetNotes({ args, provider }) {
     controller: wallet.wallet.controller,
     unusedNotes,
     spentNotes,
-    unusedTotalBaseUnits: unusedTotal.toString(),
-    unusedTotalTokens: ethers.formatUnits(unusedTotal, canonicalAssetDecimals),
-    spentTotalBaseUnits: spentTotal.toString(),
-    spentTotalTokens: ethers.formatUnits(spentTotal, canonicalAssetDecimals),
+    unusedTotalBaseUnits: unusedTotal?.toString() ?? null,
+    unusedTotalTokens: unusedTotal === null ? null : ethers.formatUnits(unusedTotal, canonicalAssetDecimals),
+    spentTotalBaseUnits: spentTotal?.toString() ?? null,
+    spentTotalTokens: spentTotal === null ? null : ethers.formatUnits(spentTotal, canonicalAssetDecimals),
     bridgeStatusMismatches: [...unusedNotes, ...spentNotes].filter((note) => !note.walletStatusMatchesBridge).length,
     noteReceiveLastScannedBlock: noteReceiveFreshness.nextBlock,
     latestBlock: noteReceiveFreshness.latestBlock,
+    viewingKeyAvailable: Boolean(wallet.wallet.noteReceivePrivateKey),
     recoveredWalletWorkspace: noteReceiveFreshness.recoveredWalletWorkspace,
     recoveredFromLogs: noteReceiveFreshness.recoveredDeliveryState?.importedNotes ?? 0,
     scannedDeliveryLogs: noteReceiveFreshness.recoveredDeliveryState?.scannedLogs ?? 0,
     noteReceiveScanRange: noteReceiveFreshness.recoveredDeliveryState?.scanRange ?? null,
+    evidenceExport,
+  });
+}
+
+async function exportWalletGetNotesEvidenceBundle({
+  args,
+  provider,
+  walletContext,
+  walletMetadata,
+  context,
+  unusedTrackedNotes,
+  spentTrackedNotes,
+}) {
+  const outputPath = path.resolve(String(requireArg(args.exportEvidence, "--export-evidence")));
+  ensureDir(path.dirname(outputPath));
+
+  const evidenceWalletContexts = loadWalletEpochContextsForEvidence({
+    baseWalletContext: walletContext,
+    networkName: walletMetadata.network,
+  });
+  const noteInputs = [];
+  for (const candidateWalletContext of evidenceWalletContexts) {
+    const notes = candidateWalletContext === walletContext
+      ? [
+        ...unusedTrackedNotes.map(normalizeTrackedNote),
+        ...spentTrackedNotes.map(normalizeTrackedNote),
+      ]
+      : [
+        ...Object.values(candidateWalletContext.wallet.notes.unused).map(normalizeTrackedNote),
+        ...Object.values(candidateWalletContext.wallet.notes.spent).map(normalizeTrackedNote),
+      ];
+    for (const note of notes) {
+      validateEvidenceNotePlaintext(note, candidateWalletContext.wallet);
+      noteInputs.push({ note, walletContext: candidateWalletContext });
+    }
+  }
+  noteInputs.sort((left, right) =>
+    String(left.walletContext.wallet.walletEpochId ?? "").localeCompare(String(right.walletContext.wallet.walletEpochId ?? ""))
+    || left.note.commitment.localeCompare(right.note.commitment));
+
+  const txHashes = uniqueNonNull([
+    ...noteInputs.map(({ note }) => note.createdAtTxHash),
+    ...noteInputs.map(({ note }) => note.spentAtTxHash),
+  ]);
+  const transactionEvidence = await buildTransactionEvidenceMap({ provider, txHashes });
+  const blockTimestampCache = buildBlockTimestampCache(transactionEvidence);
+  const noteRecords = noteInputs.map(({ note, walletContext: noteWalletContext }) => buildEvidenceNoteRecord({
+    note,
+    walletContext: noteWalletContext,
+    walletMetadata,
+    context,
+    transactionEvidence,
+    blockTimestampCache,
+  }));
+  const indexes = buildEvidenceIndexes(noteRecords);
+  const manifest = buildEvidenceManifest({
+    outputPath,
+    walletContext,
+    walletContexts: evidenceWalletContexts,
+    walletMetadata,
+    context,
+    noteRecords,
+    txHashes,
+  });
+
+  const archive = new AdmZip();
+  addEvidenceJson(archive, "manifest.json", manifest);
+  addEvidenceJson(archive, "indexes/by-commitment.json", indexes.byCommitment);
+  addEvidenceJson(archive, "indexes/by-nullifier.json", indexes.byNullifier);
+  addEvidenceJson(archive, "indexes/by-creation-tx.json", indexes.byCreationTx);
+  addEvidenceJson(archive, "indexes/by-spend-tx.json", indexes.bySpendTx);
+  addEvidenceJson(archive, "indexes/by-block-range.json", indexes.byBlockRange);
+  addEvidenceJson(archive, "indexes/by-counterparty.json", indexes.byCounterparty);
+  for (const record of noteRecords) {
+    addEvidenceJson(archive, evidenceNotePath(record), record);
+  }
+  for (const [txHash, txRecord] of Object.entries(transactionEvidence)) {
+    addEvidenceJson(archive, `transactions/${txHash}.json`, txRecord.transaction);
+    addEvidenceJson(archive, `receipts/${txHash}.json`, txRecord.receipt);
+    addEvidenceJson(archive, `events/${txHash}.json`, txRecord.events);
+  }
+
+  assertEvidenceBundleDoesNotContainSecrets({
+    wallets: evidenceWalletContexts.map((entry) => entry.wallet),
+    payload: {
+      manifest,
+      indexes,
+      noteRecords,
+      transactionEvidence,
+    },
+  });
+  fs.rmSync(outputPath, { force: true });
+  archive.writeZip(outputPath);
+  protectSecretFile(outputPath, "wallet evidence export ZIP");
+
+  return {
+    output: outputPath,
+    format: WALLET_EVIDENCE_BUNDLE_FORMAT,
+    formatVersion: WALLET_EVIDENCE_BUNDLE_FORMAT_VERSION,
+    noteCount: noteRecords.length,
+    walletEpochCount: evidenceWalletContexts.length,
+    transactionCount: txHashes.length,
+    containsNotePlaintext: true,
+    containsSpendingKey: false,
+    containsViewingKey: false,
+    containsWalletSecret: false,
+    warning: "Local full-note evidence bundle. Do not submit as-is unless full wallet-history disclosure is intended.",
+  };
+}
+
+function loadWalletEpochContextsForEvidence({ baseWalletContext, networkName }) {
+  const walletRoot = walletRootPath(baseWalletContext.walletName, networkName);
+  const index = requireWalletIndex({
+    walletRoot,
+    walletName: baseWalletContext.walletName,
+    networkName,
+  });
+  const contexts = [];
+  for (const epoch of index.epochs) {
+    const walletDir = walletEpochPathFromRoot(walletRoot, epoch.epochId);
+    if (!walletConfigExists(walletDir)) {
+      continue;
+    }
+    const context = loadWalletFromDir({
+      walletName: baseWalletContext.walletName,
+      networkName,
+      walletDir,
+    });
+    contexts.push(context);
+  }
+  expect(
+    contexts.length > 0,
+    `Wallet ${baseWalletContext.walletName} on ${networkName} has no readable wallet epochs. Run wallet recover-workspace and then wallet get-notes --export-evidence again.`,
+  );
+  return contexts;
+}
+
+function validateEvidenceNotePlaintext(note, wallet) {
+  expect(
+    note.owner && note.value !== null && note.salt && note.encryptedNoteValue,
+    [
+      `Cannot export evidence for note ${note.commitment} because plaintext note data is incomplete.`,
+      "Import the wallet viewing key and run wallet recover-workspace before exporting evidence.",
+    ].join(" "),
+  );
+  expect(
+    getAddress(note.owner) === getAddress(wallet.l2Address),
+    `Cannot export evidence for note ${note.commitment}: owner does not match wallet L2 address.`,
+  );
+  const recomputedSalt = computeEncryptedNoteSalt(note.encryptedNoteValue);
+  expect(
+    ethers.toBigInt(recomputedSalt) === ethers.toBigInt(note.salt),
+    `Cannot export evidence for note ${note.commitment}: encrypted note salt mismatch.`,
+  );
+  const plaintext = normalizePlaintextNote(note);
+  expect(
+    ethers.toBigInt(computeNoteCommitment(plaintext)) === ethers.toBigInt(note.commitment),
+    `Cannot export evidence for note ${note.commitment}: commitment mismatch.`,
+  );
+  expect(
+    ethers.toBigInt(computeNullifier(plaintext)) === ethers.toBigInt(note.nullifier),
+    `Cannot export evidence for note ${note.commitment}: nullifier mismatch.`,
+  );
+}
+
+async function buildTransactionEvidenceMap({ provider, txHashes }) {
+  const entries = {};
+  for (const txHash of txHashes) {
+    const [transaction, receipt] = await Promise.all([
+      provider.getTransaction(txHash).catch(() => null),
+      provider.getTransactionReceipt(txHash).catch(() => null),
+    ]);
+    const blockNumber = receipt?.blockNumber ?? transaction?.blockNumber ?? null;
+    const block = blockNumber === null ? null : await provider.getBlock(blockNumber).catch(() => null);
+    entries[txHash] = {
+      transaction: sanitizeTransactionEvidence(transaction, block),
+      receipt: receipt ? sanitizeReceipt(receipt) : null,
+      events: receipt ? sanitizeReceiptEvents(receipt) : [],
+    };
+  }
+  return entries;
+}
+
+function sanitizeTransactionEvidence(transaction, block) {
+  if (!transaction) {
+    return null;
+  }
+  return normalizeCliOutput(serializeBigInts({
+    hash: transaction.hash,
+    from: transaction.from,
+    to: transaction.to,
+    nonce: transaction.nonce,
+    data: transaction.data,
+    value: transaction.value,
+    chainId: transaction.chainId,
+    blockHash: transaction.blockHash,
+    blockNumber: transaction.blockNumber,
+    blockTimestamp: block?.timestamp ?? null,
+    blockTimestampIso: block?.timestamp ? new Date(Number(block.timestamp) * 1000).toISOString() : null,
+  }));
+}
+
+function sanitizeReceiptEvents(receipt) {
+  return (receipt.logs ?? []).map((log) => normalizeCliOutput(serializeBigInts({
+    address: log.address,
+    blockHash: log.blockHash,
+    blockNumber: log.blockNumber,
+    transactionHash: log.transactionHash,
+    transactionIndex: log.transactionIndex,
+    logIndex: log.index ?? log.logIndex ?? null,
+    topics: log.topics,
+    data: log.data,
+  })));
+}
+
+function buildBlockTimestampCache(transactionEvidence) {
+  const cache = {};
+  for (const txRecord of Object.values(transactionEvidence)) {
+    const tx = txRecord.transaction;
+    if (tx?.blockNumber !== null && tx?.blockNumber !== undefined) {
+      cache[Number(tx.blockNumber)] = {
+        timestamp: tx.blockTimestamp ?? null,
+        iso: tx.blockTimestampIso ?? null,
+      };
+    }
+  }
+  return cache;
+}
+
+function buildEvidenceNoteRecord({
+  note,
+  walletContext,
+  walletMetadata,
+  context,
+  transactionEvidence,
+  blockTimestampCache,
+}) {
+  const creationBlockNumber = note.createdAtBlockNumber
+    ?? transactionEvidence[note.createdAtTxHash]?.transaction?.blockNumber
+    ?? null;
+  const spentBlockNumber = note.spentAtBlockNumber
+    ?? transactionEvidence[note.spentAtTxHash]?.transaction?.blockNumber
+    ?? null;
+  const scheme = note.encryptedNoteValue ? unpackEncryptedNoteValue(note.encryptedNoteValue).scheme : null;
+  return normalizeCliOutput({
+    recordType: "note-evidence",
+    recordVersion: 1,
+    noteId: note.commitment,
+    walletScope: {
+      network: walletMetadata.network,
+      chainId: walletContext.wallet.chainId,
+      channelName: walletMetadata.channelName,
+      channelId: walletContext.wallet.channelId,
+      wallet: walletContext.walletName,
+      ...walletLifecycleMetadata(walletContext.wallet),
+      walletL1Address: walletContext.wallet.l1Address,
+      walletL2Address: walletContext.wallet.l2Address,
+      controller: context.workspace.controller,
+    },
+    plaintext: {
+      owner: note.owner,
+      value: note.value,
+      salt: note.salt,
+    },
+    derived: {
+      commitment: note.commitment,
+      nullifier: note.nullifier,
+      commitmentStorageKey: note.bridgeCommitmentKey,
+      nullifierStorageKey: note.bridgeNullifierKey,
+    },
+    encryptedDelivery: {
+      encryptedNoteValue: note.encryptedNoteValue,
+      saltDerivation: "poseidon(encryptedNoteValue)",
+      scheme: encryptedNoteSchemeLabel(scheme),
+      event: {
+        txHash: note.createdAtTxHash,
+        blockNumber: creationBlockNumber,
+        blockTimestamp: blockTimestampCache[Number(creationBlockNumber)]?.timestamp ?? null,
+        blockTimestampIso: blockTimestampCache[Number(creationBlockNumber)]?.iso ?? null,
+        logIndex: note.createdAtLogIndex,
+        contract: context.workspace.channelManager,
+      },
+    },
+    creation: {
+      txHash: note.createdAtTxHash,
+      blockNumber: creationBlockNumber,
+      blockTimestamp: blockTimestampCache[Number(creationBlockNumber)]?.timestamp ?? null,
+      blockTimestampIso: blockTimestampCache[Number(creationBlockNumber)]?.iso ?? null,
+      function: note.createdByFunction,
+      outputIndex: note.createdOutputIndex,
+      acceptedTransition: acceptedTransitionReference(note.createdAtTxHash),
+    },
+    spend: {
+      status: note.status,
+      txHash: note.spentAtTxHash,
+      blockNumber: spentBlockNumber,
+      blockTimestamp: blockTimestampCache[Number(spentBlockNumber)]?.timestamp ?? null,
+      blockTimestampIso: blockTimestampCache[Number(spentBlockNumber)]?.iso ?? null,
+      function: note.spentByFunction,
+      inputIndex: note.spentInputIndex,
+      acceptedTransition: note.spentAtTxHash ? acceptedTransitionReference(note.spentAtTxHash) : null,
+    },
+    relationshipHints: {
+      direction: note.counterpartyDirection ?? inferEvidenceDirection(note, scheme),
+      counterpartyL2Address: note.counterpartyL2Address,
+      counterpartyL1Address: null,
+      confidence: note.counterpartyConfidence ?? (note.counterpartyL2Address ? "direct-local-metadata" : "unavailable"),
+    },
+    verificationClaims: {
+      commitmentRecomputesFromPlaintext: true,
+      nullifierRecomputesFromPlaintext: true,
+      ownerMatchesWalletL2Address: true,
+      spendingKeyIncluded: false,
+      viewingKeyIncluded: false,
+      walletSecretIncluded: false,
+      fullWalletHistoryRequiredForFinalDisclosure: false,
+    },
+  });
+}
+
+function acceptedTransitionReference(txHash) {
+  if (!txHash) {
+    return null;
+  }
+  return {
+    txHash,
+    transactionPath: `transactions/${txHash}.json`,
+    receiptPath: `receipts/${txHash}.json`,
+    eventsPath: `events/${txHash}.json`,
+    proofCalldataLocation: "transactions[].data",
+    localProofArtifactIncluded: false,
+  };
+}
+
+function encryptedNoteSchemeLabel(scheme) {
+  if (scheme === ENCRYPTED_NOTE_SCHEME_SELF_MINT) {
+    return "self-mint";
+  }
+  if (scheme === ENCRYPTED_NOTE_SCHEME_TRANSFER) {
+    return "transfer";
+  }
+  return "unknown";
+}
+
+function inferEvidenceDirection(note, scheme) {
+  if (scheme === ENCRYPTED_NOTE_SCHEME_SELF_MINT) {
+    return "self-mint";
+  }
+  if (note.spentByFunction?.startsWith("transferNotes")) {
+    return "sent";
+  }
+  if (note.createdByFunction?.startsWith("transferNotes")) {
+    return "received";
+  }
+  return "unknown";
+}
+
+function buildEvidenceIndexes(noteRecords) {
+  const indexes = {
+    byCommitment: {},
+    byNullifier: {},
+    byCreationTx: {},
+    bySpendTx: {},
+    byBlockRange: [],
+    byCounterparty: {
+      unavailable: [],
+    },
+  };
+  for (const record of noteRecords) {
+    const pathName = evidenceNotePath(record);
+    indexes.byCommitment[record.derived.commitment] = pathName;
+    indexes.byNullifier[record.derived.nullifier] = pathName;
+    pushIndexEntry(indexes.byCreationTx, record.creation.txHash, pathName);
+    pushIndexEntry(indexes.bySpendTx, record.spend.txHash, pathName);
+    indexes.byBlockRange.push({
+      commitment: record.derived.commitment,
+      createdAtBlockNumber: record.creation.blockNumber,
+      spentAtBlockNumber: record.spend.blockNumber,
+      path: pathName,
+    });
+    const counterparty = record.relationshipHints.counterpartyL2Address;
+    if (counterparty) {
+      if (!indexes.byCounterparty[counterparty]) {
+        indexes.byCounterparty[counterparty] = { sent: [], received: [], both: [] };
+      }
+      const direction = record.relationshipHints.direction === "received" ? "received" : "sent";
+      indexes.byCounterparty[counterparty][direction].push(pathName);
+      indexes.byCounterparty[counterparty].both.push(pathName);
+    } else {
+      indexes.byCounterparty.unavailable.push(pathName);
+    }
+  }
+  indexes.byBlockRange.sort((left, right) =>
+    Number(left.createdAtBlockNumber ?? Number.MAX_SAFE_INTEGER)
+      - Number(right.createdAtBlockNumber ?? Number.MAX_SAFE_INTEGER));
+  return indexes;
+}
+
+function evidenceNotePath(record) {
+  expect(
+    record.walletScope?.canonicalWalletName && record.walletScope?.epochId,
+    "Evidence note path requires the current epoch-aware wallet scope.",
+  );
+  return [
+    "wallets",
+    slugifyPathComponent(record.walletScope.canonicalWalletName),
+    "epochs",
+    slugifyPathComponent(record.walletScope.epochId),
+    "notes",
+    `${record.derived.commitment}.json`,
+  ].join("/");
+}
+
+function pushIndexEntry(index, key, value) {
+  if (!key) {
+    return;
+  }
+  if (!index[key]) {
+    index[key] = [];
+  }
+  index[key].push(value);
+}
+
+function buildEvidenceManifest({
+  outputPath,
+  walletContext,
+  walletContexts = [walletContext],
+  walletMetadata,
+  context,
+  noteRecords,
+  txHashes,
+}) {
+  return normalizeCliOutput({
+    format: WALLET_EVIDENCE_BUNDLE_FORMAT,
+    formatVersion: WALLET_EVIDENCE_BUNDLE_FORMAT_VERSION,
+    bundleType: "local-full-note-evidence",
+    generatedAt: new Date().toISOString(),
+    outputFileName: path.basename(outputPath),
+    network: walletMetadata.network,
+    chainId: walletContext.wallet.chainId,
+    channelName: walletMetadata.channelName,
+    channelId: walletContext.wallet.channelId,
+    wallet: walletContext.walletName,
+    walletL1Address: walletContext.wallet.l1Address,
+    walletL2Address: walletContext.wallet.l2Address,
+    wallets: walletContexts.map((entry) => ({
+      wallet: entry.walletName,
+      ...walletLifecycleMetadata(entry.wallet),
+      walletL1Address: entry.wallet.l1Address,
+      walletL2Address: entry.wallet.l2Address,
+    })),
+    controller: context.workspace.controller,
+    channelManager: context.workspace.channelManager,
+    bridgeTokenVault: context.workspace.bridgeTokenVault,
+    containsAllLocallyKnownNotes: true,
+    containsAllLocalWalletEpochs: true,
+    containsNotePlaintext: true,
+    noteCount: noteRecords.length,
+    transactionCount: txHashes.length,
+    intendedUse: "Input for private-state-cli investigator; not a default exchange submission package.",
+    warning: "DO_NOT_SUBMIT_AS_IS unless full wallet-history disclosure is intended.",
+    excludedSecrets: {
+      spendingKey: true,
+      viewingKey: true,
+      walletSecret: true,
+      accountPrivateKey: true,
+      keyFiles: true,
+    },
   });
 }
 
+function addEvidenceJson(archive, archivePath, value) {
+  archive.addFile(archivePath, Buffer.from(`${JSON.stringify(normalizeCliOutput(value), null, 2)}\n`, "utf8"));
+}
+
+function assertEvidenceBundleDoesNotContainSecrets({ wallet = null, wallets = null, payload }) {
+  const serialized = JSON.stringify(payload);
+  const walletList = wallets ?? (wallet ? [wallet] : []);
+  const forbiddenValues = walletList.flatMap((entry) => [
+    entry.l2PrivateKey,
+    entry.noteReceivePrivateKey,
+  ]).filter((value) => typeof value === "string" && value.length > 0);
+  for (const value of forbiddenValues) {
+    expect(
+      !serialized.includes(value),
+      "Evidence export refused to write authority-bearing wallet secret material.",
+    );
+  }
+}
+
+function uniqueNonNull(values) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value.length > 0))];
+}
+
 async function handleTransferNotes({ args, provider }) {
   const { wallet } = loadUnlockedWalletWithMetadata(args);
+  requireActiveWalletLifecycle(wallet, "wallet transfer-notes");
+  requireWalletViewingCapability(wallet);
+  requireWalletSpendingCapability(wallet);
   const { signer } = restoreWalletParticipant(wallet, provider);
   const preparedContextResult = await loadFreshWalletChannelContext({
     walletContext: wallet,
@@ -4603,6 +5564,19 @@ async function handleTransferNotes({ args, provider }) {
     "The sum of --amounts must equal the sum of the selected input note values.",
   );
 
+  const { txSubmitter } = resolveTxSubmitterSigner({
+    args,
+    ownerSigner: signer,
+    provider,
+  });
+  await requireActionImpactAcknowledgement("wallet-transfer-notes", args, {
+    l1Address: txSubmitter.address,
+    l2Address: wallet.wallet.l2Address,
+    noteIds: noteIds.join(", "),
+    amounts: amountInputs.join(", "),
+    channelName: context.workspace.channelName,
+    channelId: context.workspace.channelId,
+  });
   const templatePayload = await buildTransferNotesTemplatePayload({
     context,
     signer,
@@ -4623,6 +5597,9 @@ async function handleTransferNotes({ args, provider }) {
     sourceFunction: templatePayload.method,
     sourceTxHash: execution.receipt.hash,
     bridgeCommitmentKeys: execution.noteLifecycle.outputCommitmentKeys,
+    sourceBlockNumber: execution.receipt.blockNumber,
+    counterpartyL2Addresses: templatePayload.recipientAddresses,
+    counterpartyDirection: "sent",
   });
 
   printJson({
@@ -4744,16 +5721,40 @@ function ensureWallet({
   storageKey,
   leafIndex,
   noteReceiveKeyMaterial,
+  lifecycleEpoch,
   rpcUrl,
 }) {
   const walletName = walletNameForChannelAndAddress(channelContext.workspace.channelName, signerAddress);
-  const walletDir = walletPath(walletName, channelContext.workspace.network);
+  const walletRoot = walletRootPath(walletName, channelContext.workspace.network);
+  if (fs.existsSync(walletRoot)) {
+    requireWalletIndex({
+      walletRoot,
+      walletName,
+      networkName: channelContext.workspace.network,
+    });
+  }
+  expect(lifecycleEpoch, "Current wallet workspace creation requires an on-chain wallet lifecycle epoch.");
+  const walletDir = walletEpochPath(walletName, channelContext.workspace.network, lifecycleEpoch.epochId);
   expect(!walletConfigExists(walletDir), `Wallet ${walletName} already exists on ${channelContext.workspace.network}.`);
   ensureDir(walletDir);
   ensureDir(path.join(walletDir, "operations"));
 
   const wallet = normalizeWallet({
+    walletFormatVersion: WALLET_WORKSPACE_FORMAT_VERSION,
     name: walletName,
+    canonicalWalletName: walletName,
+    walletEpochId: lifecycleEpoch.epochId,
+    lifecycleStatus: lifecycleEpoch.lifecycleStatus,
+    joinedAtTxHash: lifecycleEpoch.joinedAtTxHash,
+    joinedAtBlockNumber: lifecycleEpoch.joinedAtBlockNumber,
+    joinedAtLogIndex: lifecycleEpoch.joinedAtLogIndex,
+    joinedAtBlockTimestamp: lifecycleEpoch.joinedAtBlockTimestamp,
+    joinedAtBlockTimestampIso: lifecycleEpoch.joinedAtBlockTimestampIso,
+    exitedAtTxHash: lifecycleEpoch.exitedAtTxHash,
+    exitedAtBlockNumber: lifecycleEpoch.exitedAtBlockNumber,
+    exitedAtLogIndex: lifecycleEpoch.exitedAtLogIndex,
+    exitedAtBlockTimestamp: lifecycleEpoch.exitedAtBlockTimestamp,
+    exitedAtBlockTimestampIso: lifecycleEpoch.exitedAtBlockTimestampIso,
     network: channelContext.workspace.network,
     rpcUrl,
     chainId: channelContext.workspace.chainId,
@@ -4769,10 +5770,8 @@ function ensureWallet({
     l2AccountingVault: channelContext.workspace.l2AccountingVault,
     liquidBalancesSlot: channelContext.workspace.liquidBalancesSlot,
     l1Address: signerAddress,
-    l1PrivateKey: normalizePrivateKey(signerPrivateKey),
     l2Address: l2Identity.l2Address,
-    l2PrivateKey: ethers.hexlify(l2Identity.l2PrivateKey),
-    l2PublicKey: ethers.hexlify(l2Identity.l2PublicKey),
+    l2PublicKey: l2Identity.l2PublicKey ? ethers.hexlify(l2Identity.l2PublicKey) : null,
     l2DerivationMode: CHANNEL_BOUND_L2_DERIVATION_MODE,
     l2DerivationChannelName: channelContext.workspace.channelName,
     l2StorageKey: storageKey,
@@ -4788,31 +5787,75 @@ function ensureWallet({
       spent: {},
     },
   });
+  if (l2Identity.l2PrivateKey) {
+    wallet.l2PrivateKey = ethers.hexlify(l2Identity.l2PrivateKey);
+  }
+  wallet.noteReceivePrivateKey = normalizePrivateKey(noteReceiveKeyMaterial.privateKey);
 
   const context = {
     walletName,
     walletDir,
     wallet,
-    walletSecret,
+    walletSecret: wallet.l2PrivateKey,
   };
+  persistWalletKeys(context);
   persistWallet(context);
-  persistWalletMetadata(context);
+  persistWalletIndexForContext(context);
   return context;
 }
 
+function applyWalletLifecycleEpoch(wallet, epoch) {
+  wallet.canonicalWalletName = wallet.name;
+  wallet.walletEpochId = epoch.epochId;
+  wallet.lifecycleStatus = epoch.lifecycleStatus;
+  wallet.joinedAtTxHash = epoch.joinedAtTxHash;
+  wallet.joinedAtBlockNumber = epoch.joinedAtBlockNumber;
+  wallet.joinedAtLogIndex = epoch.joinedAtLogIndex;
+  wallet.joinedAtBlockTimestamp = epoch.joinedAtBlockTimestamp;
+  wallet.joinedAtBlockTimestampIso = epoch.joinedAtBlockTimestampIso;
+  wallet.exitedAtTxHash = epoch.exitedAtTxHash;
+  wallet.exitedAtBlockNumber = epoch.exitedAtBlockNumber;
+  wallet.exitedAtLogIndex = epoch.exitedAtLogIndex;
+  wallet.exitedAtBlockTimestamp = epoch.exitedAtBlockTimestamp;
+  wallet.exitedAtBlockTimestampIso = epoch.exitedAtBlockTimestampIso;
+}
+
+function walletLifecycleMetadata(wallet) {
+  expect(wallet.walletEpochId, "Current wallet workspace metadata is missing walletEpochId.");
+  return {
+    canonicalWalletName: wallet.canonicalWalletName ?? wallet.name,
+    epochId: wallet.walletEpochId,
+    lifecycleStatus: wallet.lifecycleStatus ?? "active",
+    joinedAtTxHash: wallet.joinedAtTxHash ?? null,
+    joinedAtBlockNumber: wallet.joinedAtBlockNumber ?? null,
+    joinedAtLogIndex: wallet.joinedAtLogIndex ?? null,
+    joinedAtBlockTimestamp: wallet.joinedAtBlockTimestamp ?? null,
+    joinedAtBlockTimestampIso: wallet.joinedAtBlockTimestampIso ?? null,
+    exitedAtTxHash: wallet.exitedAtTxHash ?? null,
+    exitedAtBlockNumber: wallet.exitedAtBlockNumber ?? null,
+    exitedAtLogIndex: wallet.exitedAtLogIndex ?? null,
+    exitedAtBlockTimestamp: wallet.exitedAtBlockTimestamp ?? null,
+    exitedAtBlockTimestampIso: wallet.exitedAtBlockTimestampIso ?? null,
+  };
+}
+
 function normalizeWallet(wallet) {
   assertWalletHasCurrentFormat(wallet, wallet.name ?? "unknown");
+  expect(wallet.walletEpochId, "Current wallet metadata requires walletEpochId. Run wallet recover-workspace to rebuild this wallet.");
   const unusedNotes = Object.values(wallet.notes.unused).map(normalizeTrackedNote);
   unusedNotes.sort(compareNotesByValueDesc);
   const spentNotes = Object.values(wallet.notes.spent).map(normalizeTrackedNote);
 
   return {
     ...wallet,
+    canonicalWalletName: wallet.canonicalWalletName ?? wallet.name,
+    walletEpochId: wallet.walletEpochId,
+    lifecycleStatus: wallet.lifecycleStatus ?? "active",
     canonicalAssetDecimals: Number(wallet.canonicalAssetDecimals),
     l2Nonce: Number(wallet.l2Nonce),
-    l1PrivateKey: normalizePrivateKey(wallet.l1PrivateKey),
-    l2PrivateKey: ethers.hexlify(wallet.l2PrivateKey),
-    l2PublicKey: ethers.hexlify(wallet.l2PublicKey),
+    l2PrivateKey: wallet.l2PrivateKey ? ethers.hexlify(wallet.l2PrivateKey) : null,
+    l2PublicKey: wallet.l2PublicKey ? ethers.hexlify(wallet.l2PublicKey) : null,
+    noteReceivePrivateKey: wallet.noteReceivePrivateKey ? normalizePrivateKey(wallet.noteReceivePrivateKey) : null,
     noteReceiveDerivationVersion: Number(wallet.noteReceiveDerivationVersion),
     noteReceiveTypedDataMethod: wallet.noteReceiveTypedDataMethod,
     noteReceivePubKeyX: normalizeBytes32Hex(wallet.noteReceivePubKeyX),
@@ -4822,18 +5865,18 @@ function normalizeWallet(wallet) {
       unused: Object.fromEntries(unusedNotes.map((note) => [note.commitment, note])),
       spent: Object.fromEntries(spentNotes.map((note) => [note.nullifier, note])),
       unusedOrder: unusedNotes.map((note) => note.commitment),
-      unusedBalance: unusedNotes.reduce((sum, note) => sum + ethers.toBigInt(note.value), 0n).toString(),
+      unusedBalance: unusedNotes.every((note) => note.value !== null)
+        ? unusedNotes.reduce((sum, note) => sum + ethers.toBigInt(note.value), 0n).toString()
+        : null,
     },
   };
 }
 
 function assertWalletHasCurrentFormat(wallet, walletName) {
   const requiredKeys = [
+    "walletFormatVersion",
     "canonicalAssetDecimals",
     "l2Nonce",
-    "l1PrivateKey",
-    "l2PrivateKey",
-    "l2PublicKey",
     "noteReceiveDerivationVersion",
     "noteReceiveTypedDataMethod",
     "noteReceivePubKeyX",
@@ -4849,18 +5892,48 @@ function assertWalletHasCurrentFormat(wallet, walletName) {
     wallet.notes && typeof wallet.notes.unused === "object" && typeof wallet.notes.spent === "object",
     `Wallet ${walletName} was not created with the current CLI notes format.`,
   );
+  expect(
+    Number(wallet.walletFormatVersion) === WALLET_WORKSPACE_FORMAT_VERSION,
+    [
+      `Wallet ${walletName} uses unsupported wallet workspace format ${wallet.walletFormatVersion ?? "missing"}.`,
+      "Rebuild the wallet metadata with wallet recover-workspace.",
+    ].join(" "),
+  );
 }
 
 function normalizeTrackedNote(note) {
   return {
-    owner: getAddress(note.owner),
-    value: ethers.toBigInt(note.value).toString(),
-    salt: normalizeBytes32Hex(note.salt),
+    owner: note.owner ? getAddress(note.owner) : null,
+    value: note.value !== undefined && note.value !== null ? ethers.toBigInt(note.value).toString() : null,
+    salt: note.salt ? normalizeBytes32Hex(note.salt) : null,
     commitment: normalizeBytes32Hex(note.commitment),
     nullifier: normalizeBytes32Hex(note.nullifier),
+    encryptedNoteValue: note.encryptedNoteValue ? normalizeEncryptedNoteValueWords(note.encryptedNoteValue) : null,
     status: note.status,
     sourceFunction: note.sourceFunction ?? null,
     sourceTxHash: note.sourceTxHash ?? null,
+    createdAtTxHash: note.createdAtTxHash ?? (note.status === "unused" ? note.sourceTxHash ?? null : null),
+    createdAtBlockNumber: note.createdAtBlockNumber !== undefined && note.createdAtBlockNumber !== null
+      ? Number(note.createdAtBlockNumber)
+      : null,
+    createdAtLogIndex: note.createdAtLogIndex !== undefined && note.createdAtLogIndex !== null
+      ? Number(note.createdAtLogIndex)
+      : null,
+    createdByFunction: note.createdByFunction ?? (note.status === "unused" ? note.sourceFunction ?? null : null),
+    createdOutputIndex: note.createdOutputIndex !== undefined && note.createdOutputIndex !== null
+      ? Number(note.createdOutputIndex)
+      : null,
+    spentAtTxHash: note.spentAtTxHash ?? (note.status === "spent" ? note.sourceTxHash ?? null : null),
+    spentAtBlockNumber: note.spentAtBlockNumber !== undefined && note.spentAtBlockNumber !== null
+      ? Number(note.spentAtBlockNumber)
+      : null,
+    spentByFunction: note.spentByFunction ?? (note.status === "spent" ? note.sourceFunction ?? null : null),
+    spentInputIndex: note.spentInputIndex !== undefined && note.spentInputIndex !== null
+      ? Number(note.spentInputIndex)
+      : null,
+    counterpartyL2Address: note.counterpartyL2Address ? getAddress(note.counterpartyL2Address) : null,
+    counterpartyDirection: note.counterpartyDirection ?? null,
+    counterpartyConfidence: note.counterpartyConfidence ?? null,
     bridgeCommitmentKey: note.bridgeCommitmentKey ? normalizeBytes32Hex(note.bridgeCommitmentKey) : null,
     bridgeNullifierKey: note.bridgeNullifierKey ? normalizeBytes32Hex(note.bridgeNullifierKey) : null,
   };
@@ -4886,15 +5959,28 @@ async function buildWalletNoteBridgeStatus({
   return {
     owner: note.owner,
     valueBaseUnits: note.value,
-    valueTokens: ethers.formatUnits(ethers.toBigInt(note.value), canonicalAssetDecimals),
+    valueTokens: note.value === null ? null : ethers.formatUnits(ethers.toBigInt(note.value), canonicalAssetDecimals),
     commitment: note.commitment,
     nullifier: note.nullifier,
+    encryptedNoteValue: note.encryptedNoteValue,
     walletStatus: note.status,
     bridgeCommitmentExists: commitmentExists,
     bridgeNullifierUsed: nullifierUsed,
     walletStatusMatchesBridge: commitmentExists && nullifierUsed === expectedNullifierUsed,
     sourceFunction: note.sourceFunction ?? null,
     sourceTxHash: note.sourceTxHash ?? null,
+    createdAtTxHash: note.createdAtTxHash ?? null,
+    createdAtBlockNumber: note.createdAtBlockNumber ?? null,
+    createdAtLogIndex: note.createdAtLogIndex ?? null,
+    createdByFunction: note.createdByFunction ?? null,
+    createdOutputIndex: note.createdOutputIndex ?? null,
+    spentAtTxHash: note.spentAtTxHash ?? null,
+    spentAtBlockNumber: note.spentAtBlockNumber ?? null,
+    spentByFunction: note.spentByFunction ?? null,
+    spentInputIndex: note.spentInputIndex ?? null,
+    counterpartyL2Address: note.counterpartyL2Address ?? null,
+    counterpartyDirection: note.counterpartyDirection ?? null,
+    counterpartyConfidence: note.counterpartyConfidence ?? null,
   };
 }
 
@@ -4912,8 +5998,8 @@ async function readBooleanStorageValueFromSnapshot({ snapshot, storageAddress, s
 }
 
 function compareNotesByValueDesc(left, right) {
-  const leftValue = ethers.toBigInt(left.value);
-  const rightValue = ethers.toBigInt(right.value);
+  const leftValue = left.value === null || left.value === undefined ? 0n : ethers.toBigInt(left.value);
+  const rightValue = right.value === null || right.value === undefined ? 0n : ethers.toBigInt(right.value);
   if (leftValue === rightValue) {
     return left.commitment.localeCompare(right.commitment);
   }
@@ -4922,13 +6008,28 @@ function compareNotesByValueDesc(left, right) {
 
 function buildTrackedNote(note, sourceFunction, sourceTxHash, bridgeKeys = {}) {
   const normalizedNote = normalizePlaintextNote(note);
+  const createdTxHash = bridgeKeys.createdAtTxHash ?? sourceTxHash ?? null;
+  const createdFunction = bridgeKeys.createdByFunction ?? sourceFunction ?? null;
   return {
     ...normalizedNote,
     commitment: normalizeBytes32Hex(computeNoteCommitment(normalizedNote)),
     nullifier: normalizeBytes32Hex(computeNullifier(normalizedNote)),
+    encryptedNoteValue: note.encryptedNoteValue ? normalizeEncryptedNoteValueWords(note.encryptedNoteValue) : null,
     status: "unused",
     sourceFunction,
     sourceTxHash,
+    createdAtTxHash: createdTxHash,
+    createdAtBlockNumber: bridgeKeys.createdAtBlockNumber ?? null,
+    createdAtLogIndex: bridgeKeys.createdAtLogIndex ?? null,
+    createdByFunction: createdFunction,
+    createdOutputIndex: bridgeKeys.createdOutputIndex ?? null,
+    spentAtTxHash: bridgeKeys.spentAtTxHash ?? null,
+    spentAtBlockNumber: bridgeKeys.spentAtBlockNumber ?? null,
+    spentByFunction: bridgeKeys.spentByFunction ?? null,
+    spentInputIndex: bridgeKeys.spentInputIndex ?? null,
+    counterpartyL2Address: bridgeKeys.counterpartyL2Address ? getAddress(bridgeKeys.counterpartyL2Address) : null,
+    counterpartyDirection: bridgeKeys.counterpartyDirection ?? null,
+    counterpartyConfidence: bridgeKeys.counterpartyConfidence ?? null,
     bridgeCommitmentKey: bridgeKeys.bridgeCommitmentKey
       ? normalizeBytes32Hex(bridgeKeys.bridgeCommitmentKey)
       : null,
@@ -4943,9 +6044,19 @@ function buildLifecycleTrackedOutputs({
   sourceFunction,
   sourceTxHash,
   bridgeCommitmentKeys,
+  sourceBlockNumber = null,
+  counterpartyL2Addresses = [],
+  counterpartyDirection = null,
 }) {
   return (outputNotes ?? []).map((note, index) => buildTrackedNote(note, sourceFunction, sourceTxHash, {
     bridgeCommitmentKey: bridgeCommitmentKeys?.[index] ?? null,
+    createdAtTxHash: sourceTxHash,
+    createdAtBlockNumber: sourceBlockNumber,
+    createdByFunction: sourceFunction,
+    createdOutputIndex: index,
+    counterpartyL2Address: counterpartyL2Addresses?.[index] ?? null,
+    counterpartyDirection,
+    counterpartyConfidence: counterpartyL2Addresses?.[index] ? "direct-local-metadata" : null,
   }));
 }
 
@@ -4958,13 +6069,11 @@ async function recoverWalletReceivedNotes({
   progressAction = null,
   fromGenesis = false,
 }) {
-  const resolvedNoteReceiveKeyMaterial = noteReceiveKeyMaterial ?? await deriveNoteReceiveKeyMaterial({
-    signer,
-    chainId: context.workspace.chainId,
-    channelId: context.workspace.channelId,
-    channelName: context.workspace.channelName,
-    account: signer.address,
-  });
+  const resolvedNoteReceiveKeyMaterial = noteReceiveKeyMaterial ?? {
+    privateKey: walletContext.wallet.noteReceivePrivateKey,
+    noteReceivePubKey: walletNoteReceivePubKey(walletContext),
+  };
+  requireWalletViewingCapability(walletContext);
   const recoveredDeliveryState = await recoverDeliveredNotesFromEventLogs({
     walletContext,
     context,
@@ -5064,12 +6173,22 @@ async function recoverDeliveredNotesFromEventLogs({
       owner: walletContext.wallet.l2Address,
       value: recoveredValue,
       salt: computeEncryptedNoteSalt(encryptedNoteValue),
+      encryptedNoteValue,
     });
     const commitment = normalizeBytes32Hex(computeNoteCommitment(plaintextNote));
     const nullifier = normalizeBytes32Hex(computeNullifier(plaintextNote));
-    const trackedNote = buildTrackedNote(plaintextNote, sourceFunction, log.transactionHash, {
+    const trackedNote = buildTrackedNote({
+      ...plaintextNote,
+      encryptedNoteValue,
+    }, sourceFunction, log.transactionHash, {
       bridgeCommitmentKey: derivePrivateStateControllerMappingStorageKey(commitment, commitmentExistsSlot),
       bridgeNullifierKey: derivePrivateStateControllerMappingStorageKey(nullifier, nullifierUsedSlot),
+      createdAtTxHash: log.transactionHash,
+      createdAtBlockNumber: log.blockNumber !== undefined ? Number(log.blockNumber) : null,
+      createdAtLogIndex: log.index ?? log.logIndex ?? null,
+      createdByFunction: sourceFunction,
+      counterpartyDirection: scheme === ENCRYPTED_NOTE_SCHEME_SELF_MINT ? "self-mint" : "received",
+      counterpartyConfidence: scheme === ENCRYPTED_NOTE_SCHEME_SELF_MINT ? "direct-local-metadata" : "unavailable",
     });
     const commitmentExists = await readBooleanStorageValueFromSnapshot({
       snapshot: context.currentSnapshot,
@@ -5420,7 +6539,7 @@ function snapshotRootForAddress(snapshot, storageAddress) {
   return snapshot.stateRoots[addressIndex];
 }
 
-function applyNoteLifecycleToWallet(walletContext, lifecycle, sourceFunction, sourceTxHash) {
+function applyNoteLifecycleToWallet(walletContext, lifecycle, sourceFunction, sourceTxHash, sourceBlockNumber = null) {
   for (const [index, inputNote] of lifecycle.inputs.entries()) {
     const trackedInput = buildTrackedNote(inputNote, sourceFunction, sourceTxHash);
     const existingUnusedNote = walletContext.wallet.notes.unused[trackedInput.commitment];
@@ -5434,12 +6553,26 @@ function applyNoteLifecycleToWallet(walletContext, lifecycle, sourceFunction, so
       sourceFunction,
       sourceTxHash,
       bridgeNullifierKey: lifecycle.inputNullifierKeys?.[index] ?? existingUnusedNote.bridgeNullifierKey ?? null,
+      spentAtTxHash: sourceTxHash,
+      spentAtBlockNumber: sourceBlockNumber,
+      spentByFunction: sourceFunction,
+      spentInputIndex: index,
+      counterpartyL2Address: lifecycle.spendCounterpartyL2Address ?? existingUnusedNote.counterpartyL2Address ?? null,
+      counterpartyDirection: lifecycle.spendCounterpartyDirection ?? existingUnusedNote.counterpartyDirection ?? null,
+      counterpartyConfidence: lifecycle.spendCounterpartyConfidence ?? existingUnusedNote.counterpartyConfidence ?? null,
     };
   }
 
   for (const [index, outputNote] of lifecycle.outputs.entries()) {
     const trackedOutput = buildTrackedNote(outputNote, sourceFunction, sourceTxHash, {
       bridgeCommitmentKey: lifecycle.outputCommitmentKeys?.[index] ?? null,
+      createdAtTxHash: sourceTxHash,
+      createdAtBlockNumber: sourceBlockNumber,
+      createdByFunction: sourceFunction,
+      createdOutputIndex: index,
+      counterpartyL2Address: lifecycle.outputCounterpartyL2Addresses?.[index] ?? null,
+      counterpartyDirection: lifecycle.outputCounterpartyDirection ?? null,
+      counterpartyConfidence: lifecycle.outputCounterpartyL2Addresses?.[index] ? "direct-local-metadata" : null,
     });
     if (trackedOutput.owner !== walletContext.wallet.l2Address) {
       continue;
@@ -5524,6 +6657,7 @@ function buildMintEncryptedOutputs({ wallet, values }) {
       owner: wallet.wallet.l2Address,
       value: ethers.toBigInt(value).toString(),
       salt: computeEncryptedNoteSalt(encryptedNoteValue),
+      encryptedNoteValue,
     });
   }
   return {
@@ -5581,6 +6715,7 @@ async function buildTransferNotesTemplatePayload({
       owner: recipient,
       value: ethers.toBigInt(outputAmounts[index]).toString(),
       salt,
+      encryptedNoteValue,
     });
   }
   return {
@@ -5589,6 +6724,7 @@ async function buildTransferNotesTemplatePayload({
     args: [transferOutputs, inputNotes],
     lifecycleInputs: inputNotes,
     lifecycleOutputs,
+    recipientAddresses,
   };
 }
 
@@ -5609,6 +6745,10 @@ function loadWalletUnusedInputNotes(walletContext, noteIds) {
   return noteIds.map((noteId) => {
     const trackedNote = walletContext.wallet.notes.unused[noteId];
     expect(trackedNote, `Unknown unused note commitment: ${noteId}.`);
+    expect(
+      trackedNote.owner && trackedNote.value !== null && trackedNote.salt,
+      `Note ${noteId} is encrypted-only. Import the wallet viewing key before spending it.`,
+    );
     return normalizePlaintextNote(trackedNote);
   });
 }
@@ -5957,6 +7097,7 @@ async function executeWalletDirectTemplateCommand({
 }) {
   emitProgress(operationName, "loading");
   const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
+  requireWalletSpendingCapability(wallet);
   const {
     txSubmitter,
     source: txSubmitterSource,
@@ -6098,7 +7239,16 @@ async function executeWalletTemplateSend({
 
   emitProgress(operationName, "persisting");
   wallet.wallet.l2Nonce = nonce + 1;
-  applyNoteLifecycleToWallet(wallet, noteLifecycle, functionName, receipt.hash);
+  if (functionName.startsWith("transferNotes")) {
+    noteLifecycle.spendCounterpartyL2Address = templatePayload.recipientAddresses?.[0] ?? null;
+    noteLifecycle.spendCounterpartyDirection = "sent";
+    noteLifecycle.spendCounterpartyConfidence = noteLifecycle.spendCounterpartyL2Address
+      ? "direct-local-metadata"
+      : null;
+    noteLifecycle.outputCounterpartyL2Addresses = templatePayload.recipientAddresses ?? [];
+    noteLifecycle.outputCounterpartyDirection = "sent";
+  }
+  applyNoteLifecycleToWallet(wallet, noteLifecycle, functionName, receipt.hash, receipt.blockNumber);
   context.currentSnapshot = nextSnapshot;
   persistWallet(wallet);
   await refreshPersistedWorkspaceAfterLocalTransaction({
@@ -6107,7 +7257,7 @@ async function executeWalletTemplateSend({
     receipt,
     progressAction: operationName,
   });
-  sealWalletOperationDir(operationDir, wallet.walletSecret);
+  sealWalletOperationDir(operationDir, walletOperationSealSecret(wallet));
 
   return {
     wallet,
@@ -6195,34 +7345,76 @@ async function loadJoinChannelContext({ args, network, provider }) {
   };
 }
 
-function loadWallet(walletName, walletSecret, networkName) {
+function loadWallet(walletName, networkName) {
+  const normalizedWalletName = requireWalletName({ wallet: walletName });
+  const normalizedNetworkName = requireNetworkName({ network: networkName });
+  const walletDir = selectedWalletEpochDir(normalizedWalletName, normalizedNetworkName);
+  return loadWalletFromDir({
+    walletName: normalizedWalletName,
+    networkName: normalizedNetworkName,
+    walletDir,
+  });
+}
+
+function loadWalletFromDir({ walletName, networkName, walletDir }) {
   const normalizedWalletName = requireWalletName({ wallet: walletName });
   const normalizedNetworkName = requireNetworkName({ network: networkName });
-  const walletDir = walletPath(normalizedWalletName, normalizedNetworkName);
   if (!walletConfigExists(walletDir)) {
     throw cliError(CLI_ERROR_CODES.UNKNOWN_WALLET, `Unknown wallet: ${normalizedWalletName} on ${normalizedNetworkName}.`);
   }
-  const rawWallet = readEncryptedWalletJson(walletConfigPath(walletDir), walletSecret);
+  const rawWallet = readJson(walletNotesMetadataPath(walletDir));
+  const spendingKey = readWalletKeySecretIfExists({
+    networkName: normalizedNetworkName,
+    walletName: normalizedWalletName,
+    keyKind: "spending",
+  });
+  const viewingKey = readWalletKeySecretIfExists({
+    networkName: normalizedNetworkName,
+    walletName: normalizedWalletName,
+    keyKind: "viewing",
+  });
+  if (spendingKey && walletSpendingKeyMatchesWallet(spendingKey.metadata, rawWallet)) {
+    rawWallet.l2PrivateKey = spendingKey.privateKey;
+    rawWallet.l2PublicKey = spendingKey.metadata?.l2PublicKey ?? rawWallet.l2PublicKey;
+  }
+  if (viewingKey && walletViewingKeyMatchesWallet(viewingKey.metadata, rawWallet)) {
+    rawWallet.noteReceivePrivateKey = viewingKey.privateKey;
+  }
   assertWalletHasRequiredKeys(rawWallet, normalizedWalletName);
   const wallet = normalizeWallet(rawWallet);
   assertWalletUsesChannelBoundDerivation(wallet, normalizedWalletName);
-  const restoredIdentity = restoreParticipantIdentityFromWallet(wallet);
-  expect(
-    wallet.l2Address === restoredIdentity.l2Address,
-    `Wallet ${normalizedWalletName} is internally inconsistent: stored keys do not match the stored L2 address.`,
-  );
+  if (wallet.l2PrivateKey) {
+    const restoredIdentity = restoreParticipantIdentityFromWallet(wallet);
+    expect(
+      wallet.l2Address === restoredIdentity.l2Address,
+      `Wallet ${normalizedWalletName} is internally inconsistent: stored keys do not match the stored L2 address.`,
+    );
+  }
+  hydrateWalletNotesWithViewingKey(wallet);
   const context = {
     walletName: normalizedWalletName,
     walletDir,
     wallet,
-    walletSecret,
+    walletSecret: wallet.l2PrivateKey ?? wallet.noteReceivePrivateKey ?? null,
   };
   return context;
 }
 
+function walletSpendingKeyMatchesWallet(metadata, wallet) {
+  return metadata?.l2Address
+    && ethers.toBigInt(getAddress(metadata.l2Address)) === ethers.toBigInt(getAddress(wallet.l2Address));
+}
+
+function walletViewingKeyMatchesWallet(metadata, wallet) {
+  return metadata?.noteReceivePubKey?.x
+    && ethers.toBigInt(normalizeBytes32Hex(metadata.noteReceivePubKey.x))
+      === ethers.toBigInt(normalizeBytes32Hex(wallet.noteReceivePubKeyX))
+    && Number(metadata.noteReceivePubKey.yParity) === Number(wallet.noteReceivePubKeyYParity);
+}
+
 function loadUnlockedWalletWithMetadata(args) {
   const networkName = requireNetworkName(args);
-  const wallet = loadWallet(requireWalletName(args), requireWalletSecret(args), networkName);
+  const wallet = loadWallet(requireWalletName(args), networkName);
   const walletMetadata = loadWalletMetadata(wallet.walletName, networkName);
   assertWalletMatchesMetadata(wallet, walletMetadata);
   expect(
@@ -6238,19 +7430,71 @@ function loadUnlockedWalletWithMetadata(args) {
   };
 }
 
+function readWalletKeySecretIfExists({ networkName, walletName, keyKind }) {
+  const secretPath = keyKind === "spending"
+    ? walletSpendingKeySecretPath(networkName, walletName)
+    : walletViewingKeySecretPath(networkName, walletName);
+  if (!fs.existsSync(secretPath)) {
+    return null;
+  }
+  const payload = JSON.parse(readSecretFile(secretPath, `${keyKind} key`));
+  validateWalletKeyPayload(payload, keyKind);
+  return payload;
+}
+
+function validateWalletKeyPayload(payload, keyKind) {
+  expect(payload?.format === WALLET_KEY_EXPORT_FORMAT, `Invalid ${keyKind} key file format.`);
+  expect(Number(payload.formatVersion) === WALLET_EXPORT_FORMAT_VERSION, `Unsupported ${keyKind} key file version.`);
+  expect(payload.keyKind === keyKind, `Expected ${keyKind} key file, received ${payload.keyKind}.`);
+  expect(typeof payload.privateKey === "string" && payload.privateKey.length > 0, `Missing ${keyKind} private key.`);
+  expect(payload.metadata && typeof payload.metadata === "object", `Missing ${keyKind} key metadata.`);
+}
+
+function hydrateWalletNotesWithViewingKey(wallet) {
+  if (!wallet.noteReceivePrivateKey) {
+    return;
+  }
+  const noteGroups = [wallet.notes?.unused ?? {}, wallet.notes?.spent ?? {}];
+  for (const notes of noteGroups) {
+    for (const note of Object.values(notes)) {
+      if (!note.encryptedNoteValue || note.value !== null) {
+        continue;
+      }
+      try {
+        const { scheme } = unpackEncryptedNoteValue(note.encryptedNoteValue);
+        let value;
+        if (scheme === ENCRYPTED_NOTE_SCHEME_TRANSFER) {
+          value = decryptEncryptedNoteValue({
+            encryptedValue: note.encryptedNoteValue,
+            noteReceivePrivateKey: wallet.noteReceivePrivateKey,
+            chainId: wallet.chainId,
+            channelId: wallet.channelId,
+            owner: wallet.l2Address,
+          });
+        } else if (scheme === ENCRYPTED_NOTE_SCHEME_SELF_MINT) {
+          value = decryptMintEncryptedNoteValue({
+            encryptedValue: note.encryptedNoteValue,
+            noteReceivePrivateKey: wallet.noteReceivePrivateKey,
+            chainId: wallet.chainId,
+            channelId: wallet.channelId,
+            owner: wallet.l2Address,
+          });
+        } else {
+          continue;
+        }
+        note.owner = wallet.l2Address;
+        note.value = ethers.toBigInt(value).toString();
+        note.salt = computeEncryptedNoteSalt(note.encryptedNoteValue);
+      } catch {
+        // Keep encrypted-only note records readable even when the local viewing key cannot decrypt them.
+      }
+    }
+  }
+  wallet.notes = normalizeWallet(wallet).notes;
+}
+
 function assertWalletHasRequiredKeys(wallet, walletName) {
-  expect(
-    typeof wallet.l1PrivateKey === "string" && wallet.l1PrivateKey.length > 0,
-    `Wallet ${walletName} is missing the stored L1 private key.`,
-  );
-  expect(
-    typeof wallet.l2PrivateKey === "string" && wallet.l2PrivateKey.length > 0,
-    `Wallet ${walletName} is missing the stored L2 private key.`,
-  );
-  expect(
-    typeof wallet.l2PublicKey === "string" && wallet.l2PublicKey.length > 0,
-    `Wallet ${walletName} is missing the stored L2 public key.`,
-  );
+  expect(wallet.walletFormatVersion !== undefined, `Wallet ${walletName} is missing walletFormatVersion.`);
 }
 
 function assertWalletUsesChannelBoundDerivation(wallet, walletName) {
@@ -6271,6 +7515,13 @@ function assertWalletUsesChannelBoundDerivation(wallet, walletName) {
 }
 
 function restoreParticipantIdentityFromWallet(wallet) {
+  if (!wallet.l2PrivateKey) {
+    return {
+      l2PrivateKey: null,
+      l2PublicKey: wallet.l2PublicKey ? Uint8Array.from(ethers.getBytes(wallet.l2PublicKey)) : null,
+      l2Address: getAddress(wallet.l2Address),
+    };
+  }
   const l2PrivateKey = Uint8Array.from(ethers.getBytes(wallet.l2PrivateKey));
   const l2PublicKey = Uint8Array.from(ethers.getBytes(wallet.l2PublicKey));
   const l2Address = getAddress(fromEdwardsToAddress(l2PublicKey).toString());
@@ -6282,7 +7533,14 @@ function restoreParticipantIdentityFromWallet(wallet) {
 }
 
 function restoreWalletSigner(walletContext, provider) {
-  return new Wallet(normalizePrivateKey(walletContext.wallet.l1PrivateKey), provider);
+  const privateKey = findAccountPrivateKeyForAddress(walletContext.wallet.network, walletContext.wallet.l1Address);
+  if (privateKey) {
+    return new Wallet(privateKey, provider);
+  }
+  return {
+    address: getAddress(walletContext.wallet.l1Address),
+    provider,
+  };
 }
 
 function restoreWalletParticipant(walletContext, provider) {
@@ -6292,6 +7550,85 @@ function restoreWalletParticipant(walletContext, provider) {
   };
 }
 
+function requireWalletOwnerSigner(walletContext, provider) {
+  const signer = restoreWalletSigner(walletContext, provider);
+  expect(
+    typeof signer.privateKey === "string",
+    [
+      `Missing local account secret for wallet owner ${walletContext.wallet.l1Address}.`,
+      "Import the matching account secret or use a command-specific transaction submitter where supported.",
+    ].join(" "),
+  );
+  return signer;
+}
+
+function requireWalletSpendingCapability(walletContext) {
+  expect(
+    walletContext.wallet.l2PrivateKey,
+    [
+      `Wallet ${walletContext.walletName} is missing its spending key.`,
+      "Import it with wallet import spending-key before commands that spend notes or change L2 channel accounting state.",
+    ].join(" "),
+  );
+}
+
+function requireWalletViewingCapability(walletContext) {
+  expect(
+    walletContext.wallet.noteReceivePrivateKey,
+    [
+      `Wallet ${walletContext.walletName} is missing its viewing key.`,
+      "Import it with wallet import viewing-key before commands that decrypt or refresh received notes.",
+    ].join(" "),
+  );
+}
+
+function requireActiveWalletLifecycle(walletContext, commandName) {
+  expect(
+    walletContext.wallet.lifecycleStatus !== "exited",
+    [
+      `${commandName} cannot operate on exited wallet epoch ${walletContext.wallet.walletEpochId ?? "unknown"}.`,
+      "Exited wallet epochs are read-only. Use wallet get-notes or wallet get-notes --export-evidence for historical disclosure.",
+    ].join(" "),
+  );
+}
+
+function walletOperationSealSecret(walletContext) {
+  const secret = walletContext.wallet.l2PrivateKey
+    ?? walletContext.wallet.noteReceivePrivateKey
+    ?? findAccountPrivateKeyForAddress(walletContext.wallet.network, walletContext.wallet.l1Address);
+  expect(
+    secret,
+    `Wallet ${walletContext.walletName} needs a local key to seal operation artifacts.`,
+  );
+  return secret;
+}
+
+function findAccountPrivateKeyForAddress(networkName, l1Address) {
+  const accountsRoot = path.join(secretRoot, requireNetworkName({ network: networkName }), "accounts");
+  if (!fs.existsSync(accountsRoot)) {
+    return null;
+  }
+  for (const entry of fs.readdirSync(accountsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const privateKeyPath = path.join(accountsRoot, entry.name, "private-key");
+    if (!fs.existsSync(privateKeyPath)) {
+      continue;
+    }
+    try {
+      const privateKey = normalizePrivateKey(readSecretFile(privateKeyPath, "--account"));
+      const signer = new Wallet(privateKey);
+      if (ethers.toBigInt(getAddress(signer.address)) === ethers.toBigInt(getAddress(l1Address))) {
+        return privateKey;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
 function loadBridgeResources({ chainId }) {
   const bridgeDeploymentPath = defaultBridgeDeploymentPath(chainId);
   const bridgeDeployment = readJson(bridgeDeploymentPath);
@@ -6309,11 +7646,11 @@ function loadBridgeResources({ chainId }) {
 function loadWalletMetadata(walletName, networkName) {
   const normalizedWalletName = requireWalletName({ wallet: walletName });
   const normalizedNetworkName = requireNetworkName({ network: networkName });
-  const walletDir = walletPath(normalizedWalletName, normalizedNetworkName);
+  const walletDir = selectedWalletEpochDir(normalizedWalletName, normalizedNetworkName);
   if (!walletConfigExists(walletDir)) {
     throw cliError(CLI_ERROR_CODES.UNKNOWN_WALLET, `Unknown wallet: ${normalizedWalletName} on ${normalizedNetworkName}.`);
   }
-  const metadataPath = walletMetadataPath(walletDir);
+  const metadataPath = walletNotesMetadataPath(walletDir);
   if (!fs.existsSync(metadataPath)) {
     throw new Error(`Wallet ${normalizedWalletName} is missing unencrypted metadata at ${metadataPath}.`);
   }
@@ -6342,14 +7679,14 @@ function assertWalletMatchesMetadata(walletContext, walletMetadata) {
     walletContext.wallet.network === walletMetadata.network,
     [
       `Wallet ${walletContext.walletName} metadata network (${walletMetadata.network}) does not match`,
-      `the encrypted wallet network (${walletContext.wallet.network}).`,
+      `the wallet note metadata network (${walletContext.wallet.network}).`,
     ].join(" "),
   );
   expect(
     walletContext.wallet.channelName === walletMetadata.channelName,
     [
       `Wallet ${walletContext.walletName} metadata channelName (${walletMetadata.channelName}) does not match`,
-      `the encrypted wallet channel (${walletContext.wallet.channelName}).`,
+      `the wallet note metadata channel (${walletContext.wallet.channelName}).`,
     ].join(" "),
   );
 }
@@ -7535,6 +8872,7 @@ const OUTPUT_BYTES32_SCALAR_KEYS = new Set([
   "commitment",
   "currentRootVectorHash",
   "currentUserKey",
+  "createdAtTxHash",
   "emittedRootVectorHash",
   "ephemeralPubKeyX",
   "hash",
@@ -7548,6 +8886,7 @@ const OUTPUT_BYTES32_SCALAR_KEYS = new Set([
   "rootVectorHash",
   "salt",
   "sourceTxHash",
+  "spentAtTxHash",
   "topic0",
   "transactionHash",
   "txHash",
@@ -7744,6 +9083,13 @@ function parseArgs(argv) {
     && parsed.positional[1]
   ) {
     parsed.command = `${parsed.command}-${parsed.positional[1]}`;
+    if (
+      parsed.positional[0] === "wallet"
+      && (parsed.positional[1] === "export" || parsed.positional[1] === "import")
+      && parsed.positional[2]
+    ) {
+      parsed.command = `${parsed.command}-${parsed.positional[2]}`;
+    }
     parsed.positional = [parsed.command];
   }
   return parsed;
@@ -7773,18 +9119,6 @@ function parseTokenAmount(value, decimals) {
   }
 }
 
-function requireWalletSecret(args) {
-  if (args.wallet !== undefined && args.network !== undefined) {
-    return resolveWalletSecretForName({
-      networkName: requireNetworkName(args),
-      walletName: requireWalletName(args),
-    });
-  }
-  throw new Error(
-    "Missing --wallet and --network. Wallet commands use the wallet-local default secret file.",
-  );
-}
-
 function requireArg(value, label) {
   if (value === undefined || value === null || value === "") {
     throw new Error(`Missing ${label}.`);
@@ -7849,6 +9183,13 @@ function requireL1Signer(args, provider) {
 
 function resolveTxSubmitterSigner({ args, ownerSigner, provider }) {
   if (args.txSubmitter === undefined) {
+    expect(
+      typeof ownerSigner.privateKey === "string",
+      [
+        `Missing local account secret for wallet owner ${ownerSigner.address}.`,
+        "Pass --tx-submitter <ACCOUNT> or import the matching local account secret.",
+      ].join(" "),
+    );
     return {
       txSubmitter: ownerSigner,
       source: "wallet-owner",
@@ -7883,68 +9224,35 @@ function resolveStandalonePrivateKeySource(args) {
   ));
 }
 
-function resolveWalletSecretForName({ networkName, walletName }) {
-  return resolveWalletDefaultSecret(networkName, walletName);
-}
-
-function resolvedWalletSecretSource(args) {
-  if (args.walletSecretPath !== undefined) return "wallet-secret-path";
-  return "wallet-default";
-}
-
-function resolvedWalletSecretFile(networkName, walletName) {
-  return walletSecretPath(networkName, walletName);
-}
-
-function resolveWalletDefaultSecret(networkName, walletName) {
-  const secretPath = walletSecretPath(networkName, walletName);
-  if (!fs.existsSync(secretPath)) {
-    throw cliError(
-      CLI_ERROR_CODES.MISSING_WALLET_SECRET,
-      [
-        `Missing wallet default secret file: ${secretPath}.`,
-        "Run channel join with --wallet-secret-path before wallet commands.",
-      ].join(" "),
-    );
-  }
-  return readSecretFile(secretPath, "wallet default secret file");
-}
-
 function prepareJoinWalletSecretForName({
   args,
   networkName,
   walletName,
 }) {
-  const secretPath = walletSecretPath(networkName, walletName);
   const { channelName } = parseWalletName(walletName);
-  const walletDir = walletPath(walletName, networkName);
+  const walletRoot = walletRootPath(walletName, networkName);
+  const walletIndex = fs.existsSync(walletRoot)
+    ? requireWalletIndex({ walletRoot, walletName, networkName })
+    : null;
+  const activeEpoch = walletIndex ? activeWalletEpoch(walletIndex) : null;
   expect(
-    !walletConfigExists(walletDir),
+    !activeEpoch,
     [
       `Wallet ${walletName} already exists on ${networkName}.`,
-      "channel join always creates a new local wallet.",
-      "If this wallet was previously exited on-chain, run",
-      `wallet recover-workspace --channel-name ${channelName} --network ${networkName} --account ${args.account ?? "<ACCOUNT>"}`,
-      "once to remove the stale local wallet, then retry channel join.",
+      "channel join creates a new active wallet epoch.",
       "Use normal wallet commands for an existing active local wallet.",
+      `For exited history, keep using wallet recover-workspace --channel-name ${channelName} --network ${networkName} --account ${args.account ?? "<ACCOUNT>"}.`,
     ].join(" "),
   );
   const sourcePath = path.resolve(String(requireArg(args.walletSecretPath, "--wallet-secret-path")));
-  const canonicalPath = path.resolve(secretPath);
-  const walletSecret = sourcePath === canonicalPath
-    ? readSecretFile(sourcePath, "--wallet-secret-path")
-    : readImportSecretSourceFile(sourcePath, "--wallet-secret-path");
-  if (sourcePath !== canonicalPath) {
-    writeSecretFile(canonicalPath, walletSecret);
-  }
-  return walletSecret;
+  return readImportSecretSourceFile(sourcePath, "--wallet-secret-path");
 }
 
 function channelWorkspacePath(networkName, name) {
   return workspaceDirForName(workspaceRoot, networkName, name);
 }
 
-function walletPath(name, networkName) {
+function walletRootPath(name, networkName) {
   const walletName = String(name);
   const { channelName } = parseWalletName(walletName);
   const normalizedNetworkName = requireNetworkName({ network: networkName });
@@ -7952,6 +9260,91 @@ function walletPath(name, networkName) {
   return walletDirForName(workspaceWalletsDir(workspaceDir), walletName);
 }
 
+function selectedWalletEpochDir(name, networkName) {
+  const root = walletRootPath(name, networkName);
+  const walletName = requireWalletName({ wallet: name });
+  const normalizedNetworkName = requireNetworkName({ network: networkName });
+  expect(
+    fs.existsSync(root),
+    cliError(CLI_ERROR_CODES.UNKNOWN_WALLET, `Unknown wallet: ${walletName} on ${normalizedNetworkName}.`),
+  );
+  const index = requireWalletIndex({ walletRoot: root, walletName, networkName: normalizedNetworkName });
+  const selected = selectedWalletEpoch(index, walletName, normalizedNetworkName);
+  return walletEpochPathFromRoot(root, selected.epochId);
+}
+
+function walletEpochPath(walletName, networkName, epochId) {
+  return walletEpochPathFromRoot(walletRootPath(walletName, networkName), epochId);
+}
+
+function walletEpochPathFromRoot(walletRoot, epochId) {
+  return path.join(walletRoot, "epochs", slugifyPathComponent(epochId));
+}
+
+function walletIndexMetadataPath(walletRoot) {
+  return path.join(walletRoot, "wallet-index.metadata.json");
+}
+
+function readWalletIndexIfExists(walletRoot) {
+  const indexPath = walletIndexMetadataPath(walletRoot);
+  if (!fs.existsSync(indexPath)) {
+    return null;
+  }
+  return normalizeWalletIndex(readJson(indexPath));
+}
+
+function requireWalletIndex({ walletRoot, walletName, networkName }) {
+  const index = readWalletIndexIfExists(walletRoot);
+  expect(index, currentWalletIndexRequiredMessage({ walletName, networkName, walletRoot }));
+  return index;
+}
+
+function selectedWalletEpoch(index, walletName, networkName) {
+  const selected = activeWalletEpoch(index) ?? latestWalletEpoch(index);
+  expect(
+    selected,
+    `Wallet ${walletName} on ${networkName} has no epoch entries. Run wallet recover-workspace to rebuild the workspace in the current format.`,
+  );
+  return selected;
+}
+
+function currentWalletIndexRequiredMessage({ walletName, networkName, walletRoot }) {
+  const channelName = parseWalletName(walletName).channelName;
+  return [
+    `Current wallet index is required for ${walletName} on ${networkName}: ${walletRoot}.`,
+    `Run wallet recover-workspace --channel-name ${channelName} --network ${networkName} --account <ACCOUNT> to rebuild the workspace.`,
+  ].join(" ");
+}
+
+function activeWalletEpoch(index) {
+  const activeEpochId = index?.activeEpochId ?? null;
+  return activeEpochId
+    ? (index.epochs ?? []).find((epoch) => epoch.epochId === activeEpochId && epoch.lifecycleStatus === "active") ?? null
+    : null;
+}
+
+function latestWalletEpoch(index) {
+  const epochs = [...(index?.epochs ?? [])];
+  epochs.sort((left, right) =>
+    Number(right.joinedAtBlockNumber ?? 0) - Number(left.joinedAtBlockNumber ?? 0)
+    || String(right.epochId).localeCompare(String(left.epochId)));
+  return epochs[0] ?? null;
+}
+
+function normalizeWalletIndex(index) {
+  expect(index?.format === WALLET_INDEX_FORMAT, "Invalid wallet index format.");
+  expect(Number(index.formatVersion) === WALLET_INDEX_FORMAT_VERSION, "Unsupported wallet index format version.");
+  expect(Array.isArray(index.epochs), "Wallet index is missing epochs[].");
+  return {
+    ...index,
+    epochs: index.epochs.map((epoch) => ({
+      ...epoch,
+      epochId: String(epoch.epochId),
+      lifecycleStatus: epoch.lifecycleStatus === "active" ? "active" : "exited",
+    })),
+  };
+}
+
 function accountPrivateKeyPath(networkName, accountName) {
   return path.join(
     secretRoot,
@@ -7986,6 +9379,24 @@ function walletSecretPath(networkName, walletName) {
   );
 }
 
+function walletViewingKeySecretPath(networkName, walletName) {
+  return walletKeySecretPath(networkName, walletName, "viewing");
+}
+
+function walletSpendingKeySecretPath(networkName, walletName) {
+  return walletKeySecretPath(networkName, walletName, "spending");
+}
+
+function walletKeySecretPath(networkName, walletName, keyKind) {
+  return path.join(
+    secretRoot,
+    requireNetworkName({ network: networkName }),
+    "wallets",
+    slugifyPathComponent(walletName),
+    `${keyKind}.key`,
+  );
+}
+
 function resolveWalletPathCandidates(walletName) {
   if (!fs.existsSync(workspaceRoot)) {
     return [];
@@ -8007,7 +9418,8 @@ function resolveWalletPathCandidates(walletName) {
       "wallets",
       walletSlug,
     );
-    if (walletConfigExists(candidate)) {
+    if (fs.existsSync(candidate)) {
+      requireWalletIndex({ walletRoot: candidate, walletName, networkName: entry.name });
       candidates.push(candidate);
     }
   }
@@ -8038,15 +9450,30 @@ function listLocalWallets({ networkFilter = null, channelFilter = null } = {}) {
         if (!walletEntry.isDirectory()) {
           continue;
         }
-        const walletDir = path.join(walletsDir, walletEntry.name);
+        const walletRoot = path.join(walletsDir, walletEntry.name);
+        const walletIndex = requireWalletIndex({
+          walletRoot,
+          walletName: walletEntry.name,
+          networkName: networkEntry.name,
+        });
+        const selectedEpoch = selectedWalletEpoch(walletIndex, walletEntry.name, networkEntry.name);
+        const walletDir = walletEpochPathFromRoot(walletRoot, selectedEpoch.epochId);
         wallets.push({
           wallet: walletEntry.name,
           network: networkEntry.name,
           channelName: channelEntry.name,
           walletDir,
-          metadataPath: walletMetadataPath(walletDir),
-          hasMetadata: fs.existsSync(walletMetadataPath(walletDir)),
-          hasEncryptedWallet: walletConfigExists(walletDir),
+          walletRoot,
+          activeEpochId: walletIndex?.activeEpochId ?? null,
+          selectedEpochId: selectedEpoch?.epochId ?? null,
+          lifecycleStatus: selectedEpoch.lifecycleStatus,
+          epochs: walletIndex.epochs,
+          metadataPath: walletNotesMetadataPath(walletDir),
+          hasMetadata: fs.existsSync(walletNotesMetadataPath(walletDir)),
+          hasEncryptedWallet: false,
+          hasBackupMetadata: walletConfigExists(walletDir),
+          hasViewingKey: fs.existsSync(walletViewingKeySecretPath(networkEntry.name, walletEntry.name)),
+          hasSpendingKey: fs.existsSync(walletSpendingKeySecretPath(networkEntry.name, walletEntry.name)),
         });
       }
     }
@@ -8068,14 +9495,14 @@ function privateStateCliDataRoot() {
 
 function resolveExportWalletInfo({ networkName, walletName }) {
   resolveCliNetwork(networkName);
-  const walletDir = walletPath(walletName, networkName);
+  const walletDir = selectedWalletEpochDir(walletName, networkName);
   return {
     wallet: walletName,
     network: networkName,
     channelName: parseWalletName(walletName).channelName,
     walletDir,
-    metadataPath: walletMetadataPath(walletDir),
-    hasMetadata: fs.existsSync(walletMetadataPath(walletDir)),
+    metadataPath: walletNotesMetadataPath(walletDir),
+    hasMetadata: fs.existsSync(walletNotesMetadataPath(walletDir)),
     hasEncryptedWallet: walletConfigExists(walletDir),
   };
 }
@@ -8083,16 +9510,12 @@ function resolveExportWalletInfo({ networkName, walletName }) {
 function normalizeExportWalletInfo(walletInfo) {
   const wallet = requireWalletName({ wallet: walletInfo.wallet });
   const network = requireNetworkName({ network: walletInfo.network });
-  const walletDir = walletInfo.walletDir ?? walletPath(wallet, network);
-  const metadataPath = walletMetadataPath(walletDir);
-  const encryptedWalletPath = walletConfigPath(walletDir);
+  const walletDir = walletInfo.walletDir ?? selectedWalletEpochDir(wallet, network);
+  const metadataPath = walletNotesMetadataPath(walletDir);
   const metadata = readJsonIfExists(metadataPath);
   const channelName = metadata?.channelName ?? walletInfo.channelName ?? parseWalletName(wallet).channelName;
-  const walletSecret = walletSecretPath(network, wallet);
 
-  expect(fs.existsSync(encryptedWalletPath), `Wallet export cannot find encrypted wallet file: ${encryptedWalletPath}.`);
   expect(fs.existsSync(metadataPath), `Wallet export cannot find wallet metadata file: ${metadataPath}.`);
-  expect(fs.existsSync(walletSecret), `Wallet export cannot find wallet-local secret file: ${walletSecret}.`);
   expect(
     metadata.network === network,
     `Wallet export metadata network ${metadata.network} does not match ${network}.`,
@@ -8107,18 +9530,27 @@ function normalizeExportWalletInfo(walletInfo) {
     channelName,
     wallet,
     walletDir,
-    walletSecretPath: walletSecret,
   };
 }
 
-function walletExportFilePaths(walletInfo, { includeNotes }) {
+function walletBackupExportFilePaths(walletInfo) {
   const walletFiles = [
-    walletInfo.walletSecretPath,
-    walletConfigPath(walletInfo.walletDir),
-    walletMetadataPath(walletInfo.walletDir),
+    walletNotesMetadataPath(walletInfo.walletDir),
   ];
-  if (!includeNotes) {
-    return walletFiles;
+  const walletRoot = walletRootPath(walletInfo.wallet, walletInfo.network);
+  requireWalletIndex({
+    walletRoot,
+    walletName: walletInfo.wallet,
+    networkName: walletInfo.network,
+  });
+  walletFiles.push(walletIndexMetadataPath(walletRoot));
+  for (const metadataPath of [
+    walletViewingKeyMetadataPath(walletInfo.walletDir),
+    walletSpendingKeyMetadataPath(walletInfo.walletDir),
+  ]) {
+    if (fs.existsSync(metadataPath)) {
+      walletFiles.push(metadataPath);
+    }
   }
 
   const workspaceDir = channelWorkspacePath(walletInfo.network, walletInfo.channelName);
@@ -8134,8 +9566,8 @@ function walletExportFilePaths(walletInfo, { includeNotes }) {
     expect(
       fs.existsSync(filePath),
       [
-        `wallet export --include-notes requires channel workspace cache file: ${filePath}.`,
-        "Run channel recover-workspace first, or export without --include-notes.",
+        `wallet export backup requires channel workspace cache file: ${filePath}.`,
+        "Run channel recover-workspace first.",
       ].join(" "),
     );
   }
@@ -8150,14 +9582,13 @@ function archivePathForLocalCliFile(filePath) {
 }
 
 function validateWalletExportManifest(manifest) {
-  expect(manifest?.format === WALLET_EXPORT_FORMAT, "Wallet import ZIP has an unsupported format.");
+  expect(manifest?.format === WALLET_BACKUP_EXPORT_FORMAT, "Wallet import ZIP has an unsupported format.");
   expect(
     Number(manifest.formatVersion) === WALLET_EXPORT_FORMAT_VERSION,
     `Wallet import ZIP format version ${manifest?.formatVersion} is not supported.`,
   );
   expect(Array.isArray(manifest.files), "Wallet import ZIP manifest is missing files[].");
   expect(Array.isArray(manifest.wallets), "Wallet import ZIP manifest is missing wallets[].");
-  expect(typeof manifest.includeNotes === "boolean", "Wallet import ZIP manifest is missing includeNotes.");
   expect(manifest.wallets.length > 0, "Wallet import ZIP manifest does not list any wallets.");
   const uniqueFiles = new Set(manifest.files);
   expect(uniqueFiles.size === manifest.files.length, "Wallet import ZIP manifest contains duplicate file paths.");
@@ -8166,9 +9597,18 @@ function validateWalletExportManifest(manifest) {
     validateWalletArchivePath(filePath);
   }
   for (const wallet of manifest.wallets) {
-    requireNetworkName({ network: wallet.network });
-    requireWalletName({ wallet: wallet.wallet });
+    const networkName = requireNetworkName({ network: wallet.network });
+    const walletName = requireWalletName({ wallet: wallet.wallet });
     requireArg(wallet.channelName, "wallets[].channelName");
+    const walletRoot = walletRootPath(walletName, networkName);
+    const expectedIndexPath = archivePathForLocalCliFile(walletIndexMetadataPath(walletRoot));
+    expect(
+      uniqueFiles.has(expectedIndexPath),
+      [
+        "Wallet import ZIP must include the current wallet index metadata.",
+        "Run wallet recover-workspace with the current CLI, then export a new backup.",
+      ].join(" "),
+    );
   }
 }
 
@@ -8179,8 +9619,8 @@ function validateWalletArchivePath(archivePath) {
   expect(!path.posix.isAbsolute(archivePath), `Wallet import ZIP path must be relative: ${archivePath}.`);
   expect(path.posix.normalize(archivePath) === archivePath, `Wallet import ZIP path is not normalized: ${archivePath}.`);
   expect(
-    archivePath.startsWith("secrets/") || archivePath.startsWith("workspace/"),
-    `Wallet import ZIP path must start with secrets/ or workspace/: ${archivePath}.`,
+    archivePath.startsWith("workspace/"),
+    `Wallet backup import ZIP path must start with workspace/: ${archivePath}.`,
   );
 }
 
@@ -8191,9 +9631,9 @@ function expectPathWithinRoot(targetPath, rootPath, message) {
 
 function applyImportedWalletFileMode(archivePath, targetPath) {
   if (
-    archivePath.startsWith("secrets/")
-    || archivePath.endsWith("/wallet.json")
-    || archivePath.endsWith("/wallet.metadata.json")
+    archivePath.endsWith("/wallet-notes.metadata.json")
+    || archivePath.endsWith("/wallet-viewing-key.metadata.json")
+    || archivePath.endsWith("/wallet-spending-key.metadata.json")
   ) {
     protectSecretFile(targetPath, `imported wallet file ${archivePath}`);
   }
@@ -8215,16 +9655,20 @@ function channelWorkspaceOperationsPath(workspaceDir) {
   return path.join(channelDataPath(workspaceDir), "operations");
 }
 
-function walletConfigPath(walletDir) {
-  return path.join(walletDir, "wallet.json");
+function walletNotesMetadataPath(walletDir) {
+  return path.join(walletDir, "wallet-notes.metadata.json");
+}
+
+function walletViewingKeyMetadataPath(walletDir) {
+  return path.join(walletDir, "wallet-viewing-key.metadata.json");
 }
 
-function walletMetadataPath(walletDir) {
-  return walletMetadataPathForDir(walletDir);
+function walletSpendingKeyMetadataPath(walletDir) {
+  return path.join(walletDir, "wallet-spending-key.metadata.json");
 }
 
 function walletConfigExists(walletDir) {
-  return fs.existsSync(walletConfigPath(walletDir));
+  return fs.existsSync(walletNotesMetadataPath(walletDir));
 }
 
 const COMMAND_ARG_SCHEMAS = Object.freeze(
@@ -8266,21 +9710,9 @@ function assertAllowedCommandKeys(args, commandName, allowedKeys, acceptedUsage)
   );
 }
 
-function assertWalletSecretArgs(args, commandName, extraOptionKeys = [], acceptedUsage = "--wallet and --network") {
-  if (COMMAND_ARG_SCHEMAS[commandName]) {
-    assertAllowedCommandSchema(args, commandName);
-    return;
-  }
-  assertAllowedCommandKeys(
-    args,
-    commandName,
-    new Set(["command", "positional", "wallet", "network", ...extraOptionKeys]),
-    acceptedUsage,
-  );
-}
-
 function assertWalletChannelMoveArgs(args, commandName) {
-  assertWalletSecretArgs(args, commandName, ["amount"], "--wallet, --network, and --amount");
+  assertAllowedCommandSchema(args, commandName);
+  assertActionImpactArg(args, COMMAND_ARG_SCHEMAS[commandName]?.label ?? commandName);
 }
 
 function assertInstallZkEvmArgs(args) {
@@ -8332,12 +9764,17 @@ function assertTransactionFeesArgs(args) {
   assertAllowedCommandSchema(args, "help-transaction-fees");
 }
 
+function assertInvestigatorArgs(args) {
+  assertAllowedCommandSchema(args, "investigator");
+}
+
 function assertAccountImportArgs(args) {
   assertAllowedCommandSchema(args, "account-import");
 }
 
 function assertMintNotesArgs(args) {
   assertAllowedCommandSchema(args, "wallet-mint-notes");
+  assertActionImpactArg(args, "wallet mint-notes");
   assertTxSubmitterArg(args);
   parseAmountVector(args.amounts, {
     allowZeroEntries: true,
@@ -8347,12 +9784,14 @@ function assertMintNotesArgs(args) {
 
 function assertRedeemNotesArgs(args) {
   assertAllowedCommandSchema(args, "wallet-redeem-notes");
+  assertActionImpactArg(args, "wallet redeem-notes");
   assertTxSubmitterArg(args);
   selectRedeemNotesMethod(parseNoteIdVector(args.noteIds).length);
 }
 
 function assertTransferNotesArgs(args) {
   assertAllowedCommandSchema(args, "wallet-transfer-notes");
+  assertActionImpactArg(args, "wallet transfer-notes");
   assertTxSubmitterArg(args);
   const noteIds = parseNoteIdVector(args.noteIds);
   const recipients = parseRecipientVector(args.recipients);
@@ -8373,8 +9812,34 @@ 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.`);
+  }
+  if (args.acknowledgeActionImpact !== true && !process.stdin.isTTY) {
+    throw new Error(`${commandName} requires --acknowledge-action-impact after reviewing the action-impact warning.`);
+  }
+}
+
 function assertWalletGetNotesArgs(args) {
-  assertWalletSecretArgs(args, "wallet-get-notes");
+  assertAllowedCommandSchema(args, "wallet-get-notes");
+  if (args.exportEvidence !== undefined) {
+    requireArg(args.exportEvidence, "--export-evidence");
+    if (args.acknowledgeFullNotePlaintextExport !== true) {
+      throw new Error(
+        "wallet get-notes --export-evidence requires --acknowledge-full-note-plaintext-export.",
+      );
+    }
+  }
+  if (
+    args.acknowledgeFullNotePlaintextExport !== undefined
+    && args.acknowledgeFullNotePlaintextExport !== true
+  ) {
+    throw new Error("wallet get-notes option --acknowledge-full-note-plaintext-export does not accept a value.");
+  }
 }
 
 function assertCreateChannelArgs(args) {
@@ -8408,18 +9873,15 @@ function assertPublishWorkspaceMirrorArgs(args) {
 
 function assertDepositBridgeArgs(args) {
   assertAllowedCommandSchema(args, "account-deposit-bridge");
+  assertActionImpactArg(args, "account deposit-bridge");
 }
 
 function assertAccountGetBridgeFundArgs(args) {
   assertAllowedCommandSchema(args, "account-get-bridge-fund");
 }
 
-function assertExplicitSignerCommandArgs(args, commandName) {
-  assertAllowedCommandSchema(args, commandName);
-}
-
 function assertRecoverWalletArgs(args) {
-  assertExplicitSignerCommandArgs(args, "wallet-recover-workspace");
+  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.");
   }
@@ -8427,10 +9889,11 @@ function assertRecoverWalletArgs(args) {
 
 function assertJoinChannelArgs(args) {
   assertAllowedCommandSchema(args, "channel-join");
+  assertActionImpactArg(args, "channel join");
 }
 
 function assertWalletGetMetaArgs(args) {
-  assertWalletSecretArgs(args, "wallet-get-meta");
+  assertAllowedCommandSchema(args, "wallet-get-meta");
 }
 
 function assertAccountGetL1AddressArgs(args) {
@@ -8447,48 +9910,45 @@ function assertListLocalWalletsArgs(args) {
   assertAllowedCommandSchema(args, "wallet-list");
 }
 
-function assertWalletExportArgs(args) {
-  assertAllowedCommandSchema(args, "wallet-export");
-  assertFlagOption(args, "all", "wallet export");
-  assertFlagOption(args, "includeNotes", "wallet export");
+function assertWalletExportBackupArgs(args) {
+  assertAllowedCommandSchema(args, "wallet-export-backup");
   requireArg(args.output, "--output");
-  if (args.all === true) {
-    expect(
-      args.network === undefined && args.wallet === undefined,
-      "wallet export --all exports every local mainnet wallet and does not accept --network or --wallet.",
-    );
-    return;
-  }
   requireNetworkName(args);
   requireWalletName(args);
 }
 
-function assertWalletImportArgs(args) {
-  assertAllowedCommandSchema(args, "wallet-import");
+function assertWalletExportKeyArgs(args, commandName) {
+  assertAllowedCommandSchema(args, commandName);
+  requireArg(args.output, "--output");
+  requireNetworkName(args);
+  requireWalletName(args);
 }
 
-function assertFlagOption(args, key, commandName) {
-  if (args[key] !== undefined && args[key] !== true) {
-    throw new Error(`${commandName} option --${toKebabCase(key)} does not accept a value.`);
-  }
+function assertWalletImportBackupArgs(args) {
+  assertAllowedCommandSchema(args, "wallet-import-backup");
+}
+
+function assertWalletImportKeyArgs(args, commandName) {
+  assertAllowedCommandSchema(args, commandName);
 }
 
 function assertWithdrawBridgeArgs(args) {
   assertAllowedCommandSchema(args, "account-withdraw-bridge");
+  assertActionImpactArg(args, "account withdraw-bridge");
 }
 
 function assertWalletGetChannelFundArgs(args) {
-  assertWalletSecretArgs(args, "wallet-get-channel-fund");
+  assertAllowedCommandSchema(args, "wallet-get-channel-fund");
 }
 
 function assertExitChannelArgs(args) {
-  assertWalletSecretArgs(args, "channel-exit");
+  assertAllowedCommandSchema(args, "channel-exit");
 }
 
 function createWalletOperationDir(walletName, networkName, suffix) {
   const timestamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
   const operationDir = path.join(
-    walletPath(walletName, networkName),
+    selectedWalletEpochDir(walletName, networkName),
     "operations",
     `${timestamp}-${slugifyPathComponent(suffix)}`,
   );
@@ -8497,14 +9957,193 @@ function createWalletOperationDir(walletName, networkName, suffix) {
 }
 
 function persistWallet(context) {
-  writeEncryptedWalletJson(path.join(context.walletDir, "wallet.json"), context.wallet, context.walletSecret);
+  writeJson(walletNotesMetadataPath(context.walletDir), sanitizeWalletForNotesMetadata(context.wallet));
+  if (context.wallet?.l2PrivateKey || context.wallet?.l2PublicKey || context.wallet?.l2Address) {
+    writeJson(walletSpendingKeyMetadataPath(context.walletDir), buildWalletSpendingKeyMetadata(context.wallet));
+  }
+  if (context.wallet?.noteReceivePubKeyX || context.wallet?.noteReceivePubKeyYParity !== undefined) {
+    writeJson(walletViewingKeyMetadataPath(context.walletDir), buildWalletViewingKeyMetadata(context.wallet));
+  }
+}
+
+function persistWalletKeys(context) {
+  if (context.wallet?.l2PrivateKey) {
+    writeSecretFile(
+      walletSpendingKeySecretPath(context.wallet.network, context.walletName),
+      JSON.stringify({
+        format: WALLET_KEY_EXPORT_FORMAT,
+        formatVersion: WALLET_EXPORT_FORMAT_VERSION,
+        keyKind: "spending",
+        metadata: buildWalletSpendingKeyMetadata(context.wallet),
+        privateKey: normalizePrivateKey(context.wallet.l2PrivateKey),
+      }, null, 2),
+    );
+  }
+  if (context.wallet?.noteReceivePrivateKey) {
+    writeSecretFile(
+      walletViewingKeySecretPath(context.wallet.network, context.walletName),
+      JSON.stringify({
+        format: WALLET_KEY_EXPORT_FORMAT,
+        formatVersion: WALLET_EXPORT_FORMAT_VERSION,
+        keyKind: "viewing",
+        metadata: buildWalletViewingKeyMetadata(context.wallet),
+        privateKey: normalizePrivateKey(context.wallet.noteReceivePrivateKey),
+      }, null, 2),
+    );
+  }
 }
 
-function persistWalletMetadata(context) {
-  writeJson(walletMetadataPath(context.walletDir), {
+function persistWalletIndexForContext(context) {
+  const walletRoot = walletRootPath(context.walletName, context.wallet.network);
+  ensureDir(walletRoot);
+  const currentIndex = readWalletIndexIfExists(walletRoot) ?? {
+    format: WALLET_INDEX_FORMAT,
+    formatVersion: WALLET_INDEX_FORMAT_VERSION,
+    canonicalWalletName: context.walletName,
+    network: context.wallet.network,
+    channelName: context.wallet.channelName,
+    channelId: context.wallet.channelId,
+    l1Address: context.wallet.l1Address,
+    activeEpochId: null,
+    epochs: [],
+  };
+  const epoch = walletEpochSummaryFromWallet(context.wallet);
+  const epochs = [
+    ...currentIndex.epochs.filter((entry) => entry.epochId !== epoch.epochId),
+    epoch,
+  ].sort((left, right) =>
+    Number(left.joinedAtBlockNumber ?? 0) - Number(right.joinedAtBlockNumber ?? 0)
+    || String(left.epochId).localeCompare(String(right.epochId)));
+  const activeEpoch = epochs.find((entry) => entry.lifecycleStatus === "active") ?? null;
+  const nextIndex = {
+    ...currentIndex,
+    canonicalWalletName: context.walletName,
     network: context.wallet.network,
-    rpcUrl: context.wallet.rpcUrl,
     channelName: context.wallet.channelName,
+    channelId: context.wallet.channelId,
+    l1Address: context.wallet.l1Address,
+    activeEpochId: activeEpoch?.epochId ?? null,
+    epochs,
+  };
+  writeJson(walletIndexMetadataPath(walletRoot), nextIndex);
+}
+
+async function markWalletEpochExited({ walletContext, receipt, provider }) {
+  const block = receipt?.blockNumber === null || receipt?.blockNumber === undefined
+    ? null
+    : await provider.getBlock(receipt.blockNumber).catch(() => null);
+  const exitedAtBlockTimestamp = block?.timestamp ?? null;
+  walletContext.wallet.lifecycleStatus = "exited";
+  walletContext.wallet.exitedAtTxHash = receipt?.hash ?? null;
+  walletContext.wallet.exitedAtBlockNumber = receipt?.blockNumber ?? null;
+  walletContext.wallet.exitedAtLogIndex = firstReceiptLogIndex(receipt);
+  walletContext.wallet.exitedAtBlockTimestamp = exitedAtBlockTimestamp;
+  walletContext.wallet.exitedAtBlockTimestampIso = exitedAtBlockTimestamp === null
+    ? null
+    : new Date(Number(exitedAtBlockTimestamp) * 1000).toISOString();
+  persistWallet(walletContext);
+  persistWalletIndexForContext(walletContext);
+  return walletEpochSummaryFromWallet(walletContext.wallet);
+}
+
+function firstReceiptLogIndex(receipt) {
+  const first = receipt?.logs?.[0] ?? null;
+  return first?.index ?? first?.logIndex ?? null;
+}
+
+function walletEpochSummaryFromWallet(wallet) {
+  const lifecycle = walletLifecycleMetadata(wallet);
+  return {
+    ...lifecycle,
+    walletDirName: slugifyPathComponent(lifecycle.epochId),
+    l2Address: wallet.l2Address,
+    l2StorageKey: wallet.l2StorageKey,
+    leafIndex: wallet.leafIndex,
+  };
+}
+
+function sanitizeWalletForNotesMetadata(wallet) {
+  const normalized = normalizeWallet({
+    ...wallet,
+    l2PrivateKey: null,
+    noteReceivePrivateKey: null,
+  });
+  const { l2PrivateKey: _l2PrivateKey, noteReceivePrivateKey: _noteReceivePrivateKey, ...publicWallet } = normalized;
+  return {
+    ...publicWallet,
+    notes: {
+      unused: sanitizeTrackedNoteMap(normalized.notes.unused),
+      spent: sanitizeTrackedNoteMap(normalized.notes.spent),
+      unusedOrder: normalized.notes.unusedOrder,
+      unusedBalance: null,
+    },
+  };
+}
+
+function sanitizeTrackedNoteMap(notes) {
+  return Object.fromEntries(Object.entries(notes ?? {}).map(([key, note]) => [key, sanitizeTrackedNoteForPersistence(note)]));
+}
+
+function sanitizeTrackedNoteForPersistence(note) {
+  const normalized = normalizeTrackedNote(note);
+  return {
+    commitment: normalized.commitment,
+    nullifier: normalized.nullifier,
+    encryptedNoteValue: normalized.encryptedNoteValue,
+    status: normalized.status,
+    sourceFunction: normalized.sourceFunction,
+    sourceTxHash: normalized.sourceTxHash,
+    createdAtTxHash: normalized.createdAtTxHash,
+    createdAtBlockNumber: normalized.createdAtBlockNumber,
+    createdAtLogIndex: normalized.createdAtLogIndex,
+    createdByFunction: normalized.createdByFunction,
+    createdOutputIndex: normalized.createdOutputIndex,
+    spentAtTxHash: normalized.spentAtTxHash,
+    spentAtBlockNumber: normalized.spentAtBlockNumber,
+    spentByFunction: normalized.spentByFunction,
+    spentInputIndex: normalized.spentInputIndex,
+    counterpartyL2Address: normalized.counterpartyL2Address,
+    counterpartyDirection: normalized.counterpartyDirection,
+    counterpartyConfidence: normalized.counterpartyConfidence,
+    bridgeCommitmentKey: normalized.bridgeCommitmentKey,
+    bridgeNullifierKey: normalized.bridgeNullifierKey,
+  };
+}
+
+function buildWalletSpendingKeyMetadata(wallet) {
+  return normalizeCliOutput({
+    walletFormatVersion: WALLET_WORKSPACE_FORMAT_VERSION,
+    network: wallet.network,
+    wallet: wallet.name,
+    ...walletLifecycleMetadata(wallet),
+    channelName: wallet.channelName,
+    channelId: wallet.channelId,
+    l1Address: wallet.l1Address,
+    l2Address: wallet.l2Address,
+    l2PublicKey: wallet.l2PublicKey,
+    l2DerivationMode: wallet.l2DerivationMode,
+    l2DerivationChannelName: wallet.l2DerivationChannelName,
+    l2StorageKey: wallet.l2StorageKey,
+    leafIndex: wallet.leafIndex,
+  });
+}
+
+function buildWalletViewingKeyMetadata(wallet) {
+  return normalizeCliOutput({
+    walletFormatVersion: WALLET_WORKSPACE_FORMAT_VERSION,
+    network: wallet.network,
+    wallet: wallet.name,
+    ...walletLifecycleMetadata(wallet),
+    channelName: wallet.channelName,
+    channelId: wallet.channelId,
+    l1Address: wallet.l1Address,
+    l2Address: wallet.l2Address,
+    noteReceiveDerivationVersion: wallet.noteReceiveDerivationVersion,
+    noteReceiveTypedDataMethod: wallet.noteReceiveTypedDataMethod,
+    noteReceivePubKey: {
+      x: wallet.noteReceivePubKeyX,
+      yParity: wallet.noteReceivePubKeyYParity,
+    },
   });
 }
 
@@ -8524,10 +10163,10 @@ Secret source options:
   A wallet secret source file is arbitrary high-entropy secret text read once by channel join.
   Create one before joining a channel, for example:
       openssl rand -hex 32 > ./wallet-secret.txt
-      private-state-cli channel join --channel-name <NAME> --network <NAME> --account <NAME> --wallet-secret-path ./wallet-secret.txt
+      private-state-cli channel join --channel-name <NAME> --network <NAME> --account <NAME> --wallet-secret-path ./wallet-secret.txt --acknowledge-action-impact
   Bridge-facing commands accept optional --rpc-url. When provided, it is saved to
   ~/tokamak-private-channels/secrets/<network>/.env as RPC_URL. When omitted, the CLI reads RPC_URL from that file.
-  Wallet commands use wallet-local default secret files only.
+  Wallet commands use separate protected viewing-key and spending-key files when those capabilities are needed.
   Source files passed to --private-key-file and --wallet-secret-path are not required to use 0600 permissions, but
   canonical CLI secret files remain protected. On macOS/Linux this means 0600; on Windows the CLI repairs ACLs when possible.
 
@@ -8861,23 +10500,6 @@ function getUsableWorkspaceRecoveryIndex({
   };
 }
 
-function writeEncryptedWalletJson(filePath, value, walletSecret) {
-  const normalizedValue = normalizeCliOutput(value);
-  writeEncryptedWalletFile(filePath, Buffer.from(`${JSON.stringify(normalizedValue, null, 2)}\n`, "utf8"), walletSecret);
-}
-
-function readEncryptedWalletJson(filePath, walletSecret) {
-  try {
-    return JSON.parse(readEncryptedWalletFile(filePath, walletSecret).toString("utf8"));
-  } catch (error) {
-    throw cliError(
-      CLI_ERROR_CODES.WALLET_DECRYPT_FAILED,
-      `Unable to decrypt wallet data at ${filePath}. Check the wallet-local default secret file.`,
-      { cause: error },
-    );
-  }
-}
-
 function writeEncryptedWalletFile(filePath, plaintextBytes, walletSecret) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   const salt = randomBytes(16);
@@ -8898,23 +10520,6 @@ function writeEncryptedWalletFile(filePath, plaintextBytes, walletSecret) {
   fs.writeFileSync(filePath, `${JSON.stringify(envelope, null, 2)}\n`);
 }
 
-function readEncryptedWalletFile(filePath, walletSecret) {
-  const envelope = readJson(filePath);
-  expect(
-    envelope.version === WALLET_ENCRYPTION_VERSION
-      && envelope.algorithm === WALLET_ENCRYPTION_ALGORITHM
-      && envelope.kdf === "scrypt",
-    `Unsupported wallet encryption envelope at ${filePath}.`,
-  );
-  const encryptionKey = deriveWalletEncryptionKey(walletSecret, Buffer.from(ethers.getBytes(envelope.salt)));
-  const decipher = createDecipheriv("aes-256-gcm", encryptionKey, Buffer.from(ethers.getBytes(envelope.iv)));
-  decipher.setAuthTag(Buffer.from(ethers.getBytes(envelope.tag)));
-  return Buffer.concat([
-    decipher.update(Buffer.from(ethers.getBytes(envelope.ciphertext))),
-    decipher.final(),
-  ]);
-}
-
 function deriveWalletEncryptionKey(walletSecret, salt) {
   return scryptSync(String(walletSecret), salt, 32);
 }
@@ -8963,6 +10568,7 @@ function loadWalletCommandRuntime(args) {
 
 const HUMAN_RESULT_RENDERERS = Object.freeze({
   guide: printGuideHumanResult,
+  investigator: printInvestigatorHumanResult,
   "transaction-fees": printTransactionFeesHumanResult,
   update: printUpdateHumanResult,
 });
@@ -9022,6 +10628,29 @@ function printGuideHumanResult(guide) {
   console.log(lines.join("\n"));
 }
 
+function printInvestigatorHumanResult(result) {
+  const lines = [
+    "Private-State Evidence Investigator",
+    `HTML path: ${formatHumanValue(result.htmlPath)}`,
+    `File URL: ${formatHumanValue(result.fileUrl)}`,
+    `Browser opened: ${result.browserOpened ? "yes" : "no"}`,
+  ];
+  if (!result.browserOpened) {
+    lines.push(
+      `Open command: ${formatHumanValue(result.browserOpenCommand)}`,
+      `Open error: ${formatHumanValue(result.browserOpenError ?? "none")}`,
+    );
+  }
+  if (Array.isArray(result.nextSteps) && result.nextSteps.length > 0) {
+    lines.push(
+      "",
+      "Next Steps",
+      ...result.nextSteps.map((step) => `- ${step}`),
+    );
+  }
+  console.log(lines.join("\n"));
+}
+
 function printTransactionFeesHumanResult(report) {
   const lines = [
     "Transaction Fees",
@@ -9356,17 +10985,6 @@ function buildRecoveryHints(error, args = {}) {
     hints.push(`private-state-cli help guide --network ${networkName} --wallet ${walletName}`);
   }
 
-  if (error?.code === CLI_ERROR_CODES.MISSING_WALLET_SECRET) {
-    hints.push("restore the wallet-local default secret file from backup before running wallet commands.");
-    hints.push(`private-state-cli help guide --network ${networkName} --wallet ${walletName}`);
-  }
-
-  if (error?.code === CLI_ERROR_CODES.WALLET_DECRYPT_FAILED) {
-    hints.push("verify that the wallet-local default secret file is the same secret used when the wallet was created.");
-    hints.push("if the encrypted wallet file is corrupted but the wallet secret and L1 account secret still exist, rerun wallet recover-workspace.");
-    hints.push("if the wallet secret was lost, the local L2 key cannot be recovered from the encrypted wallet file.");
-  }
-
   if (
     message.startsWith("Missing --account:")
     || message.includes("Missing --account.")
@@ -9384,7 +11002,7 @@ function buildRecoveryHints(error, args = {}) {
   }
 
   if (error?.code === CLI_ERROR_CODES.MISSING_CHANNEL_REGISTRATION) {
-    hints.push(`private-state-cli channel join --channel-name ${channelName} --network ${networkName} --account ${accountName} --wallet-secret-path <PATH>`);
+    hints.push(`private-state-cli channel join --channel-name ${channelName} --network ${networkName} --account ${accountName} --wallet-secret-path <PATH> --acknowledge-action-impact`);
     hints.push(`private-state-cli help guide --network ${networkName} --channel-name ${channelName} --account ${accountName}`);
   }