@veil-cash/sdk 0.6.4 → 0.7.0

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.7.0` adds Coinbase-compatible x402 payments from private USDC balances via deterministic fresh payer EOAs.
+
 `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.
@@ -91,7 +93,10 @@ 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
+# 9. Pay an x402 resource from private USDC in application code
+# See SDK.md for payX402Resource().
+
+# 10. Use JSON or unsigned modes when you need automation
 veil status --json
 veil deposit ETH 0.1 --unsigned --address 0x...
 veil subaccount status --slot 0 --json
@@ -142,11 +147,11 @@ 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. A 0.3% protocol fee is normally added on top, but each address gets free daily deposits (fee waived). The CLI checks 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 added on top:
 
 ```bash
-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            # 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 --json
 veil deposit ETH 0.1 --unsigned --address 0x...
 SIGNER_ADDRESS=0x... veil deposit ETH 0.1 --unsigned
@@ -205,6 +210,43 @@ veil merge USDC 100
 veil merge ETH 0.1 --json
 ```
 
+Pay a Coinbase-compatible x402 resource from private USDC:
+
+```typescript
+import { payX402Resource } from '@veil-cash/sdk';
+
+const result = await payX402Resource({
+  url: 'https://merchant.example/paid-resource',
+  rootPrivateKey: process.env.VEIL_KEY as `0x${string}`,
+  payerIndex: 0n,
+  maxPayment: '0.10', // reject if the resource demands more than 0.10 USDC
+  relayUrl: process.env.X402_RELAY_URL,
+  rpcUrl: process.env.RPC_URL,
+});
+
+console.log(result.response.status, result.payerAddress);
+```
+
+The helper withdraws the exact x402 amount to a deterministic fresh payer EOA,
+then signs a standard x402 v2 Base USDC `exact` payment from that EOA. Use a
+new `payerIndex` per payment. Pass `maxPayment` (a decimal USDC string) to cap
+exposure; the payment is rejected before any funds move if the requirement
+exceeds the cap. The withdrawal and payment legs are public and can be correlated
+by amount and timing, but the source private balance remains hidden.
+
+Use `quoteX402Resource({ url, rpcUrl, maxPayment, init })` to probe a resource
+for its price and payment requirement without funding a payer or paying. It
+returns the parsed requirement for a supported `402` or the raw status/body
+otherwise.
+
+If a payment is funded but delivery fails, the USDC stays on the payer EOA. Retry
+with `reuseExistingBalance: true` and the same `payerIndex` to pay from that
+balance without a second withdrawal; it throws if the balance is insufficient.
+
+To surface funds left on a payer after a failed payment, use
+`getX402PayerBalances({ rootPrivateKey, startIndex, count, nonZeroOnly })`, which
+returns the Base USDC balance of each derived payer EOA. It is read-only.
+
 ### Subaccounts
 
 Subaccounts are deterministic child slots derived from your main `VEIL_KEY`:
@@ -297,7 +339,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 fee is waived if you have daily free deposits remaining, otherwise 0.3% 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; a 0.3% protocol fee is added on top automatically)
 6. **Wait**: The Veil deposit engine processes your deposit
 7. **Done**: Your deposit is accepted into the privacy pool
 

package/SDK.md

@@ -11,6 +11,7 @@ import {
   Keypair, buildRegisterTx, buildDepositETHTx,
   buildDepositUSDCTx, buildApproveUSDCTx,
   withdraw, transfer, getSubaccountStatus, mergeSubaccount,
+  payX402Resource,
 } from '@veil-cash/sdk';
 import { createWalletClient, http } from 'viem';
 import { base } from 'viem/chains';
@@ -72,6 +73,14 @@ const subaccount = await getSubaccountStatus({
 });
 console.log(subaccount.slot.forwarderAddress);
 
+// 8. Pay an x402 resource from private USDC
+const paid = await payX402Resource({
+  url: 'https://merchant.example/paid-resource',
+  rootPrivateKey: keypair.privkey as `0x${string}`,
+  payerIndex: 0n,
+  relayUrl: process.env.X402_RELAY_URL,
+});
+console.log(paid.response.status, paid.payerAddress);
 ```
 
 ## SDK API Reference
@@ -109,10 +118,9 @@ 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).
+The CLI treats deposit amounts as net amounts and adds the 0.3% protocol fee
+automatically. The low-level transaction builders use the amount you pass as the
+gross amount sent to the Entry contract.
 
 ```typescript
 import {
@@ -182,6 +190,70 @@ const mergeResult = await mergeUtxos({
 });
 ```
 
+### x402 Payments
+
+`payX402Resource()` pays standard x402 v2 Base USDC `exact` resources from a
+private Veil USDC balance while remaining compatible with Coinbase-facilitated
+merchants.
+
+```typescript
+import {
+  deriveX402PayerAddress,
+  payX402Resource,
+  usdcAtomicToDecimalString,
+} from '@veil-cash/sdk';
+
+const payerAddress = deriveX402PayerAddress(
+  process.env.VEIL_KEY as `0x${string}`,
+  42n,
+);
+
+const amount = usdcAtomicToDecimalString('1000'); // "0.001"
+
+const result = await payX402Resource({
+  url: 'https://merchant.example/paid-resource',
+  rootPrivateKey: process.env.VEIL_KEY as `0x${string}`,
+  payerIndex: 42n,
+  maxPayment: '0.10', // cap exposure; reject if the resource demands more
+  relayUrl: process.env.X402_RELAY_URL,
+  rpcUrl: process.env.RPC_URL,
+  onProgress: (stage, detail) => console.log(stage, detail),
+});
+
+console.log({
+  status: result.response.status,
+  payerAddress: result.payerAddress,
+  relayTx: result.relayTransactionHash,
+  paymentTx: result.paymentTransactionHash,
+});
+```
+
+The payer key uses the `veil-x402-payer` derivation domain, separate from
+subaccounts. Use a fresh, persisted `payerIndex` for each payment. Set
+`maxPayment` (a decimal USDC string) to cap exposure; the payment is rejected
+before any funds move if the requirement exceeds the cap. The helper currently
+supports x402 v2 `exact` requirements on Base mainnet USDC only; it rejects other
+assets, networks, and schemes.
+
+`quoteX402Resource({ url, rpcUrl, maxPayment, init })` probes a resource without
+funding a payer or signing a payment. For a supported `402` it returns the price
+and requirement (`amount`, `amountAtomic`, `payTo`, `network`, `asset`, and
+`exceedsMax` when `maxPayment` is set); for any other status it returns the raw
+`status` and parsed `body`. Use it to validate a request and confirm cost before
+committing a withdrawal. A merchant that validates the request body only after
+payment will still return `402` here, so a quote cannot catch post-payment errors.
+
+To retry a payment whose funding succeeded but whose delivery failed (the USDC is
+still on the payer EOA), pass `reuseExistingBalance: true` with the same
+`payerIndex`. When the payer already holds at least the required amount,
+`payX402Resource` skips the withdrawal and pays directly from that balance
+(`relayTransactionHash` is empty); it throws if the balance is insufficient.
+
+`getX402PayerBalances({ rootPrivateKey, startIndex, count, nonZeroOnly })`
+inspects the Base USDC balance held by each derived payer EOA, which is useful
+for surfacing funds left on a payer after a failed payment. It is read-only and
+does not move funds.
+
 ### Browser Proof Generation
 
 `withdraw()`, `transfer()`, `mergeUtxos()`, `mergeSubaccount()`, `buildWithdrawProof()`,
@@ -232,7 +304,7 @@ such as `circomlib`, `eth-sig-util`, and `fixed-merkle-tree`.
 Balance functions accept an optional `pool` parameter (`'eth'` | `'usdc'`), defaulting to `'eth'`.
 
 ```typescript
-import { getQueueBalance, getPrivateBalance, getDailyFreeRemaining } from '@veil-cash/sdk';
+import { getQueueBalance, getPrivateBalance } from '@veil-cash/sdk';
 
 // Check ETH queue balance (pending deposits)
 const queueBalance = await getQueueBalance({
@@ -246,12 +318,6 @@ const privateBalance = await getPrivateBalance({
   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