@veil-cash/sdk 0.4.0 → 0.5.0

package/src/cli/commands/transfer.ts

@@ -6,26 +6,24 @@ import { Command } from 'commander';
 import { Keypair } from '../../keypair.js';
 import { transfer, mergeUtxos } from '../../transfer.js';
 import { handleCLIError, CLIError, ErrorCode } from '../errors.js';
+import { clearProgress, createProgressReporter, printFields, printHeader, printJson, printLine, txUrl } from '../output.js';
 import type { RelayPool } from '../../types.js';
 
 const SUPPORTED_ASSETS = ['ETH', 'USDC'];
 
-// 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('<asset>', 'Asset to transfer (ETH or USDC)')
     .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')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', `
+Examples:
+  veil transfer ETH 0.02 0xRecipientAddress
+  veil transfer USDC 25 0xRecipientAddress
+  veil transfer ETH 0.02 0xRecipientAddress --json
+`)
     .action(async (asset: string, amount: string, recipient: string, options) => {
       try {
         const assetUpper = asset.toUpperCase();
@@ -41,24 +39,16 @@ export function createTransferCommand(): Command {
         }
 
         // Get keypair
-        const veilKey = options.veilKey || process.env.VEIL_KEY;
+        const 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');
+          throw new CLIError(ErrorCode.VEIL_KEY_MISSING, 'VEIL_KEY required. Set VEIL_KEY env');
         }
 
         const senderKeypair = new Keypair(veilKey);
-        const rpcUrl = options.rpcUrl || process.env.RPC_URL;
+        const rpcUrl = process.env.RPC_URL;
         const pool = assetUpper.toLowerCase() as RelayPool;
-
-        // Progress callback
-        const onProgress = options.quiet
-          ? undefined
-          : (stage: string, detail?: string) => {
-              const msg = detail ? `${stage}: ${detail}` : stage;
-              progress(msg, options.quiet);
-            };
-
-        progress(`Starting ${assetUpper} transfer...`, options.quiet);
+        const onProgress = createProgressReporter();
+        onProgress(`Starting ${assetUpper} transfer...`);
 
         // Execute transfer
         const result = await transfer({
@@ -70,11 +60,9 @@ export function createTransferCommand(): Command {
           onProgress,
         });
 
-        // Clear progress line
-        progress('', options.quiet);
+        clearProgress();
 
-        // Output result
-        console.log(JSON.stringify({
+        const output = {
           success: result.success,
           transactionHash: result.transactionHash,
           blockNumber: result.blockNumber,
@@ -82,10 +70,24 @@ export function createTransferCommand(): Command {
           amount: result.amount,
           recipient: result.recipient,
           type: 'transfer',
-        }, null, 2));
-        process.exit(0);
+        };
+
+        if (options.json) {
+          printJson(output);
+          return;
+        }
+
+        printHeader('Transfer Submitted');
+        printFields([
+          { label: 'Asset', value: assetUpper },
+          { label: 'Amount', value: result.amount },
+          { label: 'Recipient', value: result.recipient },
+          { label: 'Transaction', value: txUrl(result.transactionHash) },
+          { label: 'Block', value: result.blockNumber },
+        ]);
+        printLine();
       } catch (error) {
-        progress('', options.quiet);
+        clearProgress();
         handleCLIError(error);
       }
     });
@@ -98,9 +100,13 @@ export function createMergeCommand(): Command {
     .description('Merge UTXOs by self-transfer (consolidate small UTXOs)')
     .argument('<asset>', 'Asset to merge (ETH or USDC)')
     .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')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', `
+Examples:
+  veil merge ETH 0.1
+  veil merge USDC 100
+  veil merge ETH 0.1 --json
+`)
     .action(async (asset: string, amount: string, options) => {
       try {
         const assetUpper = asset.toUpperCase();
@@ -111,24 +117,16 @@ export function createMergeCommand(): Command {
         }
 
         // Get keypair
-        const veilKey = options.veilKey || process.env.VEIL_KEY;
+        const 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');
+          throw new CLIError(ErrorCode.VEIL_KEY_MISSING, 'VEIL_KEY required. Set VEIL_KEY env');
         }
 
         const keypair = new Keypair(veilKey);
-        const rpcUrl = options.rpcUrl || process.env.RPC_URL;
+        const rpcUrl = process.env.RPC_URL;
         const pool = assetUpper.toLowerCase() as RelayPool;
-
-        // Progress callback
-        const onProgress = options.quiet
-          ? undefined
-          : (stage: string, detail?: string) => {
-              const msg = detail ? `${stage}: ${detail}` : stage;
-              progress(msg, options.quiet);
-            };
-
-        progress(`Starting ${assetUpper} merge (self-transfer)...`, options.quiet);
+        const onProgress = createProgressReporter();
+        onProgress(`Starting ${assetUpper} merge (self-transfer)...`);
 
         // Execute merge
         const result = await mergeUtxos({
@@ -139,21 +137,32 @@ export function createMergeCommand(): Command {
           onProgress,
         });
 
-        // Clear progress line
-        progress('', options.quiet);
+        clearProgress();
 
-        // Output result
-        console.log(JSON.stringify({
+        const output = {
           success: result.success,
           transactionHash: result.transactionHash,
           blockNumber: result.blockNumber,
           asset: assetUpper,
           amount: result.amount,
           type: 'merge',
-        }, null, 2));
-        process.exit(0);
+        };
+
+        if (options.json) {
+          printJson(output);
+          return;
+        }
+
+        printHeader('Merge Submitted');
+        printFields([
+          { label: 'Asset', value: assetUpper },
+          { label: 'Amount', value: result.amount },
+          { label: 'Transaction', value: txUrl(result.transactionHash) },
+          { label: 'Block', value: result.blockNumber },
+        ]);
+        printLine();
       } catch (error) {
-        progress('', options.quiet);
+        clearProgress();
         handleCLIError(error);
       }
     });

package/src/cli/commands/withdraw.ts

@@ -6,26 +6,24 @@ import { Command } from 'commander';
 import { Keypair } from '../../keypair.js';
 import { withdraw } from '../../withdraw.js';
 import { handleCLIError, CLIError, ErrorCode } from '../errors.js';
+import { clearProgress, createProgressReporter, printFields, printHeader, printJson, printLine, txUrl } from '../output.js';
 import type { RelayPool } from '../../types.js';
 
 const SUPPORTED_ASSETS = ['ETH', 'USDC'];
 
-// 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('<asset>', 'Asset to withdraw (ETH or USDC)')
     .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')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', `
+Examples:
+  veil withdraw ETH 0.05 0xRecipientAddress
+  veil withdraw USDC 50 0xRecipientAddress
+  veil withdraw ETH 0.05 0xRecipientAddress --json
+`)
     .action(async (asset: string, amount: string, recipient: string, options) => {
       try {
         const assetUpper = asset.toUpperCase();
@@ -41,24 +39,16 @@ export function createWithdrawCommand(): Command {
         }
 
         // Get keypair
-        const veilKey = options.veilKey || process.env.VEIL_KEY;
+        const 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');
+          throw new CLIError(ErrorCode.VEIL_KEY_MISSING, 'VEIL_KEY required. Set VEIL_KEY env');
         }
 
         const keypair = new Keypair(veilKey);
-        const rpcUrl = options.rpcUrl || process.env.RPC_URL;
+        const rpcUrl = process.env.RPC_URL;
         const pool = assetUpper.toLowerCase() as RelayPool;
-
-        // Progress callback
-        const onProgress = options.quiet
-          ? undefined
-          : (stage: string, detail?: string) => {
-              const msg = detail ? `${stage}: ${detail}` : stage;
-              progress(msg, options.quiet);
-            };
-
-        progress(`Starting ${assetUpper} withdrawal...`, options.quiet);
+        const onProgress = createProgressReporter();
+        onProgress(`Starting ${assetUpper} withdrawal...`);
 
         // Execute withdrawal
         const result = await withdraw({
@@ -70,21 +60,33 @@ export function createWithdrawCommand(): Command {
           onProgress,
         });
 
-        // Clear progress line
-        progress('', options.quiet);
+        clearProgress();
 
-        // Output result
-        console.log(JSON.stringify({
+        const output = {
           success: result.success,
           transactionHash: result.transactionHash,
           blockNumber: result.blockNumber,
           asset: assetUpper,
           amount: result.amount,
           recipient: result.recipient,
-        }, null, 2));
-        process.exit(0);
+        };
+
+        if (options.json) {
+          printJson(output);
+          return;
+        }
+
+        printHeader('Withdrawal Submitted');
+        printFields([
+          { label: 'Asset', value: assetUpper },
+          { label: 'Amount', value: result.amount },
+          { label: 'Recipient', value: result.recipient },
+          { label: 'Transaction', value: txUrl(result.transactionHash) },
+          { label: 'Block', value: result.blockNumber },
+        ]);
+        printLine();
       } catch (error) {
-        progress('', options.quiet);
+        clearProgress();
         handleCLIError(error);
       }
     });

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);
+}