@veil-cash/sdk 0.5.0 → 0.6.0

package/package.json

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

package/src/abi.ts

@@ -647,3 +647,175 @@ export const ERC20_ABI = [
     type: 'function',
   },
 ] as const;
+
+/**
+ * Veil Forwarder Factory ABI
+ */
+export const FORWARDER_FACTORY_ABI = [
+  {
+    inputs: [],
+    name: 'CONTRACT_VERSION',
+    outputs: [{ internalType: 'string', name: '', type: 'string' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [
+      { internalType: 'bytes32', name: '_salt', type: 'bytes32' },
+      { internalType: 'bytes', name: '_childDepositKey', type: 'bytes' },
+      { internalType: 'address', name: '_owner', type: 'address' },
+    ],
+    name: 'computeAddress',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [
+      { internalType: 'bytes32', name: '_salt', type: 'bytes32' },
+      { internalType: 'bytes', name: '_childDepositKey', type: 'bytes' },
+      { internalType: 'address', name: '_owner', type: 'address' },
+    ],
+    name: 'deploy',
+    outputs: [{ internalType: 'address', name: 'forwarder', type: 'address' }],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'relayer',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'veilEntry',
+    outputs: [{ internalType: 'address payable', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'usdc',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'owner',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;
+
+/**
+ * Veil Forwarder ABI
+ */
+export const FORWARDER_ABI = [
+  {
+    inputs: [],
+    name: 'CONTRACT_VERSION',
+    outputs: [{ internalType: 'string', name: '', type: 'string' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [
+      { internalType: 'address', name: '_token', type: 'address' },
+      { internalType: 'address', name: '_to', type: 'address' },
+      { internalType: 'uint256', name: '_amount', type: 'uint256' },
+      { internalType: 'uint256', name: '_nonce', type: 'uint256' },
+      { internalType: 'uint256', name: '_deadline', type: 'uint256' },
+      { internalType: 'bytes', name: '_signature', type: 'bytes' },
+    ],
+    name: 'withdraw',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+  {
+    inputs: [{ internalType: 'uint256', name: '', type: 'uint256' }],
+    name: 'usedNonces',
+    outputs: [{ internalType: 'bool', name: '', type: 'bool' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'owner',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'factory',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'childDepositKey',
+    outputs: [{ internalType: 'bytes', name: '', type: 'bytes' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'entry',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'usdc',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'sweepETH',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'sweepUSDC',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'eip712Domain',
+    outputs: [
+      { internalType: 'bytes1', name: 'fields', type: 'bytes1' },
+      { internalType: 'string', name: 'name', type: 'string' },
+      { internalType: 'string', name: 'version', type: 'string' },
+      { internalType: 'uint256', name: 'chainId', type: 'uint256' },
+      { internalType: 'address', name: 'verifyingContract', type: 'address' },
+      { internalType: 'bytes32', name: 'salt', type: 'bytes32' },
+      { internalType: 'uint256[]', name: 'extensions', type: 'uint256[]' },
+    ],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  { type: 'error', name: 'ZeroAddress', inputs: [] },
+  { type: 'error', name: 'ZeroAmount', inputs: [] },
+  { type: 'error', name: 'InvalidDepositKey', inputs: [] },
+  { type: 'error', name: 'NotRelayer', inputs: [] },
+  { type: 'error', name: 'NoETHBalance', inputs: [] },
+  { type: 'error', name: 'NoTokenBalance', inputs: [] },
+  { type: 'error', name: 'TokenApproveFailed', inputs: [] },
+  { type: 'error', name: 'ETHTransferFailed', inputs: [] },
+  { type: 'error', name: 'NonceUsed', inputs: [] },
+  { type: 'error', name: 'Unauthorized', inputs: [] },
+  { type: 'error', name: 'DeadlineExpired', inputs: [] },
+] as const;

package/src/addresses.ts

@@ -14,10 +14,16 @@ export const ADDRESSES: NetworkAddresses = {
   usdcPool: '0x5c50d58E49C59d112680c187De2Bf989d2a91242',
   usdcQueue: '0x5530241b24504bF05C9a22e95A1F5458888e6a9B',
   usdcToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  forwarderFactory: '0x2848Fd62293A1ff3b4a897E9FcD0e5962dcc8101',
   chainId: 8453,
   relayUrl: 'https://veil-relay.up.railway.app',
 } as const;
 
+/**
+ * Veil forwarder EIP-712 contract version
+ */
+export const FORWARDER_CONTRACT_VERSION = '1' as const;
+
 /**
  * Pool configuration (decimals, symbols, etc.)
  */
@@ -76,6 +82,14 @@ export function getQueueAddress(
   }
 }
 
+/**
+ * Get the forwarder factory contract address
+ * @returns Forwarder factory address for Base mainnet
+ */
+export function getForwarderFactoryAddress(): `0x${string}` {
+  return getAddresses().forwarderFactory;
+}
+
 /**
  * Get Relay URL
  * @returns Relay URL for Base mainnet

package/src/cli/commands/subaccount.ts

@@ -0,0 +1,354 @@
+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 slot = await deriveSubaccountSlot({
+          rootPrivateKey,
+          slot: options.slot,
+          rpcUrl: process.env.RPC_URL,
+        });
+        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: slot.forwarderAddress,
+        };
+
+        if (options.json) {
+          printJson(output);
+          return;
+        }
+
+        printHeader('Subaccount Deploy Submitted');
+        printFields([
+          { label: 'Slot', value: options.slot },
+          { label: 'Forwarder', value: 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}`);
+        }
+        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.0')
   .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,