@veil-cash/sdk 0.3.0 → 0.5.0

package/src/cli/config.ts

@@ -2,22 +2,50 @@
  * CLI configuration handling
  */
 
+import { CLIError, ErrorCode } from './errors.js';
+import { getAddress } from './wallet.js';
 import type { WalletConfig } from './wallet.js';
 
 export interface CLIOptions {
-  walletKey?: string;
   rpcUrl?: string;
 }
 
+export interface AddressOptions {
+  address?: string;
+}
+
+export interface ResolvedAddress {
+  address: `0x${string}`;
+  source: 'flag' | 'wallet-key' | 'signer-address';
+}
+
+function validateAddress(address: string, sourceLabel: string): `0x${string}` {
+  const normalized = address.trim();
+  if (!/^0x[a-fA-F0-9]{40}$/.test(normalized)) {
+    throw new CLIError(ErrorCode.INVALID_ADDRESS, `${sourceLabel} must be a valid 0x-prefixed Ethereum address.`);
+  }
+  return normalized as `0x${string}`;
+}
+
+function ensureAddressEnvConsistency(): void {
+  if (process.env.WALLET_KEY && process.env.SIGNER_ADDRESS) {
+    throw new CLIError(
+      ErrorCode.CONFIG_CONFLICT,
+      'WALLET_KEY and SIGNER_ADDRESS are mutually exclusive. Set only one.',
+    );
+  }
+}
+
 /**
  * Get wallet configuration from CLI options and environment variables
  */
 export function getConfig(options: CLIOptions): WalletConfig {
-  const walletKey = options.walletKey || process.env.WALLET_KEY;
+  ensureAddressEnvConsistency();
+  const 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.');
+    throw new Error('WALLET_KEY env var required. Set it before running this command.');
   }
 
   // Validate wallet key format
@@ -38,6 +66,58 @@ export function getVeilKey(options: { veilKey?: string }): string | undefined {
   return options.veilKey || process.env.VEIL_KEY;
 }
 
+/**
+ * Resolve an address for query / unsigned flows.
+ * Prefers explicit --address, then derives from WALLET_KEY, then falls back to SIGNER_ADDRESS.
+ */
+export function resolveAddress(
+  options: AddressOptions = {},
+  config: { required?: boolean; allowInvalidWalletKey?: boolean } = {},
+): ResolvedAddress | null {
+  ensureAddressEnvConsistency();
+
+  if (options.address) {
+    return {
+      address: validateAddress(options.address, '--address'),
+      source: 'flag',
+    };
+  }
+
+  const walletKey = process.env.WALLET_KEY;
+  if (walletKey) {
+    try {
+      return {
+        address: getAddress(walletKey as `0x${string}`),
+        source: 'wallet-key',
+      };
+    } catch {
+      if (!config.allowInvalidWalletKey) {
+        throw new CLIError(
+          ErrorCode.WALLET_KEY_MISSING,
+          'Invalid WALLET_KEY format. Must be a 0x-prefixed 64-character hex string.',
+        );
+      }
+    }
+  }
+
+  const signerAddress = process.env.SIGNER_ADDRESS;
+  if (signerAddress) {
+    return {
+      address: validateAddress(signerAddress, 'SIGNER_ADDRESS'),
+      source: 'signer-address',
+    };
+  }
+
+  if (config.required) {
+    throw new CLIError(
+      ErrorCode.WALLET_KEY_MISSING,
+      'Must provide --address, set SIGNER_ADDRESS, or set WALLET_KEY env.',
+    );
+  }
+
+  return null;
+}
+
 /**
  * Load environment variables from .env.veil and .env files
  */
@@ -46,10 +126,10 @@ export function loadEnv(): void {
     // 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 {

package/src/cli/errors.ts

@@ -9,6 +9,7 @@ export const ErrorCode = {
   VEIL_KEY_MISSING: 'VEIL_KEY_MISSING',
   WALLET_KEY_MISSING: 'WALLET_KEY_MISSING',
   DEPOSIT_KEY_MISSING: 'DEPOSIT_KEY_MISSING',
+  CONFIG_CONFLICT: 'CONFIG_CONFLICT',
   INVALID_ADDRESS: 'INVALID_ADDRESS',
   INVALID_AMOUNT: 'INVALID_AMOUNT',
   INSUFFICIENT_BALANCE: 'INSUFFICIENT_BALANCE',
@@ -51,6 +52,9 @@ function inferErrorCode(message: string): ErrorCodeType {
   if (msg.includes('deposit_key') || msg.includes('deposit key')) {
     return ErrorCode.DEPOSIT_KEY_MISSING;
   }
+  if (msg.includes('mutually exclusive') || msg.includes('config conflict') || msg.includes('signer_address')) {
+    return ErrorCode.CONFIG_CONFLICT;
+  }
   if (msg.includes('invalid') && msg.includes('address')) {
     return ErrorCode.INVALID_ADDRESS;
   }

package/src/cli/index.ts

@@ -8,8 +8,8 @@
  *   veil register                    # Register on-chain
  *   veil deposit ETH 0.1             # Deposit ETH
  *   veil balance                     # Show all balances
- *   veil queue-balance               # Show pending queue deposits
- *   veil private-balance             # Show private balance
+ *   veil balance queue               # Show pending queue deposits
+ *   veil balance private             # Show private balance
  *   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)
@@ -36,7 +36,14 @@ const program = new Command();
 program
   .name('veil')
   .description('CLI for Veil Cash privacy pools on Base')
-  .version('0.3.0');
+  .version('0.5.0')
+  .addHelpText('after', `
+Getting started:
+  veil init
+  veil register
+  veil deposit ETH 0.1
+  veil balance
+`);
 
 // Add commands
 program.addCommand(createInitCommand());
@@ -44,12 +51,23 @@ program.addCommand(createKeypairCommand());
 program.addCommand(createRegisterCommand());
 program.addCommand(createDepositCommand());
 program.addCommand(createBalanceCommand());
-program.addCommand(createQueueBalanceCommand());
-program.addCommand(createPrivateBalanceCommand());
+program.addCommand(createQueueBalanceCommand(), { hidden: true });
+program.addCommand(createPrivateBalanceCommand(), { hidden: true });
 program.addCommand(createWithdrawCommand());
 program.addCommand(createTransferCommand());
 program.addCommand(createMergeCommand());
 program.addCommand(createStatusCommand());
 
+const knownTopLevelCommands = new Set([
+  ...program.commands.map((command) => command.name()),
+  'help',
+]);
+
+const firstArg = process.argv[2];
+if (firstArg && !firstArg.startsWith('-') && !knownTopLevelCommands.has(firstArg)) {
+  console.error(`error: unknown command '${firstArg}'`);
+  process.exit(1);
+}
+
 // Parse and execute
 program.parse();

package/src/cli/output.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared CLI output helpers.
+ */
+
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+export interface JsonOutputOption {
+  json?: boolean;
+}
+
+export function printJson(value: unknown): void {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+export function printLine(value = ''): void {
+  console.log(value);
+}
+
+export function printHeader(title: string): void {
+  console.log();
+  console.log(`${BOLD}${title}${RESET}`);
+  console.log(`${DIM}${'─'.repeat(40)}${RESET}`);
+}
+
+export function printSection(title: string): void {
+  console.log();
+  console.log(`${BOLD}${title}${RESET}`);
+}
+
+export function printDivider(): void {
+  console.log();
+  console.log(`${DIM}${'─'.repeat(40)}${RESET}`);
+}
+
+export function printFields(fields: Array<{ label: string; value: unknown }>): void {
+  const visibleFields = fields.filter((field) => field.value !== undefined);
+  const width = visibleFields.reduce((max, field) => Math.max(max, field.label.length), 0);
+
+  for (const field of visibleFields) {
+    const label = `${DIM}${field.label.padEnd(width)}${RESET}`;
+    console.log(`  ${label}  ${formatValue(field.value)}`);
+  }
+}
+
+export function printList(items: string[]): void {
+  if (items.length === 0) {
+    console.log(`  ${DIM}(none)${RESET}`);
+    return;
+  }
+
+  for (const item of items) {
+    console.log(`  ${item}`);
+  }
+}
+
+export function maskValue(value: string, start = 10, end = 8): string {
+  if (value.length <= start + end + 3) {
+    return value;
+  }
+
+  return `${value.slice(0, start)}...${value.slice(-end)}`;
+}
+
+export function txUrl(hash: string): string {
+  return `https://basescan.org/tx/${hash}`;
+}
+
+export function clearProgress(): void {
+  process.stderr.write('\r\x1b[K');
+}
+
+export function createProgressReporter(): (stage: string, detail?: string) => void {
+  return (stage: string, detail?: string) => {
+    const message = detail ? `${stage}: ${detail}` : stage;
+    process.stderr.write(`\r\x1b[K${message}`);
+  };
+}
+
+function formatValue(value: unknown): string {
+  if (value === null) return 'null';
+  if (value === undefined) return '';
+  if (typeof value === 'boolean') return value ? 'yes' : 'no';
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value);
+}

package/src/cli/wallet.ts

@@ -9,12 +9,13 @@ import {
   decodeErrorResult,
   BaseError,
   ContractFunctionRevertedError,
+  formatUnits,
 } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { base } from 'viem/chains';
 import type { TransactionData } from '../types.js';
-import { ENTRY_ABI } from '../abi.js';
-import { getAddresses } from '../addresses.js';
+import { ENTRY_ABI, ERC20_ABI } from '../abi.js';
+import { getAddresses, POOL_CONFIG, ADDRESSES } from '../addresses.js';
 
 export interface WalletConfig {
   privateKey: `0x${string}`;
@@ -63,14 +64,25 @@ export function createWallet(config: WalletConfig): any {
  * Known custom error selectors (first 4 bytes of keccak256 hash of error signature)
  */
 const ERROR_SELECTORS: Record<string, string> = {
+  '0xd92e233d': 'ZeroAddress',
+  '0xe9e26e4e': 'OnlyOwnerCanRegister',
+  '0x1f2a2005': 'ZeroAmount',
   '0x3ee5aeb5': 'DepositsDisabled',
+  '0x4cba3441': 'InvalidDepositKey',
+  '0xc64891a5': 'NotRelayer',
+  '0xfcc00b30': 'NoETHBalance',
+  '0x7b7b36da': 'NoTokenBalance',
+  '0x7ffddb78': 'TokenApproveFailed',
+  '0xb12d13eb': 'ETHTransferFailed',
+  '0x1f6d5aef': 'NonceUsed',
+  '0x82b42900': 'Unauthorized',
+  '0x1ab7da6b': 'DeadlineExpired',
   '0x8e8f6d6f': 'MinimumDepositNotMet',
   '0x5cd83192': 'NotAllowedToDeposit',
   '0x6f5e8818': 'UserNotRegistered',
   '0x8a2ef116': 'UserAlreadyRegistered',
   '0x0dc149f0': 'InvalidDepositKey',
   '0x584a7938': 'InvalidDepositKeyForUser',
-  '0xd92e233d': 'OnlyOwnerCanRegister',
 };
 
 /**
@@ -106,11 +118,17 @@ function decodeCustomError(error: unknown): string | null {
     
     if (possibleData && typeof possibleData === 'string' && possibleData.startsWith('0x')) {
       try {
-        const decoded = decodeErrorResult({
-          abi: ENTRY_ABI,
-          data: possibleData as `0x${string}`,
-        });
-        return decoded.errorName;
+        for (const abi of [ENTRY_ABI] as const) {
+          try {
+            const decoded = decodeErrorResult({
+              abi,
+              data: possibleData as `0x${string}`,
+            });
+            return decoded.errorName;
+          } catch {
+            // Try the next ABI
+          }
+        }
       } catch {
         // Try selector lookup
         const selector = possibleData.slice(0, 10).toLowerCase();
@@ -151,16 +169,26 @@ export async function sendTransaction(
   }
 
   // Send the transaction
-  const hash = await walletClient.sendTransaction({
-    account,
-    chain,
-    to: tx.to,
-    data: tx.data,
-    value: tx.value,
-  });
+  let hash: `0x${string}`;
+  try {
+    hash = await walletClient.sendTransaction({
+      account,
+      chain,
+      to: tx.to,
+      data: tx.data,
+      value: tx.value,
+    });
+  } catch (error) {
+    throw error;
+  }
 
   // Wait for confirmation
-  const receipt = await publicClient.waitForTransactionReceipt({ hash });
+  let receipt;
+  try {
+    receipt = await publicClient.waitForTransactionReceipt({ hash });
+  } catch (error) {
+    throw error;
+  }
 
   return {
     hash,
@@ -196,6 +224,37 @@ export async function getBalance(
   return publicClient.getBalance({ address });
 }
 
+/**
+ * Get public wallet balances (ETH + USDC) for an address
+ */
+export async function getWalletBalances(
+  address: `0x${string}`,
+  rpcUrl?: string
+): Promise<{ eth: string; ethWei: string; usdc: string; usdcWei: string }> {
+  const transport = http(rpcUrl);
+  const publicClient = createPublicClient({
+    chain: base,
+    transport,
+  });
+
+  const [ethBalance, usdcBalance] = await Promise.all([
+    publicClient.getBalance({ address }),
+    publicClient.readContract({
+      address: ADDRESSES.usdcToken as `0x${string}`,
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [address],
+    }) as Promise<bigint>,
+  ]);
+
+  return {
+    eth: formatUnits(ethBalance, POOL_CONFIG.eth.decimals),
+    ethWei: ethBalance.toString(),
+    usdc: formatUnits(usdcBalance, POOL_CONFIG.usdc.decimals),
+    usdcWei: usdcBalance.toString(),
+  };
+}
+
 /**
  * Check if an address is already registered (has a deposit key on-chain)
  */

package/src/deposit.ts

@@ -181,65 +181,7 @@ export function buildDepositUSDCTx(options: {
 }
 
 /**
- * Build a transaction to approve cbBTC for deposit
- * Must be called before depositCBBTC if allowance is insufficient
- * 
- * @param options - Approval options
- * @param options.amount - Amount to approve (human readable, e.g., '0.5')
- * @returns Transaction data
- */
-export function buildApproveCBBTCTx(options: {
-  amount: string;
-}): TransactionData {
-  const { amount } = options;
-  const addresses = getAddresses();
-  
-  const amountWei = parseUnits(amount, POOL_CONFIG.cbbtc.decimals);
-  
-  const data = encodeFunctionData({
-    abi: ERC20_ABI,
-    functionName: 'approve',
-    args: [addresses.entry, amountWei],
-  });
-
-  return {
-    to: addresses.cbbtcToken,
-    data,
-  };
-}
-
-/**
- * Build a transaction to deposit cbBTC
- * Note: You must approve cbBTC first using buildApproveCBBTCTx
- * 
- * @param options - Deposit options
- * @param options.depositKey - Deposit key from Keypair.depositKey()
- * @param options.amount - Amount to deposit (human readable, e.g., '0.5')
- * @returns Transaction data
- */
-export function buildDepositCBBTCTx(options: {
-  depositKey: string;
-  amount: string;
-}): TransactionData {
-  const { depositKey, amount } = options;
-  const addresses = getAddresses();
-  
-  const amountWei = parseUnits(amount, POOL_CONFIG.cbbtc.decimals);
-  
-  const data = encodeFunctionData({
-    abi: ENTRY_ABI,
-    functionName: 'queueBTC',
-    args: [amountWei, depositKey as `0x${string}`],
-  });
-
-  return {
-    to: addresses.entry,
-    data,
-  };
-}
-
-/**
- * Build a deposit transaction (ETH, USDC, or cbBTC)
+ * Build a deposit transaction (ETH or USDC)
  * Convenience function that routes to the correct builder
  * 
  * @param options - Deposit options
@@ -260,13 +202,6 @@ export function buildDepositCBBTCTx(options: {
  *   amount: '100',
  *   token: 'USDC',
  * });
- * 
- * // cbBTC deposit (remember to approve first!)
- * const cbbtcTx = buildDepositTx({
- *   depositKey: keypair.depositKey(),
- *   amount: '0.5',
- *   token: 'CBBTC',
- * });
  * ```
  */
 export function buildDepositTx(options: {
@@ -279,10 +214,6 @@ export function buildDepositTx(options: {
   if (token === 'USDC') {
     return buildDepositUSDCTx(rest);
   }
-
-  if (token === 'CBBTC') {
-    return buildDepositCBBTCTx(rest);
-  }
   
   return buildDepositETHTx(rest);
 }

package/src/index.ts

@@ -46,8 +46,6 @@ export {
   buildDepositETHTx,
   buildDepositUSDCTx,
   buildApproveUSDCTx,
-  buildDepositCBBTCTx,
-  buildApproveCBBTCTx,
   buildDepositTx,
 } from './deposit.js';
 
@@ -118,7 +116,12 @@ export {
 } from './relay.js';
 
 // ABIs
-export { ENTRY_ABI, ERC20_ABI, QUEUE_ABI, POOL_ABI } from './abi.js';
+export {
+  ENTRY_ABI,
+  ERC20_ABI,
+  QUEUE_ABI,
+  POOL_ABI,
+} from './abi.js';
 
 // Utilities
 export { 

package/src/prover.ts

@@ -133,6 +133,9 @@ export async function prove(input: ProofInput, circuitName: string): Promise<str
     utils.stringifyBigInts(input) as any,
     wasmPath,
     zkeyPath,
+    undefined,
+    undefined,
+    { singleThread: true },
   );
   const proof = result.proof as unknown as SnarkProof;
 

package/src/relay.ts

@@ -98,8 +98,8 @@ export async function submitRelay(options: SubmitRelayOptions): Promise<RelayRes
     throw new RelayError('Invalid type. Must be "withdraw" or "transfer"', 400);
   }
 
-  if (pool !== 'eth' && pool !== 'usdc' && pool !== 'cbbtc') {
-    throw new RelayError('Invalid pool. Must be "eth", "usdc", or "cbbtc"', 400);
+  if (pool !== 'eth' && pool !== 'usdc') {
+    throw new RelayError('Invalid pool. Must be "eth" or "usdc"', 400);
   }
 
   if (!proofArgs || !extData) {

package/src/types.ts

@@ -5,7 +5,7 @@
 /**
  * Supported tokens
  */
-export type Token = 'ETH' | 'USDC' | 'CBBTC';
+export type Token = 'ETH' | 'USDC';
 
 /**
  * Encrypted message format (x25519-xsalsa20-poly1305)
@@ -27,9 +27,6 @@ export interface NetworkAddresses {
   usdcPool: `0x${string}`;
   usdcQueue: `0x${string}`;
   usdcToken: `0x${string}`;
-  cbbtcPool: `0x${string}`;
-  cbbtcQueue: `0x${string}`;
-  cbbtcToken: `0x${string}`;
   chainId: number;
   relayUrl: string;
 }
@@ -121,7 +118,7 @@ export interface PrivateBalanceResult {
 /**
  * Pool type for relay operations
  */
-export type RelayPool = 'eth' | 'usdc' | 'cbbtc';
+export type RelayPool = 'eth' | 'usdc';
 
 /**
  * Type of relay transaction