@veil-cash/sdk 0.6.1 → 0.6.3

package/dist/cli/index.cjs

@@ -4203,6 +4203,14 @@ var QUEUE_ABI = [
     outputs: [{ name: "count", type: "uint256" }],
     stateMutability: "view",
     type: "function"
+  },
+  // Get remaining daily free deposits for an address (V3+)
+  {
+    inputs: [{ name: "_depositor", type: "address" }],
+    name: "getDailyFreeRemaining",
+    outputs: [{ name: "remaining", type: "uint256" }],
+    stateMutability: "view",
+    type: "function"
   }
 ];
 var POOL_ABI = [
@@ -5784,174 +5792,6 @@ function createRegisterCommand() {
   });
   return register;
 }
-var MINIMUM_NET = {
-  ETH: 0.01,
-  USDC: 10
-};
-async function getGrossAmount(netWei, rpcUrl) {
-  const publicClient = viem.createPublicClient({
-    chain: chains.base,
-    transport: viem.http(rpcUrl)
-  });
-  const grossWei = await publicClient.readContract({
-    address: getAddresses().entry,
-    abi: ENTRY_ABI,
-    functionName: "getDepositAmountWithFee",
-    args: [netWei]
-  });
-  return { grossWei, feeWei: grossWei - netWei };
-}
-var SUPPORTED_ASSETS = ["ETH", "USDC"];
-function createDepositCommand() {
-  const deposit = new Command("deposit").description("Deposit ETH or USDC into Veil").argument("<asset>", "Asset to deposit (ETH or USDC)").argument("<amount>", "Amount to deposit \u2014 this is what arrives in your Veil balance").option("--unsigned", "Output unsigned transaction payload instead of sending").option("--json", "Output as JSON").addHelpText("after", `
-The amount you specify is the net amount that lands in your Veil balance.
-The 0.3% protocol fee is automatically added on top.
-
-Examples:
-  veil deposit ETH 0.1          # deposits 0.1 ETH (sends ~0.1003 ETH)
-  veil deposit USDC 100         # deposits 100 USDC (sends ~100.30 USDC)
-  veil deposit ETH 0.1 --unsigned
-  veil deposit ETH 0.1 --json
-`).action(async (asset, amount, options) => {
-    try {
-      const assetUpper = asset.toUpperCase();
-      if (!SUPPORTED_ASSETS.includes(assetUpper)) {
-        throw new CLIError(ErrorCode.INVALID_AMOUNT, `Unsupported asset: ${asset}. Supported: ${SUPPORTED_ASSETS.join(", ")}`);
-      }
-      const amountNum = parseFloat(amount);
-      const minimumNet = MINIMUM_NET[assetUpper];
-      if (amountNum < minimumNet) {
-        throw new CLIError(
-          ErrorCode.INVALID_AMOUNT,
-          `Minimum deposit is ${minimumNet} ${assetUpper}.`
-        );
-      }
-      const rpcUrl = process.env.RPC_URL;
-      const poolConfig = POOL_CONFIG[assetUpper.toLowerCase()];
-      const netWei = assetUpper === "ETH" ? viem.parseEther(amount) : viem.parseUnits(amount, poolConfig.decimals);
-      const progress = createProgressReporter();
-      progress("Calculating fee...");
-      const { grossWei, feeWei } = await getGrossAmount(netWei, rpcUrl);
-      const grossStr = assetUpper === "ETH" ? viem.formatEther(grossWei) : viem.formatUnits(grossWei, poolConfig.decimals);
-      const feeStr = assetUpper === "ETH" ? viem.formatEther(feeWei) : viem.formatUnits(feeWei, poolConfig.decimals);
-      const depositKey = process.env.DEPOSIT_KEY;
-      if (!depositKey) {
-        throw new CLIError(ErrorCode.DEPOSIT_KEY_MISSING, 'DEPOSIT_KEY not set. Run "veil init" first.');
-      }
-      progress("Building transaction...");
-      let tx;
-      let approveTx = null;
-      if (assetUpper === "USDC") {
-        approveTx = buildApproveUSDCTx({ amount: grossStr });
-        tx = buildDepositUSDCTx({ depositKey, amount: grossStr });
-      } else {
-        tx = buildDepositETHTx({ depositKey, amount: grossStr });
-      }
-      if (options.unsigned) {
-        clearProgress();
-        const payloads = [];
-        if (approveTx) {
-          payloads.push({
-            step: "approve",
-            to: approveTx.to,
-            data: approveTx.data,
-            value: "0",
-            chainId: 8453
-          });
-        }
-        payloads.push({
-          step: "deposit",
-          to: tx.to,
-          data: tx.data,
-          value: tx.value ? tx.value.toString() : "0",
-          chainId: 8453
-        });
-        printJson(payloads.length === 1 ? payloads[0] : payloads);
-        return;
-      }
-      const config = getConfig(options);
-      const address = getAddress(config.privateKey);
-      if (assetUpper === "ETH") {
-        progress("Checking balance...");
-        const balance = await getBalance(address, config.rpcUrl);
-        if (balance < grossWei) {
-          clearProgress();
-          throw new CLIError(
-            ErrorCode.INSUFFICIENT_BALANCE,
-            `Insufficient ETH balance. Have: ${viem.formatEther(balance)} ETH, Need: ${grossStr} ETH (${amount} + fee)`
-          );
-        }
-      }
-      if (approveTx) {
-        progress(`Approving ${assetUpper}...`);
-        const approvalResult = await sendTransaction(config, approveTx);
-        if (assetUpper === "USDC") {
-          const publicClient = viem.createPublicClient({
-            chain: chains.base,
-            transport: viem.http(config.rpcUrl)
-          });
-          const addresses = getAddresses();
-          let allowance = await publicClient.readContract({
-            address: getAddresses().usdcToken,
-            abi: ERC20_ABI,
-            functionName: "allowance",
-            args: [address, addresses.entry]
-          });
-          for (let confirmations = 2; allowance < grossWei && confirmations <= 3; confirmations++) {
-            await publicClient.waitForTransactionReceipt({
-              hash: approvalResult.hash,
-              confirmations
-            });
-            allowance = await publicClient.readContract({
-              address: addresses.usdcToken,
-              abi: ERC20_ABI,
-              functionName: "allowance",
-              args: [address, addresses.entry]
-            });
-          }
-          if (allowance < grossWei) {
-            throw new CLIError(
-              ErrorCode.CONTRACT_ERROR,
-              `USDC approval is not yet visible on RPC after confirmation. Allowance ${allowance.toString()} < required ${grossWei.toString()}.`
-            );
-          }
-        }
-      }
-      progress("Sending deposit transaction...");
-      const result = await sendTransaction(config, tx);
-      progress("Confirming...");
-      clearProgress();
-      const output = {
-        success: result.receipt.status === "success",
-        hash: result.hash,
-        asset: assetUpper,
-        amount,
-        fee: feeStr,
-        totalSent: grossStr,
-        blockNumber: result.receipt.blockNumber.toString()
-      };
-      if (options.json) {
-        printJson(output);
-        return;
-      }
-      printHeader("Deposit Submitted");
-      printFields([
-        { label: "Asset", value: assetUpper },
-        { label: "Amount", value: `${amount} ${assetUpper}` },
-        { label: "Fee", value: `${feeStr} ${assetUpper} (0.3%)` },
-        { label: "Total sent", value: `${grossStr} ${assetUpper}` },
-        { label: "From", value: address },
-        { label: "Transaction", value: txUrl(result.hash) },
-        { label: "Block", value: result.receipt.blockNumber }
-      ]);
-      printLine();
-    } catch (error) {
-      clearProgress();
-      handleCLIError(error);
-    }
-  });
-  return deposit;
-}
 
 // src/utxo.ts
 var Utxo = class _Utxo {
@@ -6084,6 +5924,25 @@ async function getQueueBalance(options) {
     pendingCount: pendingDeposits.length
   };
 }
+async function getDailyFreeRemaining(options) {
+  const { address, pool = "eth", rpcUrl } = options;
+  const queueAddress = getQueueAddress(pool);
+  const publicClient = viem.createPublicClient({
+    chain: chains.base,
+    transport: viem.http(rpcUrl)
+  });
+  try {
+    const remaining = await publicClient.readContract({
+      address: queueAddress,
+      abi: QUEUE_ABI,
+      functionName: "getDailyFreeRemaining",
+      args: [address]
+    });
+    return Number(remaining);
+  } catch {
+    return 0;
+  }
+}
 async function getPrivateBalance(options) {
   const { keypair, pool = "eth", rpcUrl, onProgress } = options;
   const poolAddress = getPoolAddress(pool);
@@ -6136,46 +5995,246 @@ async function getPrivateBalance(options) {
       if (utxo.amount > 0n) {
         decryptedUtxos.push({ utxo, index: i });
       }
-    } catch {
-    }
-  }
-  onProgress?.("Found UTXOs", `${decryptedUtxos.length} belonging to you`);
-  const utxoInfos = [];
-  let totalBalance = 0n;
-  let spentCount = 0;
-  let unspentCount = 0;
-  for (let i = 0; i < decryptedUtxos.length; i++) {
-    const { utxo, index } = decryptedUtxos[i];
-    onProgress?.("Checking spent status", `UTXO ${i + 1}/${decryptedUtxos.length}`);
-    const nullifier = utxo.getNullifier();
-    const nullifierHex = toFixedHex(nullifier);
-    const isSpent = await publicClient.readContract({
-      address: poolAddress,
-      abi: POOL_ABI,
-      functionName: "isSpent",
-      args: [nullifierHex]
-    });
-    utxoInfos.push({
-      index,
-      amount: viem.formatUnits(utxo.amount, poolConfig.decimals),
-      amountWei: utxo.amount.toString(),
-      isSpent
-    });
-    if (isSpent) {
-      spentCount++;
-    } else {
-      unspentCount++;
-      totalBalance += utxo.amount;
+    } catch {
+    }
+  }
+  onProgress?.("Found UTXOs", `${decryptedUtxos.length} belonging to you`);
+  const utxoInfos = [];
+  let totalBalance = 0n;
+  let spentCount = 0;
+  let unspentCount = 0;
+  for (let i = 0; i < decryptedUtxos.length; i++) {
+    const { utxo, index } = decryptedUtxos[i];
+    onProgress?.("Checking spent status", `UTXO ${i + 1}/${decryptedUtxos.length}`);
+    const nullifier = utxo.getNullifier();
+    const nullifierHex = toFixedHex(nullifier);
+    const isSpent = await publicClient.readContract({
+      address: poolAddress,
+      abi: POOL_ABI,
+      functionName: "isSpent",
+      args: [nullifierHex]
+    });
+    utxoInfos.push({
+      index,
+      amount: viem.formatUnits(utxo.amount, poolConfig.decimals),
+      amountWei: utxo.amount.toString(),
+      isSpent
+    });
+    if (isSpent) {
+      spentCount++;
+    } else {
+      unspentCount++;
+      totalBalance += utxo.amount;
+    }
+  }
+  return {
+    privateBalance: viem.formatUnits(totalBalance, poolConfig.decimals),
+    privateBalanceWei: totalBalance.toString(),
+    utxoCount: decryptedUtxos.length,
+    spentCount,
+    unspentCount,
+    utxos: utxoInfos
+  };
+}
+var MINIMUM_NET = {
+  ETH: 0.01,
+  USDC: 10
+};
+async function getGrossAmount(netWei, depositor, pool, rpcUrl) {
+  const freeRemaining = await getDailyFreeRemaining({ address: depositor, pool, rpcUrl });
+  if (freeRemaining > 0) {
+    return { grossWei: netWei, feeWei: 0n, dailyFreeUsed: true, dailyFreeRemaining: freeRemaining - 1 };
+  }
+  const publicClient = viem.createPublicClient({
+    chain: chains.base,
+    transport: viem.http(rpcUrl)
+  });
+  const grossWei = await publicClient.readContract({
+    address: getAddresses().entry,
+    abi: ENTRY_ABI,
+    functionName: "getDepositAmountWithFee",
+    args: [netWei]
+  });
+  return { grossWei, feeWei: grossWei - netWei, dailyFreeUsed: false, dailyFreeRemaining: 0 };
+}
+var SUPPORTED_ASSETS = ["ETH", "USDC"];
+function createDepositCommand() {
+  const deposit = new Command("deposit").description("Deposit ETH or USDC into Veil").argument("<asset>", "Asset to deposit (ETH or USDC)").argument("<amount>", "Amount to deposit \u2014 this is what arrives in your Veil balance").option("--address <address>", "Signer address (required in --unsigned mode unless SIGNER_ADDRESS or WALLET_KEY is set)").option("--unsigned", "Output unsigned transaction payload instead of sending").option("--json", "Output as JSON").addHelpText("after", `
+The amount you specify is the net amount that lands in your Veil balance.
+A 0.3% protocol fee is normally added on top, but each address gets
+free daily deposits (fee waived). The CLI checks automatically.
+
+Examples:
+  veil deposit ETH 0.1          # deposits 0.1 ETH (free or ~0.1003 ETH)
+  veil deposit USDC 100         # deposits 100 USDC (free or ~100.30 USDC)
+  veil deposit ETH 0.1 --unsigned --address 0x...
+  SIGNER_ADDRESS=0x... veil deposit ETH 0.1 --unsigned
+  veil deposit ETH 0.1 --json
+`).action(async (asset, amount, options) => {
+    try {
+      const assetUpper = asset.toUpperCase();
+      if (!SUPPORTED_ASSETS.includes(assetUpper)) {
+        throw new CLIError(ErrorCode.INVALID_AMOUNT, `Unsupported asset: ${asset}. Supported: ${SUPPORTED_ASSETS.join(", ")}`);
+      }
+      const amountNum = parseFloat(amount);
+      const minimumNet = MINIMUM_NET[assetUpper];
+      if (amountNum < minimumNet) {
+        throw new CLIError(
+          ErrorCode.INVALID_AMOUNT,
+          `Minimum deposit is ${minimumNet} ${assetUpper}.`
+        );
+      }
+      const rpcUrl = process.env.RPC_URL;
+      const pool = assetUpper.toLowerCase();
+      const poolConfig = POOL_CONFIG[pool];
+      const netWei = assetUpper === "ETH" ? viem.parseEther(amount) : viem.parseUnits(amount, poolConfig.decimals);
+      const progress = createProgressReporter();
+      let config = null;
+      let address;
+      let feeRpcUrl = rpcUrl;
+      if (options.unsigned) {
+        const resolved = resolveAddress({ address: options.address }, { required: true });
+        if (!resolved) {
+          throw new CLIError(
+            ErrorCode.WALLET_KEY_MISSING,
+            "Must provide --address, set SIGNER_ADDRESS, or set WALLET_KEY env."
+          );
+        }
+        address = resolved.address;
+      } else {
+        config = getConfig(options);
+        address = getAddress(config.privateKey);
+        feeRpcUrl = config.rpcUrl;
+      }
+      progress("Checking deposit fee...");
+      const { grossWei, feeWei, dailyFreeUsed, dailyFreeRemaining } = await getGrossAmount(
+        netWei,
+        address,
+        pool,
+        feeRpcUrl
+      );
+      const grossStr = assetUpper === "ETH" ? viem.formatEther(grossWei) : viem.formatUnits(grossWei, poolConfig.decimals);
+      const feeStr = assetUpper === "ETH" ? viem.formatEther(feeWei) : viem.formatUnits(feeWei, poolConfig.decimals);
+      const depositKey = process.env.DEPOSIT_KEY;
+      if (!depositKey) {
+        throw new CLIError(ErrorCode.DEPOSIT_KEY_MISSING, 'DEPOSIT_KEY not set. Run "veil init" first.');
+      }
+      progress("Building transaction...");
+      let tx;
+      let approveTx = null;
+      if (assetUpper === "USDC") {
+        approveTx = buildApproveUSDCTx({ amount: grossStr });
+        tx = buildDepositUSDCTx({ depositKey, amount: grossStr });
+      } else {
+        tx = buildDepositETHTx({ depositKey, amount: grossStr });
+      }
+      if (options.unsigned) {
+        clearProgress();
+        const payloads = [];
+        if (approveTx) {
+          payloads.push({
+            step: "approve",
+            to: approveTx.to,
+            data: approveTx.data,
+            value: "0",
+            chainId: 8453
+          });
+        }
+        payloads.push({
+          step: "deposit",
+          to: tx.to,
+          data: tx.data,
+          value: tx.value ? tx.value.toString() : "0",
+          chainId: 8453
+        });
+        printJson(payloads.length === 1 ? payloads[0] : payloads);
+        return;
+      }
+      if (!config) {
+        throw new CLIError(ErrorCode.WALLET_KEY_MISSING, "WALLET_KEY env var required. Set it before running this command.");
+      }
+      if (assetUpper === "ETH") {
+        progress("Checking balance...");
+        const balance = await getBalance(address, config.rpcUrl);
+        if (balance < grossWei) {
+          clearProgress();
+          throw new CLIError(
+            ErrorCode.INSUFFICIENT_BALANCE,
+            `Insufficient ETH balance. Have: ${viem.formatEther(balance)} ETH, Need: ${grossStr} ETH (${amount} + fee)`
+          );
+        }
+      }
+      if (approveTx) {
+        progress(`Approving ${assetUpper}...`);
+        const approvalResult = await sendTransaction(config, approveTx);
+        if (assetUpper === "USDC") {
+          const publicClient = viem.createPublicClient({
+            chain: chains.base,
+            transport: viem.http(config.rpcUrl)
+          });
+          const addresses = getAddresses();
+          let allowance = await publicClient.readContract({
+            address: getAddresses().usdcToken,
+            abi: ERC20_ABI,
+            functionName: "allowance",
+            args: [address, addresses.entry]
+          });
+          for (let confirmations = 2; allowance < grossWei && confirmations <= 3; confirmations++) {
+            await publicClient.waitForTransactionReceipt({
+              hash: approvalResult.hash,
+              confirmations
+            });
+            allowance = await publicClient.readContract({
+              address: addresses.usdcToken,
+              abi: ERC20_ABI,
+              functionName: "allowance",
+              args: [address, addresses.entry]
+            });
+          }
+          if (allowance < grossWei) {
+            throw new CLIError(
+              ErrorCode.CONTRACT_ERROR,
+              `USDC approval is not yet visible on RPC after confirmation. Allowance ${allowance.toString()} < required ${grossWei.toString()}.`
+            );
+          }
+        }
+      }
+      progress("Sending deposit transaction...");
+      const result = await sendTransaction(config, tx);
+      progress("Confirming...");
+      clearProgress();
+      const output = {
+        success: result.receipt.status === "success",
+        hash: result.hash,
+        asset: assetUpper,
+        amount,
+        fee: feeStr,
+        dailyFreeUsed,
+        totalSent: grossStr,
+        blockNumber: result.receipt.blockNumber.toString()
+      };
+      if (options.json) {
+        printJson(output);
+        return;
+      }
+      const feeLabel = dailyFreeUsed ? `0 ${assetUpper} (free \u2014 ${dailyFreeRemaining} remaining today)` : `${feeStr} ${assetUpper} (0.3%)`;
+      printHeader("Deposit Submitted");
+      printFields([
+        { label: "Asset", value: assetUpper },
+        { label: "Amount", value: `${amount} ${assetUpper}` },
+        { label: "Fee", value: feeLabel },
+        { label: "Total sent", value: `${grossStr} ${assetUpper}` },
+        { label: "From", value: address },
+        { label: "Transaction", value: txUrl(result.hash) },
+        { label: "Block", value: result.receipt.blockNumber }
+      ]);
+      printLine();
+    } catch (error) {
+      clearProgress();
+      handleCLIError(error);
     }
-  }
-  return {
-    privateBalance: viem.formatUnits(totalBalance, poolConfig.decimals),
-    privateBalanceWei: totalBalance.toString(),
-    utxoCount: decryptedUtxos.length,
-    spentCount,
-    unspentCount,
-    utxos: utxoInfos
-  };
+  });
+  return deposit;
 }
 
 // src/cli/commands/private-balance.ts
@@ -6682,7 +6741,16 @@ async function postRelayJson(endpoint, body, relayUrl) {
     },
     body: JSON.stringify(body)
   });
-  const data = await response.json();
+  const text = await response.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new RelayError(
+      `Relay returned non-JSON response (HTTP ${response.status})`,
+      response.status
+    );
+  }
   if (!response.ok) {
     const errorData = data;
     throw new RelayError(
@@ -7589,11 +7657,12 @@ function deriveSubaccountChildDepositKey(childPrivateKey) {
 }
 async function predictSubaccountForwarder(options) {
   const publicClient = createBaseClient(options.rpcUrl);
+  const depositKeyBytes = options.childDepositKey.startsWith("0x") ? options.childDepositKey : `0x${options.childDepositKey}`;
   return publicClient.readContract({
     abi: FORWARDER_FACTORY_ABI,
     address: getForwarderFactoryAddress(),
     functionName: "computeAddress",
-    args: [options.salt, options.childDepositKey, options.childOwner]
+    args: [options.salt, depositKeyBytes, options.childOwner]
   });
 }
 async function deriveSubaccountSlot(options) {
@@ -7630,7 +7699,7 @@ async function deploySubaccountForwarder(options) {
     slot: options.slot,
     rpcUrl: options.rpcUrl
   });
-  return postRelayJson(
+  const result = await postRelayJson(
     "/stealth/deploy",
     {
       salt: slot.salt,
@@ -7640,6 +7709,7 @@ async function deploySubaccountForwarder(options) {
     },
     options.relayUrl
   );
+  return { ...result, slot };
 }
 async function sweepSubaccountForwarder(options) {
   const asset = normalizeAsset(options.asset);
@@ -7664,11 +7734,32 @@ function toQueueStatus(asset, result) {
     pendingDeposits: result.pendingDeposits
   };
 }
+function toPrivateBalanceStatus(result) {
+  return {
+    privateBalance: result.privateBalance,
+    privateBalanceWei: result.privateBalanceWei,
+    utxoCount: result.utxoCount,
+    spentCount: result.spentCount,
+    unspentCount: result.unspentCount
+  };
+}
+async function getSubaccountPrivateBalance(options) {
+  const normalizedSlot = normalizeSlot(options.slot);
+  assertPrivateKey(options.rootPrivateKey, "rootPrivateKey");
+  const childPrivateKey = deriveSubaccountChildPrivateKey(options.rootPrivateKey, normalizedSlot);
+  const childKeypair = new Keypair(childPrivateKey);
+  return getPrivateBalance({
+    keypair: childKeypair,
+    pool: options.pool,
+    rpcUrl: options.rpcUrl,
+    onProgress: options.onProgress
+  });
+}
 async function getSubaccountStatus(options) {
   const slot = await deriveSubaccountSlot(options);
   const publicClient = createBaseClient(options.rpcUrl);
   const addresses = getAddresses();
-  const [deployed, ethWei, usdcWei, ethQueue, usdcQueue] = await Promise.all([
+  const [deployed, ethWei, usdcWei, ethQueue, usdcQueue, ethPrivate, usdcPrivate] = await Promise.all([
     isSubaccountForwarderDeployed({
       forwarderAddress: slot.forwarderAddress,
       rpcUrl: options.rpcUrl
@@ -7689,6 +7780,18 @@ async function getSubaccountStatus(options) {
       address: slot.forwarderAddress,
       pool: "usdc",
       rpcUrl: options.rpcUrl
+    }),
+    getSubaccountPrivateBalance({
+      rootPrivateKey: options.rootPrivateKey,
+      slot: options.slot,
+      pool: "eth",
+      rpcUrl: options.rpcUrl
+    }),
+    getSubaccountPrivateBalance({
+      rootPrivateKey: options.rootPrivateKey,
+      slot: options.slot,
+      pool: "usdc",
+      rpcUrl: options.rpcUrl
     })
   ]);
   return {
@@ -7704,6 +7807,10 @@ async function getSubaccountStatus(options) {
         balanceWei: usdcWei.toString()
       }
     },
+    privateBalances: {
+      eth: toPrivateBalanceStatus(ethPrivate),
+      usdc: toPrivateBalanceStatus(usdcPrivate)
+    },
     queues: {
       eth: toQueueStatus("eth", ethQueue),
       usdc: toQueueStatus("usdc", usdcQueue)
@@ -7850,6 +7957,137 @@ async function buildSubaccountRecoveryTx(options) {
     signature
   };
 }
+async function mergeSubaccount(options) {
+  const {
+    rootPrivateKey,
+    slot,
+    pool = "eth",
+    rpcUrl,
+    relayUrl,
+    onProgress
+  } = options;
+  const normalizedSlot = normalizeSlot(slot);
+  assertPrivateKey(rootPrivateKey, "rootPrivateKey");
+  const poolConfig = POOL_CONFIG[pool];
+  const poolAddress = getPoolAddress(pool);
+  const childPrivateKey = deriveSubaccountChildPrivateKey(rootPrivateKey, normalizedSlot);
+  const childKeypair = new Keypair(childPrivateKey);
+  const parentKeypair = new Keypair(rootPrivateKey);
+  onProgress?.("Fetching subaccount balance...");
+  const balanceResult = await getPrivateBalance({
+    keypair: childKeypair,
+    pool,
+    rpcUrl,
+    onProgress
+  });
+  const unspentUtxoInfos = balanceResult.utxos.filter((u) => !u.isSpent);
+  if (unspentUtxoInfos.length === 0) {
+    throw new Error("Subaccount has no unspent UTXOs to merge");
+  }
+  if (unspentUtxoInfos.length > 16) {
+    throw new Error(
+      `Subaccount has ${unspentUtxoInfos.length} unspent UTXOs which exceeds the 16-input circuit limit. Consolidate UTXOs on the subaccount first before merging.`
+    );
+  }
+  onProgress?.("Preparing UTXOs...");
+  const publicClient = viem.createPublicClient({
+    chain: chains.base,
+    transport: viem.http(rpcUrl)
+  });
+  const utxos = [];
+  for (const utxoInfo of unspentUtxoInfos) {
+    const encryptedOutputs = await publicClient.readContract({
+      address: poolAddress,
+      abi: POOL_ABI,
+      functionName: "getEncryptedOutputs",
+      args: [BigInt(utxoInfo.index), BigInt(utxoInfo.index + 1)]
+    });
+    if (encryptedOutputs.length > 0) {
+      try {
+        const utxo = Utxo.decrypt(encryptedOutputs[0], childKeypair);
+        utxo.index = utxoInfo.index;
+        utxos.push(utxo);
+      } catch {
+      }
+    }
+  }
+  if (utxos.length === 0) {
+    throw new Error("Failed to decrypt subaccount UTXOs");
+  }
+  onProgress?.("Selecting UTXOs...");
+  const amount = balanceResult.privateBalance;
+  const { selectedUtxos, changeAmount } = selectUtxosForWithdraw(
+    utxos,
+    amount,
+    poolConfig.decimals
+  );
+  const outputs = [];
+  const mergeWei = viem.parseUnits(amount, poolConfig.decimals);
+  outputs.push(new Utxo({ amount: mergeWei, keypair: parentKeypair }));
+  if (changeAmount > 0n) {
+    outputs.push(new Utxo({ amount: changeAmount, keypair: parentKeypair }));
+  }
+  onProgress?.("Fetching commitments...");
+  const nextIndex = await publicClient.readContract({
+    address: poolAddress,
+    abi: POOL_ABI,
+    functionName: "nextIndex"
+  });
+  const BATCH_SIZE = 5e3;
+  const commitments = [];
+  const totalBatches = Math.ceil(nextIndex / BATCH_SIZE);
+  for (let start = 0; start < nextIndex; start += BATCH_SIZE) {
+    const end = Math.min(start + BATCH_SIZE, nextIndex);
+    const batchNum = Math.floor(start / BATCH_SIZE) + 1;
+    onProgress?.("Fetching commitments", `batch ${batchNum}/${totalBatches}`);
+    const batch = await publicClient.readContract({
+      address: poolAddress,
+      abi: POOL_ABI,
+      functionName: "getCommitments",
+      args: [BigInt(start), BigInt(end)]
+    });
+    commitments.push(...batch.map((c) => c.toString()));
+  }
+  onProgress?.("Building ZK proof...");
+  const result = await prepareTransaction({
+    commitments,
+    inputs: selectedUtxos,
+    outputs,
+    fee: 0,
+    recipient: "0x0000000000000000000000000000000000000000",
+    relayer: "0x0000000000000000000000000000000000000000",
+    onProgress
+  });
+  onProgress?.("Submitting to relay...");
+  const relayResult = await submitRelay({
+    type: "transfer",
+    pool,
+    relayUrl,
+    proofArgs: {
+      proof: result.args.proof,
+      root: result.args.root,
+      inputNullifiers: result.args.inputNullifiers,
+      outputCommitments: result.args.outputCommitments,
+      publicAmount: result.args.publicAmount,
+      extDataHash: result.args.extDataHash
+    },
+    extData: result.extData,
+    metadata: {
+      amount,
+      recipient: "self",
+      inputUtxoCount: selectedUtxos.length,
+      outputUtxoCount: outputs.length
+    }
+  });
+  return {
+    success: relayResult.success,
+    transactionHash: relayResult.transactionHash,
+    blockNumber: relayResult.blockNumber,
+    amount,
+    slot: normalizedSlot,
+    pool
+  };
+}
 
 // src/cli/commands/subaccount.ts
 function parseSlotValue(raw) {
@@ -7883,6 +8121,13 @@ function parseAsset(raw) {
   }
   return asset;
 }
+function parsePool(raw) {
+  const pool = raw.toLowerCase();
+  if (pool !== "eth" && pool !== "usdc") {
+    throw new CLIError(ErrorCode.INVALID_AMOUNT, `Unsupported pool: ${raw}. Supported: eth, usdc`);
+  }
+  return pool;
+}
 function printQueueHuman(title, queue) {
   printSection(title);
   printFields([
@@ -7902,6 +8147,7 @@ Examples:
   veil subaccount status --slot 0
   veil subaccount deploy --slot 0
   veil subaccount sweep --slot 0 --asset eth
+  veil subaccount merge --slot 0 --pool eth
   veil subaccount recover --slot 0 --asset usdc --to 0xRecipientAddress --amount 25
   veil subaccount address --slot 0
 `);
@@ -7939,7 +8185,7 @@ Examples:
       handleCLIError(error);
     }
   });
-  subaccount.command("status").description("Show subaccount deployment, balances, and queue state").requiredOption("--slot <n>", "Subaccount slot", parseSlotValue).option("--json", "Output as JSON").action(async (options) => {
+  subaccount.command("status").description("Show subaccount deployment, forwarder balances, private balances, and queue state").requiredOption("--slot <n>", "Subaccount slot", parseSlotValue).option("--json", "Output as JSON").action(async (options) => {
     try {
       const rootPrivateKey = getRequiredVeilKey();
       const status = await getSubaccountStatus({
@@ -7964,6 +8210,17 @@ Examples:
         { label: "ETH", value: `${status.balances.eth.balance} ETH` },
         { label: "USDC", value: `${status.balances.usdc.balance} USDC` }
       ]);
+      printSection("Private Pool Balances");
+      printFields([
+        {
+          label: "ETH",
+          value: `${status.privateBalances.eth.privateBalance} ETH (${status.privateBalances.eth.unspentCount} unspent / ${status.privateBalances.eth.spentCount} spent / ${status.privateBalances.eth.utxoCount} total UTXOs)`
+        },
+        {
+          label: "USDC",
+          value: `${status.privateBalances.usdc.privateBalance} USDC (${status.privateBalances.usdc.unspentCount} unspent / ${status.privateBalances.usdc.spentCount} spent / ${status.privateBalances.usdc.utxoCount} total UTXOs)`
+        }
+      ]);
       printQueueHuman("ETH Queue", status.queues.eth);
       printQueueHuman("USDC Queue", status.queues.usdc);
       printLine();
@@ -7974,11 +8231,6 @@ Examples:
   subaccount.command("deploy").description("Deploy a subaccount forwarder through the relay").requiredOption("--slot <n>", "Subaccount slot", parseSlotValue).option("--json", "Output as JSON").action(async (options) => {
     try {
       const rootPrivateKey = getRequiredVeilKey();
-      const slot = await deriveSubaccountSlot({
-        rootPrivateKey,
-        slot: options.slot,
-        rpcUrl: process.env.RPC_URL
-      });
       const result = await deploySubaccountForwarder({
         rootPrivateKey,
         slot: options.slot,
@@ -7988,7 +8240,7 @@ Examples:
       const output = {
         ...result,
         slot: options.slot,
-        forwarderAddress: slot.forwarderAddress
+        forwarderAddress: result.slot.forwarderAddress
       };
       if (options.json) {
         printJson(output);
@@ -7997,7 +8249,7 @@ Examples:
       printHeader("Subaccount Deploy Submitted");
       printFields([
         { label: "Slot", value: options.slot },
-        { label: "Forwarder", value: slot.forwarderAddress },
+        { label: "Forwarder", value: result.slot.forwarderAddress },
         { label: "Transaction", value: txUrl(result.transactionHash) },
         { label: "Block", value: result.blockNumber }
       ]);
@@ -8042,12 +8294,63 @@ Examples:
       handleCLIError(error);
     }
   });
+  subaccount.command("merge").description("Merge a subaccount's private pool balance back to the main wallet").requiredOption("--slot <n>", "Subaccount slot", parseSlotValue).option("--pool <pool>", "Pool to merge (eth or usdc)", parsePool, "eth").option("--json", "Output as JSON").action(async (options) => {
+    try {
+      const rootPrivateKey = getRequiredVeilKey();
+      const result = await mergeSubaccount({
+        rootPrivateKey,
+        slot: options.slot,
+        pool: options.pool,
+        rpcUrl: process.env.RPC_URL,
+        relayUrl: process.env.RELAY_URL,
+        onProgress: options.json ? void 0 : (stage, detail) => {
+          const msg = detail ? `${stage} ${detail}` : stage;
+          process.stderr.write(`\r\x1B[K${msg}`);
+        }
+      });
+      if (!options.json) {
+        process.stderr.write("\r\x1B[K");
+      }
+      const output = {
+        success: result.success,
+        slot: result.slot,
+        pool: result.pool,
+        amount: result.amount,
+        transactionHash: result.transactionHash,
+        blockNumber: result.blockNumber
+      };
+      if (options.json) {
+        printJson(output);
+        return;
+      }
+      printHeader("Subaccount Merge Submitted");
+      printFields([
+        { label: "Slot", value: result.slot },
+        { label: "Pool", value: result.pool.toUpperCase() },
+        { label: "Amount", value: result.amount },
+        { label: "Transaction", value: txUrl(result.transactionHash) },
+        { label: "Block", value: result.blockNumber }
+      ]);
+      printLine();
+    } catch (error) {
+      if (!options.json) {
+        process.stderr.write("\r\x1B[K");
+      }
+      handleCLIError(error);
+    }
+  });
   subaccount.command("recover").description("Recover assets sitting on the subaccount forwarder with a direct withdraw transaction").requiredOption("--slot <n>", "Subaccount slot", parseSlotValue).requiredOption("--asset <asset>", "Asset to recover (eth or usdc)", parseAsset).requiredOption("--to <address>", "Recipient address").requiredOption("--amount <value>", "Amount to recover").option("--json", "Output as JSON").action(async (options) => {
     try {
       const rootPrivateKey = getRequiredVeilKey();
       if (!viem.isAddress(options.to)) {
         throw new CLIError(ErrorCode.INVALID_ADDRESS, `Invalid recipient address: ${options.to}`);
       }
+      if (!process.env.WALLET_KEY) {
+        throw new CLIError(
+          ErrorCode.WALLET_KEY_MISSING,
+          "WALLET_KEY required for recovery. Recovery submits a transaction on-chain and needs a gas payer."
+        );
+      }
       const config = getConfig({});
       const recovery = await buildSubaccountRecoveryTx({
         rootPrivateKey,
@@ -8118,7 +8421,7 @@ Examples:
 // src/cli/index.ts
 loadEnv();
 var program2 = new Command();
-program2.name("veil").description("CLI for Veil Cash privacy pools on Base").version("0.6.0").addHelpText("after", `
+program2.name("veil").description("CLI for Veil Cash privacy pools on Base").version("0.6.2").addHelpText("after", `
 Getting started:
   veil init
   veil register