@veil-cash/sdk 0.1.0

package/src/cli/commands/private-balance.ts

@@ -0,0 +1,68 @@
+/**
+ * Private Balance CLI command - Show private balance from Pool contract
+ */
+
+import { Command } from 'commander';
+import { getPrivateBalance } from '../../balance.js';
+import { Keypair } from '../../keypair.js';
+
+export function createPrivateBalanceCommand(): Command {
+  const privateBalance = new Command('private-balance')
+    .description('Show private balance (requires VEIL_KEY)')
+    .option('--veil-key <key>', 'Veil private key (or set VEIL_KEY env)')
+    .option('--rpc-url <url>', 'RPC URL (or set RPC_URL env)')
+    .option('--show-utxos', 'Show individual UTXO details')
+    .option('--quiet', 'Suppress progress output')
+    .action(async (options) => {
+      try {
+        // Get keypair
+        const veilKey = options.veilKey || process.env.VEIL_KEY;
+        if (!veilKey) {
+          throw new Error('Must provide --veil-key or set VEIL_KEY env');
+        }
+
+        const keypair = new Keypair(veilKey);
+        const rpcUrl = options.rpcUrl || process.env.RPC_URL;
+
+        // Progress callback - writes to stderr so JSON output is clean
+        const onProgress = options.quiet 
+          ? undefined 
+          : (stage: string, detail?: string) => {
+              const msg = detail ? `${stage}: ${detail}` : stage;
+              process.stderr.write(`\r\x1b[K${msg}`);
+            };
+
+        // Get private balance from SDK
+        const result = await getPrivateBalance({ keypair, rpcUrl, onProgress });
+
+        // Clear progress line
+        if (!options.quiet) {
+          process.stderr.write('\r\x1b[K');
+        }
+
+        // Format output
+        const output: Record<string, unknown> = {
+          privateBalance: result.privateBalance,
+          privateBalanceWei: result.privateBalanceWei,
+          utxoCount: result.utxoCount,
+          unspentCount: result.unspentCount,
+          spentCount: result.spentCount,
+        };
+
+        // Optionally include UTXO details
+        if (options.showUtxos) {
+          output.utxos = result.utxos;
+        }
+
+        console.log(JSON.stringify(output, null, 2));
+      } catch (error) {
+        // Clear progress line on error
+        process.stderr.write('\r\x1b[K');
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.log(JSON.stringify({ success: false, error: errorMessage }));
+        process.exit(1);
+      }
+    });
+
+  return privateBalance;
+}

package/src/cli/commands/queue-balance.ts

@@ -0,0 +1,58 @@
+/**
+ * Queue Balance CLI command - Show queue balance and pending deposits
+ */
+
+import { Command } from 'commander';
+import { getQueueBalance } from '../../balance.js';
+import { getAddress } from '../wallet.js';
+
+export function createQueueBalanceCommand(): Command {
+  const balance = new Command('queue-balance')
+    .description('Show queue balance and pending deposits')
+    .option('--wallet-key <key>', 'Ethereum wallet key (or set WALLET_KEY env)')
+    .option('--address <address>', 'Address to check (or derived from wallet key)')
+    .option('--rpc-url <url>', 'RPC URL (or set RPC_URL env)')
+    .option('--quiet', 'Suppress progress output')
+    .action(async (options) => {
+      try {
+        // Get address
+        let address: `0x${string}`;
+        if (options.address) {
+          address = options.address as `0x${string}`;
+        } else {
+          const walletKey = options.walletKey || process.env.WALLET_KEY;
+          if (!walletKey) {
+            throw new Error('Must provide --address or --wallet-key (or set WALLET_KEY env)');
+          }
+          address = getAddress(walletKey as `0x${string}`);
+        }
+
+        // Progress callback - writes to stderr so JSON output is clean
+        const onProgress = options.quiet 
+          ? undefined 
+          : (stage: string, detail?: string) => {
+              const msg = detail ? `${stage}: ${detail}` : stage;
+              process.stderr.write(`\r\x1b[K${msg}`);
+            };
+
+        // Get queue balance from SDK
+        const rpcUrl = options.rpcUrl || process.env.RPC_URL;
+        const result = await getQueueBalance({ address, rpcUrl, onProgress });
+
+        // Clear progress line
+        if (!options.quiet) {
+          process.stderr.write('\r\x1b[K');
+        }
+
+        console.log(JSON.stringify(result, null, 2));
+      } catch (error) {
+        // Clear progress line on error
+        process.stderr.write('\r\x1b[K');
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.log(JSON.stringify({ success: false, error: errorMessage }));
+        process.exit(1);
+      }
+    });
+
+  return balance;
+}

package/src/cli/commands/register.ts

@@ -0,0 +1,119 @@
+/**
+ * Register CLI command - Register your deposit key on-chain
+ */
+
+import { Command } from 'commander';
+import { buildRegisterTx } from '../../deposit.js';
+import { sendTransaction, getAddress, isRegistered } from '../wallet.js';
+import { getConfig } from '../config.js';
+import { handleCLIError, CLIError, ErrorCode } from '../errors.js';
+
+export function createRegisterCommand(): Command {
+  const register = new Command('register')
+    .description('Register your deposit key on-chain (one-time)')
+    .option('--deposit-key <key>', 'Your Veil deposit key (or set DEPOSIT_KEY env)')
+    .option('--wallet-key <key>', 'Ethereum wallet key for signing (or set WALLET_KEY env)')
+    .option('--address <address>', 'Owner address (required with --unsigned)')
+    .option('--rpc-url <url>', 'RPC URL (or set RPC_URL env)')
+    .option('--unsigned', 'Output unsigned transaction payload (Bankr-compatible format)')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      const jsonOutput = options.json;
+
+      try {
+        // Get deposit key from option or env
+        const depositKey = options.depositKey || process.env.DEPOSIT_KEY;
+        if (!depositKey) {
+          throw new CLIError(ErrorCode.DEPOSIT_KEY_MISSING, 'Deposit key required. Run "veil init" first or use --deposit-key');
+        }
+
+        // Handle --unsigned mode (no wallet required, just build payload)
+        if (options.unsigned) {
+          let address: `0x${string}`;
+          if (options.address) {
+            address = options.address as `0x${string}`;
+          } else {
+            const walletKey = options.walletKey || process.env.WALLET_KEY;
+            if (!walletKey) {
+              throw new CLIError(ErrorCode.WALLET_KEY_MISSING, 'Must provide --address or --wallet-key for --unsigned mode');
+            }
+            address = getAddress(walletKey as `0x${string}`);
+          }
+
+          const tx = buildRegisterTx(depositKey, address);
+
+          const payload = {
+            to: tx.to,
+            data: tx.data,
+            value: '0',
+            chainId: 8453,
+          };
+
+          console.log(JSON.stringify(payload, null, 2));
+          process.exit(0);
+          return;
+        }
+
+        // Regular mode: sign and send
+        const config = getConfig(options);
+        const address = getAddress(config.privateKey);
+
+        // Check if already registered
+        if (!jsonOutput) console.log('\nChecking registration status...');
+        const { registered, depositKey: existingKey } = await isRegistered(address, config.rpcUrl);
+        
+        if (registered) {
+          if (jsonOutput) {
+            console.log(JSON.stringify({
+              success: true,
+              alreadyRegistered: true,
+              address,
+              depositKey: existingKey,
+            }, null, 2));
+          } else {
+            console.log(`\nAddress ${address} is already registered.`);
+            console.log(`\nExisting deposit key:`);
+            console.log(`  ${existingKey}`);
+          }
+          process.exit(0);
+          return;
+        }
+
+        if (!jsonOutput) {
+          console.log('Registering deposit key...');
+          console.log(`  Address: ${address}`);
+          console.log(`  Deposit Key: ${depositKey.slice(0, 40)}...`);
+        }
+
+        // Build and send
+        const tx = buildRegisterTx(depositKey, address);
+        const result = await sendTransaction(config, tx);
+
+        if (result.receipt.status === 'success') {
+          if (jsonOutput) {
+            console.log(JSON.stringify({
+              success: true,
+              alreadyRegistered: false,
+              address,
+              transactionHash: result.hash,
+              blockNumber: result.receipt.blockNumber.toString(),
+              gasUsed: result.receipt.gasUsed.toString(),
+            }, null, 2));
+          } else {
+            console.log('\nRegistration successful!');
+            console.log(`  Transaction: ${result.hash}`);
+            console.log(`  Block: ${result.receipt.blockNumber}`);
+            console.log(`  Gas used: ${result.receipt.gasUsed}`);
+            console.log('\nNext step: veil deposit <amount>');
+          }
+          process.exit(0);
+        } else {
+          throw new CLIError(ErrorCode.CONTRACT_ERROR, `Transaction reverted: ${result.hash}`);
+        }
+      } catch (error) {
+        handleCLIError(error);
+      }
+    });
+
+  return register;
+}

package/src/cli/commands/transfer.ts

@@ -0,0 +1,137 @@
+/**
+ * Transfer CLI command
+ */
+
+import { Command } from 'commander';
+import { Keypair } from '../../keypair.js';
+import { transfer, mergeUtxos } from '../../transfer.js';
+import { handleCLIError, CLIError, ErrorCode } from '../errors.js';
+
+// Progress helper - writes to stderr so JSON output stays clean
+function progress(msg: string, quiet?: boolean) {
+  if (!quiet) {
+    process.stderr.write(`\r\x1b[K${msg}`);
+  }
+}
+
+export function createTransferCommand(): Command {
+  const transferCmd = new Command('transfer')
+    .description('Transfer privately within the pool to another registered address')
+    .argument('<amount>', 'Amount to transfer (e.g., 0.1)')
+    .argument('<recipient>', 'Recipient address (must be registered)')
+    .option('--veil-key <key>', 'Veil private key (or set VEIL_KEY env)')
+    .option('--rpc-url <url>', 'RPC URL (or set RPC_URL env)')
+    .option('--quiet', 'Suppress progress output')
+    .action(async (amount: string, recipient: string, options) => {
+      try {
+        // Validate recipient
+        if (!/^0x[a-fA-F0-9]{40}$/.test(recipient)) {
+          throw new CLIError(ErrorCode.INVALID_ADDRESS, 'Invalid recipient address format');
+        }
+
+        // Get keypair
+        const veilKey = options.veilKey || process.env.VEIL_KEY;
+        if (!veilKey) {
+          throw new CLIError(ErrorCode.VEIL_KEY_MISSING, 'VEIL_KEY required. Use --veil-key or set VEIL_KEY env');
+        }
+
+        const senderKeypair = new Keypair(veilKey);
+        const rpcUrl = options.rpcUrl || process.env.RPC_URL;
+
+        // Progress callback
+        const onProgress = options.quiet
+          ? undefined
+          : (stage: string, detail?: string) => {
+              const msg = detail ? `${stage}: ${detail}` : stage;
+              progress(msg, options.quiet);
+            };
+
+        progress('Starting transfer...', options.quiet);
+
+        // Execute transfer
+        const result = await transfer({
+          amount,
+          recipientAddress: recipient as `0x${string}`,
+          senderKeypair,
+          rpcUrl,
+          onProgress,
+        });
+
+        // Clear progress line
+        progress('', options.quiet);
+
+        // Output result
+        console.log(JSON.stringify({
+          success: result.success,
+          transactionHash: result.transactionHash,
+          blockNumber: result.blockNumber,
+          amount: result.amount,
+          recipient: result.recipient,
+          type: 'transfer',
+        }, null, 2));
+        process.exit(0);
+      } catch (error) {
+        progress('', options.quiet);
+        handleCLIError(error);
+      }
+    });
+
+  return transferCmd;
+}
+
+export function createMergeCommand(): Command {
+  const mergeCmd = new Command('merge')
+    .description('Merge UTXOs by self-transfer (consolidate small UTXOs)')
+    .argument('<amount>', 'Amount to merge (e.g., 0.5)')
+    .option('--veil-key <key>', 'Veil private key (or set VEIL_KEY env)')
+    .option('--rpc-url <url>', 'RPC URL (or set RPC_URL env)')
+    .option('--quiet', 'Suppress progress output')
+    .action(async (amount: string, options) => {
+      try {
+        // Get keypair
+        const veilKey = options.veilKey || process.env.VEIL_KEY;
+        if (!veilKey) {
+          throw new CLIError(ErrorCode.VEIL_KEY_MISSING, 'VEIL_KEY required. Use --veil-key or set VEIL_KEY env');
+        }
+
+        const keypair = new Keypair(veilKey);
+        const rpcUrl = options.rpcUrl || process.env.RPC_URL;
+
+        // Progress callback
+        const onProgress = options.quiet
+          ? undefined
+          : (stage: string, detail?: string) => {
+              const msg = detail ? `${stage}: ${detail}` : stage;
+              progress(msg, options.quiet);
+            };
+
+        progress('Starting merge (self-transfer)...', options.quiet);
+
+        // Execute merge
+        const result = await mergeUtxos({
+          amount,
+          keypair,
+          rpcUrl,
+          onProgress,
+        });
+
+        // Clear progress line
+        progress('', options.quiet);
+
+        // Output result
+        console.log(JSON.stringify({
+          success: result.success,
+          transactionHash: result.transactionHash,
+          blockNumber: result.blockNumber,
+          amount: result.amount,
+          type: 'merge',
+        }, null, 2));
+        process.exit(0);
+      } catch (error) {
+        progress('', options.quiet);
+        handleCLIError(error);
+      }
+    });
+
+  return mergeCmd;
+}

package/src/cli/commands/withdraw.ts

@@ -0,0 +1,79 @@
+/**
+ * Withdraw CLI command
+ */
+
+import { Command } from 'commander';
+import { Keypair } from '../../keypair.js';
+import { withdraw } from '../../withdraw.js';
+import { handleCLIError, CLIError, ErrorCode } from '../errors.js';
+
+// Progress helper - writes to stderr so JSON output stays clean
+function progress(msg: string, quiet?: boolean) {
+  if (!quiet) {
+    process.stderr.write(`\r\x1b[K${msg}`);
+  }
+}
+
+export function createWithdrawCommand(): Command {
+  const withdrawCmd = new Command('withdraw')
+    .description('Withdraw from private pool to a public address')
+    .argument('<amount>', 'Amount to withdraw (e.g., 0.1)')
+    .argument('<recipient>', 'Recipient address (e.g., 0x...)')
+    .option('--veil-key <key>', 'Veil private key (or set VEIL_KEY env)')
+    .option('--rpc-url <url>', 'RPC URL (or set RPC_URL env)')
+    .option('--quiet', 'Suppress progress output')
+    .action(async (amount: string, recipient: string, options) => {
+      try {
+        // Validate recipient
+        if (!/^0x[a-fA-F0-9]{40}$/.test(recipient)) {
+          throw new CLIError(ErrorCode.INVALID_ADDRESS, 'Invalid recipient address format');
+        }
+
+        // Get keypair
+        const veilKey = options.veilKey || process.env.VEIL_KEY;
+        if (!veilKey) {
+          throw new CLIError(ErrorCode.VEIL_KEY_MISSING, 'VEIL_KEY required. Use --veil-key or set VEIL_KEY env');
+        }
+
+        const keypair = new Keypair(veilKey);
+        const rpcUrl = options.rpcUrl || process.env.RPC_URL;
+
+        // Progress callback
+        const onProgress = options.quiet
+          ? undefined
+          : (stage: string, detail?: string) => {
+              const msg = detail ? `${stage}: ${detail}` : stage;
+              progress(msg, options.quiet);
+            };
+
+        progress('Starting withdrawal...', options.quiet);
+
+        // Execute withdrawal
+        const result = await withdraw({
+          amount,
+          recipient: recipient as `0x${string}`,
+          keypair,
+          rpcUrl,
+          onProgress,
+        });
+
+        // Clear progress line
+        progress('', options.quiet);
+
+        // Output result
+        console.log(JSON.stringify({
+          success: result.success,
+          transactionHash: result.transactionHash,
+          blockNumber: result.blockNumber,
+          amount: result.amount,
+          recipient: result.recipient,
+        }, null, 2));
+        process.exit(0);
+      } catch (error) {
+        progress('', options.quiet);
+        handleCLIError(error);
+      }
+    });
+
+  return withdrawCmd;
+}

package/src/cli/config.ts

@@ -0,0 +1,58 @@
+/**
+ * CLI configuration handling
+ */
+
+import type { WalletConfig } from './wallet.js';
+
+export interface CLIOptions {
+  walletKey?: string;
+  rpcUrl?: string;
+}
+
+/**
+ * Get wallet configuration from CLI options and environment variables
+ */
+export function getConfig(options: CLIOptions): WalletConfig {
+  const walletKey = options.walletKey || process.env.WALLET_KEY;
+  const rpcUrl = options.rpcUrl || process.env.RPC_URL || 'https://mainnet.base.org';
+
+  if (!walletKey) {
+    throw new Error('Wallet key required. Use --wallet-key or set WALLET_KEY environment variable.');
+  }
+
+  // Validate wallet key format
+  if (!walletKey.startsWith('0x') || walletKey.length !== 66) {
+    throw new Error('Invalid wallet key format. Must be a 0x-prefixed 64-character hex string.');
+  }
+
+  return {
+    privateKey: walletKey as `0x${string}`,
+    rpcUrl,
+  };
+}
+
+/**
+ * Get Veil private key from CLI options or environment
+ */
+export function getVeilKey(options: { veilKey?: string }): string | undefined {
+  return options.veilKey || process.env.VEIL_KEY;
+}
+
+/**
+ * Load environment variables from .env.veil and .env files
+ */
+export function loadEnv(): void {
+  try {
+    // Dynamic import to avoid bundling issues
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const dotenv = require('dotenv');
+    
+    // Load .env.veil first (Veil-specific config)
+    dotenv.config({ path: '.env.veil', quiet: true });
+    
+    // Then load .env (for WALLET_KEY, RPC_URL if not in .env.veil)
+    dotenv.config({ quiet: true });
+  } catch {
+    // dotenv not available, skip
+  }
+}

package/src/cli/errors.ts

@@ -0,0 +1,114 @@
+/**
+ * Standardized CLI error handling
+ */
+
+/**
+ * Error codes for machine-readable error handling
+ */
+export const ErrorCode = {
+  VEIL_KEY_MISSING: 'VEIL_KEY_MISSING',
+  WALLET_KEY_MISSING: 'WALLET_KEY_MISSING',
+  DEPOSIT_KEY_MISSING: 'DEPOSIT_KEY_MISSING',
+  INVALID_ADDRESS: 'INVALID_ADDRESS',
+  INVALID_AMOUNT: 'INVALID_AMOUNT',
+  INSUFFICIENT_BALANCE: 'INSUFFICIENT_BALANCE',
+  USER_NOT_REGISTERED: 'USER_NOT_REGISTERED',
+  USER_ALREADY_REGISTERED: 'USER_ALREADY_REGISTERED',
+  NO_UTXOS: 'NO_UTXOS',
+  RELAY_ERROR: 'RELAY_ERROR',
+  RPC_ERROR: 'RPC_ERROR',
+  CONTRACT_ERROR: 'CONTRACT_ERROR',
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+} as const;
+
+export type ErrorCodeType = typeof ErrorCode[keyof typeof ErrorCode];
+
+/**
+ * CLI Error with error code
+ */
+export class CLIError extends Error {
+  code: ErrorCodeType;
+
+  constructor(code: ErrorCodeType, message: string) {
+    super(message);
+    this.code = code;
+    this.name = 'CLIError';
+  }
+}
+
+/**
+ * Map common error messages to error codes
+ */
+function inferErrorCode(message: string): ErrorCodeType {
+  const msg = message.toLowerCase();
+  
+  if (msg.includes('veil_key') || msg.includes('veil key')) {
+    return ErrorCode.VEIL_KEY_MISSING;
+  }
+  if (msg.includes('wallet_key') || msg.includes('wallet key')) {
+    return ErrorCode.WALLET_KEY_MISSING;
+  }
+  if (msg.includes('deposit_key') || msg.includes('deposit key')) {
+    return ErrorCode.DEPOSIT_KEY_MISSING;
+  }
+  if (msg.includes('invalid') && msg.includes('address')) {
+    return ErrorCode.INVALID_ADDRESS;
+  }
+  if (msg.includes('insufficient balance') || msg.includes('not enough')) {
+    return ErrorCode.INSUFFICIENT_BALANCE;
+  }
+  if (msg.includes('not registered')) {
+    return ErrorCode.USER_NOT_REGISTERED;
+  }
+  if (msg.includes('already registered')) {
+    return ErrorCode.USER_ALREADY_REGISTERED;
+  }
+  if (msg.includes('no unspent') || msg.includes('no utxo')) {
+    return ErrorCode.NO_UTXOS;
+  }
+  if (msg.includes('relay')) {
+    return ErrorCode.RELAY_ERROR;
+  }
+  if (msg.includes('rpc') || msg.includes('network') || msg.includes('connection')) {
+    return ErrorCode.RPC_ERROR;
+  }
+  if (msg.includes('revert') || msg.includes('contract')) {
+    return ErrorCode.CONTRACT_ERROR;
+  }
+  
+  return ErrorCode.UNKNOWN_ERROR;
+}
+
+/**
+ * Format error for JSON output
+ */
+export function formatErrorOutput(error: unknown): { success: false; errorCode: ErrorCodeType; error: string } {
+  let code: ErrorCodeType;
+  let message: string;
+
+  if (error instanceof CLIError) {
+    code = error.code;
+    message = error.message;
+  } else if (error instanceof Error) {
+    message = error.message;
+    code = inferErrorCode(message);
+  } else {
+    message = String(error);
+    code = inferErrorCode(message);
+  }
+
+  return {
+    success: false,
+    errorCode: code,
+    error: message,
+  };
+}
+
+/**
+ * Handle CLI error: print JSON and exit
+ */
+export function handleCLIError(error: unknown): never {
+  const output = formatErrorOutput(error);
+  console.log(JSON.stringify(output, null, 2));
+  process.exit(1);
+}

package/src/cli/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Veil CLI - Command-line interface for Veil Cash
+ * 
+ * Usage:
+ *   veil init              # Generate keypair
+ *   veil keypair           # Show keypair (JSON)
+ *   veil register          # Register on-chain
+ *   veil deposit 0.1       # Deposit ETH
+ *   veil balance           # Show all balances
+ *   veil queue-balance     # Show pending queue deposits
+ *   veil private-balance   # Show private balance
+ *   veil withdraw 0.1 --recipient 0x...  # Withdraw to public address
+ *   veil transfer 0.1 --to 0x...         # Transfer privately
+ *   veil merge 0.5         # Merge UTXOs (self-transfer)
+ */
+
+import { Command } from 'commander';
+import { loadEnv } from './config.js';
+import { createInitCommand } from './commands/init.js';
+import { createKeypairCommand } from './commands/keypair.js';
+import { createRegisterCommand } from './commands/register.js';
+import { createDepositCommand } from './commands/deposit.js';
+import { createBalanceCommand } from './commands/balance.js';
+import { createQueueBalanceCommand } from './commands/queue-balance.js';
+import { createPrivateBalanceCommand } from './commands/private-balance.js';
+import { createWithdrawCommand } from './commands/withdraw.js';
+import { createTransferCommand, createMergeCommand } from './commands/transfer.js';
+
+// Load environment variables
+loadEnv();
+
+const program = new Command();
+
+program
+  .name('veil')
+  .description('CLI for Veil Cash privacy pools on Base')
+  .version('0.1.0');
+
+// Add commands
+program.addCommand(createInitCommand());
+program.addCommand(createKeypairCommand());
+program.addCommand(createRegisterCommand());
+program.addCommand(createDepositCommand());
+program.addCommand(createBalanceCommand());
+program.addCommand(createQueueBalanceCommand());
+program.addCommand(createPrivateBalanceCommand());
+program.addCommand(createWithdrawCommand());
+program.addCommand(createTransferCommand());
+program.addCommand(createMergeCommand());
+
+// Parse and execute
+program.parse();