@veil-cash/sdk 0.4.0 → 0.6.0

package/README.md

@@ -8,6 +8,8 @@ SDK and CLI for interacting with [Veil Cash](https://veil.cash) privacy pools on
 
 Generate keypairs, register, deposit, withdraw, transfer, and merge ETH and USDC privately.
 
+`0.6.0` adds SDK-first subaccount support for deterministic slot derivation, forwarder status, relay-backed deploy/sweep, and direct recovery.
+
 ## Installation
 
 ```bash
@@ -23,6 +25,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 +48,172 @@ 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
-```
 
-## CLI Commands
+# 8. Work with subaccounts
+veil subaccount derive --slot 0
+veil subaccount status --slot 0
+veil subaccount deploy --slot 0
+veil subaccount sweep --slot 0 --asset eth
+veil subaccount recover --slot 0 --asset usdc --to 0xRecipientAddress --amount 25
 
-### `veil init`
+# 9. Use JSON or unsigned modes when you need automation
+veil status --json
+veil deposit ETH 0.1 --unsigned
+veil subaccount status --slot 0 --json
+```
 
-Generate or derive a Veil keypair.
+## CLI Tasks
 
-```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
+### Setup
 
-# Derive from wallet (same keypair as frontend login)
-veil init --sign-message --wallet-key 0x...
+Derive a Veil keypair from your wallet (default) or generate a random one:
 
-# Derive from a pre-computed EIP-191 signature (from Bankr, MPC, etc.)
+```bash
+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
 
-### `veil balance`
+Show combined balances across queue and private pools:
 
-Show both queue and private balances.
+```bash
+veil balance
+veil balance --pool eth
+veil balance --pool usdc
+veil balance --json
+```
+
+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
+veil transfer ETH 0.02 0xRecipientAddress --json
 ```
 
-Output:
-```json
-{
-  "success": true,
-  "transactionHash": "0x...",
-  "blockNumber": 12345678,
-  "asset": "ETH",
-  "amount": "0.02",
-  "recipient": "0x...",
-  "type": "transfer"
-}
+Merge small UTXOs into one:
+
+```bash
+veil merge ETH 0.1
+veil merge USDC 100
+veil merge ETH 0.1 --json
 ```
 
-### `veil merge <asset> <amount>`
+### Subaccounts
 
-Consolidate multiple small UTXOs into one (self-transfer).
+Subaccounts are deterministic child slots derived from your main `VEIL_KEY`:
 
-```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
-```
+`root key -> slot -> child key -> child deposit key -> forwarder`
 
-Output:
-```json
-{
-  "success": true,
-  "transactionHash": "0x...",
-  "blockNumber": 12345678,
-  "asset": "ETH",
-  "amount": "0.1",
-  "type": "merge"
-}
+Base mainnet only. Deploy and sweep are relay-backed. Status reports the forwarder wallet and queue state only, not private pool attribution after queued funds are accepted. Recovery is for assets still sitting on the forwarder after refund or rejection, and is submitted directly on-chain by your CLI gas payer.
+
+```bash
+veil subaccount derive --slot 0
+veil subaccount status --slot 0
+veil subaccount address --slot 0
+veil subaccount deploy --slot 0
+veil subaccount sweep --slot 0 --asset eth
+veil subaccount recover --slot 0 --asset usdc --to 0xRecipientAddress --amount 25
+veil subaccount status --slot 0 --json
 ```
 
 ## Environment Variables
@@ -274,7 +223,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 +232,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, subaccount deploy/sweep, 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,7 +257,9 @@ 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_SLOT` | Invalid subaccount slot format |
 | `INVALID_AMOUNT` | Invalid or below minimum amount |
 | `INSUFFICIENT_BALANCE` | Not enough ETH balance |
 | `USER_NOT_REGISTERED` | Recipient not registered in Veil |
@@ -314,311 +269,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';
+## SDK Docs
 
-const addresses = getAddresses();
-console.log(addresses.entry);     // Entry contract
-console.log(addresses.ethPool);   // ETH pool
-console.log(addresses.usdcPool);  // USDC pool
+The CLI is the main entrypoint for most users. If you are integrating Veil programmatically, use the dedicated SDK guide:
 
-// 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
-
-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