@veil-cash/sdk 0.6.2 → 0.6.4

package/README.md

@@ -93,7 +93,7 @@ veil subaccount recover --slot 0 --asset usdc --to 0xRecipientAddress --amount 2
 
 # 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
 ```
 
@@ -142,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
@@ -287,6 +288,7 @@ Commands print human-readable success output by default. Errors are standardized
 The CLI is the main entrypoint for most users. If you are integrating Veil programmatically, use the dedicated SDK guide:
 
 - [SDK Quick Start and API Reference](./SDK.md)
+- [Browser proof generation](./SDK.md#browser-proof-generation)
 - [AI agent and signer integration notes](./SDK.md#for-ai-agents)
 
 ## Deposit Flow
@@ -295,7 +297,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

@@ -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,
@@ -177,12 +182,57 @@ const mergeResult = await mergeUtxos({
 });
 ```
 
+### Browser Proof Generation
+
+`withdraw()`, `transfer()`, `mergeUtxos()`, `mergeSubaccount()`, `buildWithdrawProof()`,
+`buildTransferProof()`, and `prepareTransaction()` can generate proofs in browser
+runtimes.
+
+In Node, the SDK uses the packaged `keys/` directory by default. In browsers,
+the SDK defaults to same-origin hosted proving keys:
+
+```text
+/keys/transaction2.wasm
+/keys/transaction2.zkey
+/keys/transaction16.wasm
+/keys/transaction16.zkey
+```
+
+For most web apps, copy the SDK `keys/` files into your app's public assets
+directory. For example, in Next.js/Vite, serving them from `public/keys` makes
+the default path work.
+
+If you host keys elsewhere, pass `provingKeyPath`:
+
+```typescript
+await withdraw({
+  amount: '0.05',
+  recipient: '0xRecipientAddress',
+  keypair,
+  provingKeyPath: 'https://cdn.example.com/veil-keys',
+});
+
+await transfer({
+  amount: '0.02',
+  recipientAddress: '0xRecipientAddress',
+  senderKeypair: keypair,
+  provingKeyPath: (circuitName) => `/static/zk/${circuitName}`,
+});
+```
+
+`provingKeyPath` may be a directory/base URL (`/keys`) or a resolver returning
+the circuit base path without the `.wasm` / `.zkey` extension.
+
+This removes Node `fs` key lookup from the browser proof path. Some bundlers
+may still require standard Node-core polyfills for existing legacy dependencies
+such as `circomlib`, `eth-sig-util`, and `fixed-merkle-tree`.
+
 ### Balance Queries
 
 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 +245,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
@@ -291,8 +348,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
@@ -344,12 +401,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