@veil-cash/sdk 0.2.0 → 0.4.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, transfer, and merge ETH privately.
+Generate keypairs, register, deposit, withdraw, transfer, and merge ETH and USDC privately.
 
 ## Installation
 
@@ -23,6 +23,13 @@ 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` |
+
 ## CLI Quick Start
 
 ```bash
@@ -38,14 +45,17 @@ veil register
 # 4. Check your setup
 veil status
 
-# 5. Deposit ETH
+# 5. Deposit (ETH or USDC)
 veil deposit ETH 0.1
+veil deposit USDC 100
 
 # 6. Check your balance
-veil balance
+veil balance                  # ETH pool (default)
+veil balance --pool usdc      # USDC pool
 
 # 7. Withdraw to any address
 veil withdraw ETH 0.05 0xRecipientAddress
+veil withdraw USDC 50 0xRecipientAddress
 
 # 8. Transfer privately to another registered user
 veil transfer ETH 0.02 0xRecipientAddress
@@ -58,14 +68,19 @@ veil merge ETH 0.1
 
 ### `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`
@@ -109,20 +124,27 @@ Output:
 
 ### `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 ETH <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.
+
+### `veil deposit <asset> <amount>`
 
-Deposit ETH into the privacy pool.
+Deposit ETH or USDC into the privacy pool. For USDC, the CLI automatically handles ERC20 approval before depositing.
 
 ```bash
-veil deposit ETH 0.1                    # Signs & sends (JSON output)
+veil deposit ETH 0.1                    # Deposit ETH
+veil deposit USDC 100                   # Approve + deposit USDC
 veil deposit ETH 0.1 --unsigned         # Unsigned payload for agents
 veil deposit ETH 0.1 --quiet            # Suppress progress output
 ```
@@ -132,6 +154,7 @@ Output:
 {
   "success": true,
   "hash": "0x...",
+  "asset": "ETH",
   "amount": "0.1",
   "blockNumber": "12345678",
   "gasUsed": "150000"
@@ -143,7 +166,8 @@ 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 --quiet                # Suppress progress output
 ```
 
@@ -151,6 +175,8 @@ Output:
 ```json
 {
   "address": "0x...",
+  "pool": "ETH",
+  "symbol": "ETH",
   "depositKey": "0x...",
   "totalBalance": "0.15",
   "totalBalanceWei": "150000000000000000",
@@ -174,12 +200,13 @@ Output:
 }
 ```
 
-### `veil withdraw ETH <amount> <recipient>`
+### `veil withdraw <asset> <amount> <recipient>`
 
 Withdraw from the privacy pool to any public address.
 
 ```bash
 veil withdraw ETH 0.05 0xRecipientAddress
+veil withdraw USDC 50 0xRecipientAddress
 veil withdraw ETH 0.05 0xRecipientAddress --quiet
 ```
 
@@ -189,18 +216,19 @@ Output:
   "success": true,
   "transactionHash": "0x...",
   "blockNumber": 12345678,
+  "asset": "ETH",
   "amount": "0.05",
-  "recipient": "0x...",
-  "type": "withdraw"
+  "recipient": "0x..."
 }
 ```
 
-### `veil transfer ETH <amount> <recipient>`
+### `veil transfer <asset> <amount> <recipient>`
 
 Transfer privately to another registered Veil user.
 
 ```bash
 veil transfer ETH 0.02 0xRecipientAddress
+veil transfer USDC 25 0xRecipientAddress
 veil transfer ETH 0.02 0xRecipientAddress --quiet
 ```
 
@@ -210,18 +238,20 @@ Output:
   "success": true,
   "transactionHash": "0x...",
   "blockNumber": 12345678,
+  "asset": "ETH",
   "amount": "0.02",
   "recipient": "0x...",
   "type": "transfer"
 }
 ```
 
-### `veil merge ETH <amount>`
+### `veil merge <asset> <amount>`
 
 Consolidate multiple small UTXOs into one (self-transfer).
 
 ```bash
-veil merge ETH 0.1                      # Merge UTXOs totaling 0.1 ETH
+veil merge ETH 0.1                      # Merge ETH UTXOs totaling 0.1 ETH
+veil merge USDC 100                     # Merge USDC UTXOs
 veil merge ETH 0.1 --quiet
 ```
 
@@ -231,6 +261,7 @@ Output:
   "success": true,
   "transactionHash": "0x...",
   "blockNumber": 12345678,
+  "asset": "ETH",
   "amount": "0.1",
   "type": "merge"
 }
@@ -286,7 +317,11 @@ 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,
+  withdraw, transfer,
+} from '@veil-cash/sdk';
 import { createWalletClient, http } from 'viem';
 import { base } from 'viem/chains';
 import { privateKeyToAccount } from 'viem/accounts';
@@ -311,18 +346,25 @@ 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,
+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(usdcTx);
 
 // 5. Withdraw (sent via relayer, no wallet signing needed)
 const withdrawResult = await withdraw({
   amount: '0.05',
   recipient: '0xRecipientAddress',
   keypair,
+  pool: 'eth', // 'eth' | 'usdc' (default: 'eth')
 });
 
 // 6. Transfer privately
@@ -330,6 +372,7 @@ const transferResult = await transfer({
   amount: '0.02',
   recipientAddress: '0xRecipientAddress',
   senderKeypair: keypair,
+  pool: 'eth', // 'eth' | 'usdc' (default: 'eth')
 });
 ```
 
@@ -338,14 +381,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)
 
@@ -356,72 +412,107 @@ keypair.privkey; // '0x...'
 ### Transaction Builders
 
 ```typescript
-import { buildRegisterTx, buildDepositETHTx } from '@veil-cash/sdk';
+import {
+  buildRegisterTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx,
+  buildDepositUSDCTx, buildApproveUSDCTx,
+} 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',
+});
+
+// Generic builder (routes by token)
+const tx = buildDepositTx({
+  depositKey: keypair.depositKey(),
+  amount: '0.1',
+  token: 'ETH', // 'ETH' | 'USDC'
+});
 ```
 
 ### Withdraw & Transfer
 
+All withdraw, transfer, and merge functions accept an optional `pool` parameter (`'eth'` | `'usdc'`), 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
-const transferResult = await transfer({
-  amount: '0.02',
-  recipientAddress: '0xRecipientAddress',
-  senderKeypair: keypair,
+// Withdraw USDC
+const withdrawUsdc = await withdraw({
+  amount: '50',
+  recipient: '0xRecipientAddress',
+  keypair,
+  pool: 'usdc',
 });
 
 // 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'`), 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',
 });
+
 ```
 
 ### 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
+
+// Helper functions to resolve by pool name
+console.log(getPoolAddress('eth'));   // ETH pool address
+console.log(getPoolAddress('usdc')); // USDC pool address
 ```
 
 ## For AI Agents
@@ -439,14 +530,48 @@ veil init --json
 # Get unsigned transaction payloads for agent signing
 veil register --unsigned --address 0x...
 veil deposit ETH 0.1 --unsigned
+veil deposit USDC 100 --unsigned    # Outputs approve + deposit payloads
 
 # Suppress progress output for clean JSON
 veil balance --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
@@ -459,7 +584,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);
@@ -469,11 +594,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'
 });
 // → { success, transactionHash, blockNumber }
 ```
@@ -483,14 +616,14 @@ 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. **Check Status**: Run `veil status` to verify your setup
-4. **Deposit**: Run `veil deposit ETH <amount>` to send ETH
+4. **Deposit**: Run `veil deposit <asset> <amount>` (e.g., `veil deposit ETH 0.1`, `veil deposit USDC 100`)
 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 ETH <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