@veil-cash/sdk 0.6.0 → 0.6.2

package/README.md

@@ -1,13 +1,15 @@
 # @veil-cash/sdk
 
-[![npm version](https://img.shields.io/npm/v/@veil-cash/sdk.svg)](https://www.npmjs.com/package/@veil-cash/sdk)
-[![npm downloads](https://img.shields.io/npm/dm/@veil-cash/sdk.svg)](https://www.npmjs.com/package/@veil-cash/sdk)
-[![license](https://img.shields.io/npm/l/@veil-cash/sdk.svg)](https://github.com/veildotcash/veildotcash-sdk/blob/main/LICENSE)
+[npm version](https://www.npmjs.com/package/@veil-cash/sdk)
+[npm downloads](https://www.npmjs.com/package/@veil-cash/sdk)
+[license](https://github.com/veildotcash/veildotcash-sdk/blob/main/LICENSE)
 
 SDK and CLI for interacting with [Veil Cash](https://veil.cash) privacy pools on Base.
 
 Generate keypairs, register, deposit, withdraw, transfer, and merge ETH and USDC privately.
 
+`0.6.2` adds `mergeSubaccount` — transfer a subaccount's private pool balance back to the main wallet via a ZK proof. Also adds `veil subaccount merge` CLI command.
+
 `0.6.0` adds SDK-first subaccount support for deterministic slot derivation, forwarder status, relay-backed deploy/sweep, and direct recovery.
 
 ## Installation
@@ -21,13 +23,14 @@ pnpm add @veil-cash/sdk
 ```
 
 For global CLI access:
+
 ```bash
 npm install -g @veil-cash/sdk
 ```
 
 ## Agent Skill
 
-This repo includes a Veil agent skill at [`skills/veil/SKILL.md`](./skills/veil/SKILL.md).
+This repo includes a Veil agent skill at [skills/veil/SKILL.md](./skills/veil/SKILL.md).
 
 Quick mapping:
 
@@ -35,16 +38,18 @@ Quick mapping:
 - CLI binary: `veil`
 - agent skill file: `skills/veil/SKILL.md`
 
-If you are pointing an agent at this repo, send it to [`skills/veil/SKILL.md`](./skills/veil/SKILL.md) for the canonical CLI workflow.
+If you are pointing an agent at this repo, send it to [skills/veil/SKILL.md](./skills/veil/SKILL.md) for the canonical CLI workflow.
 
 If you install the npm package, the published package also includes the `skills/` directory so the same skill can be discovered from the installed package contents.
 
 ## Supported Assets
 
-| Asset | Decimals | Token Contract |
-|-------|----------|---------------|
-| ETH | 18 | Native ETH (via WETH) |
-| USDC | 6 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+
+| Asset | Decimals | Token Contract                               |
+| ----- | -------- | -------------------------------------------- |
+| ETH   | 18       | Native ETH (via WETH)                        |
+| USDC  | 6        | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+
 
 ## CLI Quick Start
 
@@ -83,6 +88,7 @@ veil subaccount derive --slot 0
 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
 
 # 9. Use JSON or unsigned modes when you need automation
@@ -204,7 +210,7 @@ Subaccounts are deterministic child slots derived from your main `VEIL_KEY`:
 
 `root key -> slot -> child key -> child deposit key -> forwarder`
 
-Base mainnet only. Deploy and sweep are relay-backed. Status reports the forwarder wallet and queue state only, not private pool attribution after queued funds are accepted. Recovery is for assets still sitting on the forwarder after refund or rejection, and is submitted directly on-chain by your CLI gas payer.
+Base mainnet only. Deploy and sweep are relay-backed. Merge transfers the subaccount's private pool balance back to the main wallet via a ZK proof. Status reports forwarder wallet balances, private pool balances, and queue state for the child slot. Recovery is for assets still sitting on the forwarder after refund or rejection, and is submitted directly on-chain by your CLI gas payer.
 
 ```bash
 veil subaccount derive --slot 0
@@ -212,6 +218,7 @@ veil subaccount status --slot 0
 veil subaccount address --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 status --slot 0 --json
 ```
@@ -220,21 +227,25 @@ veil subaccount status --slot 0 --json
 
 The CLI uses two config files:
 
-| File | Purpose |
-|------|---------|
-| `.env.veil` | Veil keypair (VEIL_KEY, DEPOSIT_KEY) - created by `veil init` |
-| `.env` | Wallet config (WALLET_KEY or SIGNER_ADDRESS, RPC_URL) - your existing config |
+
+| File        | Purpose                                                                      |
+| ----------- | ---------------------------------------------------------------------------- |
+| `.env.veil` | Veil keypair (VEIL_KEY, DEPOSIT_KEY) - created by `veil init`                |
+| `.env`      | Wallet config (WALLET_KEY or SIGNER_ADDRESS, RPC_URL) - your existing config |
+
 
 ### Variables
 
-| Variable | Description |
-|----------|-------------|
-| `VEIL_KEY` | Your Veil private key (for ZK proofs, withdrawals, transfers) |
-| `DEPOSIT_KEY` | Your Veil deposit key (public, for register/deposit) |
-| `WALLET_KEY` | Ethereum wallet private key (for signing transactions) |
-| `SIGNER_ADDRESS` | Ethereum address for unsigned/query flows when signing is handled externally |
-| `RPC_URL` | Base RPC URL (optional, defaults to public RPC) |
-| `RELAY_URL` | Override relay base URL for relayed CLI operations, subaccount deploy/sweep, and status checks |
+
+| Variable         | Description                                                                                    |
+| ---------------- | ---------------------------------------------------------------------------------------------- |
+| `VEIL_KEY`       | Your Veil private key (for ZK proofs, withdrawals, transfers)                                  |
+| `DEPOSIT_KEY`    | Your Veil deposit key (public, for register/deposit)                                           |
+| `WALLET_KEY`     | Ethereum wallet private key (for signing transactions)                                         |
+| `SIGNER_ADDRESS` | Ethereum address for unsigned/query flows when signing is handled externally                   |
+| `RPC_URL`        | Base RPC URL (optional, defaults to public RPC)                                                |
+| `RELAY_URL`      | Override relay base URL for relayed CLI operations, subaccount deploy/sweep, and status checks |
+
 
 `WALLET_KEY` and `SIGNER_ADDRESS` are mutually exclusive. Use `WALLET_KEY` for commands that sign transactions, and `SIGNER_ADDRESS` for address-only agent flows like `status`, `balance`, and `register --unsigned`.
 
@@ -252,22 +263,24 @@ Commands print human-readable success output by default. Errors are standardized
 
 ### Error Codes
 
-| Code | Description |
-|------|-------------|
-| `VEIL_KEY_MISSING` | VEIL_KEY not provided |
-| `WALLET_KEY_MISSING` | WALLET_KEY not provided |
-| `DEPOSIT_KEY_MISSING` | DEPOSIT_KEY not provided |
-| `CONFIG_CONFLICT` | Conflicting CLI env vars provided |
-| `INVALID_ADDRESS` | Invalid Ethereum address format |
-| `INVALID_SLOT` | Invalid subaccount slot format |
-| `INVALID_AMOUNT` | Invalid or below minimum amount |
-| `INSUFFICIENT_BALANCE` | Not enough ETH balance |
-| `USER_NOT_REGISTERED` | Recipient not registered in Veil |
-| `NO_UTXOS` | No unspent UTXOs available |
-| `RELAY_ERROR` | Error from relayer service |
-| `RPC_ERROR` | RPC/network error |
-| `CONTRACT_ERROR` | Smart contract reverted |
-| `UNKNOWN_ERROR` | Unexpected error |
+
+| Code                   | Description                       |
+| ---------------------- | --------------------------------- |
+| `VEIL_KEY_MISSING`     | VEIL_KEY not provided             |
+| `WALLET_KEY_MISSING`   | WALLET_KEY not provided           |
+| `DEPOSIT_KEY_MISSING`  | DEPOSIT_KEY not provided          |
+| `CONFIG_CONFLICT`      | Conflicting CLI env vars provided |
+| `INVALID_ADDRESS`      | Invalid Ethereum address format   |
+| `INVALID_SLOT`         | Invalid subaccount slot format    |
+| `INVALID_AMOUNT`       | Invalid or below minimum amount   |
+| `INSUFFICIENT_BALANCE` | Not enough ETH balance            |
+| `USER_NOT_REGISTERED`  | Recipient not registered in Veil  |
+| `NO_UTXOS`             | No unspent UTXOs available        |
+| `RELAY_ERROR`          | Error from relayer service        |
+| `RPC_ERROR`            | RPC/network error                 |
+| `CONTRACT_ERROR`       | Smart contract reverted           |
+| `UNKNOWN_ERROR`        | Unexpected error                  |
+
 
 ## SDK Docs
 

package/SDK.md

@@ -10,7 +10,7 @@ If you are looking for the CLI first-run flow, go back to the main [README](./RE
 import {
   Keypair, buildRegisterTx, buildDepositETHTx,
   buildDepositUSDCTx, buildApproveUSDCTx,
-  withdraw, transfer, getSubaccountStatus,
+  withdraw, transfer, getSubaccountStatus, mergeSubaccount,
 } from '@veil-cash/sdk';
 import { createWalletClient, http } from 'viem';
 import { base } from 'viem/chains';
@@ -203,14 +203,16 @@ Subaccounts are deterministic child slots derived from your main Veil key:
 
 `root key -> slot -> child key -> child deposit key -> forwarder`
 
-Base mainnet only. Status shows the forwarder wallet and queue state only. Deploy and sweep are relay-backed. Recovery signs a forwarder withdraw request with the child key and returns a direct transaction for your gas payer to submit.
+Base mainnet only. Status shows the child slot's forwarder wallet balances, private pool balances, and queue state. Deploy and sweep are relay-backed. Merge transfers the subaccount's private pool balance back to the main wallet via a ZK proof. Recovery signs a forwarder withdraw request with the child key and returns a direct transaction for your gas payer to submit.
 
 ```typescript
 import {
   deriveSubaccountSlot,
+  getSubaccountPrivateBalance,
   getSubaccountStatus,
   deploySubaccountForwarder,
   sweepSubaccountForwarder,
+  mergeSubaccount,
   buildSubaccountRecoveryTx,
 } from '@veil-cash/sdk';
 
@@ -223,6 +225,14 @@ const status = await getSubaccountStatus({
   rootPrivateKey: veilKey,
   slot: 0,
 });
+// status.privateBalances.eth.privateBalance, status.privateBalances.usdc.privateBalance
+
+const privateBalance = await getSubaccountPrivateBalance({
+  rootPrivateKey: veilKey,
+  slot: 0,
+  pool: 'eth',
+});
+// privateBalance.privateBalance, privateBalance.unspentCount
 
 await deploySubaccountForwarder({
   rootPrivateKey: veilKey,
@@ -234,6 +244,14 @@ await sweepSubaccountForwarder({
   asset: 'eth',
 });
 
+// Merge subaccount's private pool balance back to the main wallet
+const mergeResult = await mergeSubaccount({
+  rootPrivateKey: veilKey,
+  slot: 0,
+  pool: 'eth', // 'eth' | 'usdc' (default: 'eth')
+});
+// mergeResult.amount, mergeResult.transactionHash
+
 const recovery = await buildSubaccountRecoveryTx({
   rootPrivateKey: veilKey,
   slot: 0,

package/dist/cli/index.cjs

@@ -6682,7 +6682,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 +7598,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 +7640,7 @@ async function deploySubaccountForwarder(options) {
     slot: options.slot,
     rpcUrl: options.rpcUrl
   });
-  return postRelayJson(
+  const result = await postRelayJson(
     "/stealth/deploy",
     {
       salt: slot.salt,
@@ -7640,6 +7650,7 @@ async function deploySubaccountForwarder(options) {
     },
     options.relayUrl
   );
+  return { ...result, slot };
 }
 async function sweepSubaccountForwarder(options) {
   const asset = normalizeAsset(options.asset);
@@ -7664,11 +7675,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 +7721,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 +7748,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 +7898,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 +8062,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 +8088,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 +8126,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 +8151,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 +8172,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 +8181,7 @@ Examples:
       const output = {
         ...result,
         slot: options.slot,
-        forwarderAddress: slot.forwarderAddress
+        forwarderAddress: result.slot.forwarderAddress
       };
       if (options.json) {
         printJson(output);
@@ -7997,7 +8190,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 +8235,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 +8362,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