@veil-cash/sdk 0.6.1 → 0.6.2

package/README.md

@@ -8,6 +8,8 @@ SDK and CLI for interacting with [Veil Cash](https://veil.cash) privacy pools on
 
 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
@@ -86,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
@@ -207,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
@@ -215,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
 ```

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