@veil-cash/sdk 0.6.0 → 0.6.1

package/README.md

@@ -1,8 +1,8 @@
 # @veil-cash/sdk
 
-[![npm version](https://img.shields.io/npm/v/@veil-cash/sdk.svg)](https://www.npmjs.com/package/@veil-cash/sdk)
-[![npm downloads](https://img.shields.io/npm/dm/@veil-cash/sdk.svg)](https://www.npmjs.com/package/@veil-cash/sdk)
-[![license](https://img.shields.io/npm/l/@veil-cash/sdk.svg)](https://github.com/veildotcash/veildotcash-sdk/blob/main/LICENSE)
+[npm version](https://www.npmjs.com/package/@veil-cash/sdk)
+[npm downloads](https://www.npmjs.com/package/@veil-cash/sdk)
+[license](https://github.com/veildotcash/veildotcash-sdk/blob/main/LICENSE)
 
 SDK and CLI for interacting with [Veil Cash](https://veil.cash) privacy pools on Base.
 
@@ -21,13 +21,14 @@ pnpm add @veil-cash/sdk
 ```
 
 For global CLI access:
+
 ```bash
 npm install -g @veil-cash/sdk
 ```
 
 ## Agent Skill
 
-This repo includes a Veil agent skill at [`skills/veil/SKILL.md`](./skills/veil/SKILL.md).
+This repo includes a Veil agent skill at [skills/veil/SKILL.md](./skills/veil/SKILL.md).
 
 Quick mapping:
 
@@ -35,16 +36,18 @@ Quick mapping:
 - 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 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 |
-|-------|----------|---------------|
-| ETH | 18 | Native ETH (via WETH) |
-| USDC | 6 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+
+| Asset | Decimals | Token Contract                               |
+| ----- | -------- | -------------------------------------------- |
+| ETH   | 18       | Native ETH (via WETH)                        |
+| USDC  | 6        | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+
 
 ## CLI Quick Start
 
@@ -220,21 +223,25 @@ veil subaccount status --slot 0 --json
 
 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 or SIGNER_ADDRESS, RPC_URL) - your existing config |
+
+| File        | Purpose                                                                      |
+| ----------- | ---------------------------------------------------------------------------- |
+| `.env.veil` | Veil keypair (VEIL_KEY, DEPOSIT_KEY) - created by `veil init`                |
+| `.env`      | Wallet config (WALLET_KEY or SIGNER_ADDRESS, RPC_URL) - your existing config |
+
 
 ### Variables
 
-| Variable | Description |
-|----------|-------------|
-| `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 |
+
+| Variable         | Description                                                                                    |
+| ---------------- | ---------------------------------------------------------------------------------------------- |
+| `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`.
 
@@ -252,22 +259,24 @@ Commands print human-readable success output by default. Errors are standardized
 
 ### Error Codes
 
-| Code | Description |
-|------|-------------|
-| `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 |
-| `NO_UTXOS` | No unspent UTXOs available |
-| `RELAY_ERROR` | Error from relayer service |
-| `RPC_ERROR` | RPC/network error |
-| `CONTRACT_ERROR` | Smart contract reverted |
-| `UNKNOWN_ERROR` | Unexpected error |
+
+| Code                   | Description                       |
+| ---------------------- | --------------------------------- |
+| `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  |
+| `NO_UTXOS`             | No unspent UTXOs available        |
+| `RELAY_ERROR`          | Error from relayer service        |
+| `RPC_ERROR`            | RPC/network error                 |
+| `CONTRACT_ERROR`       | Smart contract reverted           |
+| `UNKNOWN_ERROR`        | Unexpected error                  |
+
 
 ## SDK Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veil-cash/sdk",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "SDK and CLI for interacting with Veil Cash privacy pools - keypair generation, deposits, and status checking",
   "type": "module",
   "main": "./dist/index.js",

package/skills/veil/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: veil
-version: 0.5.0
+version: 0.6.0
 description: >
   Veil CLI for private ETH and USDC transactions on Base. Use when the user wants
   to deposit, withdraw, or transfer assets privately, check private balances,
-  manage Veil keypairs, register on-chain, or build unsigned transaction payloads
+  manage Veil keypairs, register on-chain, manage deterministic subaccounts
+  (forwarder deploy, sweep, recover), or build unsigned transaction payloads
   for an external signer (e.g. Bankr). All operations target Base (chain ID 8453).
 author: veildotcash
 metadata:
@@ -27,11 +28,15 @@ triggers:
   - pattern: veil withdraw
   - pattern: veil transfer
   - pattern: veil merge
+  - pattern: veil subaccount
   - pattern: unsigned payload
   - pattern: privacy pool
   - pattern: deposit privately
   - pattern: withdraw privately
   - pattern: private transfer
+  - pattern: subaccount
+  - pattern: forwarder
+  - pattern: stealth deposit
 ---
 
 # Veil CLI
@@ -164,6 +169,8 @@ What do you want to do?
 |
 +-- Withdraw / transfer / merge       → Section 5
 |
++-- Subaccounts (forwarders)          → Section 5B
+|
 +-- Inspect or rotate keypair         → veil keypair / veil init --force
 ```
 
@@ -188,6 +195,12 @@ What do you want to do?
 | Withdraw | `veil withdraw ETH 0.05 0xRecipient` |
 | Transfer privately | `veil transfer ETH 0.02 0xRecipient` |
 | Merge UTXOs | `veil merge ETH 0.1` |
+| Derive subaccount | `veil subaccount derive --slot 0` |
+| Subaccount status | `veil subaccount status --slot 0` |
+| Subaccount address | `veil subaccount address --slot 0` |
+| Deploy forwarder | `veil subaccount deploy --slot 0` |
+| Sweep forwarder | `veil subaccount sweep --slot 0 --asset eth` |
+| Recover from forwarder | `veil subaccount recover --slot 0 --asset usdc --to 0xAddr --amount 25` |
 
 ---
 
@@ -315,6 +328,8 @@ Important:
 
 Deposits treat the CLI amount as the **net** amount that lands in the pool.
 The `0.3%` protocol fee is calculated on-chain and added automatically.
+After submission, deposits go through screening / queue processing before they
+are accepted into the private pool. This typically takes around `10-15 minutes`.
 
 ```bash
 veil deposit ETH 0.1
@@ -369,6 +384,9 @@ Human-readable balance output includes:
 - wallet public balances (`ETH`, `USDC`)
 - queue and private balances
 
+If a recent deposit still appears in queue balance, screening / queue processing
+may still be in progress. Typical processing time is around `10-15 minutes`.
+
 ---
 
 ## 5. Private Actions
@@ -403,6 +421,59 @@ Note: withdraw proof generation is single-threaded for reliable CLI exit after s
 
 ---
 
+## 5B. Subaccounts
+
+Subaccounts are deterministic child slots derived from your main `VEIL_KEY`:
+
+`root key → slot → child key → child deposit key → forwarder`
+
+Base mainnet only. Slots are `0`–`2` (max 3 subaccounts). Deploy and sweep are
+relay-backed (no `WALLET_KEY` needed). Recovery submits a direct on-chain
+transaction and **requires `WALLET_KEY`** as a gas payer.
+
+Status reports the forwarder wallet balances and queue state only, not private
+pool attribution after queued funds are accepted.
+
+### Derive and inspect
+
+```bash
+veil subaccount derive --slot 0           # Full slot metadata
+veil subaccount derive --slot 0 --json
+veil subaccount address --slot 0          # Just the forwarder address
+veil subaccount status --slot 0           # Deployment, balances, queue state
+veil subaccount status --slot 0 --json
+```
+
+### Deploy and sweep (relay-backed)
+
+```bash
+veil subaccount deploy --slot 0           # Deploy the forwarder contract
+veil subaccount deploy --slot 0 --json
+veil subaccount sweep --slot 0 --asset eth    # Sweep ETH into the pool
+veil subaccount sweep --slot 0 --asset usdc   # Sweep USDC into the pool
+veil subaccount sweep --slot 0 --asset eth --json
+```
+
+### Recover (direct on-chain — requires WALLET_KEY)
+
+Recovery is for assets still sitting on the forwarder after refund or rejection.
+It signs a forwarder withdraw with the child key and submits the transaction
+using `WALLET_KEY` as the gas payer.
+
+```bash
+veil subaccount recover --slot 0 --asset usdc --to 0xRecipient --amount 25
+veil subaccount recover --slot 0 --asset eth --to 0xRecipient --amount 0.05 --json
+```
+
+Important:
+
+- `--asset` is `eth` or `usdc` (case-insensitive in the CLI)
+- `--slot` is `0`–`2`
+- Deploy and sweep only need `VEIL_KEY`
+- Recover needs both `VEIL_KEY` and `WALLET_KEY`
+
+---
+
 ## 6. Unsigned Payloads
 
 `--unsigned` is for external signer workflows. The CLI emits a signer-compatible
@@ -504,6 +575,7 @@ All CLI errors output JSON with a standardised `errorCode`:
 | `DEPOSIT_KEY_MISSING` | `DEPOSIT_KEY` missing from `.env.veil` | Re-run `veil init` to regenerate |
 | `USER_NOT_REGISTERED` | Transfer recipient has no deposit key registered on-chain | Recipient must run `veil register` first |
 | `INVALID_AMOUNT` | Amount below minimum or invalid format | ETH min: `0.01`, USDC min: `10` |
+| `INVALID_SLOT` | Invalid subaccount slot | Slot must be `0`–`2` (non-negative integer) |
 | `INSUFFICIENT_BALANCE` | Not enough ETH for gas | Top up Base ETH balance |
 | `RPC_ERROR` | Network or RPC failure | Check `RPC_URL` env var or retry |
 | `RELAY_ERROR` | Relayer rejected the proof | Check relay health with `veil status`; retry |

package/skills/veil/reference.md

@@ -143,6 +143,63 @@ const priv = await getPrivateBalance({
 });
 ```
 
+### Subaccounts
+
+```typescript
+import {
+  deriveSubaccountSlot,
+  getSubaccountStatus,
+  deploySubaccountForwarder,
+  sweepSubaccountForwarder,
+  buildSubaccountRecoveryTx,
+  isSubaccountForwarderDeployed,
+  MAX_SUBACCOUNT_SLOTS,
+} from '@veil-cash/sdk';
+
+// Derive slot metadata (child key, salt, predicted forwarder address)
+const slot = await deriveSubaccountSlot({
+  rootPrivateKey: '0xVEIL_KEY',
+  slot: 0,           // 0–2
+});
+// slot.forwarderAddress, slot.childOwner, slot.childDepositKey, slot.salt
+
+// Check deployment status
+const deployed = await isSubaccountForwarderDeployed({
+  forwarderAddress: slot.forwarderAddress,
+});
+
+// Full status (deployment, balances, queue state)
+const status = await getSubaccountStatus({
+  rootPrivateKey: '0xVEIL_KEY',
+  slot: 0,
+});
+// status.deployed, status.balances.eth, status.balances.usdc, status.queues
+
+// Deploy forwarder (relay-backed, no WALLET_KEY needed)
+const deployResult = await deploySubaccountForwarder({
+  rootPrivateKey: '0xVEIL_KEY',
+  slot: 0,
+});
+// deployResult.transactionHash, deployResult.slot.forwarderAddress
+
+// Sweep assets into pool (relay-backed)
+const sweepResult = await sweepSubaccountForwarder({
+  forwarderAddress: slot.forwarderAddress,
+  asset: 'eth',     // 'eth' | 'usdc'
+});
+
+// Build recovery transaction (for assets stuck on forwarder)
+const recovery = await buildSubaccountRecoveryTx({
+  rootPrivateKey: '0xVEIL_KEY',
+  slot: 0,
+  asset: 'usdc',
+  to: '0xRecipient',
+  amount: '25',
+});
+// recovery.transaction — submit with your wallet client
+// recovery.forwarderAddress, recovery.signature, recovery.nonce, recovery.deadline
+```
+
 ---
 
 ## CLI quick reference
@@ -158,7 +215,7 @@ Install globally: `npm install -g @veil-cash/sdk`
 | `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 |
+| `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 `SIGNER_ADDRESS` only for address-only CLI flows.
 
@@ -195,6 +252,18 @@ 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
+
+veil subaccount derive --slot 0                    # Derive slot metadata
+veil subaccount derive --slot 0 --json             # Derive as JSON
+veil subaccount address --slot 0                   # Print forwarder address
+veil subaccount status --slot 0                    # Deployment, balances, queue state
+veil subaccount status --slot 0 --json             # Status as JSON
+veil subaccount deploy --slot 0                    # Deploy forwarder (relay-backed)
+veil subaccount deploy --slot 0 --json             # Deploy as JSON
+veil subaccount sweep --slot 0 --asset eth         # Sweep ETH into pool (relay-backed)
+veil subaccount sweep --slot 0 --asset usdc --json # Sweep USDC as JSON
+veil subaccount recover --slot 0 --asset usdc --to 0x... --amount 25   # Recover assets (needs WALLET_KEY)
+veil subaccount recover --slot 0 --asset eth --to 0x... --amount 0.05 --json
 ```
 
 ### Error format
@@ -210,7 +279,7 @@ All CLI errors output JSON with a standardized `errorCode`:
 ```
 
 Common codes: `VEIL_KEY_MISSING`, `WALLET_KEY_MISSING`, `DEPOSIT_KEY_MISSING`,
-`CONFIG_CONFLICT`, `INVALID_AMOUNT`, `INSUFFICIENT_BALANCE`, `CONTRACT_ERROR`, `RPC_ERROR`.
+`CONFIG_CONFLICT`, `INVALID_AMOUNT`, `INVALID_SLOT`, `INSUFFICIENT_BALANCE`, `CONTRACT_ERROR`, `RPC_ERROR`.
 
 ---
 

package/src/cli/commands/subaccount.ts

@@ -178,11 +178,6 @@ Examples:
     .action(async (options) => {
       try {
         const rootPrivateKey = getRequiredVeilKey();
-        const slot = await deriveSubaccountSlot({
-          rootPrivateKey,
-          slot: options.slot,
-          rpcUrl: process.env.RPC_URL,
-        });
         const result = await deploySubaccountForwarder({
           rootPrivateKey,
           slot: options.slot,
@@ -193,7 +188,7 @@ Examples:
         const output = {
           ...result,
           slot: options.slot,
-          forwarderAddress: slot.forwarderAddress,
+          forwarderAddress: result.slot.forwarderAddress,
         };
 
         if (options.json) {
@@ -204,7 +199,7 @@ Examples:
         printHeader('Subaccount Deploy Submitted');
         printFields([
           { label: 'Slot', value: options.slot },
-          { label: 'Forwarder', value: slot.forwarderAddress },
+          { label: 'Forwarder', value: result.slot.forwarderAddress },
           { label: 'Transaction', value: txUrl(result.transactionHash) },
           { label: 'Block', value: result.blockNumber },
         ]);
@@ -274,6 +269,12 @@ Examples:
         if (!isAddress(options.to)) {
           throw new CLIError(ErrorCode.INVALID_ADDRESS, `Invalid recipient address: ${options.to}`);
         }
+        if (!process.env.WALLET_KEY) {
+          throw new CLIError(
+            ErrorCode.WALLET_KEY_MISSING,
+            'WALLET_KEY required for recovery. Recovery submits a transaction on-chain and needs a gas payer.',
+          );
+        }
         const config = getConfig({});
         const recovery = await buildSubaccountRecoveryTx({
           rootPrivateKey,

package/src/cli/index.ts

@@ -38,7 +38,7 @@ const program = new Command();
 program
   .name('veil')
   .description('CLI for Veil Cash privacy pools on Base')
-  .version('0.6.0')
+  .version('0.6.1')
   .addHelpText('after', `
 Getting started:
   veil init

package/src/relay.ts

@@ -64,7 +64,16 @@ export async function postRelayJson<T>(
     body: JSON.stringify(body),
   });
 
-  const data = await response.json();
+  const text = await response.text();
+  let data: unknown;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new RelayError(
+      `Relay returned non-JSON response (HTTP ${response.status})`,
+      response.status,
+    );
+  }
 
   if (!response.ok) {
     const errorData = data as RelayErrorResponse;

package/src/subaccount.ts

@@ -134,11 +134,14 @@ export async function predictSubaccountForwarder(options: {
   rpcUrl?: string;
 }): Promise<`0x${string}`> {
   const publicClient = createBaseClient(options.rpcUrl);
+  const depositKeyBytes = options.childDepositKey.startsWith('0x')
+    ? options.childDepositKey
+    : `0x${options.childDepositKey}`;
   return publicClient.readContract({
     abi: FORWARDER_FACTORY_ABI,
     address: getForwarderFactoryAddress(),
     functionName: 'computeAddress',
-    args: [options.salt, options.childDepositKey as `0x${string}`, options.childOwner],
+    args: [options.salt, depositKeyBytes as `0x${string}`, options.childOwner],
   }) as Promise<`0x${string}`>;
 }
 
@@ -183,14 +186,14 @@ export async function isSubaccountForwarderDeployed(options: {
 
 export async function deploySubaccountForwarder(
   options: SubaccountDeployRequest,
-): Promise<SubaccountRelayResult> {
+): Promise<SubaccountRelayResult & { slot: SubaccountSlot }> {
   const slot = await deriveSubaccountSlot({
     rootPrivateKey: options.rootPrivateKey,
     slot: options.slot,
     rpcUrl: options.rpcUrl,
   });
 
-  return postRelayJson<SubaccountRelayResult>(
+  const result = await postRelayJson<SubaccountRelayResult>(
     '/stealth/deploy',
     {
       salt: slot.salt,
@@ -200,6 +203,8 @@ export async function deploySubaccountForwarder(
     },
     options.relayUrl,
   );
+
+  return { ...result, slot };
 }
 
 export async function sweepSubaccountForwarder(