@veil-cash/sdk 0.6.1 → 0.6.3

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.2` adds `mergeSubaccount` — transfer a subaccount's private pool balance back to the main wallet via a ZK proof. Also adds `veil subaccount merge` CLI command.
+
 `0.6.0` adds SDK-first subaccount support for deterministic slot derivation, forwarder status, relay-backed deploy/sweep, and direct recovery.
 
 ## Installation
@@ -86,11 +88,12 @@ veil subaccount derive --slot 0
 veil subaccount status --slot 0
 veil subaccount deploy --slot 0
 veil subaccount sweep --slot 0 --asset eth
+veil subaccount merge --slot 0 --pool 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 deposit ETH 0.1 --unsigned --address 0x...
 veil subaccount status --slot 0 --json
 ```
 
@@ -139,13 +142,14 @@ SIGNER_ADDRESS=0x... veil register --unsigned
 
 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 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:
+Deposit ETH or USDC into Veil. The amount you specify is the **net** amount that arrives in your Veil balance. A 0.3% protocol fee is normally added on top, but each address gets free daily deposits (fee waived). The CLI checks automatically:
 
 ```bash
-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            # 0.1 ETH lands in pool (free or ~0.1003 ETH sent)
+veil deposit USDC 100           # 100 USDC lands in pool (free or ~100.30 USDC sent)
 veil deposit ETH 0.1 --json
-veil deposit ETH 0.1 --unsigned
+veil deposit ETH 0.1 --unsigned --address 0x...
+SIGNER_ADDRESS=0x... veil deposit ETH 0.1 --unsigned
 ```
 
 ### Balances
@@ -207,7 +211,7 @@ 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.
+Base mainnet only. Deploy and sweep are relay-backed. Merge transfers the subaccount's private pool balance back to the main wallet via a ZK proof. Status reports forwarder wallet balances, private pool balances, and queue state for the child slot. 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
@@ -215,6 +219,7 @@ veil subaccount status --slot 0
 veil subaccount address --slot 0
 veil subaccount deploy --slot 0
 veil subaccount sweep --slot 0 --asset eth
+veil subaccount merge --slot 0 --pool eth
 veil subaccount recover --slot 0 --asset usdc --to 0xRecipientAddress --amount 25
 veil subaccount status --slot 0 --json
 ```
@@ -291,7 +296,7 @@ The CLI is the main entrypoint for most users. If you are integrating Veil progr
 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)
+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 fee is waived if you have daily free deposits remaining, otherwise 0.3% is added automatically)
 6. **Wait**: The Veil deposit engine processes your deposit
 7. **Done**: Your deposit is accepted into the privacy pool
 

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, getSubaccountStatus,
+  withdraw, transfer, getSubaccountStatus, mergeSubaccount,
 } from '@veil-cash/sdk';
 import { createWalletClient, http } from 'viem';
 import { base } from 'viem/chains';
@@ -109,6 +109,11 @@ keypair.privkey; // '0x...'
 
 ### Transaction Builders
 
+> **Daily free deposits**: Each address gets a configurable number of fee-free
+> deposits per UTC day. The CLI handles this automatically. If you use the
+> builders programmatically, call `getDailyFreeRemaining()` first — when the
+> user has free slots, pass the net amount directly (no fee markup needed).
+
 ```typescript
 import {
   buildRegisterTx, buildChangeDepositKeyTx, buildDepositETHTx, buildDepositTx,
@@ -182,7 +187,7 @@ const mergeResult = await mergeUtxos({
 Balance functions accept an optional `pool` parameter (`'eth'` | `'usdc'`), defaulting to `'eth'`.
 
 ```typescript
-import { getQueueBalance, getPrivateBalance } from '@veil-cash/sdk';
+import { getQueueBalance, getPrivateBalance, getDailyFreeRemaining } from '@veil-cash/sdk';
 
 // Check ETH queue balance (pending deposits)
 const queueBalance = await getQueueBalance({
@@ -195,6 +200,13 @@ const privateBalance = await getPrivateBalance({
   keypair,
   pool: 'usdc',
 });
+
+// Check how many fee-free deposits the user has left today
+const freeRemaining = await getDailyFreeRemaining({
+  address: '0x...',
+  pool: 'eth', // default
+});
+// freeRemaining: number — 0 when all free slots are used or the feature is disabled
 ```
 
 ### Subaccounts
@@ -203,14 +215,16 @@ 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.
+Base mainnet only. Status shows the child slot's forwarder wallet balances, private pool balances, and queue state. Deploy and sweep are relay-backed. Merge transfers the subaccount's private pool balance back to the main wallet via a ZK proof. Recovery signs a forwarder withdraw request with the child key and returns a direct transaction for your gas payer to submit.
 
 ```typescript
 import {
   deriveSubaccountSlot,
+  getSubaccountPrivateBalance,
   getSubaccountStatus,
   deploySubaccountForwarder,
   sweepSubaccountForwarder,
+  mergeSubaccount,
   buildSubaccountRecoveryTx,
 } from '@veil-cash/sdk';
 
@@ -223,6 +237,14 @@ const status = await getSubaccountStatus({
   rootPrivateKey: veilKey,
   slot: 0,
 });
+// status.privateBalances.eth.privateBalance, status.privateBalances.usdc.privateBalance
+
+const privateBalance = await getSubaccountPrivateBalance({
+  rootPrivateKey: veilKey,
+  slot: 0,
+  pool: 'eth',
+});
+// privateBalance.privateBalance, privateBalance.unspentCount
 
 await deploySubaccountForwarder({
   rootPrivateKey: veilKey,
@@ -234,6 +256,14 @@ await sweepSubaccountForwarder({
   asset: 'eth',
 });
 
+// Merge subaccount's private pool balance back to the main wallet
+const mergeResult = await mergeSubaccount({
+  rootPrivateKey: veilKey,
+  slot: 0,
+  pool: 'eth', // 'eth' | 'usdc' (default: 'eth')
+});
+// mergeResult.amount, mergeResult.transactionHash
+
 const recovery = await buildSubaccountRecoveryTx({
   rootPrivateKey: veilKey,
   slot: 0,
@@ -273,8 +303,8 @@ veil init --json
 
 # Get unsigned transaction payloads for agent signing
 SIGNER_ADDRESS=0x... veil register --unsigned
-veil deposit ETH 0.1 --unsigned
-veil deposit USDC 100 --unsigned    # Outputs approve + deposit payloads
+SIGNER_ADDRESS=0x... veil deposit ETH 0.1 --unsigned
+veil deposit USDC 100 --unsigned --address 0x...    # Outputs approve + deposit payloads
 
 # Request machine-readable status or balances
 veil balance --json
@@ -326,12 +356,13 @@ Use `--unsigned` to get signer-compatible transaction payloads:
 ```bash
 SIGNER_ADDRESS=0x... veil register --unsigned
 SIGNER_ADDRESS=0x... veil register --unsigned --force
-veil deposit ETH 0.1 --unsigned
+SIGNER_ADDRESS=0x... veil deposit ETH 0.1 --unsigned
+veil deposit ETH 0.1 --unsigned --address 0x...
 # {"to":"0x...","data":"0x...","value":"100000000000000000","chainId":8453}
 ```
 
 The `--unsigned` flag outputs a standard `{to, data, value, chainId}` payload compatible with any signer that accepts arbitrary transactions.
-When `SIGNER_ADDRESS` is set, `veil register --unsigned` no longer requires the `--address` flag.
+When `SIGNER_ADDRESS` is set, `veil register --unsigned` and `veil deposit --unsigned` no longer require the `--address` flag.
 For `veil register --unsigned --force`, the CLI checks on-chain registration state first and emits `changeDepositKey` only when the address is already registered; otherwise it falls back to `register`.
 
 ### Programmatic SDK Usage