@veil-cash/sdk 0.4.0 → 0.5.0

package/README.md

@@ -23,6 +23,20 @@ For global CLI access:
 npm install -g @veil-cash/sdk
 ```
 
+## Agent Skill
+
+This repo includes a Veil agent skill at [`skills/veil/SKILL.md`](./skills/veil/SKILL.md).
+
+Quick mapping:
+
+- npm package: `@veil-cash/sdk`
+- CLI binary: `veil`
+- agent skill file: `skills/veil/SKILL.md`
+
+If you are pointing an agent at this repo, send it to [`skills/veil/SKILL.md`](./skills/veil/SKILL.md) for the canonical CLI workflow.
+
+If you install the npm package, the published package also includes the `skills/` directory so the same skill can be discovered from the installed package contents.
+
 ## Supported Assets
 
 | Asset | Decimals | Token Contract |
@@ -32,239 +46,146 @@ npm install -g @veil-cash/sdk
 
 ## CLI Quick Start
 
-```bash
-# 1. Generate and save your Veil keypair
-veil init
+The CLI is human-readable by default. Add `--json` when you want stable machine-readable output. `--unsigned` commands always emit transaction payload JSON for automation and agents.
 
-# 2. Set your Ethereum wallet key (for signing transactions)
+```bash
+# 1. Set your Ethereum wallet key
 export WALLET_KEY=0x...
 
+# 2. Derive and save your Veil keypair
+veil init
+
 # 3. Register your deposit key (one-time)
 veil register
 
 # 4. Check your setup
 veil status
 
-# 5. Deposit (ETH or USDC)
+# 5. Deposit into the pool (amount is what arrives in your balance; fee added automatically)
 veil deposit ETH 0.1
 veil deposit USDC 100
 
-# 6. Check your balance
-veil balance                  # ETH pool (default)
-veil balance --pool usdc      # USDC pool
+# 6. Inspect balances
+veil balance
+veil balance --pool eth
+veil balance queue --pool usdc
+veil balance private
 
-# 7. Withdraw to any address
+# 7. Use privacy actions
 veil withdraw ETH 0.05 0xRecipientAddress
-veil withdraw USDC 50 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
+
+# 8. Use JSON or unsigned modes when you need automation
+veil status --json
+veil deposit ETH 0.1 --unsigned
 ```
 
-## CLI Commands
+## CLI Tasks
 
-### `veil init`
+### Setup
 
-Generate or derive a Veil keypair.
+Derive a Veil keypair from your wallet (default) or generate a random one:
 
 ```bash
-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
+veil init --generate
 veil init --signature 0x...
+veil init --force
+veil init --no-save
+veil init --json
 ```
 
-### `veil keypair`
-
-Show current Veil keypair as JSON (from VEIL_KEY env).
+Show the current keypair from `VEIL_KEY`:
 
 ```bash
 veil keypair
-# {"veilPrivateKey":"0x...","depositKey":"0x..."}
+veil keypair --json
 ```
 
-### `veil status`
-
-Check configuration and service status.
+Check local configuration, registration, and relay health:
 
 ```bash
 veil status
+veil status --json
 ```
 
-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 status` shows a **Signing** row that reflects the active mode: `local (WALLET_KEY)`, `external (SIGNER_ADDRESS)`, or `not configured`. It also shows the resolved address, public ETH balance when available, and registration state. For unsigned or agent flows, set `SIGNER_ADDRESS` to let `veil status` and balance commands resolve address and registration without a private key.
 
-### `veil register`
+### Registration and Deposits
 
-Register or update your deposit key on-chain.
+Register or update your deposit key on-chain:
 
 ```bash
-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 register
+veil register --force
+veil register --json
+veil register --unsigned --address 0x...
+SIGNER_ADDRESS=0x... veil register --unsigned
 ```
 
-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>`
+In `--unsigned` mode, `--address` is optional when `SIGNER_ADDRESS` is set. `veil register --force` checks on-chain state first and emits a `changeDepositKey` payload only if the address is already registered; otherwise it emits a normal `register` payload.
 
-Deposit ETH or USDC into the privacy pool. For USDC, the CLI automatically handles ERC20 approval before depositing.
+Deposit ETH or USDC into Veil. The amount you specify is the **net** amount that arrives in your Veil balance. The 0.3% protocol fee is calculated on-chain and added automatically:
 
 ```bash
-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
+veil deposit ETH 0.1            # 0.1 ETH lands in pool, ~0.1003 ETH sent
+veil deposit USDC 100           # 100 USDC lands in pool, ~100.30 USDC sent
+veil deposit ETH 0.1 --json
+veil deposit ETH 0.1 --unsigned
 ```
 
-Output:
-```json
-{
-  "success": true,
-  "hash": "0x...",
-  "asset": "ETH",
-  "amount": "0.1",
-  "blockNumber": "12345678",
-  "gasUsed": "150000"
-}
-```
+### Balances
+
+Show combined balances across queue and private pools:
 
-### `veil balance`
+```bash
+veil balance
+veil balance --pool eth
+veil balance --pool usdc
+veil balance --json
+```
 
-Show both queue and private balances.
+Inspect queue balances directly:
 
 ```bash
-veil balance                        # ETH pool (default)
-veil balance --pool usdc            # USDC pool
-veil balance --quiet                # Suppress progress output
+veil balance queue
+veil balance queue --pool usdc
+veil balance queue --address 0x... --json
 ```
 
-Output:
-```json
-{
-  "address": "0x...",
-  "pool": "ETH",
-  "symbol": "ETH",
-  "depositKey": "0x...",
-  "totalBalance": "0.15",
-  "totalBalanceWei": "150000000000000000",
-  "private": {
-    "balance": "0.10",
-    "balanceWei": "100000000000000000",
-    "utxoCount": 2,
-    "utxos": [
-      { "index": 5, "amount": "0.05" },
-      { "index": 8, "amount": "0.05" }
-    ]
-  },
-  "queue": {
-    "balance": "0.05",
-    "balanceWei": "50000000000000000",
-    "count": 1,
-    "deposits": [
-      { "nonce": 42, "amount": "0.05", "status": "pending" }
-    ]
-  }
-}
+Inspect private balances directly:
+
+```bash
+veil balance private
+veil balance private --pool usdc
+veil balance private --json
 ```
 
-### `veil withdraw <asset> <amount> <recipient>`
+### Private Actions
 
-Withdraw from the privacy pool to any public address.
+Withdraw from the private pool to a public address:
 
 ```bash
 veil withdraw ETH 0.05 0xRecipientAddress
 veil withdraw USDC 50 0xRecipientAddress
-veil withdraw ETH 0.05 0xRecipientAddress --quiet
+veil withdraw ETH 0.05 0xRecipientAddress --json
 ```
 
-Output:
-```json
-{
-  "success": true,
-  "transactionHash": "0x...",
-  "blockNumber": 12345678,
-  "asset": "ETH",
-  "amount": "0.05",
-  "recipient": "0x..."
-}
-```
-
-### `veil transfer <asset> <amount> <recipient>`
-
-Transfer privately to another registered Veil user.
+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
-```
-
-Output:
-```json
-{
-  "success": true,
-  "transactionHash": "0x...",
-  "blockNumber": 12345678,
-  "asset": "ETH",
-  "amount": "0.02",
-  "recipient": "0x...",
-  "type": "transfer"
-}
+veil transfer ETH 0.02 0xRecipientAddress --json
 ```
 
-### `veil merge <asset> <amount>`
-
-Consolidate multiple small UTXOs into one (self-transfer).
+Merge small UTXOs into one:
 
 ```bash
-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
-```
-
-Output:
-```json
-{
-  "success": true,
-  "transactionHash": "0x...",
-  "blockNumber": 12345678,
-  "asset": "ETH",
-  "amount": "0.1",
-  "type": "merge"
-}
+veil merge ETH 0.1
+veil merge USDC 100
+veil merge ETH 0.1 --json
 ```
 
 ## Environment Variables
@@ -274,7 +195,7 @@ The CLI uses two config files:
 | File | Purpose |
 |------|---------|
 | `.env.veil` | Veil keypair (VEIL_KEY, DEPOSIT_KEY) - created by `veil init` |
-| `.env` | Wallet config (WALLET_KEY, RPC_URL) - your existing config |
+| `.env` | Wallet config (WALLET_KEY or SIGNER_ADDRESS, RPC_URL) - your existing config |
 
 ### Variables
 
@@ -283,17 +204,21 @@ The CLI uses two config files:
 | `VEIL_KEY` | Your Veil private key (for ZK proofs, withdrawals, transfers) |
 | `DEPOSIT_KEY` | Your Veil deposit key (public, for register/deposit) |
 | `WALLET_KEY` | Ethereum wallet private key (for signing transactions) |
+| `SIGNER_ADDRESS` | Ethereum address for unsigned/query flows when signing is handled externally |
 | `RPC_URL` | Base RPC URL (optional, defaults to public RPC) |
+| `RELAY_URL` | Override relay base URL for relayed CLI operations and status checks |
+
+`WALLET_KEY` and `SIGNER_ADDRESS` are mutually exclusive. Use `WALLET_KEY` for commands that sign transactions, and `SIGNER_ADDRESS` for address-only agent flows like `status`, `balance`, and `register --unsigned`.
 
 ## Error Handling
 
-All CLI commands output JSON with standardized error codes:
+Commands print human-readable success output by default. Errors are standardized JSON with machine-readable error codes so scripts can detect failure cases reliably:
 
 ```json
 {
   "success": false,
   "errorCode": "VEIL_KEY_MISSING",
-  "error": "VEIL_KEY required. Use --veil-key or set VEIL_KEY env"
+  "error": "VEIL_KEY required. Set VEIL_KEY env"
 }
 ```
 
@@ -304,6 +229,7 @@ All CLI commands output JSON with standardized error codes:
 | `VEIL_KEY_MISSING` | VEIL_KEY not provided |
 | `WALLET_KEY_MISSING` | WALLET_KEY not provided |
 | `DEPOSIT_KEY_MISSING` | DEPOSIT_KEY not provided |
+| `CONFIG_CONFLICT` | Conflicting CLI env vars provided |
 | `INVALID_ADDRESS` | Invalid Ethereum address format |
 | `INVALID_AMOUNT` | Invalid or below minimum amount |
 | `INSUFFICIENT_BALANCE` | Not enough ETH balance |
@@ -314,311 +240,22 @@ All CLI commands output JSON with standardized error codes:
 | `CONTRACT_ERROR` | Smart contract reverted |
 | `UNKNOWN_ERROR` | Unexpected error |
 
-## SDK Quick Start
-
-```typescript
-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';
-
-// 1. Generate a Veil keypair (do this once, save securely!)
-const keypair = new Keypair();
-console.log('Veil Private Key:', keypair.privkey);  // SAVE THIS!
-console.log('Deposit Key:', keypair.depositKey());  // Register this on-chain
-
-// 2. Setup your Ethereum wallet
-const account = privateKeyToAccount('0x...');
-const client = createWalletClient({
-  account,
-  chain: base,
-  transport: http(),
-});
-
-// 3. Register your deposit key (one-time)
-const registerTx = buildRegisterTx(keypair.depositKey(), account.address);
-await client.sendTransaction(registerTx);
-
-// 4. Deposit ETH
-const depositTx = buildDepositETHTx({
-  depositKey: keypair.depositKey(),
-  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(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
-const transferResult = await transfer({
-  amount: '0.02',
-  recipientAddress: '0xRecipientAddress',
-  senderKeypair: keypair,
-  pool: 'eth', // 'eth' | 'usdc' (default: 'eth')
-});
-```
-
-## SDK API Reference
-
-### Keypair
-
-```typescript
-import { Keypair, VEIL_SIGNED_MESSAGE } from '@veil-cash/sdk';
-import type { MessageSigner } from '@veil-cash/sdk';
-
-// 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)
-
-// Veil private key (store securely!)
-keypair.privkey; // '0x...'
-```
-
-### Transaction Builders
-
-```typescript
-import {
-  buildRegisterTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx,
-  buildDepositUSDCTx, buildApproveUSDCTx,
-} from '@veil-cash/sdk';
-
-// 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 ETH to public address
-const withdrawResult = await withdraw({
-  amount: '0.05',
-  recipient: '0xRecipientAddress',
-  keypair,
-  pool: 'eth', // default
-  onProgress: (stage, detail) => console.log(stage, detail),
-});
-
-// 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 ETH queue balance (pending deposits)
-const queueBalance = await getQueueBalance({
-  address: '0x...',
-  pool: 'eth', // default
-});
-
-// Check USDC private balance (requires keypair)
-const privateBalance = await getPrivateBalance({
-  keypair,
-  pool: 'usdc',
-});
-
-```
-
-### Addresses
-
-```typescript
-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.usdcPool);  // USDC pool
+## SDK Docs
 
-// Helper functions to resolve by pool name
-console.log(getPoolAddress('eth'));   // ETH pool address
-console.log(getPoolAddress('usdc')); // USDC pool address
-```
-
-## For AI Agents
-
-This SDK is designed to work with AI agent frameworks like [Bankr](https://bankr.bot).
-
-### Non-Interactive CLI
-
-All commands output JSON and support non-interactive usage:
-
-```bash
-# Generate keypair as JSON (no prompts, no file save)
-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
+The CLI is the main entrypoint for most users. If you are integrating Veil programmatically, use the dedicated SDK guide:
 
-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 ETH 0.1 --unsigned
-# {"to":"0x...","data":"0x...","value":"100000000000000000","chainId":8453}
-```
-
-The `--unsigned` flag outputs the [Bankr arbitrary transaction format](https://github.com/BankrBot/moltbot-skills/blob/main/bankr/references/arbitrary-transaction.md).
-
-### Programmatic SDK Usage
-
-```typescript
-import { Keypair, buildDepositETHTx, buildDepositTx, withdraw } from '@veil-cash/sdk';
-
-// For deposits: build transaction, let agent sign via Bankr
-const keypair = new Keypair(veilKey);
-const tx = buildDepositETHTx({
-  depositKey: keypair.depositKey(),
-  amount: '0.1',
-});
-// → { 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 }
-```
+- [SDK Quick Start and API Reference](./SDK.md)
+- [AI agent and signer integration notes](./SDK.md#for-ai-agents)
 
 ## Deposit Flow
 
-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 <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
+1. **Set Wallet Key**: `export WALLET_KEY=0x...` in your `.env` or shell
+2. **Derive Keypair**: Run `veil init` to derive and save your Veil keypair
+3. **Register**: Run `veil register` to link your deposit key on-chain (one-time)
+4. **Check Status**: Run `veil status` to verify your setup
+5. **Deposit**: Run `veil deposit <asset> <amount>` — the amount is what lands in your balance (e.g., `veil deposit ETH 0.1` deposits 0.1 ETH; the 0.3% fee is added automatically)
+6. **Wait**: The Veil deposit engine processes your deposit
+7. **Done**: Your deposit is accepted into the privacy pool
 
 ## Withdrawal Flow