@veil-cash/sdk 0.1.0

package/src/balance.ts

@@ -0,0 +1,266 @@
+/**
+ * Balance functions for Veil SDK
+ * Query queue and private balances directly from blockchain
+ */
+
+import { createPublicClient, http, formatEther } from 'viem';
+import { base } from 'viem/chains';
+import { getAddresses } from './addresses.js';
+import { QUEUE_ABI, POOL_ABI } from './abi.js';
+import { Keypair } from './keypair.js';
+import { Utxo } from './utxo.js';
+import { toFixedHex } from './utils.js';
+import type { 
+  QueueBalanceResult, 
+  PendingDeposit, 
+  PrivateBalanceResult,
+  UtxoInfo,
+} from './types.js';
+
+// Deposit status enum from Queue contract
+const DEPOSIT_STATUS_MAP = {
+  0: 'pending',
+  1: 'accepted',
+  2: 'rejected',
+  3: 'refunded',
+} as const;
+
+/**
+ * Progress callback type
+ */
+export type ProgressCallback = (stage: string, detail?: string) => void;
+
+/**
+ * Get queue balance and pending deposits for an address
+ * Queries the Queue contract directly (no API dependency)
+ * 
+ * @param options - Query options
+ * @param options.address - Address to check
+ * @param options.rpcUrl - Optional RPC URL (uses default if not provided)
+ * @param options.onProgress - Optional progress callback
+ * @returns Queue balance and pending deposits
+ * 
+ * @example
+ * ```typescript
+ * const result = await getQueueBalance({
+ *   address: '0x...',
+ *   onProgress: (stage, detail) => console.log(stage, detail),
+ * });
+ * 
+ * console.log(`Queue balance: ${result.queueBalance} ETH`);
+ * console.log(`Pending deposits: ${result.pendingCount}`);
+ * ```
+ */
+export async function getQueueBalance(options: {
+  address: `0x${string}`;
+  rpcUrl?: string;
+  onProgress?: ProgressCallback;
+}): Promise<QueueBalanceResult> {
+  const { address, rpcUrl, onProgress } = options;
+  const addresses = getAddresses();
+
+  // Create public client
+  const publicClient = createPublicClient({
+    chain: base,
+    transport: http(rpcUrl),
+  });
+
+  // Get all pending deposit nonces
+  onProgress?.('Fetching pending deposits...');
+  const pendingNonces = await publicClient.readContract({
+    address: addresses.ethQueue,
+    abi: QUEUE_ABI,
+    functionName: 'getPendingDeposits',
+  }) as bigint[];
+  onProgress?.('Queue status', `${pendingNonces.length} pending deposits in queue`);
+
+  // Fetch deposit details for each pending nonce
+  const pendingDeposits: PendingDeposit[] = [];
+  let totalQueueBalance = 0n;
+
+  for (let i = 0; i < pendingNonces.length; i++) {
+    const nonce = pendingNonces[i];
+    onProgress?.('Checking deposit', `${i + 1}/${pendingNonces.length}`);
+    
+    const deposit = await publicClient.readContract({
+      address: addresses.ethQueue,
+      abi: QUEUE_ABI,
+      functionName: 'getDeposit',
+      args: [nonce],
+    }) as {
+      fallbackReceiver: `0x${string}`;
+      amountIn: bigint;
+      fee: bigint;
+      shieldAmount: bigint;
+      timestamp: bigint;
+      status: number;
+      depositKey: `0x${string}`;
+    };
+
+    // Check if this deposit belongs to the user
+    if (deposit.fallbackReceiver.toLowerCase() === address.toLowerCase()) {
+      totalQueueBalance += deposit.amountIn;
+      pendingDeposits.push({
+        nonce: nonce.toString(),
+        status: DEPOSIT_STATUS_MAP[deposit.status as keyof typeof DEPOSIT_STATUS_MAP] || 'pending',
+        amount: formatEther(deposit.amountIn),
+        amountWei: deposit.amountIn.toString(),
+        timestamp: new Date(Number(deposit.timestamp) * 1000).toISOString(),
+      });
+    }
+  }
+
+  if (pendingDeposits.length > 0) {
+    onProgress?.('Found', `${pendingDeposits.length} deposits for your address`);
+  }
+
+  return {
+    address,
+    queueBalance: formatEther(totalQueueBalance),
+    queueBalanceWei: totalQueueBalance.toString(),
+    pendingDeposits,
+    pendingCount: pendingDeposits.length,
+  };
+}
+
+/**
+ * Get private balance from the Pool contract
+ * Decrypts all encrypted outputs, calculates nullifiers, and checks spent status
+ * 
+ * @param options - Query options
+ * @param options.keypair - Keypair to decrypt UTXOs with
+ * @param options.rpcUrl - Optional RPC URL (uses default if not provided)
+ * @param options.onProgress - Optional progress callback
+ * @returns Private balance and UTXO details
+ * 
+ * @example
+ * ```typescript
+ * const keypair = new Keypair(process.env.VEIL_KEY);
+ * const result = await getPrivateBalance({ 
+ *   keypair,
+ *   onProgress: (stage, detail) => console.log(stage, detail),
+ * });
+ * 
+ * console.log(`Private balance: ${result.privateBalance} ETH`);
+ * console.log(`Unspent UTXOs: ${result.unspentCount}`);
+ * ```
+ */
+export async function getPrivateBalance(options: {
+  keypair: Keypair;
+  rpcUrl?: string;
+  onProgress?: ProgressCallback;
+}): Promise<PrivateBalanceResult> {
+  const { keypair, rpcUrl, onProgress } = options;
+  const addresses = getAddresses();
+
+  if (!keypair.privkey) {
+    throw new Error('Keypair must have a private key to calculate private balance');
+  }
+
+  // Create public client
+  const publicClient = createPublicClient({
+    chain: base,
+    transport: http(rpcUrl),
+  });
+
+  // 1. Get total count of encrypted outputs
+  onProgress?.('Fetching pool index...');
+  const nextIndex = await publicClient.readContract({
+    address: addresses.ethPool,
+    abi: POOL_ABI,
+    functionName: 'nextIndex',
+  }) as number;
+  onProgress?.('Pool index', `${nextIndex} commitments`);
+
+  if (nextIndex === 0) {
+    return {
+      privateBalance: '0',
+      privateBalanceWei: '0',
+      utxoCount: 0,
+      spentCount: 0,
+      unspentCount: 0,
+      utxos: [],
+    };
+  }
+
+  // 2. Fetch encrypted outputs in batches of 5000
+  const BATCH_SIZE = 5000;
+  const allEncryptedOutputs: string[] = [];
+  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 encrypted outputs', `batch ${batchNum}/${totalBatches} (${start}-${end})`);
+    
+    const batch = await publicClient.readContract({
+      address: addresses.ethPool,
+      abi: POOL_ABI,
+      functionName: 'getEncryptedOutputs',
+      args: [BigInt(start), BigInt(end)],
+    }) as string[];
+    allEncryptedOutputs.push(...batch);
+  }
+
+  // 3. Decrypt outputs - only user's UTXOs will decrypt successfully
+  onProgress?.('Decrypting outputs', `scanning ${allEncryptedOutputs.length} outputs...`);
+  const decryptedUtxos: { utxo: Utxo; index: number }[] = [];
+
+  for (let i = 0; i < allEncryptedOutputs.length; i++) {
+    try {
+      const utxo = Utxo.decrypt(allEncryptedOutputs[i], keypair);
+      utxo.index = i;
+      // Only include UTXOs with non-zero amounts
+      if (utxo.amount > 0n) {
+        decryptedUtxos.push({ utxo, index: i });
+      }
+    } catch {
+      // Not our UTXO - decryption fails, skip
+    }
+  }
+  onProgress?.('Found UTXOs', `${decryptedUtxos.length} belonging to you`);
+
+  // 4. Check spent status for each UTXO
+  const utxoInfos: UtxoInfo[] = [];
+  let totalBalance = 0n;
+  let spentCount = 0;
+  let unspentCount = 0;
+
+  for (let i = 0; i < decryptedUtxos.length; i++) {
+    const { utxo, index } = decryptedUtxos[i];
+    onProgress?.('Checking spent status', `UTXO ${i + 1}/${decryptedUtxos.length}`);
+    
+    const nullifier = utxo.getNullifier();
+    const nullifierHex = toFixedHex(nullifier) as `0x${string}`;
+
+    const isSpent = await publicClient.readContract({
+      address: addresses.ethPool,
+      abi: POOL_ABI,
+      functionName: 'isSpent',
+      args: [nullifierHex],
+    }) as boolean;
+
+    utxoInfos.push({
+      index,
+      amount: formatEther(utxo.amount),
+      amountWei: utxo.amount.toString(),
+      isSpent,
+    });
+
+    if (isSpent) {
+      spentCount++;
+    } else {
+      unspentCount++;
+      totalBalance += utxo.amount;
+    }
+  }
+
+  return {
+    privateBalance: formatEther(totalBalance),
+    privateBalanceWei: totalBalance.toString(),
+    utxoCount: decryptedUtxos.length,
+    spentCount,
+    unspentCount,
+    utxos: utxoInfos,
+  };
+}

package/src/cli/commands/balance.ts

@@ -0,0 +1,118 @@
+/**
+ * Balance CLI command - Show both queue and private balances
+ */
+
+import { Command } from 'commander';
+import { getQueueBalance, getPrivateBalance } from '../../balance.js';
+import { Keypair } from '../../keypair.js';
+import { getAddress } from '../wallet.js';
+import { formatEther } from 'viem';
+import { handleCLIError, CLIError, ErrorCode } from '../errors.js';
+
+export function createBalanceCommand(): Command {
+  const balance = new Command('balance')
+    .description('Show queue and private balances')
+    .option('--wallet-key <key>', 'Ethereum wallet key (or set WALLET_KEY env)')
+    .option('--address <address>', 'Address to check (or derived from wallet 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('--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 CLIError(ErrorCode.WALLET_KEY_MISSING, 'Must provide --address or --wallet-key (or set WALLET_KEY env)');
+          }
+          address = getAddress(walletKey as `0x${string}`);
+        }
+
+        // Get keypair for private balance
+        const veilKey = options.veilKey || process.env.VEIL_KEY;
+        const keypair = veilKey ? new Keypair(veilKey) : null;
+
+        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;
+              process.stderr.write(`\r\x1b[K${msg}`);
+            };
+
+        // Get queue balance
+        const queueResult = await getQueueBalance({ address, rpcUrl, onProgress });
+
+        // Get private balance if keypair available
+        let privateResult = null;
+        if (keypair) {
+          privateResult = await getPrivateBalance({ keypair, rpcUrl, onProgress });
+        }
+
+        // Clear progress line
+        if (!options.quiet) {
+          process.stderr.write('\r\x1b[K');
+        }
+
+        // Calculate total balance
+        const queueBalanceWei = BigInt(queueResult.queueBalanceWei);
+        const privateBalanceWei = privateResult ? BigInt(privateResult.privateBalanceWei) : 0n;
+        const totalBalanceWei = queueBalanceWei + privateBalanceWei;
+
+        // Get deposit key if available
+        const depositKey = process.env.DEPOSIT_KEY || (keypair ? keypair.depositKey() : null);
+
+        // Build output structure
+        const output: Record<string, unknown> = {
+          address,
+          depositKey: depositKey || null,
+          totalBalance: formatEther(totalBalanceWei),
+          totalBalanceWei: totalBalanceWei.toString(),
+        };
+
+        // Private balance first
+        if (privateResult) {
+          const unspentUtxos = privateResult.utxos.filter(u => !u.isSpent);
+          output.private = {
+            balance: privateResult.privateBalance,
+            balanceWei: privateResult.privateBalanceWei,
+            utxoCount: privateResult.unspentCount,
+            utxos: unspentUtxos.map(u => ({
+              index: u.index,
+              amount: u.amount,
+            })),
+          };
+        } else {
+          output.private = {
+            balance: null,
+            note: 'Set VEIL_KEY to see private balance',
+          };
+        }
+
+        // Queue details second
+        output.queue = {
+          balance: queueResult.queueBalance,
+          balanceWei: queueResult.queueBalanceWei,
+          count: queueResult.pendingCount,
+          deposits: queueResult.pendingDeposits.map(d => ({
+            nonce: d.nonce,
+            amount: d.amount,
+            status: d.status,
+            timestamp: d.timestamp,
+          })),
+        };
+
+        console.log(JSON.stringify(output, null, 2));
+      } catch (error) {
+        process.stderr.write('\r\x1b[K');
+        handleCLIError(error);
+      }
+    });
+
+  return balance;
+}

package/src/cli/commands/deposit.ts

@@ -0,0 +1,115 @@
+/**
+ * Deposit CLI command
+ */
+
+import { Command } from 'commander';
+import { buildDepositETHTx } from '../../deposit.js';
+import { sendTransaction, getAddress, getBalance } from '../wallet.js';
+import { getConfig } from '../config.js';
+import { parseEther, formatEther } from 'viem';
+import { handleCLIError, CLIError, ErrorCode } from '../errors.js';
+
+// Minimum deposit: 0.01 ETH (net after 0.3% fee)
+// To deposit 0.01 ETH net, you need to send: 0.01 / (1 - 0.003) ≈ 0.01003 ETH
+const MINIMUM_DEPOSIT_ETH = 0.01;
+const DEPOSIT_FEE_PERCENT = 0.3;
+const MINIMUM_DEPOSIT_WITH_FEE = MINIMUM_DEPOSIT_ETH / (1 - DEPOSIT_FEE_PERCENT / 100);
+
+// 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 createDepositCommand(): Command {
+  const deposit = new Command('deposit')
+    .description('Deposit ETH into Veil')
+    .argument('<amount>', 'Amount to deposit (e.g., 0.1)')
+    .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('--rpc-url <url>', 'RPC URL (or set RPC_URL env)')
+    .option('--unsigned', 'Output unsigned transaction payload (Bankr-compatible format)')
+    .option('--quiet', 'Suppress progress output')
+    .action(async (amount: string, options) => {
+      try {
+        const amountNum = parseFloat(amount);
+        
+        // Check minimum deposit
+        if (amountNum < MINIMUM_DEPOSIT_WITH_FEE) {
+          throw new CLIError(
+            ErrorCode.INVALID_AMOUNT,
+            `Minimum deposit is ${MINIMUM_DEPOSIT_ETH} ETH (net). ` +
+            `With ${DEPOSIT_FEE_PERCENT}% fee, send at least ${MINIMUM_DEPOSIT_WITH_FEE.toFixed(5)} ETH.`
+          );
+        }
+
+        // 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. Use --deposit-key or set DEPOSIT_KEY in .env (run: veil init)');
+        }
+
+        progress('Building transaction...', options.quiet);
+
+        // Build the transaction
+        const tx = buildDepositETHTx({
+          depositKey,
+          amount,
+        });
+
+        // Handle --unsigned mode (no wallet required, just build payload)
+        if (options.unsigned) {
+          progress('', options.quiet); // Clear line
+          // Output Bankr-compatible format
+          const payload = {
+            to: tx.to,
+            data: tx.data,
+            value: tx.value ? tx.value.toString() : '0',
+            chainId: 8453, // Base mainnet
+          };
+
+          console.log(JSON.stringify(payload, null, 2));
+          return;
+        }
+
+        // Regular mode: sign and send
+        const config = getConfig(options);
+        const address = getAddress(config.privateKey);
+
+        progress('Checking balance...', options.quiet);
+
+        // Check balance
+        const balance = await getBalance(address, config.rpcUrl);
+        const amountWei = parseEther(amount);
+        
+        if (balance < amountWei) {
+          progress('', options.quiet);
+          throw new CLIError(ErrorCode.INSUFFICIENT_BALANCE, `Insufficient ETH balance. Have: ${formatEther(balance)} ETH, Need: ${amount} ETH`);
+        }
+
+        progress('Sending transaction...', options.quiet);
+
+        // Send the transaction
+        const result = await sendTransaction(config, tx);
+
+        progress('Confirming...', options.quiet);
+
+        // Clear progress line
+        progress('', options.quiet);
+
+        console.log(JSON.stringify({
+          success: result.receipt.status === 'success',
+          hash: result.hash,
+          amount,
+          blockNumber: result.receipt.blockNumber.toString(),
+          gasUsed: result.receipt.gasUsed.toString(),
+        }, null, 2));
+      } catch (error) {
+        progress('', options.quiet); // Clear progress line
+        handleCLIError(error);
+      }
+    });
+
+  return deposit;
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,147 @@
+/**
+ * Init CLI command - Generate and save a Veil keypair
+ */
+
+import { Command } from 'commander';
+import { createInterface } from 'readline';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import { mkdirSync } from 'fs';
+import { Keypair } from '../../keypair.js';
+
+/**
+ * Prompt user for yes/no confirmation
+ */
+async function confirm(question: string): Promise<boolean> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(`${question} (y/n): `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+/**
+ * Get the default path to .env.veil file (current directory)
+ */
+function getDefaultEnvPath(): string {
+  return '.env.veil';
+}
+
+/**
+ * Check if VEIL_KEY exists in an env file
+ */
+function veilKeyExistsAt(envPath: string): boolean {
+  if (!existsSync(envPath)) return false;
+  
+  const content = readFileSync(envPath, 'utf-8');
+  return /^VEIL_KEY=/m.test(content);
+}
+
+/**
+ * Update or add a key in .env content
+ */
+function updateEnvVar(content: string, key: string, value: string): string {
+  const regex = new RegExp(`^${key}=.*`, 'm');
+  if (regex.test(content)) {
+    return content.replace(regex, `${key}=${value}`);
+  } else {
+    if (content && !content.endsWith('\n')) {
+      content += '\n';
+    }
+    return content + `${key}=${value}\n`;
+  }
+}
+
+/**
+ * Save Veil keypair to a file
+ */
+function saveVeilKeypair(veilKey: string, depositKey: string, envPath: string): void {
+  // Ensure directory exists
+  const dir = dirname(envPath);
+  if (dir && dir !== '.' && !existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  
+  let content = '';
+  
+  if (existsSync(envPath)) {
+    content = readFileSync(envPath, 'utf-8');
+  } else {
+    content = '# Veil Cash Configuration\n# Generated by: veil init\n\n';
+  }
+  
+  content = updateEnvVar(content, 'VEIL_KEY', veilKey);
+  content = updateEnvVar(content, 'DEPOSIT_KEY', depositKey);
+  
+  writeFileSync(envPath, content);
+}
+
+export function createInitCommand(): Command {
+  const init = new Command('init')
+    .description('Generate a new Veil keypair')
+    .option('--force', 'Overwrite existing keypair without prompting')
+    .option('--json', 'Output as JSON (no prompts, no file save)')
+    .option('--out <path>', 'Save to custom path instead of .env.veil')
+    .option('--no-save', 'Print keypair without saving to file')
+    .action(async (options) => {
+      const envPath = options.out || getDefaultEnvPath();
+      
+      // JSON mode: no prompts, no save, just output JSON
+      if (options.json) {
+        const kp = new Keypair();
+        console.log(JSON.stringify({
+          veilKey: kp.privkey,
+          depositKey: kp.depositKey(),
+        }, null, 2));
+        process.exit(0);
+        return;
+      }
+
+      // No-save mode: print but don't save
+      if (!options.save) {
+        const kp = new Keypair();
+        console.log('\nGenerated new Veil keypair:\n');
+        console.log('Veil Private Key:');
+        console.log(`  ${kp.privkey}\n`);
+        console.log('Deposit Key (register this on-chain):');
+        console.log(`  ${kp.depositKey()}\n`);
+        console.log('(Not saved - use --out <path> to save to a file)');
+        process.exit(0);
+        return;
+      }
+
+      // Check if VEIL_KEY already exists (unless --force)
+      const keyExists = veilKeyExistsAt(envPath);
+      
+      if (keyExists && !options.force) {
+        console.log(`\nWARNING: A Veil key already exists in ${envPath}`);
+        const proceed = await confirm('Create a new key? This will overwrite the existing one');
+        if (!proceed) {
+          console.log('Aborted. Existing key preserved.');
+          process.exit(0);
+          return;
+        }
+      }
+      
+      const kp = new Keypair();
+      
+      console.log('\nGenerated new Veil keypair:\n');
+      console.log('Veil Private Key:');
+      console.log(`  ${kp.privkey}\n`);
+      console.log('Deposit Key (register this on-chain):');
+      console.log(`  ${kp.depositKey()}\n`);
+      
+      saveVeilKeypair(kp.privkey!, kp.depositKey(), envPath);
+      console.log(`Saved to ${envPath}`);
+      console.log('\nNext step: veil register');
+      process.exit(0);
+    });
+
+  return init;
+}

package/src/cli/commands/keypair.ts

@@ -0,0 +1,31 @@
+/**
+ * Keypair CLI command - Show current keypair as JSON
+ */
+
+import { Command } from 'commander';
+import { Keypair } from '../../keypair.js';
+
+export function createKeypairCommand(): Command {
+  const keypair = new Command('keypair')
+    .description('Show current Veil keypair as JSON')
+    .action(() => {
+      const veilKey = process.env.VEIL_KEY;
+      
+      if (!veilKey) {
+        console.log(JSON.stringify({ 
+          success: false, 
+          error: 'No keypair found. Run "veil init" first.' 
+        }, null, 2));
+        process.exit(1);
+      }
+      
+      const kp = new Keypair(veilKey);
+      
+      console.log(JSON.stringify({
+        veilPrivateKey: kp.privkey,
+        depositKey: kp.depositKey(),
+      }, null, 2));
+    });
+
+  return keypair;
+}