@veil-cash/sdk 0.6.1 → 0.6.3

package/dist/index.d.cts

@@ -406,6 +406,23 @@ interface SubaccountBalances {
     eth: SubaccountAssetBalance;
     usdc: SubaccountAssetBalance;
 }
+/**
+ * Private pool balance summary for a specific asset
+ */
+interface SubaccountPrivateBalanceStatus {
+    privateBalance: string;
+    privateBalanceWei: string;
+    utxoCount: number;
+    spentCount: number;
+    unspentCount: number;
+}
+/**
+ * Private pool balances for both supported assets
+ */
+interface SubaccountPrivateBalances {
+    eth: SubaccountPrivateBalanceStatus;
+    usdc: SubaccountPrivateBalanceStatus;
+}
 /**
  * Queue status for a specific asset
  */
@@ -423,6 +440,7 @@ interface SubaccountStatusResult {
     slot: SubaccountSlot;
     deployed: boolean;
     balances: SubaccountBalances;
+    privateBalances: SubaccountPrivateBalances;
     queues: {
         eth: SubaccountQueueStatus;
         usdc: SubaccountQueueStatus;
@@ -453,6 +471,40 @@ interface SubaccountWithdrawTypedData {
         deadline: bigint;
     };
 }
+/**
+ * Options for merging a subaccount's private balance back to the main wallet
+ */
+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
+ */
+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
  */
@@ -766,6 +818,31 @@ declare function getQueueBalance(options: {
     rpcUrl?: string;
     onProgress?: ProgressCallback;
 }): Promise<QueueBalanceResult>;
+/**
+ * Get remaining daily free deposits for an address.
+ * Returns 0 if the queue contract has not been upgraded to V3 yet
+ * or if the daily free feature is disabled.
+ *
+ * @param options - Query options
+ * @param options.address - Depositor address to check
+ * @param options.pool - Pool identifier ('eth' or 'usdc', default: 'eth')
+ * @param options.rpcUrl - Optional RPC URL
+ * @returns Number of free deposits remaining today
+ *
+ * @example
+ * ```typescript
+ * const remaining = await getDailyFreeRemaining({
+ *   address: '0x...',
+ *   pool: 'eth',
+ * });
+ * console.log(`Free deposits left today: ${remaining}`);
+ * ```
+ */
+declare function getDailyFreeRemaining(options: {
+    address: `0x${string}`;
+    pool?: RelayPool;
+    rpcUrl?: string;
+}): Promise<number>;
 /**
  * Get private balance from the Pool contract
  * Decrypts all encrypted outputs, calculates nullifiers, and checks spent status
@@ -1596,6 +1673,18 @@ declare const QUEUE_ABI: readonly [{
     }];
     readonly stateMutability: "view";
     readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_depositor";
+        readonly type: "address";
+    }];
+    readonly name: "getDailyFreeRemaining";
+    readonly outputs: readonly [{
+        readonly name: "remaining";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
 }];
 /**
  * ETH Pool Contract ABI
@@ -2587,8 +2676,17 @@ declare function isSubaccountForwarderDeployed(options: {
     forwarderAddress: `0x${string}`;
     rpcUrl?: string;
 }): Promise<boolean>;
-declare function deploySubaccountForwarder(options: SubaccountDeployRequest): Promise<SubaccountRelayResult>;
+declare function deploySubaccountForwarder(options: SubaccountDeployRequest): Promise<SubaccountRelayResult & {
+    slot: SubaccountSlot;
+}>;
 declare function sweepSubaccountForwarder(options: SubaccountSweepRequest): Promise<SubaccountRelayResult>;
+declare function getSubaccountPrivateBalance(options: {
+    rootPrivateKey: `0x${string}`;
+    slot: number;
+    pool?: 'eth' | 'usdc';
+    rpcUrl?: string;
+    onProgress?: (stage: string, detail?: string) => void;
+}): Promise<PrivateBalanceResult>;
 declare function getSubaccountStatus(options: {
     rootPrivateKey: `0x${string}`;
     slot: number;
@@ -2627,6 +2725,27 @@ declare function buildSubaccountRecoveryTx(options: {
     deadline?: bigint | number;
     rpcUrl?: string;
 }): Promise<SubaccountRecoveryResult>;
+/**
+ * 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}`);
+ * ```
+ */
+declare function mergeSubaccount(options: SubaccountMergeOptions): Promise<SubaccountMergeResult>;
 
 /**
  * Crypto utilities for Veil SDK
@@ -2697,4 +2816,4 @@ declare function getExtDataHash(extData: ExtDataInput): bigint;
  */
 declare function shuffle<T>(array: T[]): T[];
 
-export { ADDRESSES, type BuildTransferProofOptions, type BuildWithdrawProofOptions, CIRCUIT_CONFIG, type DepositTxOptions, ENTRY_ABI, ERC20_ABI, type EncryptedMessage, type ExtData, type ExtDataInput, FIELD_SIZE, FORWARDER_ABI, FORWARDER_CONTRACT_VERSION, FORWARDER_FACTORY_ABI, Keypair, MAX_SUBACCOUNT_SLOTS, MERKLE_TREE_HEIGHT, type MessageSigner, type NetworkAddresses, POOL_ABI, POOL_CONFIG, type PendingDeposit, type PoolConfig, type PrepareTransactionParams, type PrivateBalanceResult, type ProgressCallback, type ProofArgs, type ProofBuildResult, type ProofInput, QUEUE_ABI, type QueueBalanceResult, type RegisterTxOptions, RelayError, type RelayErrorResponse, type RelayExtData, type RelayMetadata, type RelayPool, type RelayProofArgs, type RelayRequest, type RelayResponse, type RelayType, type SubaccountAsset, type SubaccountAssetBalance, type SubaccountBalances, type SubaccountDeployRequest, type SubaccountQueueStatus, type SubaccountRecoveryResult, type SubaccountRelayResult, type SubaccountSlot, type SubaccountStatusResult, type SubaccountSweepRequest, type SubaccountWithdrawTypedData, type SubmitRelayOptions, type Token, type TransactionData, type TransactionResult, type TransferResult, Utxo, type UtxoInfo, type UtxoParams, type UtxoSelectionResult, VEIL_SIGNED_MESSAGE, type WithdrawResult, buildApproveUSDCTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx, buildDepositUSDCTx, buildMerkleTree, buildRegisterTx, buildSubaccountRecoveryTx, buildSubaccountWithdrawTypedData, buildTransferProof, buildWithdrawProof, checkRecipientRegistration, checkRelayHealth, deploySubaccountForwarder, deriveSubaccountChildDepositKey, deriveSubaccountChildOwner, deriveSubaccountChildPrivateKey, deriveSubaccountSalt, deriveSubaccountSlot, findNextSubaccountWithdrawNonce, getAddresses, getExtDataHash, getForwarderFactoryAddress, getMerklePath, getPoolAddress, getPrivateBalance, getQueueAddress, getQueueBalance, getRelayInfo, getRelayUrl, getSubaccountStatus, isSubaccountForwarderDeployed, isSubaccountWithdrawNonceUsed, mergeUtxos, packEncryptedMessage, poseidonHash, poseidonHash2, predictSubaccountForwarder, prepareTransaction, prove, randomBN, selectCircuit, selectUtxosForWithdraw, shuffle, signSubaccountWithdraw, submitRelay, sweepSubaccountForwarder, toBuffer, toFixedHex, transfer, unpackEncryptedMessage, withdraw };
+export { ADDRESSES, type BuildTransferProofOptions, type BuildWithdrawProofOptions, CIRCUIT_CONFIG, type DepositTxOptions, ENTRY_ABI, ERC20_ABI, type EncryptedMessage, type ExtData, type ExtDataInput, FIELD_SIZE, FORWARDER_ABI, FORWARDER_CONTRACT_VERSION, FORWARDER_FACTORY_ABI, Keypair, MAX_SUBACCOUNT_SLOTS, MERKLE_TREE_HEIGHT, type MessageSigner, type NetworkAddresses, POOL_ABI, POOL_CONFIG, type PendingDeposit, type PoolConfig, type PrepareTransactionParams, type PrivateBalanceResult, type ProgressCallback, type ProofArgs, type ProofBuildResult, type ProofInput, QUEUE_ABI, type QueueBalanceResult, type RegisterTxOptions, RelayError, type RelayErrorResponse, type RelayExtData, type RelayMetadata, type RelayPool, type RelayProofArgs, type RelayRequest, type RelayResponse, type RelayType, type SubaccountAsset, type SubaccountAssetBalance, type SubaccountBalances, type SubaccountDeployRequest, type SubaccountMergeOptions, type SubaccountMergeResult, type SubaccountPrivateBalanceStatus, type SubaccountPrivateBalances, type SubaccountQueueStatus, type SubaccountRecoveryResult, type SubaccountRelayResult, type SubaccountSlot, type SubaccountStatusResult, type SubaccountSweepRequest, type SubaccountWithdrawTypedData, type SubmitRelayOptions, type Token, type TransactionData, type TransactionResult, type TransferResult, Utxo, type UtxoInfo, type UtxoParams, type UtxoSelectionResult, VEIL_SIGNED_MESSAGE, type WithdrawResult, buildApproveUSDCTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx, buildDepositUSDCTx, buildMerkleTree, buildRegisterTx, buildSubaccountRecoveryTx, buildSubaccountWithdrawTypedData, buildTransferProof, buildWithdrawProof, checkRecipientRegistration, checkRelayHealth, deploySubaccountForwarder, deriveSubaccountChildDepositKey, deriveSubaccountChildOwner, deriveSubaccountChildPrivateKey, deriveSubaccountSalt, deriveSubaccountSlot, findNextSubaccountWithdrawNonce, getAddresses, getDailyFreeRemaining, getExtDataHash, getForwarderFactoryAddress, getMerklePath, getPoolAddress, getPrivateBalance, getQueueAddress, getQueueBalance, getRelayInfo, getRelayUrl, getSubaccountPrivateBalance, getSubaccountStatus, isSubaccountForwarderDeployed, isSubaccountWithdrawNonceUsed, mergeSubaccount, mergeUtxos, packEncryptedMessage, poseidonHash, poseidonHash2, predictSubaccountForwarder, prepareTransaction, prove, randomBN, selectCircuit, selectUtxosForWithdraw, shuffle, signSubaccountWithdraw, submitRelay, sweepSubaccountForwarder, toBuffer, toFixedHex, transfer, unpackEncryptedMessage, withdraw };

package/dist/index.d.ts

@@ -406,6 +406,23 @@ interface SubaccountBalances {
     eth: SubaccountAssetBalance;
     usdc: SubaccountAssetBalance;
 }
+/**
+ * Private pool balance summary for a specific asset
+ */
+interface SubaccountPrivateBalanceStatus {
+    privateBalance: string;
+    privateBalanceWei: string;
+    utxoCount: number;
+    spentCount: number;
+    unspentCount: number;
+}
+/**
+ * Private pool balances for both supported assets
+ */
+interface SubaccountPrivateBalances {
+    eth: SubaccountPrivateBalanceStatus;
+    usdc: SubaccountPrivateBalanceStatus;
+}
 /**
  * Queue status for a specific asset
  */
@@ -423,6 +440,7 @@ interface SubaccountStatusResult {
     slot: SubaccountSlot;
     deployed: boolean;
     balances: SubaccountBalances;
+    privateBalances: SubaccountPrivateBalances;
     queues: {
         eth: SubaccountQueueStatus;
         usdc: SubaccountQueueStatus;
@@ -453,6 +471,40 @@ interface SubaccountWithdrawTypedData {
         deadline: bigint;
     };
 }
+/**
+ * Options for merging a subaccount's private balance back to the main wallet
+ */
+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
+ */
+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
  */
@@ -766,6 +818,31 @@ declare function getQueueBalance(options: {
     rpcUrl?: string;
     onProgress?: ProgressCallback;
 }): Promise<QueueBalanceResult>;
+/**
+ * Get remaining daily free deposits for an address.
+ * Returns 0 if the queue contract has not been upgraded to V3 yet
+ * or if the daily free feature is disabled.
+ *
+ * @param options - Query options
+ * @param options.address - Depositor address to check
+ * @param options.pool - Pool identifier ('eth' or 'usdc', default: 'eth')
+ * @param options.rpcUrl - Optional RPC URL
+ * @returns Number of free deposits remaining today
+ *
+ * @example
+ * ```typescript
+ * const remaining = await getDailyFreeRemaining({
+ *   address: '0x...',
+ *   pool: 'eth',
+ * });
+ * console.log(`Free deposits left today: ${remaining}`);
+ * ```
+ */
+declare function getDailyFreeRemaining(options: {
+    address: `0x${string}`;
+    pool?: RelayPool;
+    rpcUrl?: string;
+}): Promise<number>;
 /**
  * Get private balance from the Pool contract
  * Decrypts all encrypted outputs, calculates nullifiers, and checks spent status
@@ -1596,6 +1673,18 @@ declare const QUEUE_ABI: readonly [{
     }];
     readonly stateMutability: "view";
     readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly name: "_depositor";
+        readonly type: "address";
+    }];
+    readonly name: "getDailyFreeRemaining";
+    readonly outputs: readonly [{
+        readonly name: "remaining";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
 }];
 /**
  * ETH Pool Contract ABI
@@ -2587,8 +2676,17 @@ declare function isSubaccountForwarderDeployed(options: {
     forwarderAddress: `0x${string}`;
     rpcUrl?: string;
 }): Promise<boolean>;
-declare function deploySubaccountForwarder(options: SubaccountDeployRequest): Promise<SubaccountRelayResult>;
+declare function deploySubaccountForwarder(options: SubaccountDeployRequest): Promise<SubaccountRelayResult & {
+    slot: SubaccountSlot;
+}>;
 declare function sweepSubaccountForwarder(options: SubaccountSweepRequest): Promise<SubaccountRelayResult>;
+declare function getSubaccountPrivateBalance(options: {
+    rootPrivateKey: `0x${string}`;
+    slot: number;
+    pool?: 'eth' | 'usdc';
+    rpcUrl?: string;
+    onProgress?: (stage: string, detail?: string) => void;
+}): Promise<PrivateBalanceResult>;
 declare function getSubaccountStatus(options: {
     rootPrivateKey: `0x${string}`;
     slot: number;
@@ -2627,6 +2725,27 @@ declare function buildSubaccountRecoveryTx(options: {
     deadline?: bigint | number;
     rpcUrl?: string;
 }): Promise<SubaccountRecoveryResult>;
+/**
+ * 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}`);
+ * ```
+ */
+declare function mergeSubaccount(options: SubaccountMergeOptions): Promise<SubaccountMergeResult>;
 
 /**
  * Crypto utilities for Veil SDK
@@ -2697,4 +2816,4 @@ declare function getExtDataHash(extData: ExtDataInput): bigint;
  */
 declare function shuffle<T>(array: T[]): T[];
 
-export { ADDRESSES, type BuildTransferProofOptions, type BuildWithdrawProofOptions, CIRCUIT_CONFIG, type DepositTxOptions, ENTRY_ABI, ERC20_ABI, type EncryptedMessage, type ExtData, type ExtDataInput, FIELD_SIZE, FORWARDER_ABI, FORWARDER_CONTRACT_VERSION, FORWARDER_FACTORY_ABI, Keypair, MAX_SUBACCOUNT_SLOTS, MERKLE_TREE_HEIGHT, type MessageSigner, type NetworkAddresses, POOL_ABI, POOL_CONFIG, type PendingDeposit, type PoolConfig, type PrepareTransactionParams, type PrivateBalanceResult, type ProgressCallback, type ProofArgs, type ProofBuildResult, type ProofInput, QUEUE_ABI, type QueueBalanceResult, type RegisterTxOptions, RelayError, type RelayErrorResponse, type RelayExtData, type RelayMetadata, type RelayPool, type RelayProofArgs, type RelayRequest, type RelayResponse, type RelayType, type SubaccountAsset, type SubaccountAssetBalance, type SubaccountBalances, type SubaccountDeployRequest, type SubaccountQueueStatus, type SubaccountRecoveryResult, type SubaccountRelayResult, type SubaccountSlot, type SubaccountStatusResult, type SubaccountSweepRequest, type SubaccountWithdrawTypedData, type SubmitRelayOptions, type Token, type TransactionData, type TransactionResult, type TransferResult, Utxo, type UtxoInfo, type UtxoParams, type UtxoSelectionResult, VEIL_SIGNED_MESSAGE, type WithdrawResult, buildApproveUSDCTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx, buildDepositUSDCTx, buildMerkleTree, buildRegisterTx, buildSubaccountRecoveryTx, buildSubaccountWithdrawTypedData, buildTransferProof, buildWithdrawProof, checkRecipientRegistration, checkRelayHealth, deploySubaccountForwarder, deriveSubaccountChildDepositKey, deriveSubaccountChildOwner, deriveSubaccountChildPrivateKey, deriveSubaccountSalt, deriveSubaccountSlot, findNextSubaccountWithdrawNonce, getAddresses, getExtDataHash, getForwarderFactoryAddress, getMerklePath, getPoolAddress, getPrivateBalance, getQueueAddress, getQueueBalance, getRelayInfo, getRelayUrl, getSubaccountStatus, isSubaccountForwarderDeployed, isSubaccountWithdrawNonceUsed, mergeUtxos, packEncryptedMessage, poseidonHash, poseidonHash2, predictSubaccountForwarder, prepareTransaction, prove, randomBN, selectCircuit, selectUtxosForWithdraw, shuffle, signSubaccountWithdraw, submitRelay, sweepSubaccountForwarder, toBuffer, toFixedHex, transfer, unpackEncryptedMessage, withdraw };
+export { ADDRESSES, type BuildTransferProofOptions, type BuildWithdrawProofOptions, CIRCUIT_CONFIG, type DepositTxOptions, ENTRY_ABI, ERC20_ABI, type EncryptedMessage, type ExtData, type ExtDataInput, FIELD_SIZE, FORWARDER_ABI, FORWARDER_CONTRACT_VERSION, FORWARDER_FACTORY_ABI, Keypair, MAX_SUBACCOUNT_SLOTS, MERKLE_TREE_HEIGHT, type MessageSigner, type NetworkAddresses, POOL_ABI, POOL_CONFIG, type PendingDeposit, type PoolConfig, type PrepareTransactionParams, type PrivateBalanceResult, type ProgressCallback, type ProofArgs, type ProofBuildResult, type ProofInput, QUEUE_ABI, type QueueBalanceResult, type RegisterTxOptions, RelayError, type RelayErrorResponse, type RelayExtData, type RelayMetadata, type RelayPool, type RelayProofArgs, type RelayRequest, type RelayResponse, type RelayType, type SubaccountAsset, type SubaccountAssetBalance, type SubaccountBalances, type SubaccountDeployRequest, type SubaccountMergeOptions, type SubaccountMergeResult, type SubaccountPrivateBalanceStatus, type SubaccountPrivateBalances, type SubaccountQueueStatus, type SubaccountRecoveryResult, type SubaccountRelayResult, type SubaccountSlot, type SubaccountStatusResult, type SubaccountSweepRequest, type SubaccountWithdrawTypedData, type SubmitRelayOptions, type Token, type TransactionData, type TransactionResult, type TransferResult, Utxo, type UtxoInfo, type UtxoParams, type UtxoSelectionResult, VEIL_SIGNED_MESSAGE, type WithdrawResult, buildApproveUSDCTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx, buildDepositUSDCTx, buildMerkleTree, buildRegisterTx, buildSubaccountRecoveryTx, buildSubaccountWithdrawTypedData, buildTransferProof, buildWithdrawProof, checkRecipientRegistration, checkRelayHealth, deploySubaccountForwarder, deriveSubaccountChildDepositKey, deriveSubaccountChildOwner, deriveSubaccountChildPrivateKey, deriveSubaccountSalt, deriveSubaccountSlot, findNextSubaccountWithdrawNonce, getAddresses, getDailyFreeRemaining, getExtDataHash, getForwarderFactoryAddress, getMerklePath, getPoolAddress, getPrivateBalance, getQueueAddress, getQueueBalance, getRelayInfo, getRelayUrl, getSubaccountPrivateBalance, getSubaccountStatus, isSubaccountForwarderDeployed, isSubaccountWithdrawNonceUsed, mergeSubaccount, mergeUtxos, packEncryptedMessage, poseidonHash, poseidonHash2, predictSubaccountForwarder, prepareTransaction, prove, randomBN, selectCircuit, selectUtxosForWithdraw, shuffle, signSubaccountWithdraw, submitRelay, sweepSubaccountForwarder, toBuffer, toFixedHex, transfer, unpackEncryptedMessage, withdraw };

package/dist/index.js

@@ -597,6 +597,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 = [
@@ -1314,6 +1322,25 @@ async function getQueueBalance(options) {
     pendingCount: pendingDeposits.length
   };
 }
+async function getDailyFreeRemaining(options) {
+  const { address, pool = "eth", rpcUrl } = options;
+  const queueAddress = getQueueAddress(pool);
+  const publicClient = createPublicClient({
+    chain: base,
+    transport: 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);
@@ -1641,7 +1668,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(
@@ -2213,11 +2249,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) {
@@ -2254,7 +2291,7 @@ async function deploySubaccountForwarder(options) {
     slot: options.slot,
     rpcUrl: options.rpcUrl
   });
-  return postRelayJson(
+  const result = await postRelayJson(
     "/stealth/deploy",
     {
       salt: slot.salt,
@@ -2264,6 +2301,7 @@ async function deploySubaccountForwarder(options) {
     },
     options.relayUrl
   );
+  return { ...result, slot };
 }
 async function sweepSubaccountForwarder(options) {
   const asset = normalizeAsset(options.asset);
@@ -2288,11 +2326,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
@@ -2313,6 +2372,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 {
@@ -2328,6 +2399,10 @@ async function getSubaccountStatus(options) {
         balanceWei: usdcWei.toString()
       }
     },
+    privateBalances: {
+      eth: toPrivateBalanceStatus(ethPrivate),
+      usdc: toPrivateBalanceStatus(usdcPrivate)
+    },
     queues: {
       eth: toQueueStatus("eth", ethQueue),
       usdc: toQueueStatus("usdc", usdcQueue)
@@ -2474,7 +2549,138 @@ 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 = createPublicClient({
+    chain: base,
+    transport: 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 = 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
+  };
+}
 
-export { ADDRESSES, CIRCUIT_CONFIG, ENTRY_ABI, ERC20_ABI, FIELD_SIZE, FORWARDER_ABI, FORWARDER_CONTRACT_VERSION, FORWARDER_FACTORY_ABI, Keypair, MAX_SUBACCOUNT_SLOTS, MERKLE_TREE_HEIGHT, POOL_ABI, POOL_CONFIG, QUEUE_ABI, RelayError, Utxo, VEIL_SIGNED_MESSAGE, buildApproveUSDCTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx, buildDepositUSDCTx, buildMerkleTree, buildRegisterTx, buildSubaccountRecoveryTx, buildSubaccountWithdrawTypedData, buildTransferProof, buildWithdrawProof, checkRecipientRegistration, checkRelayHealth, deploySubaccountForwarder, deriveSubaccountChildDepositKey, deriveSubaccountChildOwner, deriveSubaccountChildPrivateKey, deriveSubaccountSalt, deriveSubaccountSlot, findNextSubaccountWithdrawNonce, getAddresses, getExtDataHash, getForwarderFactoryAddress, getMerklePath, getPoolAddress, getPrivateBalance, getQueueAddress, getQueueBalance, getRelayInfo, getRelayUrl, getSubaccountStatus, isSubaccountForwarderDeployed, isSubaccountWithdrawNonceUsed, mergeUtxos, packEncryptedMessage, poseidonHash, poseidonHash2, predictSubaccountForwarder, prepareTransaction, prove, randomBN, selectCircuit, selectUtxosForWithdraw, shuffle, signSubaccountWithdraw, submitRelay, sweepSubaccountForwarder, toBuffer, toFixedHex, transfer, unpackEncryptedMessage, withdraw };
+export { ADDRESSES, CIRCUIT_CONFIG, ENTRY_ABI, ERC20_ABI, FIELD_SIZE, FORWARDER_ABI, FORWARDER_CONTRACT_VERSION, FORWARDER_FACTORY_ABI, Keypair, MAX_SUBACCOUNT_SLOTS, MERKLE_TREE_HEIGHT, POOL_ABI, POOL_CONFIG, QUEUE_ABI, RelayError, Utxo, VEIL_SIGNED_MESSAGE, buildApproveUSDCTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx, buildDepositUSDCTx, buildMerkleTree, buildRegisterTx, buildSubaccountRecoveryTx, buildSubaccountWithdrawTypedData, buildTransferProof, buildWithdrawProof, checkRecipientRegistration, checkRelayHealth, deploySubaccountForwarder, deriveSubaccountChildDepositKey, deriveSubaccountChildOwner, deriveSubaccountChildPrivateKey, deriveSubaccountSalt, deriveSubaccountSlot, findNextSubaccountWithdrawNonce, getAddresses, getDailyFreeRemaining, getExtDataHash, getForwarderFactoryAddress, getMerklePath, getPoolAddress, getPrivateBalance, getQueueAddress, getQueueBalance, getRelayInfo, getRelayUrl, getSubaccountPrivateBalance, getSubaccountStatus, isSubaccountForwarderDeployed, isSubaccountWithdrawNonceUsed, mergeSubaccount, mergeUtxos, packEncryptedMessage, poseidonHash, poseidonHash2, predictSubaccountForwarder, prepareTransaction, prove, randomBN, selectCircuit, selectUtxosForWithdraw, shuffle, signSubaccountWithdraw, submitRelay, sweepSubaccountForwarder, toBuffer, toFixedHex, transfer, unpackEncryptedMessage, withdraw };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map