@veil-cash/sdk 0.3.0 → 0.5.0

package/src/cli/commands/status.ts

@@ -3,13 +3,28 @@
  */
 
 import { Command } from 'commander';
-import { isRegistered, getAddress } from '../wallet.js';
+import { isRegistered, getAddress, getWalletBalances } from '../wallet.js';
+import { resolveAddress } from '../config.js';
 import { checkRelayHealth } from '../../relay.js';
+import { handleCLIError } from '../errors.js';
+import { maskValue, printFields, printHeader, printJson, printSection } from '../output.js';
 
 interface StatusResult {
   walletKey: {
     found: boolean;
     address?: string;
+    valid?: boolean;
+    ethBalance?: string;
+    error?: string;
+  };
+  signerAddress: {
+    found: boolean;
+    address?: string;
+    valid?: boolean;
+  };
+  resolvedAddress: {
+    address?: string;
+    source?: string;
   };
   veilKey: {
     found: boolean;
@@ -41,89 +56,200 @@ interface StatusResult {
 export function createStatusCommand(): Command {
   const status = new Command('status')
     .description('Check configuration and service status')
-    .option('--rpc-url <url>', 'RPC URL (or set RPC_URL env)')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', `
+Examples:
+  veil status
+  veil status --json
+`)
     .action(async (options) => {
-      const result: StatusResult = {
-        walletKey: { found: false },
-        veilKey: { found: false },
-        depositKey: { found: false },
-        rpcUrl: { found: false, url: 'https://mainnet.base.org' },
-        registration: { checked: false },
-        relay: { checked: false },
-      };
-
-      // Check WALLET_KEY
-      const walletKey = process.env.WALLET_KEY;
-      if (walletKey) {
-        result.walletKey.found = true;
-        try {
-          result.walletKey.address = getAddress(walletKey as `0x${string}`);
-        } catch {
-          // Invalid key format, but it was found
+      try {
+        const result: StatusResult = {
+          walletKey: { found: false },
+          signerAddress: { found: false },
+          resolvedAddress: {},
+          veilKey: { found: false },
+          depositKey: { found: false },
+          rpcUrl: { found: false, url: 'https://mainnet.base.org' },
+          registration: { checked: false },
+          relay: { checked: false },
+        };
+
+        // Check WALLET_KEY
+        const walletKey = process.env.WALLET_KEY;
+        if (walletKey) {
+          result.walletKey.found = true;
+          try {
+            result.walletKey.address = getAddress(walletKey as `0x${string}`);
+            result.walletKey.valid = true;
+          } catch {
+            result.walletKey.valid = false;
+            result.walletKey.error = 'invalid format';
+          }
         }
-      }
 
-      // Check VEIL_KEY
-      const veilKey = process.env.VEIL_KEY;
-      if (veilKey) {
-        result.veilKey.found = true;
-      }
+        // Check SIGNER_ADDRESS
+        const signerAddress = process.env.SIGNER_ADDRESS;
+        if (signerAddress) {
+          result.signerAddress.found = true;
+          if (/^0x[a-fA-F0-9]{40}$/.test(signerAddress.trim())) {
+            result.signerAddress.valid = true;
+            result.signerAddress.address = signerAddress.trim();
+          } else {
+            result.signerAddress.valid = false;
+          }
+        }
 
-      // Check DEPOSIT_KEY
-      const depositKey = process.env.DEPOSIT_KEY;
-      if (depositKey) {
-        result.depositKey.found = true;
-        // Show truncated key
-        if (depositKey.length > 20) {
-          result.depositKey.key = `${depositKey.slice(0, 10)}...${depositKey.slice(-8)}`;
-        } else {
-          result.depositKey.key = depositKey;
+        // Check VEIL_KEY
+        const veilKey = process.env.VEIL_KEY;
+        if (veilKey) {
+          result.veilKey.found = true;
         }
-      }
 
-      // Check RPC_URL
-      const rpcUrl = options.rpcUrl || process.env.RPC_URL;
-      if (rpcUrl) {
-        result.rpcUrl.found = true;
-        result.rpcUrl.url = rpcUrl;
-      }
-      const effectiveRpcUrl = rpcUrl || 'https://mainnet.base.org';
+        // Check DEPOSIT_KEY
+        const depositKey = process.env.DEPOSIT_KEY;
+        if (depositKey) {
+          result.depositKey.found = true;
+          if (depositKey.length > 20) {
+            result.depositKey.key = `${depositKey.slice(0, 10)}...${depositKey.slice(-8)}`;
+          } else {
+            result.depositKey.key = depositKey;
+          }
+        }
 
-      // Check registration status (requires wallet address)
-      if (result.walletKey.found && result.walletKey.address) {
-        result.registration.checked = true;
-        try {
-          const regStatus = await isRegistered(
-            result.walletKey.address as `0x${string}`,
-            effectiveRpcUrl
-          );
-          result.registration.registered = regStatus.registered;
-          result.registration.onChainKey = regStatus.depositKey;
-
-          // Check if on-chain key matches env DEPOSIT_KEY
-          if (regStatus.registered && depositKey && regStatus.depositKey) {
-            result.registration.matches = 
-              regStatus.depositKey.toLowerCase() === depositKey.toLowerCase();
+        // Check RPC_URL
+        const rpcUrl = process.env.RPC_URL;
+        if (rpcUrl) {
+          result.rpcUrl.found = true;
+          result.rpcUrl.url = rpcUrl;
+        }
+        const effectiveRpcUrl = rpcUrl || 'https://mainnet.base.org';
+
+        const resolvedAddress = resolveAddress({}, { required: false, allowInvalidWalletKey: true });
+        if (resolvedAddress) {
+          result.resolvedAddress.address = resolvedAddress.address;
+          result.resolvedAddress.source =
+            resolvedAddress.source === 'wallet-key'
+              ? 'WALLET_KEY'
+              : resolvedAddress.source === 'signer-address'
+                ? 'SIGNER_ADDRESS'
+                : '--address';
+
+          try {
+            const walletBalances = await getWalletBalances(
+              resolvedAddress.address,
+              effectiveRpcUrl
+            );
+            result.walletKey.ethBalance = walletBalances.eth;
+          } catch {
+            // Ignore wallet balance lookup errors so status can still report config/registration
+          }
+
+          result.registration.checked = true;
+          try {
+            const regStatus = await isRegistered(
+              resolvedAddress.address,
+              effectiveRpcUrl
+            );
+            result.registration.registered = regStatus.registered;
+            result.registration.onChainKey = regStatus.depositKey;
+
+            if (regStatus.registered && depositKey && regStatus.depositKey) {
+              result.registration.matches =
+                regStatus.depositKey.toLowerCase() === depositKey.toLowerCase();
+            }
+          } catch (error) {
+            result.registration.error = error instanceof Error ? error.message : 'Unknown error';
           }
+        }
+
+        // Check relay health
+        const relayUrl = process.env.RELAY_URL;
+        result.relay.checked = true;
+        try {
+          const health = await checkRelayHealth(relayUrl);
+          result.relay.healthy = health.status === 'ok';
+          result.relay.status = health.status;
+          result.relay.network = health.network;
         } catch (error) {
-          result.registration.error = error instanceof Error ? error.message : 'Unknown error';
+          result.relay.healthy = false;
+          result.relay.error = error instanceof Error ? error.message : 'Unknown error';
         }
-      }
 
-      // Check relay health
-      result.relay.checked = true;
-      try {
-        const health = await checkRelayHealth();
-        result.relay.healthy = health.status === 'ok';
-        result.relay.status = health.status;
-        result.relay.network = health.network;
+        if (options.json) {
+          printJson(result);
+          return;
+        }
+
+        const signingValue = result.signerAddress.found
+          ? result.signerAddress.valid === false
+            ? 'external (SIGNER_ADDRESS invalid)'
+            : 'external (SIGNER_ADDRESS)'
+          : result.walletKey.found
+            ? result.walletKey.valid === false
+              ? 'local (WALLET_KEY invalid)'
+              : 'local (WALLET_KEY)'
+            : 'not configured';
+
+        printHeader('Veil CLI Status');
+        printSection('Configuration');
+        printFields([
+          { label: 'Signing', value: signingValue },
+          { label: 'Address', value: result.resolvedAddress.address || 'n/a' },
+          { label: 'ETH balance', value: result.walletKey.ethBalance ? `${result.walletKey.ethBalance} ETH` : 'n/a' },
+          { label: 'Veil key', value: result.veilKey.found ? 'configured' : 'missing' },
+          { label: 'Deposit key', value: result.depositKey.found ? maskValue(result.depositKey.key || '') : 'missing' },
+          { label: 'RPC URL', value: maskUrl(result.rpcUrl.url) },
+        ]);
+
+        printSection('Registration');
+        if (!result.registration.checked) {
+          printFields([
+            {
+              label: 'Status',
+              value: result.walletKey.found && result.walletKey.valid === false
+                ? 'skipped (invalid WALLET_KEY)'
+                : 'skipped (no WALLET_KEY or SIGNER_ADDRESS)'
+            },
+          ]);
+        } else if (result.registration.error) {
+          printFields([
+            { label: 'Error', value: result.registration.error },
+          ]);
+        } else {
+          printFields([
+            { label: 'Registered', value: result.registration.registered },
+            { label: 'Keys match', value: result.registration.matches ?? 'n/a' },
+            { label: 'On-chain key', value: result.registration.onChainKey ? maskValue(result.registration.onChainKey) : 'n/a' },
+          ]);
+        }
+
+        printSection('Relay');
+        if (result.relay.error) {
+          printFields([
+            { label: 'Healthy', value: false },
+            { label: 'Error', value: result.relay.error },
+          ]);
+        } else {
+          printFields([
+            { label: 'Healthy', value: result.relay.healthy },
+            { label: 'Status', value: result.relay.status || 'n/a' },
+            { label: 'Network', value: result.relay.network || 'n/a' },
+          ]);
+        }
       } catch (error) {
-        result.relay.healthy = false;
-        result.relay.error = error instanceof Error ? error.message : 'Unknown error';
+        handleCLIError(error);
       }
-
-      console.log(JSON.stringify(result, null, 2));
     });
 
   return status;
 }
+
+function maskUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return parsed.origin;
+  } catch {
+    return maskValue(url);
+  }
+}

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', 'CBBTC'];
-
-// 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}`);
-  }
-}
+const SUPPORTED_ASSETS = ['ETH', 'USDC'];
 
 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, USDC, or CBBTC)')
+    .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);
       }
     });
@@ -96,11 +98,15 @@ export function createTransferCommand(): Command {
 export function createMergeCommand(): Command {
   const mergeCmd = new Command('merge')
     .description('Merge UTXOs by self-transfer (consolidate small UTXOs)')
-    .argument('<asset>', 'Asset to merge (ETH, USDC, or CBBTC)')
+    .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', 'CBBTC'];
-
-// 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}`);
-  }
-}
+const SUPPORTED_ASSETS = ['ETH', 'USDC'];
 
 export function createWithdrawCommand(): Command {
   const withdrawCmd = new Command('withdraw')
     .description('Withdraw from private pool to a public address')
-    .argument('<asset>', 'Asset to withdraw (ETH, USDC, or CBBTC)')
+    .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);
       }
     });