@veil-cash/sdk 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veil-cash/sdk",
-  "version": "0.6.0",
+  "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,11 +1,13 @@
 ---
 name: veil
-version: 0.5.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, or build unsigned transaction payloads
-  for an external signer (e.g. Bankr). All operations target Base (chain ID 8453).
+  manage Veil keypairs, register on-chain, manage deterministic subaccounts
+  (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
@@ -27,11 +29,16 @@ triggers:
   - pattern: veil withdraw
   - pattern: veil transfer
   - pattern: veil merge
+  - pattern: veil subaccount
   - pattern: unsigned payload
   - pattern: privacy pool
   - pattern: deposit privately
   - pattern: withdraw privately
   - pattern: private transfer
+  - pattern: subaccount
+  - pattern: subaccount merge
+  - pattern: forwarder
+  - pattern: stealth deposit
 ---
 
 # Veil CLI
@@ -164,6 +171,8 @@ What do you want to do?
 |
 +-- Withdraw / transfer / merge       → Section 5
 |
++-- Subaccounts (forwarders)          → Section 5B
+|
 +-- Inspect or rotate keypair         → veil keypair / veil init --force
 ```
 
@@ -188,6 +197,13 @@ What do you want to do?
 | Withdraw | `veil withdraw ETH 0.05 0xRecipient` |
 | Transfer privately | `veil transfer ETH 0.02 0xRecipient` |
 | Merge UTXOs | `veil merge ETH 0.1` |
+| Derive subaccount | `veil subaccount derive --slot 0` |
+| Subaccount status | `veil subaccount status --slot 0` |
+| 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` |
 
 ---
 
@@ -315,6 +331,8 @@ Important:
 
 Deposits treat the CLI amount as the **net** amount that lands in the pool.
 The `0.3%` protocol fee is calculated on-chain and added automatically.
+After submission, deposits go through screening / queue processing before they
+are accepted into the private pool. This typically takes around `10-15 minutes`.
 
 ```bash
 veil deposit ETH 0.1
@@ -369,6 +387,9 @@ Human-readable balance output includes:
 - wallet public balances (`ETH`, `USDC`)
 - queue and private balances
 
+If a recent deposit still appears in queue balance, screening / queue processing
+may still be in progress. Typical processing time is around `10-15 minutes`.
+
 ---
 
 ## 5. Private Actions
@@ -403,6 +424,74 @@ Note: withdraw proof generation is single-threaded for reliable CLI exit after s
 
 ---
 
+## 5B. Subaccounts
+
+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). 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 child slot's forwarder wallet balances, private pool
+balances, and queue state.
+
+### Derive and inspect
+
+```bash
+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, forwarder balances, private balances, queue state
+veil subaccount status --slot 0 --json
+```
+
+### Deploy and sweep (relay-backed)
+
+```bash
+veil subaccount deploy --slot 0           # Deploy the forwarder contract
+veil subaccount deploy --slot 0 --json
+veil subaccount sweep --slot 0 --asset eth    # Sweep ETH into the pool
+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.
+It signs a forwarder withdraw with the child key and submits the transaction
+using `WALLET_KEY` as the gas payer.
+
+```bash
+veil subaccount recover --slot 0 --asset usdc --to 0xRecipient --amount 25
+veil subaccount recover --slot 0 --asset eth --to 0xRecipient --amount 0.05 --json
+```
+
+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`
+
+---
+
 ## 6. Unsigned Payloads
 
 `--unsigned` is for external signer workflows. The CLI emits a signer-compatible
@@ -504,6 +593,7 @@ All CLI errors output JSON with a standardised `errorCode`:
 | `DEPOSIT_KEY_MISSING` | `DEPOSIT_KEY` missing from `.env.veil` | Re-run `veil init` to regenerate |
 | `USER_NOT_REGISTERED` | Transfer recipient has no deposit key registered on-chain | Recipient must run `veil register` first |
 | `INVALID_AMOUNT` | Amount below minimum or invalid format | ETH min: `0.01`, USDC min: `10` |
+| `INVALID_SLOT` | Invalid subaccount slot | Slot must be `0`–`2` (non-negative integer) |
 | `INSUFFICIENT_BALANCE` | Not enough ETH for gas | Top up Base ETH balance |
 | `RPC_ERROR` | Network or RPC failure | Check `RPC_URL` env var or retry |
 | `RELAY_ERROR` | Relayer rejected the proof | Check relay health with `veil status`; retry |

package/skills/veil/reference.md

@@ -143,6 +143,81 @@ const priv = await getPrivateBalance({
 });
 ```
 
+### Subaccounts
+
+```typescript
+import {
+  deriveSubaccountSlot,
+  getSubaccountPrivateBalance,
+  getSubaccountStatus,
+  deploySubaccountForwarder,
+  sweepSubaccountForwarder,
+  mergeSubaccount,
+  buildSubaccountRecoveryTx,
+  isSubaccountForwarderDeployed,
+  MAX_SUBACCOUNT_SLOTS,
+} from '@veil-cash/sdk';
+
+// Derive slot metadata (child key, salt, predicted forwarder address)
+const slot = await deriveSubaccountSlot({
+  rootPrivateKey: '0xVEIL_KEY',
+  slot: 0,           // 0–2
+});
+// slot.forwarderAddress, slot.childOwner, slot.childDepositKey, slot.salt
+
+// Check deployment status
+const deployed = await isSubaccountForwarderDeployed({
+  forwarderAddress: slot.forwarderAddress,
+});
+
+// Full status (deployment, forwarder balances, private balances, queue state)
+const status = await getSubaccountStatus({
+  rootPrivateKey: '0xVEIL_KEY',
+  slot: 0,
+});
+// 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({
+  rootPrivateKey: '0xVEIL_KEY',
+  slot: 0,
+});
+// deployResult.transactionHash, deployResult.slot.forwarderAddress
+
+// Sweep assets into pool (relay-backed)
+const sweepResult = await sweepSubaccountForwarder({
+  forwarderAddress: slot.forwarderAddress,
+  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',
+  slot: 0,
+  asset: 'usdc',
+  to: '0xRecipient',
+  amount: '25',
+});
+// recovery.transaction — submit with your wallet client
+// recovery.forwarderAddress, recovery.signature, recovery.nonce, recovery.deadline
+```
+
 ---
 
 ## CLI quick reference
@@ -158,7 +233,7 @@ Install globally: `npm install -g @veil-cash/sdk`
 | `WALLET_KEY` | Ethereum wallet private key (for signing) |
 | `SIGNER_ADDRESS` | Ethereum address for unsigned/query flows when signing is external |
 | `RPC_URL` | Base RPC URL (optional, defaults to public RPC) |
-| `RELAY_URL` | Override relay base URL for relayed CLI operations |
+| `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 `SIGNER_ADDRESS` only for address-only CLI flows.
 
@@ -195,6 +270,20 @@ veil balance queue --pool eth                      # Queue-only balance
 veil balance queue --address 0x... --json          # Queue balance for explicit address
 veil balance private --pool eth                    # Private-only balance
 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, 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
 ```
 
 ### Error format
@@ -210,7 +299,7 @@ All CLI errors output JSON with a standardized `errorCode`:
 ```
 
 Common codes: `VEIL_KEY_MISSING`, `WALLET_KEY_MISSING`, `DEPOSIT_KEY_MISSING`,
-`CONFIG_CONFLICT`, `INVALID_AMOUNT`, `INSUFFICIENT_BALANCE`, `CONTRACT_ERROR`, `RPC_ERROR`.
+`CONFIG_CONFLICT`, `INVALID_AMOUNT`, `INVALID_SLOT`, `INSUFFICIENT_BALANCE`, `CONTRACT_ERROR`, `RPC_ERROR`.
 
 ---
 

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();
@@ -178,11 +200,6 @@ Examples:
     .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,
@@ -193,7 +210,7 @@ Examples:
         const output = {
           ...result,
           slot: options.slot,
-          forwarderAddress: slot.forwarderAddress,
+          forwarderAddress: result.slot.forwarderAddress,
         };
 
         if (options.json) {
@@ -204,7 +221,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 },
         ]);
@@ -260,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')
@@ -274,6 +349,12 @@ Examples:
         if (!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,

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.0')
+  .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/relay.ts

@@ -64,7 +64,16 @@ export async function postRelayJson<T>(
     body: JSON.stringify(body),
   });
 
-  const data = await response.json();
+  const text = await response.text();
+  let data: unknown;
+  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 as RelayErrorResponse;