@veil-cash/sdk 0.5.0 → 0.6.1

package/README.md

@@ -1,13 +1,15 @@
 # @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.
 
 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
@@ -19,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:
 
@@ -33,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
 
@@ -76,9 +81,17 @@ veil withdraw ETH 0.05 0xRecipientAddress
 veil transfer ETH 0.02 0xRecipientAddress
 veil merge ETH 0.1
 
-# 8. Use JSON or unsigned modes when you need automation
+# 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
+
+# 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
 ```
 
 ## CLI Tasks
@@ -188,25 +201,47 @@ veil merge USDC 100
 veil merge ETH 0.1 --json
 ```
 
+### Subaccounts
+
+Subaccounts are deterministic child slots derived from your main `VEIL_KEY`:
+
+`root key -> slot -> child key -> child deposit key -> forwarder`
+
+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
 
 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 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`.
 
@@ -224,21 +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_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/SDK.md

@@ -10,7 +10,7 @@ If you are looking for the CLI first-run flow, go back to the main [README](./RE
 import {
   Keypair, buildRegisterTx, buildDepositETHTx,
   buildDepositUSDCTx, buildApproveUSDCTx,
-  withdraw, transfer,
+  withdraw, transfer, getSubaccountStatus,
 } from '@veil-cash/sdk';
 import { createWalletClient, http } from 'viem';
 import { base } from 'viem/chains';
@@ -65,6 +65,13 @@ const transferResult = await transfer({
   pool: 'eth', // 'eth' | 'usdc' (default: 'eth')
 });
 
+// 7. Inspect a deterministic subaccount slot
+const subaccount = await getSubaccountStatus({
+  rootPrivateKey: keypair.privkey as `0x${string}`,
+  slot: 0,
+});
+console.log(subaccount.slot.forwarderAddress);
+
 ```
 
 ## SDK API Reference
@@ -190,6 +197,53 @@ const privateBalance = await getPrivateBalance({
 });
 ```
 
+### Subaccounts
+
+Subaccounts are deterministic child slots derived from your main Veil key:
+
+`root key -> slot -> child key -> child deposit key -> forwarder`
+
+Base mainnet only. Status shows the forwarder wallet and queue state only. Deploy and sweep are relay-backed. Recovery signs a forwarder withdraw request with the child key and returns a direct transaction for your gas payer to submit.
+
+```typescript
+import {
+  deriveSubaccountSlot,
+  getSubaccountStatus,
+  deploySubaccountForwarder,
+  sweepSubaccountForwarder,
+  buildSubaccountRecoveryTx,
+} from '@veil-cash/sdk';
+
+const slot = await deriveSubaccountSlot({
+  rootPrivateKey: veilKey,
+  slot: 0,
+});
+
+const status = await getSubaccountStatus({
+  rootPrivateKey: veilKey,
+  slot: 0,
+});
+
+await deploySubaccountForwarder({
+  rootPrivateKey: veilKey,
+  slot: 0,
+});
+
+await sweepSubaccountForwarder({
+  forwarderAddress: slot.forwarderAddress,
+  asset: 'eth',
+});
+
+const recovery = await buildSubaccountRecoveryTx({
+  rootPrivateKey: veilKey,
+  slot: 0,
+  asset: 'usdc',
+  to: '0xRecipientAddress',
+  amount: '25',
+});
+// Send recovery.transaction with your wallet client
+```
+
 ### Addresses
 
 ```typescript