@veil-cash/sdk 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veil-cash/sdk",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "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

@@ -165,7 +165,7 @@ What do you want to do?
 |
 +-- Register deposit key on-chain     → veil register [--unsigned]
 |
-+-- Deposit ETH or USDC               → veil deposit <asset> <amount> [--unsigned]
++-- Deposit ETH or USDC               → veil deposit <asset> <amount> [--unsigned --address 0x...]
 |
 +-- Check balances                    → veil balance [queue|private] [--pool eth|usdc]
 |
@@ -330,7 +330,9 @@ Important:
   - If not yet registered, returns a normal `register` payload.
 
 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.
+Each address gets a configurable number of fee-free deposits per UTC day.
+The CLI checks automatically — if free slots remain the fee is waived;
+otherwise the `0.3%` protocol fee is calculated on-chain and added.
 After submission, deposits go through screening / queue processing before they
 are accepted into the private pool. This typically takes around `10-15 minutes`.
 
@@ -338,8 +340,8 @@ are accepted into the private pool. This typically takes around `10-15 minutes`.
 veil deposit ETH 0.1
 veil deposit USDC 100
 veil deposit ETH 0.1 --json
-veil deposit ETH 0.1 --unsigned
-veil deposit USDC 100 --unsigned
+veil deposit ETH 0.1 --unsigned --address 0x...
+SIGNER_ADDRESS=0x... veil deposit USDC 100 --unsigned
 ```
 
 Minimums:

package/skills/veil/reference.md

@@ -258,8 +258,8 @@ SIGNER_ADDRESS=0x... veil register --unsigned --force # Unsigned register/change
 veil register --unsigned --address 0x...           # Unsigned register payload (explicit address)
 veil register --json                               # Register and output result as JSON
 
-veil deposit ETH 0.1 --unsigned                    # Unsigned ETH deposit payload
-veil deposit USDC 100 --unsigned                   # Unsigned USDC deposit payload(s)
+veil deposit ETH 0.1 --unsigned --address 0x...    # Unsigned ETH deposit payload
+SIGNER_ADDRESS=0x... veil deposit USDC 100 --unsigned # Unsigned USDC deposit payload(s)
 veil deposit ETH 0.1 --json                        # Deposit and output result as JSON
 
 veil balance                                       # All pool balances
@@ -307,10 +307,10 @@ Common codes: `VEIL_KEY_MISSING`, `WALLET_KEY_MISSING`, `DEPOSIT_KEY_MISSING`,
 
 | Asset | Minimum (net) | Notes |
 |-------|--------------|-------|
-| ETH | 0.01 | Fee (0.3%) added automatically via on-chain `getDepositAmountWithFee` |
-| USDC | 10 | Fee (0.3%) added automatically via on-chain `getDepositAmountWithFee` |
+| ETH | 0.01 | Fee (0.3%) added automatically, or waived if daily free deposits remain |
+| USDC | 10 | Fee (0.3%) added automatically, or waived if daily free deposits remain |
 
-The CLI amount is the **net** amount that lands in the pool. The fee is calculated on-chain and added to the transaction automatically — users do not need to account for it.
+The CLI amount is the **net** amount that lands in the pool. The CLI checks `getDailyFreeRemaining` on the queue contract — if the user has free slots left today the fee is skipped; otherwise the 0.3% fee is calculated on-chain and added to the transaction automatically.
 
 ---
 

package/src/abi.ts

@@ -218,6 +218,14 @@ export const QUEUE_ABI = [
     stateMutability: 'view',
     type: 'function',
   },
+  // Get remaining daily free deposits for an address (V3+)
+  {
+    inputs: [{ name: '_depositor', type: 'address' }],
+    name: 'getDailyFreeRemaining',
+    outputs: [{ name: 'remaining', type: 'uint256' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
 ] as const;
 
 /**

package/src/balance.ts

@@ -127,6 +127,54 @@ export async function getQueueBalance(options: {
   };
 }
 
+/**
+ * Get remaining daily free deposits for an address.
+ * Returns 0 if the queue contract has not been upgraded to V3 yet
+ * or if the daily free feature is disabled.
+ *
+ * @param options - Query options
+ * @param options.address - Depositor address to check
+ * @param options.pool - Pool identifier ('eth' or 'usdc', default: 'eth')
+ * @param options.rpcUrl - Optional RPC URL
+ * @returns Number of free deposits remaining today
+ *
+ * @example
+ * ```typescript
+ * const remaining = await getDailyFreeRemaining({
+ *   address: '0x...',
+ *   pool: 'eth',
+ * });
+ * console.log(`Free deposits left today: ${remaining}`);
+ * ```
+ */
+export async function getDailyFreeRemaining(options: {
+  address: `0x${string}`;
+  pool?: RelayPool;
+  rpcUrl?: string;
+}): Promise<number> {
+  const { address, pool = 'eth', rpcUrl } = options;
+  const queueAddress = getQueueAddress(pool);
+
+  const publicClient = createPublicClient({
+    chain: base,
+    transport: http(rpcUrl),
+  });
+
+  try {
+    const remaining = await publicClient.readContract({
+      address: queueAddress,
+      abi: QUEUE_ABI,
+      functionName: 'getDailyFreeRemaining',
+      args: [address],
+    }) as bigint;
+
+    return Number(remaining);
+  } catch {
+    // V2 contracts don't have this function — treat as 0 remaining
+    return 0;
+  }
+}
+
 /**
  * Get private balance from the Pool contract
  * Decrypts all encrypted outputs, calculates nullifiers, and checks spent status

package/src/cli/commands/deposit.ts

@@ -4,8 +4,9 @@
 
 import { Command } from 'commander';
 import { buildDepositETHTx, buildDepositUSDCTx, buildApproveUSDCTx } from '../../deposit.js';
+import { getDailyFreeRemaining } from '../../balance.js';
 import { sendTransaction, getAddress, getBalance } from '../wallet.js';
-import { getConfig } from '../config.js';
+import { getConfig, resolveAddress } from '../config.js';
 import { createPublicClient, http, parseEther, parseUnits, formatEther, formatUnits } from 'viem';
 import { base } from 'viem/chains';
 import { handleCLIError, CLIError, ErrorCode } from '../errors.js';
@@ -13,6 +14,7 @@ import { clearProgress, createProgressReporter, printFields, printHeader, printJ
 import { POOL_CONFIG, getAddresses } from '../../addresses.js';
 import { ENTRY_ABI, ERC20_ABI } from '../../abi.js';
 import type { TransactionData } from '../../types.js';
+import type { WalletConfig } from '../wallet.js';
 
 const MINIMUM_NET: Record<string, number> = {
   ETH: 0.01,
@@ -20,13 +22,22 @@ const MINIMUM_NET: Record<string, number> = {
 };
 
 /**
- * Query the Entry contract for the exact gross amount (net + fee).
- * This matches the contract's own fee math and avoids rounding mismatches.
+ * Compute the gross amount and fee for a deposit.
+ * Checks daily free deposit availability first — if the user has
+ * free slots remaining the fee is waived and gross === net.
  */
 async function getGrossAmount(
   netWei: bigint,
+  depositor: `0x${string}`,
+  pool: 'eth' | 'usdc',
   rpcUrl: string | undefined,
-): Promise<{ grossWei: bigint; feeWei: bigint }> {
+): Promise<{ grossWei: bigint; feeWei: bigint; dailyFreeUsed: boolean; dailyFreeRemaining: number }> {
+  const freeRemaining = await getDailyFreeRemaining({ address: depositor, pool, rpcUrl });
+
+  if (freeRemaining > 0) {
+    return { grossWei: netWei, feeWei: 0n, dailyFreeUsed: true, dailyFreeRemaining: freeRemaining - 1 };
+  }
+
   const publicClient = createPublicClient({
     chain: base,
     transport: http(rpcUrl),
@@ -39,7 +50,7 @@ async function getGrossAmount(
     args: [netWei],
   }) as bigint;
 
-  return { grossWei, feeWei: grossWei - netWei };
+  return { grossWei, feeWei: grossWei - netWei, dailyFreeUsed: false, dailyFreeRemaining: 0 };
 }
 
 const SUPPORTED_ASSETS = ['ETH', 'USDC'];
@@ -49,16 +60,19 @@ export function createDepositCommand(): Command {
     .description('Deposit ETH or USDC into Veil')
     .argument('<asset>', 'Asset to deposit (ETH or USDC)')
     .argument('<amount>', 'Amount to deposit — this is what arrives in your Veil balance')
+    .option('--address <address>', 'Signer address (required in --unsigned mode unless SIGNER_ADDRESS or WALLET_KEY is set)')
     .option('--unsigned', 'Output unsigned transaction payload instead of sending')
     .option('--json', 'Output as JSON')
     .addHelpText('after', `
 The amount you specify is the net amount that lands in your Veil balance.
-The 0.3% protocol fee is automatically added on top.
+A 0.3% protocol fee is normally added on top, but each address gets
+free daily deposits (fee waived). The CLI checks automatically.
 
 Examples:
-  veil deposit ETH 0.1          # deposits 0.1 ETH (sends ~0.1003 ETH)
-  veil deposit USDC 100         # deposits 100 USDC (sends ~100.30 USDC)
-  veil deposit ETH 0.1 --unsigned
+  veil deposit ETH 0.1          # deposits 0.1 ETH (free or ~0.1003 ETH)
+  veil deposit USDC 100         # deposits 100 USDC (free or ~100.30 USDC)
+  veil deposit ETH 0.1 --unsigned --address 0x...
+  SIGNER_ADDRESS=0x... veil deposit ETH 0.1 --unsigned
   veil deposit ETH 0.1 --json
 `)
     .action(async (asset: string, amount: string, options) => {
@@ -80,15 +94,41 @@ Examples:
         }
 
         const rpcUrl = process.env.RPC_URL;
-        const poolConfig = POOL_CONFIG[assetUpper.toLowerCase() as 'eth' | 'usdc'];
+        const pool = assetUpper.toLowerCase() as 'eth' | 'usdc';
+        const poolConfig = POOL_CONFIG[pool];
         const netWei = assetUpper === 'ETH'
           ? parseEther(amount)
           : parseUnits(amount, poolConfig.decimals);
 
         const progress = createProgressReporter();
-        progress('Calculating fee...');
 
-        const { grossWei, feeWei } = await getGrossAmount(netWei, rpcUrl);
+        let config: WalletConfig | null = null;
+        let address: `0x${string}`;
+        let feeRpcUrl = rpcUrl;
+
+        if (options.unsigned) {
+          const resolved = resolveAddress({ address: options.address }, { required: true });
+          if (!resolved) {
+            throw new CLIError(
+              ErrorCode.WALLET_KEY_MISSING,
+              'Must provide --address, set SIGNER_ADDRESS, or set WALLET_KEY env.',
+            );
+          }
+          address = resolved.address;
+        } else {
+          config = getConfig(options);
+          address = getAddress(config.privateKey);
+          feeRpcUrl = config.rpcUrl;
+        }
+
+        progress('Checking deposit fee...');
+
+        const { grossWei, feeWei, dailyFreeUsed, dailyFreeRemaining } = await getGrossAmount(
+          netWei,
+          address,
+          pool,
+          feeRpcUrl,
+        );
         const grossStr = assetUpper === 'ETH'
           ? formatEther(grossWei)
           : formatUnits(grossWei, poolConfig.decimals);
@@ -140,8 +180,9 @@ Examples:
           return;
         }
 
-        const config = getConfig(options);
-        const address = getAddress(config.privateKey);
+        if (!config) {
+          throw new CLIError(ErrorCode.WALLET_KEY_MISSING, 'WALLET_KEY env var required. Set it before running this command.');
+        }
 
         if (assetUpper === 'ETH') {
           progress('Checking balance...');
@@ -203,6 +244,7 @@ Examples:
           asset: assetUpper,
           amount,
           fee: feeStr,
+          dailyFreeUsed,
           totalSent: grossStr,
           blockNumber: result.receipt.blockNumber.toString(),
         };
@@ -212,11 +254,15 @@ Examples:
           return;
         }
 
+        const feeLabel = dailyFreeUsed
+          ? `0 ${assetUpper} (free — ${dailyFreeRemaining} remaining today)`
+          : `${feeStr} ${assetUpper} (0.3%)`;
+
         printHeader('Deposit Submitted');
         printFields([
           { label: 'Asset', value: assetUpper },
           { label: 'Amount', value: `${amount} ${assetUpper}` },
-          { label: 'Fee', value: `${feeStr} ${assetUpper} (0.3%)` },
+          { label: 'Fee', value: feeLabel },
           { label: 'Total sent', value: `${grossStr} ${assetUpper}` },
           { label: 'From', value: address },
           { label: 'Transaction', value: txUrl(result.hash) },

package/src/index.ts

@@ -53,6 +53,7 @@ export {
 export {
   getQueueBalance,
   getPrivateBalance,
+  getDailyFreeRemaining,
 } from './balance.js';
 export type { ProgressCallback } from './balance.js';