@veil-cash/sdk 0.6.1 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veil-cash/sdk",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "SDK and CLI for interacting with Veil Cash privacy pools - keypair generation, deposits, and status checking",
   "type": "module",
   "main": "./dist/index.js",

package/skills/veil/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: veil
-version: 0.6.0
+version: 0.6.2
 description: >
   Veil CLI for private ETH and USDC transactions on Base. Use when the user wants
   to deposit, withdraw, or transfer assets privately, check private balances,
   manage Veil keypairs, register on-chain, manage deterministic subaccounts
-  (forwarder deploy, sweep, recover), or build unsigned transaction payloads
-  for an external signer (e.g. Bankr). All operations target Base (chain ID 8453).
+  (forwarder deploy, sweep, merge to main wallet, recover), or build unsigned
+  transaction payloads for an external signer (e.g. Bankr). All operations
+  target Base (chain ID 8453).
 author: veildotcash
 metadata:
   homepage: https://veil.cash
@@ -35,6 +36,7 @@ triggers:
   - pattern: withdraw privately
   - pattern: private transfer
   - pattern: subaccount
+  - pattern: subaccount merge
   - pattern: forwarder
   - pattern: stealth deposit
 ---
@@ -200,6 +202,7 @@ What do you want to do?
 | Subaccount address | `veil subaccount address --slot 0` |
 | Deploy forwarder | `veil subaccount deploy --slot 0` |
 | Sweep forwarder | `veil subaccount sweep --slot 0 --asset eth` |
+| Merge subaccount to main | `veil subaccount merge --slot 0 --pool eth` |
 | Recover from forwarder | `veil subaccount recover --slot 0 --asset usdc --to 0xAddr --amount 25` |
 
 ---
@@ -428,11 +431,13 @@ Subaccounts are deterministic child slots derived from your main `VEIL_KEY`:
 `root key → slot → child key → child deposit key → forwarder`
 
 Base mainnet only. Slots are `0`–`2` (max 3 subaccounts). Deploy and sweep are
-relay-backed (no `WALLET_KEY` needed). Recovery submits a direct on-chain
-transaction and **requires `WALLET_KEY`** as a gas payer.
+relay-backed (no `WALLET_KEY` needed). Merge transfers the subaccount's private
+pool balance back to the main wallet via a ZK proof (relay-backed, no `WALLET_KEY`
+needed). Recovery submits a direct on-chain transaction and **requires `WALLET_KEY`**
+as a gas payer.
 
-Status reports the forwarder wallet balances and queue state only, not private
-pool attribution after queued funds are accepted.
+Status reports the child slot's forwarder wallet balances, private pool
+balances, and queue state.
 
 ### Derive and inspect
 
@@ -440,7 +445,7 @@ pool attribution after queued funds are accepted.
 veil subaccount derive --slot 0           # Full slot metadata
 veil subaccount derive --slot 0 --json
 veil subaccount address --slot 0          # Just the forwarder address
-veil subaccount status --slot 0           # Deployment, balances, queue state
+veil subaccount status --slot 0           # Deployment, forwarder balances, private balances, queue state
 veil subaccount status --slot 0 --json
 ```
 
@@ -454,6 +459,18 @@ veil subaccount sweep --slot 0 --asset usdc   # Sweep USDC into the pool
 veil subaccount sweep --slot 0 --asset eth --json
 ```
 
+### Merge subaccount to main wallet (relay-backed)
+
+Merge transfers the subaccount's entire private pool balance back to the main
+wallet. It builds a ZK proof transferring child UTXOs to the parent keypair and
+submits via the relay. Only needs `VEIL_KEY`.
+
+```bash
+veil subaccount merge --slot 0 --pool eth
+veil subaccount merge --slot 0 --pool usdc
+veil subaccount merge --slot 0 --pool eth --json
+```
+
 ### Recover (direct on-chain — requires WALLET_KEY)
 
 Recovery is for assets still sitting on the forwarder after refund or rejection.
@@ -470,6 +487,7 @@ Important:
 - `--asset` is `eth` or `usdc` (case-insensitive in the CLI)
 - `--slot` is `0`–`2`
 - Deploy and sweep only need `VEIL_KEY`
+- Merge only needs `VEIL_KEY`
 - Recover needs both `VEIL_KEY` and `WALLET_KEY`
 
 ---

package/skills/veil/reference.md

@@ -148,9 +148,11 @@ const priv = await getPrivateBalance({
 ```typescript
 import {
   deriveSubaccountSlot,
+  getSubaccountPrivateBalance,
   getSubaccountStatus,
   deploySubaccountForwarder,
   sweepSubaccountForwarder,
+  mergeSubaccount,
   buildSubaccountRecoveryTx,
   isSubaccountForwarderDeployed,
   MAX_SUBACCOUNT_SLOTS,
@@ -168,12 +170,20 @@ const deployed = await isSubaccountForwarderDeployed({
   forwarderAddress: slot.forwarderAddress,
 });
 
-// Full status (deployment, balances, queue state)
+// Full status (deployment, forwarder balances, private balances, queue state)
 const status = await getSubaccountStatus({
   rootPrivateKey: '0xVEIL_KEY',
   slot: 0,
 });
-// status.deployed, status.balances.eth, status.balances.usdc, status.queues
+// status.deployed, status.balances, status.privateBalances, status.queues
+
+// Private pool balance for a single slot + pool
+const privateBalance = await getSubaccountPrivateBalance({
+  rootPrivateKey: '0xVEIL_KEY',
+  slot: 0,
+  pool: 'eth',
+});
+// privateBalance.privateBalance, privateBalance.unspentCount, privateBalance.utxos
 
 // Deploy forwarder (relay-backed, no WALLET_KEY needed)
 const deployResult = await deploySubaccountForwarder({
@@ -188,6 +198,14 @@ const sweepResult = await sweepSubaccountForwarder({
   asset: 'eth',     // 'eth' | 'usdc'
 });
 
+// Merge subaccount's private balance back to main wallet (relay-backed)
+const mergeResult = await mergeSubaccount({
+  rootPrivateKey: '0xVEIL_KEY',
+  slot: 0,
+  pool: 'eth',     // 'eth' | 'usdc' (default: 'eth')
+});
+// mergeResult.success, mergeResult.transactionHash, mergeResult.amount, mergeResult.slot, mergeResult.pool
+
 // Build recovery transaction (for assets stuck on forwarder)
 const recovery = await buildSubaccountRecoveryTx({
   rootPrivateKey: '0xVEIL_KEY',
@@ -256,12 +274,14 @@ veil balance private --json                        # Private balance as JSON
 veil subaccount derive --slot 0                    # Derive slot metadata
 veil subaccount derive --slot 0 --json             # Derive as JSON
 veil subaccount address --slot 0                   # Print forwarder address
-veil subaccount status --slot 0                    # Deployment, balances, queue state
+veil subaccount status --slot 0                    # Deployment, forwarder balances, private balances, queue state
 veil subaccount status --slot 0 --json             # Status as JSON
 veil subaccount deploy --slot 0                    # Deploy forwarder (relay-backed)
 veil subaccount deploy --slot 0 --json             # Deploy as JSON
 veil subaccount sweep --slot 0 --asset eth         # Sweep ETH into pool (relay-backed)
 veil subaccount sweep --slot 0 --asset usdc --json # Sweep USDC as JSON
+veil subaccount merge --slot 0 --pool eth          # Merge subaccount balance to main wallet
+veil subaccount merge --slot 0 --pool usdc --json  # Merge USDC as JSON
 veil subaccount recover --slot 0 --asset usdc --to 0x... --amount 25   # Recover assets (needs WALLET_KEY)
 veil subaccount recover --slot 0 --asset eth --to 0x... --amount 0.05 --json
 ```

package/src/cli/commands/subaccount.ts

@@ -7,13 +7,14 @@ import {
   getSubaccountStatus,
   isSubaccountForwarderDeployed,
   MAX_SUBACCOUNT_SLOTS,
+  mergeSubaccount,
   sweepSubaccountForwarder,
 } from '../../subaccount.js';
 import { getConfig } from '../config.js';
 import { CLIError, ErrorCode, handleCLIError } from '../errors.js';
 import { printFields, printHeader, printJson, printLine, printList, printSection, txUrl } from '../output.js';
 import { sendTransaction } from '../wallet.js';
-import type { SubaccountAsset } from '../../types.js';
+import type { SubaccountAsset, RelayPool } from '../../types.js';
 
 function parseSlotValue(raw: string): number {
   const normalized = raw.trim();
@@ -51,6 +52,14 @@ function parseAsset(raw: string): SubaccountAsset {
   return asset;
 }
 
+function parsePool(raw: string): RelayPool {
+  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: string,
   queue: {
@@ -81,6 +90,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
 `);
@@ -130,7 +140,7 @@ Examples:
 
   subaccount
     .command('status')
-    .description('Show subaccount deployment, balances, and queue state')
+    .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) => {
@@ -162,6 +172,18 @@ Examples:
           { 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();
@@ -255,6 +277,64 @@ Examples:
       }
     });
 
+  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' as RelayPool)
+    .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
+            ? undefined
+            : (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')

package/src/cli/index.ts

@@ -38,7 +38,7 @@ const program = new Command();
 program
   .name('veil')
   .description('CLI for Veil Cash privacy pools on Base')
-  .version('0.6.1')
+  .version('0.6.2')
   .addHelpText('after', `
 Getting started:
   veil init

package/src/index.ts

@@ -139,12 +139,14 @@ export {
   isSubaccountForwarderDeployed,
   deploySubaccountForwarder,
   sweepSubaccountForwarder,
+  getSubaccountPrivateBalance,
   getSubaccountStatus,
   buildSubaccountWithdrawTypedData,
   signSubaccountWithdraw,
   isSubaccountWithdrawNonceUsed,
   findNextSubaccountWithdrawNonce,
   buildSubaccountRecoveryTx,
+  mergeSubaccount,
 } from './subaccount.js';
 
 // Utilities
@@ -197,8 +199,12 @@ export type {
   SubaccountRelayResult,
   SubaccountAssetBalance,
   SubaccountBalances,
+  SubaccountPrivateBalanceStatus,
+  SubaccountPrivateBalances,
   SubaccountQueueStatus,
   SubaccountStatusResult,
   SubaccountWithdrawTypedData,
   SubaccountRecoveryResult,
+  SubaccountMergeOptions,
+  SubaccountMergeResult,
 } from './types.js';

package/src/subaccount.ts

@@ -12,14 +12,21 @@ import {
 } from 'viem';
 import { privateKeyToAccount, privateKeyToAddress } from 'viem/accounts';
 import { base } from 'viem/chains';
-import { FORWARDER_ABI, FORWARDER_FACTORY_ABI, ERC20_ABI } from './abi.js';
-import { FORWARDER_CONTRACT_VERSION, getAddresses, getForwarderFactoryAddress } from './addresses.js';
-import { getQueueBalance } from './balance.js';
+import { FORWARDER_ABI, FORWARDER_FACTORY_ABI, ERC20_ABI, POOL_ABI } from './abi.js';
+import { FORWARDER_CONTRACT_VERSION, getAddresses, getForwarderFactoryAddress, getPoolAddress, POOL_CONFIG } from './addresses.js';
+import { getPrivateBalance, getQueueBalance } from './balance.js';
 import { Keypair } from './keypair.js';
-import { postRelayJson } from './relay.js';
+import { postRelayJson, submitRelay } from './relay.js';
+import { prepareTransaction } from './transaction.js';
+import { Utxo } from './utxo.js';
+import { selectUtxosForWithdraw } from './withdraw.js';
 import type {
   SubaccountAsset,
   SubaccountDeployRequest,
+  SubaccountMergeOptions,
+  SubaccountMergeResult,
+  PrivateBalanceResult,
+  SubaccountPrivateBalanceStatus,
   SubaccountQueueStatus,
   SubaccountRecoveryResult,
   SubaccountRelayResult,
@@ -238,6 +245,37 @@ function toQueueStatus(
   };
 }
 
+function toPrivateBalanceStatus(result: PrivateBalanceResult): SubaccountPrivateBalanceStatus {
+  return {
+    privateBalance: result.privateBalance,
+    privateBalanceWei: result.privateBalanceWei,
+    utxoCount: result.utxoCount,
+    spentCount: result.spentCount,
+    unspentCount: result.unspentCount,
+  };
+}
+
+export async function getSubaccountPrivateBalance(options: {
+  rootPrivateKey: `0x${string}`;
+  slot: number;
+  pool?: 'eth' | 'usdc';
+  rpcUrl?: string;
+  onProgress?: (stage: string, detail?: string) => void;
+}): Promise<PrivateBalanceResult> {
+  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,
+  });
+}
+
 export async function getSubaccountStatus(options: {
   rootPrivateKey: `0x${string}`;
   slot: number;
@@ -247,7 +285,7 @@ export async function getSubaccountStatus(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,
@@ -269,6 +307,18 @@ export async function getSubaccountStatus(options: {
       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 {
@@ -284,6 +334,10 @@ export async function getSubaccountStatus(options: {
         balanceWei: usdcWei.toString(),
       },
     },
+    privateBalances: {
+      eth: toPrivateBalanceStatus(ethPrivate),
+      usdc: toPrivateBalanceStatus(usdcPrivate),
+    },
     queues: {
       eth: toQueueStatus('eth', ethQueue),
       usdc: toQueueStatus('usdc', usdcQueue),
@@ -479,3 +533,188 @@ export async function buildSubaccountRecoveryTx(options: {
     signature,
   };
 }
+
+/**
+ * Merge a subaccount's entire private balance back to the main wallet.
+ *
+ * Builds a ZK transfer proof that moves every unspent UTXO belonging to the
+ * child keypair into a new UTXO encrypted to the parent (root) keypair,
+ * then submits it via the relay.
+ *
+ * @param options - Merge options
+ * @returns Merge result with transaction hash and amount
+ *
+ * @example
+ * ```typescript
+ * const result = await mergeSubaccount({
+ *   rootPrivateKey: process.env.VEIL_KEY as `0x${string}`,
+ *   slot: 0,
+ *   pool: 'eth',
+ * });
+ * console.log(`Merged ${result.amount} — tx: ${result.transactionHash}`);
+ * ```
+ */
+export async function mergeSubaccount(
+  options: SubaccountMergeOptions,
+): Promise<SubaccountMergeResult> {
+  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);
+
+  // Derive child and parent keypairs
+  const childPrivateKey = deriveSubaccountChildPrivateKey(rootPrivateKey, normalizedSlot);
+  const childKeypair = new Keypair(childPrivateKey);
+  const parentKeypair = new Keypair(rootPrivateKey);
+
+  // Fetch child's private balance
+  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.',
+    );
+  }
+
+  // Re-decrypt UTXOs to get full Utxo objects
+  onProgress?.('Preparing UTXOs...');
+  const publicClient = createPublicClient({
+    chain: base,
+    transport: http(rpcUrl),
+  });
+
+  const utxos: Utxo[] = [];
+  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)],
+    }) as string[];
+
+    if (encryptedOutputs.length > 0) {
+      try {
+        const utxo = Utxo.decrypt(encryptedOutputs[0], childKeypair);
+        utxo.index = utxoInfo.index;
+        utxos.push(utxo);
+      } catch {
+        // Skip if decryption fails
+      }
+    }
+  }
+
+  if (utxos.length === 0) {
+    throw new Error('Failed to decrypt subaccount UTXOs');
+  }
+
+  // Select all UTXOs — transfer the full balance
+  onProgress?.('Selecting UTXOs...');
+  const amount = balanceResult.privateBalance;
+  const { selectedUtxos, changeAmount } = selectUtxosForWithdraw(
+    utxos,
+    amount,
+    poolConfig.decimals,
+  );
+
+  // Create output UTXO encrypted to the parent keypair
+  const outputs: Utxo[] = [];
+  const mergeWei = parseUnits(amount, poolConfig.decimals);
+
+  outputs.push(new Utxo({ amount: mergeWei, keypair: parentKeypair }));
+
+  if (changeAmount > 0n) {
+    outputs.push(new Utxo({ amount: changeAmount, keypair: parentKeypair }));
+  }
+
+  // Fetch all commitments from pool
+  onProgress?.('Fetching commitments...');
+  const nextIndex = await publicClient.readContract({
+    address: poolAddress,
+    abi: POOL_ABI,
+    functionName: 'nextIndex',
+  }) as number;
+
+  const BATCH_SIZE = 5000;
+  const commitments: string[] = [];
+  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)],
+    }) as `0x${string}`[];
+
+    commitments.push(...batch.map(c => c.toString()));
+  }
+
+  // Build ZK proof (recipient = 0x0 for in-pool transfer)
+  onProgress?.('Building ZK proof...');
+  const result = await prepareTransaction({
+    commitments,
+    inputs: selectedUtxos,
+    outputs,
+    fee: 0,
+    recipient: '0x0000000000000000000000000000000000000000',
+    relayer: '0x0000000000000000000000000000000000000000',
+    onProgress,
+  });
+
+  // Submit to relay
+  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 as [string, string],
+      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,
+  };
+}

package/src/types.ts

@@ -377,6 +377,25 @@ export interface SubaccountBalances {
   usdc: SubaccountAssetBalance;
 }
 
+/**
+ * Private pool balance summary for a specific asset
+ */
+export interface SubaccountPrivateBalanceStatus {
+  privateBalance: string;
+  privateBalanceWei: string;
+  utxoCount: number;
+  spentCount: number;
+  unspentCount: number;
+}
+
+/**
+ * Private pool balances for both supported assets
+ */
+export interface SubaccountPrivateBalances {
+  eth: SubaccountPrivateBalanceStatus;
+  usdc: SubaccountPrivateBalanceStatus;
+}
+
 /**
  * Queue status for a specific asset
  */
@@ -395,6 +414,7 @@ export interface SubaccountStatusResult {
   slot: SubaccountSlot;
   deployed: boolean;
   balances: SubaccountBalances;
+  privateBalances: SubaccountPrivateBalances;
   queues: {
     eth: SubaccountQueueStatus;
     usdc: SubaccountQueueStatus;
@@ -427,6 +447,42 @@ export interface SubaccountWithdrawTypedData {
   };
 }
 
+/**
+ * Options for merging a subaccount's private balance back to the main wallet
+ */
+export interface SubaccountMergeOptions {
+  /** Root private key (VEIL_KEY) */
+  rootPrivateKey: `0x${string}`;
+  /** Subaccount slot (0-2) */
+  slot: number;
+  /** Pool to merge in (default: 'eth') */
+  pool?: RelayPool;
+  /** Optional RPC URL */
+  rpcUrl?: string;
+  /** Optional relay URL */
+  relayUrl?: string;
+  /** Progress callback */
+  onProgress?: (stage: string, detail?: string) => void;
+}
+
+/**
+ * Result from merging a subaccount's balance to the main wallet
+ */
+export interface SubaccountMergeResult {
+  /** Whether the merge was successful */
+  success: boolean;
+  /** Transaction hash */
+  transactionHash: string;
+  /** Block number of the transaction */
+  blockNumber: string;
+  /** Amount merged (human-readable) */
+  amount: string;
+  /** Subaccount slot that was merged */
+  slot: number;
+  /** Pool the merge was executed in */
+  pool: RelayPool;
+}
+
 /**
  * Built recovery transaction and signing metadata
  */