@veil-cash/sdk 0.1.1 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@
 
 SDK and CLI for interacting with [Veil Cash](https://veil.cash) privacy pools on Base.
 
-Generate keypairs, register, deposit, withdraw, and transfer ETH privately.
+Generate keypairs, register, deposit, withdraw, transfer, and merge ETH, USDC, and cbBTC privately.
 
 ## Installation
 
@@ -23,6 +23,14 @@ For global CLI access:
 npm install -g @veil-cash/sdk
 ```
 
+## Supported Assets
+
+| Asset | Decimals | Token Contract |
+|-------|----------|---------------|
+| ETH | 18 | Native ETH (via WETH) |
+| USDC | 6 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+| cbBTC | 8 | `0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf` |
+
 ## CLI Quick Start
 
 ```bash
@@ -35,60 +43,115 @@ export WALLET_KEY=0x...
 # 3. Register your deposit key (one-time)
 veil register
 
-# 4. Deposit ETH
-veil deposit 0.1
+# 4. Check your setup
+veil status
+
+# 5. Deposit (ETH, USDC, or cbBTC)
+veil deposit ETH 0.1
+veil deposit USDC 100
+veil deposit CBBTC 0.001
 
-# 5. Check your balance
-veil balance
+# 6. Check your balance
+veil balance                  # ETH pool (default)
+veil balance --pool usdc      # USDC pool
+veil balance --pool cbbtc       # cbBTC pool
 
-# 6. Withdraw to any address
-veil withdraw 0.05 0xRecipientAddress
+# 7. Withdraw to any address
+veil withdraw ETH 0.05 0xRecipientAddress
+veil withdraw USDC 50 0xRecipientAddress
+veil withdraw CBBTC 0.0005 0xRecipientAddress
 
-# 7. Transfer privately to another registered user
-veil transfer 0.02 0xRecipientAddress
+# 8. Transfer privately to another registered user
+veil transfer ETH 0.02 0xRecipientAddress
+
+# 9. Merge small UTXOs (consolidate balances)
+veil merge ETH 0.1
 ```
 
 ## CLI Commands
 
 ### `veil init`
 
-Generate a new Veil keypair.
+Generate or derive a Veil keypair.
 
 ```bash
-veil init              # Interactive, saves to .env.veil
-veil init --force      # Overwrite existing without prompting
-veil init --json       # Output as JSON (no prompts, no file save)
-veil init --out path   # Save to custom path
-veil init --no-save    # Print keypair without saving
+veil init                                  # Random keypair, saves to .env.veil
+veil init --force                          # Overwrite existing without prompting
+veil init --json                           # Output as JSON (no prompts, no file save)
+veil init --no-save                        # Print keypair without saving
+
+# Derive from wallet (same keypair as frontend login)
+veil init --sign-message --wallet-key 0x...
+
+# Derive from a pre-computed EIP-191 signature (from Bankr, MPC, etc.)
+veil init --signature 0x...
 ```
 
 ### `veil keypair`
 
-Generate and show a new keypair as JSON (does not save).
+Show current Veil keypair as JSON (from VEIL_KEY env).
 
 ```bash
 veil keypair
 # {"veilPrivateKey":"0x...","depositKey":"0x..."}
 ```
 
+### `veil status`
+
+Check configuration and service status.
+
+```bash
+veil status
+```
+
+Output:
+```json
+{
+  "walletKey": { "found": true, "address": "0x..." },
+  "veilKey": { "found": true },
+  "depositKey": { "found": true, "key": "0x1234...abcd" },
+  "rpcUrl": { "found": false, "url": "https://mainnet.base.org" },
+  "registration": {
+    "checked": true,
+    "registered": true,
+    "matches": true,
+    "onChainKey": "0x..."
+  },
+  "relay": {
+    "checked": true,
+    "healthy": true,
+    "status": "ok",
+    "network": "mainnet"
+  }
+}
+```
+
 ### `veil register`
 
-Register your deposit key on-chain (one-time per address).
+Register or update your deposit key on-chain.
 
 ```bash
-veil register                              # Signs & sends
+veil register                              # Register (first time)
 veil register --json                       # JSON output
 veil register --unsigned --address 0x...   # Unsigned payload for agents
+
+# Change deposit key (if already registered with a different key)
+veil register --force                      # Change to local deposit key
+veil register --force --unsigned           # Unsigned change payload for agents
 ```
 
-### `veil deposit <amount>`
+If already registered with the same key, the command exits successfully. If registered with a different key (e.g. after `veil init --sign-message`), use `--force` to update it on-chain.
 
-Deposit ETH into the privacy pool.
+### `veil deposit <asset> <amount>`
+
+Deposit ETH, USDC, or cbBTC into the privacy pool. For USDC and cbBTC, the CLI automatically handles ERC20 approval before depositing.
 
 ```bash
-veil deposit 0.1                    # Signs & sends (JSON output)
-veil deposit 0.1 --unsigned         # Unsigned payload for agents
-veil deposit 0.1 --quiet            # Suppress progress output
+veil deposit ETH 0.1                    # Deposit ETH
+veil deposit USDC 100                   # Approve + deposit USDC
+veil deposit CBBTC 0.001                  # Approve + deposit cbBTC
+veil deposit ETH 0.1 --unsigned         # Unsigned payload for agents
+veil deposit ETH 0.1 --quiet            # Suppress progress output
 ```
 
 Output:
@@ -96,6 +159,7 @@ Output:
 {
   "success": true,
   "hash": "0x...",
+  "asset": "ETH",
   "amount": "0.1",
   "blockNumber": "12345678",
   "gasUsed": "150000"
@@ -107,7 +171,9 @@ Output:
 Show both queue and private balances.
 
 ```bash
-veil balance                        # Show all balances
+veil balance                        # ETH pool (default)
+veil balance --pool usdc            # USDC pool
+veil balance --pool cbbtc             # cbBTC pool
 veil balance --quiet                # Suppress progress output
 ```
 
@@ -115,6 +181,8 @@ Output:
 ```json
 {
   "address": "0x...",
+  "pool": "ETH",
+  "symbol": "ETH",
   "depositKey": "0x...",
   "totalBalance": "0.15",
   "totalBalanceWei": "150000000000000000",
@@ -138,13 +206,15 @@ Output:
 }
 ```
 
-### `veil withdraw <amount> <recipient>`
+### `veil withdraw <asset> <amount> <recipient>`
 
 Withdraw from the privacy pool to any public address.
 
 ```bash
-veil withdraw 0.05 0xRecipientAddress
-veil withdraw 0.05 0xRecipientAddress --quiet
+veil withdraw ETH 0.05 0xRecipientAddress
+veil withdraw USDC 50 0xRecipientAddress
+veil withdraw CBBTC 0.0005 0xRecipientAddress
+veil withdraw ETH 0.05 0xRecipientAddress --quiet
 ```
 
 Output:
@@ -153,19 +223,21 @@ Output:
   "success": true,
   "transactionHash": "0x...",
   "blockNumber": 12345678,
+  "asset": "ETH",
   "amount": "0.05",
-  "recipient": "0x...",
-  "type": "withdraw"
+  "recipient": "0x..."
 }
 ```
 
-### `veil transfer <amount> <recipient>`
+### `veil transfer <asset> <amount> <recipient>`
 
 Transfer privately to another registered Veil user.
 
 ```bash
-veil transfer 0.02 0xRecipientAddress
-veil transfer 0.02 0xRecipientAddress --quiet
+veil transfer ETH 0.02 0xRecipientAddress
+veil transfer USDC 25 0xRecipientAddress
+veil transfer CBBTC 0.0002 0xRecipientAddress
+veil transfer ETH 0.02 0xRecipientAddress --quiet
 ```
 
 Output:
@@ -174,19 +246,34 @@ Output:
   "success": true,
   "transactionHash": "0x...",
   "blockNumber": 12345678,
+  "asset": "ETH",
   "amount": "0.02",
   "recipient": "0x...",
   "type": "transfer"
 }
 ```
 
-### `veil merge <amount>`
+### `veil merge <asset> <amount>`
 
 Consolidate multiple small UTXOs into one (self-transfer).
 
 ```bash
-veil merge 0.1                      # Merge UTXOs totaling 0.1 ETH
-veil merge 0.1 --quiet
+veil merge ETH 0.1                      # Merge ETH UTXOs totaling 0.1 ETH
+veil merge USDC 100                     # Merge USDC UTXOs
+veil merge CBBTC 0.001                    # Merge cbBTC UTXOs
+veil merge ETH 0.1 --quiet
+```
+
+Output:
+```json
+{
+  "success": true,
+  "transactionHash": "0x...",
+  "blockNumber": 12345678,
+  "asset": "ETH",
+  "amount": "0.1",
+  "type": "merge"
+}
 ```
 
 ## Environment Variables
@@ -239,7 +326,12 @@ All CLI commands output JSON with standardized error codes:
 ## SDK Quick Start
 
 ```typescript
-import { Keypair, buildRegisterTx, buildDepositETHTx, withdraw, transfer } from '@veil-cash/sdk';
+import {
+  Keypair, buildRegisterTx, buildDepositETHTx,
+  buildDepositUSDCTx, buildApproveUSDCTx,
+  buildDepositCBBTCTx, buildApproveCBBTCTx,
+  withdraw, transfer,
+} from '@veil-cash/sdk';
 import { createWalletClient, http } from 'viem';
 import { base } from 'viem/chains';
 import { privateKeyToAccount } from 'viem/accounts';
@@ -264,18 +356,34 @@ await client.sendTransaction(registerTx);
 // 4. Deposit ETH
 const depositTx = buildDepositETHTx({
   depositKey: keypair.depositKey(),
-  amount: '0.1', // 0.1 ETH
+  amount: '0.1',
+});
+await client.sendTransaction({ ...depositTx, value: depositTx.value });
+
+// 4b. Deposit USDC (approve first)
+const approveTx = buildApproveUSDCTx({ amount: '100' });
+await client.sendTransaction(approveTx);
+const usdcTx = buildDepositUSDCTx({
+  depositKey: keypair.depositKey(),
+  amount: '100',
 });
-await client.sendTransaction({
-  ...depositTx,
-  value: depositTx.value,
+await client.sendTransaction(usdcTx);
+
+// 4c. Deposit cbBTC (approve first)
+const approveCbbtcTx = buildApproveCBBTCTx({ amount: '0.001' });
+await client.sendTransaction(approveCbbtcTx);
+const cbbtcTx = buildDepositCBBTCTx({
+  depositKey: keypair.depositKey(),
+  amount: '0.001',
 });
+await client.sendTransaction(cbbtcTx);
 
 // 5. Withdraw (sent via relayer, no wallet signing needed)
 const withdrawResult = await withdraw({
   amount: '0.05',
   recipient: '0xRecipientAddress',
   keypair,
+  pool: 'eth', // 'eth' | 'usdc' | 'cbbtc' (default: 'eth')
 });
 
 // 6. Transfer privately
@@ -283,6 +391,7 @@ const transferResult = await transfer({
   amount: '0.02',
   recipientAddress: '0xRecipientAddress',
   senderKeypair: keypair,
+  pool: 'eth', // 'eth' | 'usdc' | 'cbbtc' (default: 'eth')
 });
 ```
 
@@ -291,14 +400,27 @@ const transferResult = await transfer({
 ### Keypair
 
 ```typescript
-import { Keypair } from '@veil-cash/sdk';
+import { Keypair, VEIL_SIGNED_MESSAGE } from '@veil-cash/sdk';
+import type { MessageSigner } from '@veil-cash/sdk';
 
-// Generate new keypair
+// Generate random keypair
 const keypair = new Keypair();
 
 // Restore from saved Veil private key
 const restored = new Keypair(savedVeilKey);
 
+// Derive from wallet key (same keypair as frontend login)
+const derived = await Keypair.fromWalletKey('0xYOUR_WALLET_KEY');
+
+// Derive from a raw EIP-191 signature
+const fromSig = Keypair.fromSignature('0xSIGNATURE...');
+
+// Derive from any external signer (Bankr, MPC, custodial, etc.)
+const fromSigner = await Keypair.fromSigner(async (message) => {
+  // Sign `message` using any personal_sign provider and return the signature
+  return await mySigningService.personalSign(message);
+});
+
 // Get deposit key (for registration)
 keypair.depositKey(); // '0x...' (130 hex chars)
 
@@ -309,72 +431,131 @@ keypair.privkey; // '0x...'
 ### Transaction Builders
 
 ```typescript
-import { buildRegisterTx, buildDepositETHTx } from '@veil-cash/sdk';
+import {
+  buildRegisterTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx,
+  buildDepositUSDCTx, buildApproveUSDCTx,
+  buildDepositCBBTCTx, buildApproveCBBTCTx,
+} from '@veil-cash/sdk';
 
-// Register deposit key (one-time)
+// Register deposit key (first time)
 const registerTx = buildRegisterTx(depositKey, ownerAddress);
 // → { to: '0x...', data: '0x...' }
 
+// Change deposit key (must already be registered)
+const changeTx = buildChangeDepositKeyTx(newDepositKey, ownerAddress);
+// → { to: '0x...', data: '0x...' }
+
 // Deposit ETH
 const depositTx = buildDepositETHTx({
   depositKey: keypair.depositKey(),
   amount: '0.1',
 });
 // → { to: '0x...', data: '0x...', value: 100000000000000000n }
+
+// Deposit USDC (approve + deposit)
+const approveUsdcTx = buildApproveUSDCTx({ amount: '100' });
+const depositUsdcTx = buildDepositUSDCTx({
+  depositKey: keypair.depositKey(),
+  amount: '100',
+});
+
+// Deposit cbBTC (approve + deposit)
+const approveCbbtcTx = buildApproveCBBTCTx({ amount: '0.001' });
+const depositCbbtcTx = buildDepositCBBTCTx({
+  depositKey: keypair.depositKey(),
+  amount: '0.001',
+});
+
+// Generic builder (routes by token)
+const tx = buildDepositTx({
+  depositKey: keypair.depositKey(),
+  amount: '0.1',
+  token: 'ETH', // 'ETH' | 'USDC' | 'CBBTC'
+});
 ```
 
 ### Withdraw & Transfer
 
+All withdraw, transfer, and merge functions accept an optional `pool` parameter (`'eth'` | `'usdc'` | `'cbbtc'`), defaulting to `'eth'`.
+
 ```typescript
 import { withdraw, transfer, mergeUtxos } from '@veil-cash/sdk';
 
-// Withdraw to public address
+// Withdraw ETH to public address
 const withdrawResult = await withdraw({
   amount: '0.05',
   recipient: '0xRecipientAddress',
   keypair,
+  pool: 'eth', // default
   onProgress: (stage, detail) => console.log(stage, detail),
 });
 
-// Transfer to another registered user
+// Withdraw USDC
+const withdrawUsdc = await withdraw({
+  amount: '50',
+  recipient: '0xRecipientAddress',
+  keypair,
+  pool: 'usdc',
+});
+
+// Transfer cbBTC to another registered user
 const transferResult = await transfer({
-  amount: '0.02',
+  amount: '0.0002',
   recipientAddress: '0xRecipientAddress',
   senderKeypair: keypair,
+  pool: 'cbbtc',
 });
 
 // Merge UTXOs (consolidate small balances)
 const mergeResult = await mergeUtxos({
   amount: '0.1',
   keypair,
+  pool: 'eth',
 });
 ```
 
 ### Balance Queries
 
+Balance functions accept an optional `pool` parameter (`'eth'` | `'usdc'` | `'cbbtc'`), defaulting to `'eth'`.
+
 ```typescript
 import { getQueueBalance, getPrivateBalance } from '@veil-cash/sdk';
 
-// Check queue balance (pending deposits)
+// Check ETH queue balance (pending deposits)
 const queueBalance = await getQueueBalance({
   address: '0x...',
+  pool: 'eth', // default
 });
 
-// Check private balance (requires keypair)
+// Check USDC private balance (requires keypair)
 const privateBalance = await getPrivateBalance({
   keypair,
+  pool: 'usdc',
+});
+
+// Check cbBTC private balance
+const btcBalance = await getPrivateBalance({
+  keypair,
+  pool: 'cbbtc',
 });
 ```
 
 ### Addresses
 
 ```typescript
-import { getAddresses } from '@veil-cash/sdk';
+import { getAddresses, getPoolAddress, getQueueAddress } from '@veil-cash/sdk';
 
 const addresses = getAddresses();
 console.log(addresses.entry);     // Entry contract
 console.log(addresses.ethPool);   // ETH pool
-console.log(addresses.ethQueue);  // ETH queue
+console.log(addresses.usdcPool);  // USDC pool
+console.log(addresses.cbbtcPool);   // cbBTC pool
+
+// Helper functions to resolve by pool name
+console.log(getPoolAddress('eth'));   // ETH pool address
+console.log(getPoolAddress('usdc')); // USDC pool address
+console.log(getPoolAddress('cbbtc'));  // cbBTC pool address
+console.log(getQueueAddress('cbbtc')); // cbBTC queue address
 ```
 
 ## For AI Agents
@@ -391,19 +572,54 @@ veil init --json
 
 # Get unsigned transaction payloads for agent signing
 veil register --unsigned --address 0x...
-veil deposit 0.1 --unsigned
+veil deposit ETH 0.1 --unsigned
+veil deposit USDC 100 --unsigned    # Outputs approve + deposit payloads
+veil deposit CBBTC 0.001 --unsigned
 
 # Suppress progress output for clean JSON
 veil balance --quiet
-veil withdraw 0.05 0xRecipient --quiet
+veil balance --pool usdc --quiet
+veil withdraw ETH 0.05 0xRecipient --quiet
 ```
 
 ### Bankr Integration
 
+#### Keypair Derivation via Bankr Sign API
+
+Use `Keypair.fromSigner()` with Bankr's `POST /agent/sign` endpoint to derive the same keypair as the frontend:
+
+```typescript
+import { Keypair } from '@veil-cash/sdk';
+
+const keypair = await Keypair.fromSigner(async (message) => {
+  const res = await fetch('https://api.bankr.bot/agent/sign', {
+    method: 'POST',
+    headers: { 'X-API-Key': BANKR_API_KEY, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ signatureType: 'personal_sign', message }),
+  });
+  return (await res.json()).signature;
+});
+```
+
+Or via CLI (two-step):
+```bash
+# 1. Get signature from Bankr sign API
+SIG=$(curl -s -X POST "https://api.bankr.bot/agent/sign" \
+  -H "X-API-Key: $BANKR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{\"signatureType\":\"personal_sign\",\"message\":\"$(node -e "const{VEIL_SIGNED_MESSAGE}=require('@veil-cash/sdk');console.log(VEIL_SIGNED_MESSAGE)")\"}" \
+  | jq -r '.signature')
+
+# 2. Derive keypair from signature
+veil init --signature $SIG
+```
+
+#### Unsigned Transaction Payloads
+
 Use `--unsigned` to get Bankr-compatible transaction payloads:
 
 ```bash
-veil deposit 0.1 --unsigned
+veil deposit ETH 0.1 --unsigned
 # {"to":"0x...","data":"0x...","value":"100000000000000000","chainId":8453}
 ```
 
@@ -412,7 +628,7 @@ The `--unsigned` flag outputs the [Bankr arbitrary transaction format](https://g
 ### Programmatic SDK Usage
 
 ```typescript
-import { Keypair, buildDepositETHTx, withdraw } from '@veil-cash/sdk';
+import { Keypair, buildDepositETHTx, buildDepositTx, withdraw } from '@veil-cash/sdk';
 
 // For deposits: build transaction, let agent sign via Bankr
 const keypair = new Keypair(veilKey);
@@ -422,11 +638,19 @@ const tx = buildDepositETHTx({
 });
 // → { to, data, value } - pass to Bankr for signing
 
+// Generic builder works for any asset
+const usdcTx = buildDepositTx({
+  depositKey: keypair.depositKey(),
+  amount: '100',
+  token: 'USDC',
+});
+
 // For withdrawals: SDK handles ZK proofs, submits to relayer
 const result = await withdraw({
   amount: '0.05',
   recipient: '0xRecipient',
   keypair,
+  pool: 'eth', // 'eth' | 'usdc' | 'cbbtc'
 });
 // → { success, transactionHash, blockNumber }
 ```
@@ -435,14 +659,15 @@ const result = await withdraw({
 
 1. **Generate Keypair**: Run `veil init` to create and save your Veil keypair
 2. **Register**: Run `veil register` to link your deposit key on-chain (one-time)
-3. **Deposit**: Run `veil deposit <amount>` to send ETH
-4. **Wait**: The Veil deposit engine processes your deposit
-5. **Done**: Your deposit is accepted into the privacy pool
+3. **Check Status**: Run `veil status` to verify your setup
+4. **Deposit**: Run `veil deposit <asset> <amount>` (e.g., `veil deposit ETH 0.1`, `veil deposit USDC 100`, `veil deposit CBBTC 0.001`)
+5. **Wait**: The Veil deposit engine processes your deposit
+6. **Done**: Your deposit is accepted into the privacy pool
 
 ## Withdrawal Flow
 
-1. **Check Balance**: Run `veil balance` to see your private balance
-2. **Withdraw**: Run `veil withdraw <amount> <recipient>`
+1. **Check Balance**: Run `veil balance --pool <pool>` to see your private balance
+2. **Withdraw**: Run `veil withdraw <asset> <amount> <recipient>`
 3. **Done**: The SDK builds ZK proofs and submits via the relayer
 
 ## License