@veil-cash/sdk 0.3.0 → 0.5.0

package/skills/veil/reference.md

@@ -0,0 +1,231 @@
+# Veil SDK Reference
+
+Detailed payload spec and SDK function signatures for agent integration.
+
+## Unsigned payload spec
+
+All `--unsigned` CLI output and programmatic builders target **Base mainnet** (chain ID 8453).
+
+### Payload shape
+
+```json
+{
+  "to": "0x...",
+  "data": "0x...",
+  "value": "0",
+  "chainId": 8453
+}
+```
+
+### Field reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `to` | `string` | yes | Target contract address (`0x` + 40 hex chars) |
+| `data` | `string` | yes | ABI-encoded calldata (`0x` + hex) |
+| `value` | `string` | yes | ETH amount in wei as a **string** (e.g. `"0"`, `"1000000000000000000"` for 1 ETH) |
+| `chainId` | `number` | yes | `8453` (Base) |
+
+`value` must always be a string. For register and USDC transactions it is `"0"`.
+For ETH deposits it equals the deposit amount in wei.
+
+### CLI extra fields
+
+The CLI may include an `action` or `step` field for context:
+
+- **Register**: `"action": "register"` or `"action": "changeDepositKey"`
+- **Deposit**: `"step": "approve"` (USDC only) and `"step": "deposit"`
+
+These fields are informational and can be ignored by the signer.
+For `veil register --unsigned --force`, the CLI checks chain state first and chooses `"register"` vs `"changeDepositKey"` based on whether the address is already registered.
+
+---
+
+## SDK build functions
+
+All functions are exported from `@veil-cash/sdk`.
+
+### Keypair
+
+```typescript
+import { Keypair, VEIL_SIGNED_MESSAGE } from '@veil-cash/sdk';
+import type { MessageSigner } from '@veil-cash/sdk';
+
+// Random keypair
+const keypair = new Keypair();
+
+// Restore from saved private key
+const restored = new Keypair('0xSAVED_VEIL_KEY');
+
+// Derive from Ethereum wallet key (same keypair as frontend login)
+const derived = await Keypair.fromWalletKey('0xWALLET_KEY');
+
+// Derive from pre-computed EIP-191 signature
+const fromSig = Keypair.fromSignature('0xSIG');
+
+// Derive via external signer callback
+const fromSigner = await Keypair.fromSigner(async (msg) => {
+  return await externalSignerService.personalSign(msg);
+});
+
+// Public deposit key (register on-chain)
+keypair.depositKey(); // 0x-prefixed, 130 hex chars
+
+// Private key (store securely)
+keypair.privkey; // 0x-prefixed, 66 hex chars
+```
+
+### Register
+
+```typescript
+import { buildRegisterTx, buildChangeDepositKeyTx } from '@veil-cash/sdk';
+import type { TransactionData } from '@veil-cash/sdk';
+
+// First-time registration
+const tx: TransactionData = buildRegisterTx(depositKey, '0xSIGNER_ADDRESS');
+// tx = { to: '0x...', data: '0x...' }
+
+// Update existing deposit key
+const changeTx: TransactionData = buildChangeDepositKeyTx(newDepositKey, '0xSIGNER_ADDRESS');
+```
+
+`TransactionData` type:
+
+```typescript
+interface TransactionData {
+  to: `0x${string}`;
+  data: `0x${string}`;
+  value?: bigint;
+}
+```
+
+For register transactions `value` is `undefined` (use `"0"` when forwarding to signer).
+
+### Deposit
+
+```typescript
+import {
+  buildDepositETHTx,
+  buildDepositUSDCTx,
+  buildApproveUSDCTx,
+  buildDepositTx,
+} from '@veil-cash/sdk';
+
+// ETH deposit
+const ethTx = buildDepositETHTx({ depositKey, amount: '0.1' });
+// ethTx.value = 100000000000000000n (bigint)
+
+// USDC deposit (two-step)
+const approveTx = buildApproveUSDCTx({ amount: '100' });
+const usdcTx = buildDepositUSDCTx({ depositKey, amount: '100' });
+
+// Generic (routes to ETH or USDC builder)
+const tx = buildDepositTx({ depositKey, amount: '0.1', token: 'ETH' });
+```
+
+When serializing for a signer: `value` must be converted to a string (`tx.value?.toString() ?? '0'`).
+
+### Balance
+
+```typescript
+import { getQueueBalance, getPrivateBalance } from '@veil-cash/sdk';
+
+// Queue balance (pending deposits)
+const queue = await getQueueBalance({
+  address: '0x...',
+  pool: 'eth',
+});
+
+// Private balance (in-pool UTXOs)
+const priv = await getPrivateBalance({
+  keypair,
+  pool: 'eth',
+});
+```
+
+---
+
+## CLI quick reference
+
+Install globally: `npm install -g @veil-cash/sdk`
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `VEIL_KEY` | Veil private key (for ZK proofs) |
+| `DEPOSIT_KEY` | Veil deposit key (public) |
+| `WALLET_KEY` | Ethereum wallet private key (for signing) |
+| `SIGNER_ADDRESS` | Ethereum address for unsigned/query flows when signing is external |
+| `RPC_URL` | Base RPC URL (optional, defaults to public RPC) |
+| `RELAY_URL` | Override relay base URL for relayed CLI operations |
+
+`WALLET_KEY` and `SIGNER_ADDRESS` are mutually exclusive. Use `SIGNER_ADDRESS` only for address-only CLI flows.
+
+### Commands
+
+```bash
+veil init                                          # Derive keypair from WALLET_KEY (saves to .env.veil)
+veil init --generate                               # Generate random keypair
+veil init --signature 0x...                        # Derive from pre-computed EIP-191 signature
+veil init --force                                  # Overwrite existing keypair without prompting
+veil init --no-save                                # Print keypair without saving to disk
+veil init --json                                   # Output keypair as JSON (no prompts, no file save)
+
+veil keypair                                       # Show current keypair (from VEIL_KEY)
+veil keypair --json                                # Show current keypair as JSON
+
+veil status                                        # Check config, signing mode, registration, and relay health
+veil status --json                                 # Machine-readable status
+
+SIGNER_ADDRESS=0x... veil register --unsigned       # Unsigned register payload
+SIGNER_ADDRESS=0x... veil register --unsigned --force # Unsigned register/change-key payload (depends on chain state)
+veil register --unsigned --address 0x...           # Unsigned register payload (explicit address)
+veil register --json                               # Register and output result as JSON
+
+veil deposit ETH 0.1 --unsigned                    # Unsigned ETH deposit payload
+veil deposit USDC 100 --unsigned                   # Unsigned USDC deposit payload(s)
+veil deposit ETH 0.1 --json                        # Deposit and output result as JSON
+
+veil balance                                       # All pool balances
+veil balance --pool eth                            # ETH pool only
+veil balance --pool usdc                           # USDC pool only
+veil balance --json                                # Machine-readable balances
+veil balance queue --pool eth                      # Queue-only balance
+veil balance queue --address 0x... --json          # Queue balance for explicit address
+veil balance private --pool eth                    # Private-only balance
+veil balance private --json                        # Private balance as JSON
+```
+
+### Error format
+
+All CLI errors output JSON with a standardized `errorCode`:
+
+```json
+{
+  "success": false,
+  "errorCode": "VEIL_KEY_MISSING",
+  "error": "VEIL_KEY required. Set VEIL_KEY env"
+}
+```
+
+Common codes: `VEIL_KEY_MISSING`, `WALLET_KEY_MISSING`, `DEPOSIT_KEY_MISSING`,
+`CONFIG_CONFLICT`, `INVALID_AMOUNT`, `INSUFFICIENT_BALANCE`, `CONTRACT_ERROR`, `RPC_ERROR`.
+
+---
+
+## Deposit minimums
+
+| Asset | Minimum (net) | Notes |
+|-------|--------------|-------|
+| ETH | 0.01 | Fee (0.3%) added automatically via on-chain `getDepositAmountWithFee` |
+| USDC | 10 | Fee (0.3%) added automatically via on-chain `getDepositAmountWithFee` |
+
+The CLI amount is the **net** amount that lands in the pool. The fee is calculated on-chain and added to the transaction automatically — users do not need to account for it.
+
+---
+
+## Links
+
+- npm: [@veil-cash/sdk](https://www.npmjs.com/package/@veil-cash/sdk)
+- Veil Cash: [https://veil.cash](https://veil.cash)

package/src/abi.ts

@@ -101,18 +101,6 @@ export const ENTRY_ABI = [
     type: 'function',
   },
 
-  // Queue cbBTC deposit
-  {
-    inputs: [
-      { name: '_amount', type: 'uint256' },
-      { name: '_depositKey', type: 'bytes' },
-    ],
-    name: 'queueBTC',
-    outputs: [],
-    stateMutability: 'nonpayable',
-    type: 'function',
-  },
-
   // Read deposit keys
   {
     inputs: [{ name: '', type: 'address' }],

package/src/addresses.ts

@@ -14,9 +14,6 @@ export const ADDRESSES: NetworkAddresses = {
   usdcPool: '0x5c50d58E49C59d112680c187De2Bf989d2a91242',
   usdcQueue: '0x5530241b24504bF05C9a22e95A1F5458888e6a9B',
   usdcToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
-  cbbtcPool: '0x51A021da774b4bBB59B47f7CB4ccd631337680BA',
-  cbbtcQueue: '0x977741CaDF8D1431c4816C0993D32b02094cD35C',
-  cbbtcToken: '0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf',
   chainId: 8453,
   relayUrl: 'https://veil-relay.up.railway.app',
 } as const;
@@ -37,12 +34,6 @@ export const POOL_CONFIG = {
     symbol: 'USDC',
     name: 'USD Coin',
   },
-  cbbtc: {
-    decimals: 8,
-    displayDecimals: 6,
-    symbol: 'cbBTC',
-    name: 'Coinbase Bitcoin',
-  },
 } as const;
 
 /**
@@ -55,30 +46,32 @@ export function getAddresses(): NetworkAddresses {
 
 /**
  * Get the pool contract address for a given pool
- * @param pool - Pool identifier ('eth', 'usdc', or 'cbbtc')
+ * @param pool - Pool identifier ('eth' or 'usdc')
  * @returns Pool contract address
  */
-export function getPoolAddress(pool: RelayPool): `0x${string}` {
+export function getPoolAddress(
+  pool: RelayPool
+): `0x${string}` {
   const addresses = getAddresses();
   switch (pool) {
     case 'eth': return addresses.ethPool;
     case 'usdc': return addresses.usdcPool;
-    case 'cbbtc': return addresses.cbbtcPool;
     default: throw new Error(`Unknown pool: ${pool}`);
   }
 }
 
 /**
  * Get the queue contract address for a given pool
- * @param pool - Pool identifier ('eth', 'usdc', or 'cbbtc')
+ * @param pool - Pool identifier ('eth' or 'usdc')
  * @returns Queue contract address
  */
-export function getQueueAddress(pool: RelayPool): `0x${string}` {
+export function getQueueAddress(
+  pool: RelayPool
+): `0x${string}` {
   const addresses = getAddresses();
   switch (pool) {
     case 'eth': return addresses.ethQueue;
     case 'usdc': return addresses.usdcQueue;
-    case 'cbbtc': return addresses.cbbtcQueue;
     default: throw new Error(`Unknown pool: ${pool}`);
   }
 }

package/src/balance.ts

@@ -101,14 +101,14 @@ export async function getQueueBalance(options: {
       depositKey: `0x${string}`;
     };
 
-    // Check if this deposit belongs to the user
+    // Report the net shielded amount so queue totals match what will land in private balance.
     if (deposit.fallbackReceiver.toLowerCase() === address.toLowerCase()) {
-      totalQueueBalance += deposit.amountIn;
+      totalQueueBalance += deposit.shieldAmount;
       pendingDeposits.push({
         nonce: nonce.toString(),
         status: DEPOSIT_STATUS_MAP[deposit.status as keyof typeof DEPOSIT_STATUS_MAP] || 'pending',
-        amount: formatUnits(deposit.amountIn, poolConfig.decimals),
-        amountWei: deposit.amountIn.toString(),
+        amount: formatUnits(deposit.shieldAmount, poolConfig.decimals),
+        amountWei: deposit.shieldAmount.toString(),
         timestamp: new Date(Number(deposit.timestamp) * 1000).toISOString(),
       });
     }

package/src/cli/commands/balance.ts

@@ -6,12 +6,16 @@ import { Command } from 'commander';
 import { getQueueBalance, getPrivateBalance } from '../../balance.js';
 import { POOL_CONFIG } from '../../addresses.js';
 import { Keypair } from '../../keypair.js';
-import { getAddress } from '../wallet.js';
+import { getWalletBalances } from '../wallet.js';
+import { resolveAddress } from '../config.js';
 import { formatUnits } from 'viem';
 import { handleCLIError, CLIError, ErrorCode } from '../errors.js';
+import { clearProgress, createProgressReporter, maskValue, printFields, printHeader, printJson, printLine, printList, printSection } from '../output.js';
+import { createPrivateBalanceCommand } from './private-balance.js';
+import { createQueueBalanceCommand } from './queue-balance.js';
 import type { RelayPool } from '../../types.js';
 
-const SUPPORTED_POOLS: RelayPool[] = ['eth', 'usdc', 'cbbtc'];
+const SUPPORTED_POOLS: RelayPool[] = ['eth', 'usdc'];
 
 /**
  * Fetch balance for a single pool and return structured output
@@ -88,12 +92,16 @@ async function fetchPoolBalance(
 export function createBalanceCommand(): Command {
   const balance = new Command('balance')
     .description('Show queue and private balances (all pools by default)')
-    .option('--pool <pool>', 'Pool to check (eth, usdc, cbbtc, or all)', 'all')
-    .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')
+    .option('--pool <pool>', 'Pool to check (eth, usdc, or all)', 'all')
+    .option('--address <address>', 'Address to check (or derived from WALLET_KEY / SIGNER_ADDRESS)')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', `
+Examples:
+  veil balance
+  veil balance --pool eth
+  veil balance queue --pool usdc
+  veil balance --json
+`)
     .action(async (options) => {
       try {
         const poolArg = (options.pool || 'all').toLowerCase();
@@ -106,73 +114,153 @@ export function createBalanceCommand(): Command {
         const poolsToQuery: RelayPool[] = poolArg === 'all' ? [...SUPPORTED_POOLS] : [poolArg as RelayPool];
 
         // 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}`);
+        const resolvedAddress = resolveAddress({ address: options.address }, { required: true });
+        if (!resolvedAddress) {
+          throw new CLIError(
+            ErrorCode.WALLET_KEY_MISSING,
+            'Must provide --address, set SIGNER_ADDRESS, or set WALLET_KEY env.',
+          );
         }
+        const address = resolvedAddress.address;
 
         // Get keypair for private balance
-        const veilKey = options.veilKey || process.env.VEIL_KEY;
+        const veilKey = process.env.VEIL_KEY;
         const keypair = veilKey ? new Keypair(veilKey) : null;
 
-        const rpcUrl = options.rpcUrl || process.env.RPC_URL;
+        const 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}`);
-            };
+        const onProgress = createProgressReporter();
 
         // Get deposit key if available
         const depositKey = process.env.DEPOSIT_KEY || (keypair ? keypair.depositKey() : null);
 
         // Single pool mode -- flat output (backwards compatible)
         if (poolsToQuery.length === 1) {
-          const poolResult = await fetchPoolBalance(poolsToQuery[0], address, keypair, rpcUrl, onProgress);
+          const [poolResult, walletBalances] = await Promise.all([
+            fetchPoolBalance(poolsToQuery[0], address, keypair, rpcUrl, onProgress),
+            getWalletBalances(address, rpcUrl),
+          ]);
 
-          // Clear progress line
-          if (!options.quiet) process.stderr.write('\r\x1b[K');
+          clearProgress();
 
           const output = {
             address,
             depositKey: depositKey || null,
+            wallet: walletBalances,
             ...poolResult,
           };
 
-          console.log(JSON.stringify(output, null, 2));
+          if (options.json) {
+            printJson(output);
+            return;
+          }
+
+          printCombinedBalanceHuman(output);
           return;
         }
 
         // All pools mode -- nested output
-        const pools: Record<string, unknown>[] = [];
-        for (const pool of poolsToQuery) {
-          const poolResult = await fetchPoolBalance(pool, address, keypair, rpcUrl, onProgress);
-          pools.push(poolResult);
-        }
+        const poolPromises = poolsToQuery.map(pool =>
+          fetchPoolBalance(pool, address, keypair, rpcUrl, onProgress),
+        );
+        const [walletBalances, ...poolResults] = await Promise.all([
+          getWalletBalances(address, rpcUrl),
+          ...poolPromises,
+        ]);
 
-        // Clear progress line
-        if (!options.quiet) process.stderr.write('\r\x1b[K');
+        clearProgress();
 
         const output = {
           address,
           depositKey: depositKey || null,
-          pools,
+          wallet: walletBalances,
+          pools: poolResults,
         };
 
-        console.log(JSON.stringify(output, null, 2));
+        if (options.json) {
+          printJson(output);
+          return;
+        }
+
+        printMultiPoolBalanceHuman(output);
       } catch (error) {
-        process.stderr.write('\r\x1b[K');
+        clearProgress();
         handleCLIError(error);
       }
     });
 
+  balance.addCommand(createQueueBalanceCommand('queue'));
+  balance.addCommand(createPrivateBalanceCommand('private'));
+
   return balance;
 }
+
+function printPoolHuman(output: Record<string, unknown>): void {
+  const symbol = output.symbol as string;
+
+  printSection(`${output.pool}`);
+  printFields([
+    { label: 'Total', value: `${output.totalBalance} ${symbol}` },
+  ]);
+
+  const privateData = output.private as { balance?: string | null; balanceWei?: string; utxoCount?: number; note?: string; utxos?: Array<{ index: number; amount: string }> };
+  if (privateData.note) {
+    printFields([
+      { label: 'Private', value: privateData.note },
+    ]);
+  } else {
+    printFields([
+      { label: 'Private', value: `${privateData.balance} ${symbol}` },
+    ]);
+  }
+
+  const queueData = output.queue as { balance: string; balanceWei: string; count: number; deposits: Array<{ nonce: string | number; amount: string; status: string }> };
+  printFields([
+    { label: 'Queue', value: `${queueData.balance} ${symbol}` },
+    { label: 'Pending', value: queueData.count },
+  ]);
+  if (queueData.deposits.length > 0) {
+    printList(
+      queueData.deposits.map((d) => `nonce ${d.nonce}: ${d.amount} (${d.status})`)
+    );
+  }
+}
+
+function printCombinedBalanceHuman(output: Record<string, unknown>): void {
+  const wallet = output.wallet as { eth: string; usdc: string };
+
+  printHeader(`${output.pool} Balance`);
+  printFields([
+    { label: 'Address', value: output.address },
+    { label: 'Deposit key', value: typeof output.depositKey === 'string' ? maskValue(output.depositKey) : 'not set' },
+  ]);
+
+  printSection('Wallet (public)');
+  printFields([
+    { label: 'ETH', value: `${wallet.eth} ETH` },
+    { label: 'USDC', value: `${wallet.usdc} USDC` },
+  ]);
+
+  printPoolHuman(output);
+  printLine();
+}
+
+function printMultiPoolBalanceHuman(output: { address: string; depositKey: string | null; wallet: { eth: string; usdc: string }; pools: Record<string, unknown>[] }): void {
+  printHeader('Balances');
+  printFields([
+    { label: 'Address', value: output.address },
+    { label: 'Deposit key', value: output.depositKey ? maskValue(output.depositKey) : 'not set' },
+  ]);
+
+  printSection('Wallet (public)');
+  printFields([
+    { label: 'ETH', value: `${output.wallet.eth} ETH` },
+    { label: 'USDC', value: `${output.wallet.usdc} USDC` },
+  ]);
+
+  for (const poolResult of output.pools) {
+    printPoolHuman(poolResult);
+  }
+
+  printLine();
+}