@veil-cash/sdk 0.5.0 → 0.6.1

package/src/cli/commands/subaccount.ts

@@ -0,0 +1,355 @@
+import { Command } from 'commander';
+import { isAddress } from 'viem';
+import {
+  buildSubaccountRecoveryTx,
+  deploySubaccountForwarder,
+  deriveSubaccountSlot,
+  getSubaccountStatus,
+  isSubaccountForwarderDeployed,
+  MAX_SUBACCOUNT_SLOTS,
+  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';
+
+function parseSlotValue(raw: string): number {
+  const normalized = raw.trim();
+  if (!/^\d+$/.test(normalized)) {
+    throw new CLIError(ErrorCode.INVALID_SLOT, '--slot must be a non-negative integer');
+  }
+
+  const slot = Number(normalized);
+  if (slot >= MAX_SUBACCOUNT_SLOTS) {
+    throw new CLIError(
+      ErrorCode.INVALID_SLOT,
+      `--slot must be 0-${MAX_SUBACCOUNT_SLOTS - 1} (max ${MAX_SUBACCOUNT_SLOTS} subaccounts supported)`,
+    );
+  }
+
+  return slot;
+}
+
+function getRequiredVeilKey(): `0x${string}` {
+  const veilKey = process.env.VEIL_KEY;
+  if (!veilKey) {
+    throw new CLIError(ErrorCode.VEIL_KEY_MISSING, 'VEIL_KEY required. Set VEIL_KEY env');
+  }
+  if (!/^0x[a-fA-F0-9]{64}$/.test(veilKey)) {
+    throw new CLIError(ErrorCode.VEIL_KEY_MISSING, 'VEIL_KEY must be a 0x-prefixed 32-byte hex string');
+  }
+  return veilKey as `0x${string}`;
+}
+
+function parseAsset(raw: string): SubaccountAsset {
+  const asset = raw.toLowerCase();
+  if (asset !== 'eth' && asset !== 'usdc') {
+    throw new CLIError(ErrorCode.INVALID_AMOUNT, `Unsupported asset: ${raw}. Supported: eth, usdc`);
+  }
+  return asset;
+}
+
+function printQueueHuman(
+  title: string,
+  queue: {
+    queueBalance: string;
+    pendingCount: number;
+    pendingDeposits: Array<{ nonce: string; amount: string; status: string }>;
+  },
+): void {
+  printSection(title);
+  printFields([
+    { label: 'Queue balance', value: queue.queueBalance },
+    { label: 'Pending', value: queue.pendingCount },
+  ]);
+
+  if (queue.pendingDeposits.length > 0) {
+    printList(
+      queue.pendingDeposits.map((deposit) => `nonce ${deposit.nonce}: ${deposit.amount} (${deposit.status})`),
+    );
+  }
+}
+
+export function createSubaccountCommand(): Command {
+  const subaccount = new Command('subaccount')
+    .description('Manage Veil subaccounts')
+    .addHelpText('after', `
+Examples:
+  veil subaccount derive --slot 0
+  veil subaccount status --slot 0
+  veil subaccount deploy --slot 0
+  veil subaccount sweep --slot 0 --asset eth
+  veil subaccount recover --slot 0 --asset usdc --to 0xRecipientAddress --amount 25
+  veil subaccount address --slot 0
+`);
+
+  subaccount
+    .command('derive')
+    .description('Derive subaccount metadata for a slot')
+    .requiredOption('--slot <n>', 'Subaccount slot', parseSlotValue)
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const rootPrivateKey = getRequiredVeilKey();
+        const rpcUrl = process.env.RPC_URL;
+        const slot = await deriveSubaccountSlot({
+          rootPrivateKey,
+          slot: options.slot,
+          rpcUrl,
+        });
+        const deployed = await isSubaccountForwarderDeployed({
+          forwarderAddress: slot.forwarderAddress,
+          rpcUrl,
+        });
+
+        const output = {
+          ...slot,
+          deployed,
+        };
+
+        if (options.json) {
+          printJson(output);
+          return;
+        }
+
+        printHeader(`Subaccount Slot ${slot.slot}`);
+        printFields([
+          { label: 'Child owner', value: slot.childOwner },
+          { label: 'Deposit key', value: slot.childDepositKey },
+          { label: 'Salt', value: slot.salt },
+          { label: 'Forwarder', value: slot.forwarderAddress },
+          { label: 'Deployed', value: deployed },
+        ]);
+        printLine();
+      } catch (error) {
+        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) => {
+      try {
+        const rootPrivateKey = getRequiredVeilKey();
+        const status = await getSubaccountStatus({
+          rootPrivateKey,
+          slot: options.slot,
+          rpcUrl: process.env.RPC_URL,
+        });
+
+        if (options.json) {
+          printJson(status);
+          return;
+        }
+
+        printHeader(`Subaccount Slot ${status.slot.slot}`);
+        printFields([
+          { label: 'Forwarder', value: status.slot.forwarderAddress },
+          { label: 'Child owner', value: status.slot.childOwner },
+          { label: 'Deposit key', value: status.slot.childDepositKey },
+          { label: 'Salt', value: status.slot.salt },
+          { label: 'Deployed', value: status.deployed },
+        ]);
+
+        printSection('Forwarder Balances');
+        printFields([
+          { label: 'ETH', value: `${status.balances.eth.balance} ETH` },
+          { label: 'USDC', value: `${status.balances.usdc.balance} USDC` },
+        ]);
+
+        printQueueHuman('ETH Queue', status.queues.eth);
+        printQueueHuman('USDC Queue', status.queues.usdc);
+        printLine();
+      } catch (error) {
+        handleCLIError(error);
+      }
+    });
+
+  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 result = await deploySubaccountForwarder({
+          rootPrivateKey,
+          slot: options.slot,
+          rpcUrl: process.env.RPC_URL,
+          relayUrl: process.env.RELAY_URL,
+        });
+
+        const output = {
+          ...result,
+          slot: options.slot,
+          forwarderAddress: result.slot.forwarderAddress,
+        };
+
+        if (options.json) {
+          printJson(output);
+          return;
+        }
+
+        printHeader('Subaccount Deploy Submitted');
+        printFields([
+          { label: 'Slot', value: options.slot },
+          { label: 'Forwarder', value: result.slot.forwarderAddress },
+          { label: 'Transaction', value: txUrl(result.transactionHash) },
+          { label: 'Block', value: result.blockNumber },
+        ]);
+        printLine();
+      } catch (error) {
+        handleCLIError(error);
+      }
+    });
+
+  subaccount
+    .command('sweep')
+    .description('Sweep ETH or USDC from a subaccount forwarder through the relay')
+    .requiredOption('--slot <n>', 'Subaccount slot', parseSlotValue)
+    .requiredOption('--asset <asset>', 'Asset to sweep (eth or usdc)', parseAsset)
+    .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 sweepSubaccountForwarder({
+          forwarderAddress: slot.forwarderAddress,
+          asset: options.asset,
+          relayUrl: process.env.RELAY_URL,
+        });
+
+        const output = {
+          ...result,
+          slot: options.slot,
+          asset: options.asset,
+          forwarderAddress: slot.forwarderAddress,
+        };
+
+        if (options.json) {
+          printJson(output);
+          return;
+        }
+
+        printHeader('Subaccount Sweep Submitted');
+        printFields([
+          { label: 'Slot', value: options.slot },
+          { label: 'Asset', value: options.asset.toUpperCase() },
+          { label: 'Forwarder', value: slot.forwarderAddress },
+          { label: 'Transaction', value: txUrl(result.transactionHash) },
+          { label: 'Block', value: result.blockNumber },
+        ]);
+        printLine();
+      } catch (error) {
+        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 (!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,
+          slot: options.slot,
+          asset: options.asset,
+          to: options.to as `0x${string}`,
+          amount: options.amount,
+          rpcUrl: process.env.RPC_URL,
+        });
+        const result = await sendTransaction(config, recovery.transaction);
+
+        const output = {
+          success: result.receipt.status === 'success',
+          slot: options.slot,
+          asset: recovery.asset,
+          amount: recovery.amount,
+          amountWei: recovery.amountWei,
+          forwarderAddress: recovery.forwarderAddress,
+          recipient: recovery.recipient,
+          nonce: recovery.nonce,
+          deadline: recovery.deadline,
+          signature: recovery.signature,
+          transactionHash: result.hash,
+          blockNumber: result.receipt.blockNumber.toString(),
+        };
+
+        if (options.json) {
+          printJson(output);
+          return;
+        }
+
+        printHeader('Subaccount Recovery Submitted');
+        printFields([
+          { label: 'Slot', value: options.slot },
+          { label: 'Asset', value: recovery.asset.toUpperCase() },
+          { label: 'Amount', value: recovery.amount },
+          { label: 'Recipient', value: recovery.recipient },
+          { label: 'Forwarder', value: recovery.forwarderAddress },
+          { label: 'Nonce', value: recovery.nonce },
+          { label: 'Transaction', value: txUrl(result.hash) },
+          { label: 'Block', value: result.receipt.blockNumber },
+        ]);
+        printLine();
+      } catch (error) {
+        handleCLIError(error);
+      }
+    });
+
+  subaccount
+    .command('address')
+    .description('Print the predicted forwarder address for a subaccount slot')
+    .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,
+        });
+
+        if (options.json) {
+          printJson({
+            slot: options.slot,
+            forwarderAddress: slot.forwarderAddress,
+          });
+          return;
+        }
+
+        printLine(slot.forwarderAddress);
+      } catch (error) {
+        handleCLIError(error);
+      }
+    });
+
+  return subaccount;
+}

package/src/cli/errors.ts

@@ -11,6 +11,7 @@ export const ErrorCode = {
   DEPOSIT_KEY_MISSING: 'DEPOSIT_KEY_MISSING',
   CONFIG_CONFLICT: 'CONFIG_CONFLICT',
   INVALID_ADDRESS: 'INVALID_ADDRESS',
+  INVALID_SLOT: 'INVALID_SLOT',
   INVALID_AMOUNT: 'INVALID_AMOUNT',
   INSUFFICIENT_BALANCE: 'INSUFFICIENT_BALANCE',
   USER_NOT_REGISTERED: 'USER_NOT_REGISTERED',
@@ -58,6 +59,9 @@ function inferErrorCode(message: string): ErrorCodeType {
   if (msg.includes('invalid') && msg.includes('address')) {
     return ErrorCode.INVALID_ADDRESS;
   }
+  if (msg.includes('invalid') && msg.includes('slot')) {
+    return ErrorCode.INVALID_SLOT;
+  }
   if (msg.includes('insufficient balance') || msg.includes('not enough')) {
     return ErrorCode.INSUFFICIENT_BALANCE;
   }

package/src/cli/index.ts

@@ -13,6 +13,7 @@
  *   veil withdraw ETH 0.1 0x...      # Withdraw to public address
  *   veil transfer ETH 0.1 0x...      # Transfer privately
  *   veil merge ETH 0.5               # Merge UTXOs (self-transfer)
+ *   veil subaccount status --slot 0  # Check subaccount status
  */
 
 import { Command } from 'commander';
@@ -27,6 +28,7 @@ import { createPrivateBalanceCommand } from './commands/private-balance.js';
 import { createWithdrawCommand } from './commands/withdraw.js';
 import { createTransferCommand, createMergeCommand } from './commands/transfer.js';
 import { createStatusCommand } from './commands/status.js';
+import { createSubaccountCommand } from './commands/subaccount.js';
 
 // Load environment variables
 loadEnv();
@@ -36,13 +38,14 @@ const program = new Command();
 program
   .name('veil')
   .description('CLI for Veil Cash privacy pools on Base')
-  .version('0.5.0')
+  .version('0.6.1')
   .addHelpText('after', `
 Getting started:
   veil init
   veil register
   veil deposit ETH 0.1
   veil balance
+  veil subaccount status --slot 0
 `);
 
 // Add commands
@@ -57,6 +60,7 @@ program.addCommand(createWithdrawCommand());
 program.addCommand(createTransferCommand());
 program.addCommand(createMergeCommand());
 program.addCommand(createStatusCommand());
+program.addCommand(createSubaccountCommand());
 
 const knownTopLevelCommands = new Set([
   ...program.commands.map((command) => command.name()),

package/src/cli/wallet.ts

@@ -14,7 +14,7 @@ import {
 import { privateKeyToAccount } from 'viem/accounts';
 import { base } from 'viem/chains';
 import type { TransactionData } from '../types.js';
-import { ENTRY_ABI, ERC20_ABI } from '../abi.js';
+import { ENTRY_ABI, ERC20_ABI, FORWARDER_ABI } from '../abi.js';
 import { getAddresses, POOL_CONFIG, ADDRESSES } from '../addresses.js';
 
 export interface WalletConfig {
@@ -118,7 +118,7 @@ function decodeCustomError(error: unknown): string | null {
     
     if (possibleData && typeof possibleData === 'string' && possibleData.startsWith('0x')) {
       try {
-        for (const abi of [ENTRY_ABI] as const) {
+        for (const abi of [ENTRY_ABI, FORWARDER_ABI] as const) {
           try {
             const decoded = decodeErrorResult({
               abi,

package/src/index.ts

@@ -100,8 +100,10 @@ export type { ProofInput } from './prover.js';
 // Addresses and config
 export { 
   ADDRESSES, 
+  FORWARDER_CONTRACT_VERSION,
   POOL_CONFIG, 
   getAddresses,
+  getForwarderFactoryAddress,
   getPoolAddress,
   getQueueAddress,
   getRelayUrl,
@@ -119,10 +121,32 @@ export {
 export {
   ENTRY_ABI,
   ERC20_ABI,
+  FORWARDER_ABI,
+  FORWARDER_FACTORY_ABI,
   QUEUE_ABI,
   POOL_ABI,
 } from './abi.js';
 
+// Subaccount functions
+export {
+  MAX_SUBACCOUNT_SLOTS,
+  deriveSubaccountChildPrivateKey,
+  deriveSubaccountSalt,
+  deriveSubaccountChildOwner,
+  deriveSubaccountChildDepositKey,
+  deriveSubaccountSlot,
+  predictSubaccountForwarder,
+  isSubaccountForwarderDeployed,
+  deploySubaccountForwarder,
+  sweepSubaccountForwarder,
+  getSubaccountStatus,
+  buildSubaccountWithdrawTypedData,
+  signSubaccountWithdraw,
+  isSubaccountWithdrawNonceUsed,
+  findNextSubaccountWithdrawNonce,
+  buildSubaccountRecoveryTx,
+} from './subaccount.js';
+
 // Utilities
 export { 
   poseidonHash, 
@@ -166,4 +190,15 @@ export type {
   WithdrawResult,
   TransferResult,
   UtxoSelectionResult,
+  SubaccountAsset,
+  SubaccountSlot,
+  SubaccountDeployRequest,
+  SubaccountSweepRequest,
+  SubaccountRelayResult,
+  SubaccountAssetBalance,
+  SubaccountBalances,
+  SubaccountQueueStatus,
+  SubaccountStatusResult,
+  SubaccountWithdrawTypedData,
+  SubaccountRecoveryResult,
 } from './types.js';

package/src/relay.ts

@@ -50,6 +50,44 @@ export class RelayError extends Error {
   }
 }
 
+export async function postRelayJson<T>(
+  endpoint: string,
+  body: unknown,
+  relayUrl?: string,
+): Promise<T> {
+  const url = relayUrl || getRelayUrl();
+  const response = await fetch(`${url}${endpoint}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+
+  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;
+    throw new RelayError(
+      errorData.error || errorData.message || 'Relay request failed',
+      response.status,
+      errorData.retryAfter,
+      errorData.network,
+    );
+  }
+
+  return data as T;
+}
+
 /**
  * Submit a withdrawal or transfer to the relay service
  * 
@@ -107,34 +145,17 @@ export async function submitRelay(options: SubmitRelayOptions): Promise<RelayRes
   }
 
   const relayUrl = customRelayUrl || getRelayUrl();
-  const endpoint = `${relayUrl}/relay/${pool}`;
-
-  const response = await fetch(endpoint, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
+  const endpoint = `/relay/${pool}`;
+  return postRelayJson<RelayResponse>(
+    endpoint,
+    {
       type,
       proofArgs,
       extData,
       metadata,
-    }),
-  });
-
-  const data = await response.json();
-
-  if (!response.ok) {
-    const errorData = data as RelayErrorResponse;
-    throw new RelayError(
-      errorData.error || errorData.message || 'Relay request failed',
-      response.status,
-      errorData.retryAfter,
-      errorData.network
-    );
-  }
-
-  return data as RelayResponse;
+    },
+    relayUrl,
+  );
 }
 
 /**