@veil-cash/sdk 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veil-cash/sdk",
-  "version": "0.5.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/abi.ts

@@ -647,3 +647,175 @@ export const ERC20_ABI = [
     type: 'function',
   },
 ] as const;
+
+/**
+ * Veil Forwarder Factory ABI
+ */
+export const FORWARDER_FACTORY_ABI = [
+  {
+    inputs: [],
+    name: 'CONTRACT_VERSION',
+    outputs: [{ internalType: 'string', name: '', type: 'string' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [
+      { internalType: 'bytes32', name: '_salt', type: 'bytes32' },
+      { internalType: 'bytes', name: '_childDepositKey', type: 'bytes' },
+      { internalType: 'address', name: '_owner', type: 'address' },
+    ],
+    name: 'computeAddress',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [
+      { internalType: 'bytes32', name: '_salt', type: 'bytes32' },
+      { internalType: 'bytes', name: '_childDepositKey', type: 'bytes' },
+      { internalType: 'address', name: '_owner', type: 'address' },
+    ],
+    name: 'deploy',
+    outputs: [{ internalType: 'address', name: 'forwarder', type: 'address' }],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'relayer',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'veilEntry',
+    outputs: [{ internalType: 'address payable', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'usdc',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'owner',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;
+
+/**
+ * Veil Forwarder ABI
+ */
+export const FORWARDER_ABI = [
+  {
+    inputs: [],
+    name: 'CONTRACT_VERSION',
+    outputs: [{ internalType: 'string', name: '', type: 'string' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [
+      { internalType: 'address', name: '_token', type: 'address' },
+      { internalType: 'address', name: '_to', type: 'address' },
+      { internalType: 'uint256', name: '_amount', type: 'uint256' },
+      { internalType: 'uint256', name: '_nonce', type: 'uint256' },
+      { internalType: 'uint256', name: '_deadline', type: 'uint256' },
+      { internalType: 'bytes', name: '_signature', type: 'bytes' },
+    ],
+    name: 'withdraw',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+  {
+    inputs: [{ internalType: 'uint256', name: '', type: 'uint256' }],
+    name: 'usedNonces',
+    outputs: [{ internalType: 'bool', name: '', type: 'bool' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'owner',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'factory',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'childDepositKey',
+    outputs: [{ internalType: 'bytes', name: '', type: 'bytes' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'entry',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'usdc',
+    outputs: [{ internalType: 'address', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'sweepETH',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'sweepUSDC',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+  {
+    inputs: [],
+    name: 'eip712Domain',
+    outputs: [
+      { internalType: 'bytes1', name: 'fields', type: 'bytes1' },
+      { internalType: 'string', name: 'name', type: 'string' },
+      { internalType: 'string', name: 'version', type: 'string' },
+      { internalType: 'uint256', name: 'chainId', type: 'uint256' },
+      { internalType: 'address', name: 'verifyingContract', type: 'address' },
+      { internalType: 'bytes32', name: 'salt', type: 'bytes32' },
+      { internalType: 'uint256[]', name: 'extensions', type: 'uint256[]' },
+    ],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  { type: 'error', name: 'ZeroAddress', inputs: [] },
+  { type: 'error', name: 'ZeroAmount', inputs: [] },
+  { type: 'error', name: 'InvalidDepositKey', inputs: [] },
+  { type: 'error', name: 'NotRelayer', inputs: [] },
+  { type: 'error', name: 'NoETHBalance', inputs: [] },
+  { type: 'error', name: 'NoTokenBalance', inputs: [] },
+  { type: 'error', name: 'TokenApproveFailed', inputs: [] },
+  { type: 'error', name: 'ETHTransferFailed', inputs: [] },
+  { type: 'error', name: 'NonceUsed', inputs: [] },
+  { type: 'error', name: 'Unauthorized', inputs: [] },
+  { type: 'error', name: 'DeadlineExpired', inputs: [] },
+] as const;

package/src/addresses.ts

@@ -14,10 +14,16 @@ export const ADDRESSES: NetworkAddresses = {
   usdcPool: '0x5c50d58E49C59d112680c187De2Bf989d2a91242',
   usdcQueue: '0x5530241b24504bF05C9a22e95A1F5458888e6a9B',
   usdcToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  forwarderFactory: '0x2848Fd62293A1ff3b4a897E9FcD0e5962dcc8101',
   chainId: 8453,
   relayUrl: 'https://veil-relay.up.railway.app',
 } as const;
 
+/**
+ * Veil forwarder EIP-712 contract version
+ */
+export const FORWARDER_CONTRACT_VERSION = '1' as const;
+
 /**
  * Pool configuration (decimals, symbols, etc.)
  */
@@ -76,6 +82,14 @@ export function getQueueAddress(
   }
 }
 
+/**
+ * Get the forwarder factory contract address
+ * @returns Forwarder factory address for Base mainnet
+ */
+export function getForwarderFactoryAddress(): `0x${string}` {
+  return getAddresses().forwarderFactory;
+}
+
 /**
  * Get Relay URL
  * @returns Relay URL for Base mainnet