@blackpool/cli 0.4.1 → 0.4.3

package/AGENTS.md

@@ -134,8 +134,15 @@ Private payment to any EVM address on the same chain. `amount` is what leaves yo
 ```
 To make the recipient receive exactly `X`, send `(X + flat) / (1 − 0.0035)` rounded up (see §5).
 
+`amount` can be `max`: the whole private balance of `--pool`, of every pool on the chain when `--pool` is omitted, or of every pool on every chain with `--chain all`. A send spends at most two notes, so a balance spread over more notes goes out in several sends; a balance at or below twice its fee is left as dust.
+```json
+{"ok":true,"command":"send","recipient":"0x…","amount":"max","sends":[{"chain":"bsc","pool":"usdt","amount":"12.253307487806713664",
+ "received":"11.7104…","fee":"0.5428…","txHash":"0x…"}],"received":{"USDT":"11.7104…"},"dust":[],"errors":[]}
+```
+
 ### `swap <amount> --from P [--chain C] [--slippage BPS]`
 Private same-chain swap between the chain's native pool and stablecoin pool; the output is re-shielded into your private balance. `--slippage` in basis points, default `100` (1%). No gas needed. ~1–3 min.
+`amount` can be `max`: the most one swap can move (its two largest notes). If the balance is spread over more notes, the output says what is left; run `swap max` again for the rest.
 ```json
 {"ok":true,"command":"swap","chain":"base","from":"eth","amount":0.01,"received":"22.41",
  "symbol":"USDC","txHash":"0x…","explorer":"https://basescan.org/tx/0x…","privateBalance":"36.375"}
@@ -144,6 +151,7 @@ If it fails half-way, funds sit on a registered burner: run `recover`.
 
 ### `bridge <dest-asset> <recipient> <amount> --from ORIGIN [--no-wait]`
 Private cross-chain transfer through NEAR Intents. `ORIGIN` is the private pool paying (default `base_usdc`); `dest-asset` and recipient format are listed in §6. The withdrawal is private; the solver delivers on the destination chain. Without `--no-wait` the CLI polls up to 6 minutes.
+`amount` can be `max`: the most one bridge can move from the `--from` pool (its two largest notes); the route minimum still applies.
 ```json
 {"ok":true,"command":"bridge","from":"base_usdc","to":"sol_usdc","recipient":"7Gx4…kQ2m","amount":10,
  "amountOutQuote":"8.91","withdrawTx":"0x…","depositAddress":"0x…","statusUrl":"https://…",
@@ -419,6 +427,8 @@ Use the hosted server to plan (fees, routes, quotes, status) and the local serve
 | `insufficient` / `no unspent` | Private balance too low | `balance`, then `deposit` more. |
 | `Withdrawal must be more than twice the fee` | Amount too close to the fee | Larger amount. |
 | `Amount is too low for this route. Minimum is …` | Solver minimum for that bridge | Bridge at least that much. |
+| `This route needs at least $… right now` | Temporary USD floor the solver network sets on a route (code `ROUTE_MINIMUM`; currently every route to or from BNB Chain) | Bridge at least that much or pick another destination. Nothing left the private balance. |
+| `No route for this pair right now` | No solver quotes the pair (code `NO_ROUTE`) | Pick another token or chain. |
 | `rate limited, slow down` | API limit (40 relay ops, 600 reads per minute per IP) | The CLI already waited and retried 4 times; pause a minute. |
 | `simulation failed: …` | The relayer refused a transaction that would revert | Do not retry blindly; check `balance`; report the message. |
 | `reshield would revert` / `swap output … too small` | Swap stopped after funds reached the burner | `recover`, then `deposit` again. |

package/README.md

@@ -1,6 +1,6 @@
 # @blackpool/cli
 
-Private payments for onchain agents. One env var or one hidden prompt, then shield / send / swap / bridge with zero-knowledge privacy on **Base**, **Robinhood Chain**, **Arbitrum**, and **BNB Smart Chain**. Wraps the same API `docs.blackpool.cash/agents` uses - no ZK client needed on your side.
+Private payments for onchain agents. One env var or one hidden prompt, then shield / send / swap / bridge with zero-knowledge privacy on **Base**, **Robinhood Chain**, **Arbitrum**, and **BNB Smart Chain**. Proofs are built on your machine, the same way the web app does it; the full agent guide is [AGENTS.md](https://blackpool.cash/AGENTS.md).
 
 Every command takes an optional `--chain base|robinhood|arbitrum|bsc` flag (default `base`). On Base and Arbitrum the stablecoin is USDC; on Robinhood it's USDG; on BSC the stablecoins are USDC and USDT (Binance-Peg, 18 decimals) and the native asset is BNB.
 
@@ -57,20 +57,22 @@ blackpool deposit 0.05 --pool bnb --chain bsc       # shield BNB (BSC native poo
 blackpool send 0xRECIPIENT 2.5               # send 2.5 USDC privately (no gas from you)
 blackpool send 0xRECIPIENT 0.01 --pool eth   # send private ETH
 blackpool send 0xRECIPIENT 2.5 --chain robinhood    # send 2.5 USDG privately on Robinhood
+blackpool send 0xRECIPIENT max --pool usdt --chain bsc  # send the whole private USDT balance
+blackpool send 0xRECIPIENT max --chain all   # empty every private pool on every chain into one address
 blackpool swap 0.001 --from eth              # private same-chain swap ETH -> USDC (Uniswap V3)
 blackpool swap 3 --from usdc                 # private same-chain swap USDC -> ETH
+blackpool swap max --from eth --chain arbitrum      # swap as much private ETH as one swap can move
 blackpool bridge arb_usdc 0xRECIPIENT 2.5    # bridge cross-chain privately to Arbitrum (1Click)
 blackpool bridge bsc_usdt 0xRECIPIENT 5 --from bsc_usdc  # 1Click origin can be any shielded pool
-blackpool bridge rarb_eth 0xRECIPIENT 0.01 --chain robinhood  # router: Robinhood -> Arbitrum
-blackpool bridge rbsc_bnb 0xRECIPIENT 0.01 --chain robinhood  # router: Robinhood -> BSC
+blackpool bridge base_eth 0xRECIPIENT max --from hood_eth  # bridge as much as one bridge can move
 blackpool assets                             # list all supported bridge destinations
-blackpool recover                            # sweep any stranded funds from burner slots
+blackpool recover                            # sweep any stranded funds from one-time burners
 blackpool recover --to 0xADDR                # sweep to a different destination
 ```
 
 ## How it works
 
-Each command follows the pattern `docs.blackpool.cash/agents` documents.
+Each command follows the pattern [AGENTS.md](https://blackpool.cash/AGENTS.md) documents.
 
 **Login / balance / send / bridge** - you sign once; the CLI scans your notes and builds the Groth16 proof locally (the 20 MB proving key is downloaded once to `~/.blackpool/zk/`), then the relayer broadcasts it. You pay no gas. The relayer is compensated via the protocol fee (flat + 0.35% per withdraw / swap / bridge).
 

package/bin/blackpool.js

@@ -5,7 +5,7 @@
  * Usage:
  *   blackpool login              -- sign BLACKPOOL message, cache signature for this wallet
  *   blackpool balance [--pool p] -- print private balance
- *   blackpool send <to> <amount> -- send privately to an address
+ *   blackpool send <to> <amount> -- send privately to an address (amount "max" = the whole private balance)
  *
  * Auth: BLACKPOOL_KEY env var (agent private key, hex). No mnemonic support in MVP.
  * Config: ~/.blackpool/config.json stores cached signatures (per address).
@@ -454,6 +454,10 @@ async function broadcastAndWait(signer, provider, txRequest, { label = 'transact
       if (i < 5) await new Promise(r => setTimeout(r, 700 * (i + 1)))
     }
   }
+  if (!sent) {
+    // The node may have accepted the tx and still answered with an error: look for it before giving up.
+    try { if (await withRpcRetry(() => provider.getTransaction(txHash), { label: `${label} (lookup)` })) sent = true } catch {}
+  }
   if (!sent) throw new Error(`${label}: could not broadcast after repeated connection drops`)
 
   // Poll for the receipt ourselves (retrying connection errors) instead of tx.wait(), which throws
@@ -486,13 +490,26 @@ async function chainGasOverrides(provider, chain) {
     return { gasPrice: gp }
   }
   const cap = ethers.utils.parseUnits(CHAINS[chain].gasCapGwei, 'gwei')
+  const minPrio = ethers.utils.parseUnits('0.001', 'gwei')
+  // 2 x baseFee + tip, like wallets do. Not getFeeData(): ethers v5 adds a 1.5 gwei tip, which then hits the cap
+  // (0.5 gwei on Arbitrum, ~50x the real price) and makes the node reject value + gas x maxFee as unaffordable.
   let netMax
-  try { const fd = await provider.getFeeData(); netMax = fd.maxFeePerGas } catch {}
+  try { const b = await provider.getBlock('latest'); if (b && b.baseFeePerGas) netMax = b.baseFeePerGas.mul(2).add(minPrio) } catch {}
+  if (!netMax) { try { const fd = await provider.getFeeData(); netMax = fd.maxFeePerGas } catch {} }
   const maxFeePerGas = netMax && netMax.lt(cap) ? netMax : cap
-  const minPrio = ethers.utils.parseUnits('0.001', 'gwei')
   const maxPriorityFeePerGas = maxFeePerGas.lt(minPrio) ? maxFeePerGas : minPrio
   return { maxFeePerGas, maxPriorityFeePerGas }
 }
+// Burner txs inside one swap: 2 x baseFee + tip (headroom for the minute or two the swap takes), capped.
+async function burnerFees(provider, chain) {
+  if (CHAINS[chain].legacyGas) return chainGasOverrides(provider, chain)
+  const cap = ethers.utils.parseUnits(CHAINS[chain].gasCapGwei, 'gwei')
+  const tip = ethers.utils.parseUnits('0.001', 'gwei')
+  let want
+  try { const b = await provider.getBlock('latest'); if (b && b.baseFeePerGas) want = b.baseFeePerGas.mul(2).add(tip) } catch {}
+  const maxFeePerGas = want && want.lt(cap) ? want : cap
+  return { maxFeePerGas, maxPriorityFeePerGas: maxFeePerGas.lt(tip) ? maxFeePerGas : tip }
+}
 // Sync version (fixed chain cap, no network fetch) — for burner txs where we set an explicit gasLimit
 // and just need a chain-realistic price. Replaces the old Base-only baseGasOverrides().
 function chainGasOverridesSync(chain) {
@@ -680,7 +697,7 @@ async function cmdDeposit(args) {
   info('preparing deposit (the proof is generated on this machine)...')
 
   const prep = await apiPost('/api/deposit/prepare', {
-    signature: sig, address: wallet.address, amount: n, pool, chain,
+    signature: sig, address: wallet.address, amount: String(amount), pool, chain,
   }, { timeoutMs: 180_000 })
 
   // ERC pool with insufficient allowance -> approve first
@@ -828,6 +845,53 @@ async function waitTokenBalance(provider, tokenAddr, addr, min, retries = 60) {
   throw new Error(`token balance never reached on ${addr}`)
 }
 // Poll until ETH balance >= minimum. Mirrors frontend e9().
+// After a swap's reshield: send the burner's unused gas back to the relayer that advanced it, so the burner ends
+// empty. Keeps only the cost of this transfer (+30%, plus an L1 data-fee cushion on Base). Never fails the swap.
+async function returnUnusedGas(burner, provider, chain, afterBlock) {
+  try {
+    const cfg = await apiGet('/api/zk/config')
+    const to = cfg && cfg.relayer
+    if (!to || !/^0x[a-fA-F0-9]{40}$/.test(to)) return
+    const fees = await burnerFees(provider, chain)
+    const fee = fees.maxFeePerGas || fees.gasPrice
+    let bal = await settledBalance(provider, burner.address, { atBlock: afterBlock, label: 'burner balance' })
+    let gas = ethers.BigNumber.from(21_000)
+    try { gas = await provider.estimateGas({ from: burner.address, to, value: 1 }) } catch {}
+    const gasLimit = gas.mul(13).div(10)
+    const l1Cushion = chain === 'base' ? ethers.utils.parseUnits('2000', 'gwei') : ethers.BigNumber.from(0) // OP-stack L1 data fee
+    let keep = gasLimit.mul(fee).add(l1Cushion)
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (bal.lte(keep.mul(2))) return // nothing worth moving
+      const value = bal.sub(keep)
+      try {
+        await broadcastAndWait(burner, provider, { to, value, gasLimit, ...fees }, { label: 'return unused gas' })
+        info(`returned ${ethers.utils.formatEther(value)} unused gas to the relayer (burner is empty)`)
+        return
+      } catch (e) {
+        if (attempt === 2 || !/insufficient funds/i.test(String(e && (e.reason || e.message) || ''))) throw e
+        await new Promise(r => setTimeout(r, 3000))
+        bal = await provider.getBalance(burner.address) // the node may have been a block behind
+        keep = keep.mul(2)
+      }
+    }
+  } catch (e) {
+    info(`could not return the unused gas (${cleanErr(e)}); \`blackpool recover\` can sweep it later`)
+  }
+}
+
+// Balance as of `atBlock` (a load-balanced RPC can answer "latest" from a node a block behind). A node without that
+// block errors, so retry; after a few tries fall back to "latest". With `min`, wait until the balance reaches it.
+async function settledBalance(provider, addr, { atBlock, min, label = 'balance' } = {}) {
+  for (let i = 0; i < 60; i++) {
+    try {
+      const b = await provider.getBalance(addr, atBlock != null && i < 12 ? atBlock : 'latest')
+      if (!min || b.gte(min)) return b
+    } catch {}
+    await new Promise(r => setTimeout(r, 2500))
+  }
+  throw new Error(`${label} never arrived on ${addr}`)
+}
+
 async function waitEthBalance(provider, addr, min, label = 'eth') {
   for (let i = 0; i < 80; i++) {
     const b = await provider.getBalance(addr)
@@ -868,6 +932,11 @@ const BRIDGE_ORIGINS = {
 // blackpool bridge <destAssetKey> <recipient> <amount> [--from ...] [--chain ...]
 // Every destination uses the NEAR Intents 1Click flow (/api/swap + poll) — Robinhood included.
 async function cmdBridge(args) {
+  if (/^(max|all)$/i.test(String(args[2] || ''))) {
+    const o = BRIDGE_ORIGINS[getFlag(args, '--from') || 'base_usdc']
+    if (!o) fail(`unknown --from "${getFlag(args, '--from')}" (1Click origins: ${Object.keys(BRIDGE_ORIGINS).join(', ')})`)
+    args = [...args]; args[2] = await resolveMaxAmount(o.chain, o.pool, 'bridge')
+  }
   const toAsset = args[0]
   const recipient = args[1]
   const amount = args[2]
@@ -910,7 +979,7 @@ async function cmdBridge(args) {
   info('quote + groth16 proof + private withdraw to solver... can take ~1-2 min')
 
   const res = await apiPost('/api/swap', {
-    signature: sig, fromAsset, toAsset, amount: n, recipient,
+    signature: sig, fromAsset, toAsset, amount: String(amount), recipient,
     refundTo: wallet.address, // Solana/XRP recipients: solver refunds (origin chain) come back to this wallet
   }, { timeoutMs: 180_000 })
 
@@ -1074,6 +1143,11 @@ async function cmdRecover(args) {
 }
 
 async function cmdSwap(args) {
+  if (/^(max|all)$/i.test(String(args[0] || ''))) {
+    const fromPool = getFlag(args, '--from')
+    if (!fromPool) fail('usage: blackpool swap max --from <pool> [--chain C]', 2)
+    args = [...args]; args[0] = await resolveMaxAmount(resolveChain(args), fromPool, 'swap')
+  }
   const chain = resolveChain(args)
   const C = CHAINS[chain]
   const amount = args[0]
@@ -1093,7 +1167,8 @@ async function cmdSwap(args) {
   // per-chain Uniswap V3 + token addresses (registry)
   const U = { router: C.uni.router, quoter: C.uni.quoter, weth: C.uni.weth, stable: C.uni.stable, fee: C.uni.fee }
   const stableDecimals = C.pools[stablePool].decimals
-  const gasOv = (limit) => ({ gasLimit: limit, ...(chainGasOverridesSync(chain)) })
+  let liveFees = null // set before the first burner tx (see reserve sizing below)
+  const gasOv = (limit) => ({ gasLimit: limit, ...(liveFees || chainGasOverridesSync(chain)) })
 
   const wallet = getWallet()
   const sig = await ensureSignature(wallet)
@@ -1117,7 +1192,7 @@ async function cmdSwap(args) {
   const wp = await apiPost('/api/swap-private', {
     signature: sig, chain, pool: from,
     fromAsset: chain === 'base' ? (isEthOrigin ? 'base_eth' : 'base_usdc') : undefined,
-    amount: n, burnerAddress: burner.address,
+    amount: String(amount), burnerAddress: burner.address,
   }, { timeoutMs: 180_000 })
   info(`withdraw tx: ${explorerTx(chain, wp.txHash)}`)
 
@@ -1125,8 +1200,12 @@ async function cmdSwap(args) {
   // stablecoin dest, or a single ~1.6M-gas deposit for an ETH dest — priced at the chain's gas cap
   // (never ethers' 1.5 gwei default). Under-reserving here is exactly what stranded ETH→USDG on
   // Robinhood, so reserve generously (+50%).
-  const gasCap = ethers.utils.parseUnits(C.gasCapGwei, 'gwei')
-  const reshieldGasReserve = ethers.BigNumber.from(1_680_000).mul(gasCap).mul(15).div(10)
+  // Priced at the LIVE fee (3 x baseFee + tip, never above the chain cap) rather than the cap itself: on Arbitrum the
+  // cap is ~50x the real price, which left most of a small swap sitting on the burner as unused gas.
+  liveFees = await burnerFees(provider, chain)
+  const feePerGas = liveFees.maxFeePerGas || liveFees.gasPrice
+  const reshieldGasNeed = ethers.BigNumber.from(1_680_000).mul(feePerGas) // approve + ZK deposit, advanced by the relayer
+  const swapGasReserve = ethers.BigNumber.from(320_000).mul(feePerGas).mul(15).div(10) // the swap tx itself
 
   // === Step 3: wait funds on burner + top-up gas for stablecoin origin ===
   let amountIn
@@ -1134,9 +1213,9 @@ async function cmdSwap(args) {
     info('waiting for ETH on burner...')
     await waitEthBalance(provider, burner.address, ethers.utils.parseEther('0.0001'), 'burner funding')
     const bal = await provider.getBalance(burner.address)
-    // Leave enough ETH for the stablecoin reshield's approve+deposit (dest is a stablecoin here).
-    if (bal.lte(reshieldGasReserve)) fail('burner balance too low after fees')
-    amountIn = bal.sub(reshieldGasReserve)
+    // Swap everything except the swap tx's own gas; the relayer advances the reshield gas afterwards.
+    if (bal.lte(swapGasReserve)) fail('burner balance too low after fees')
+    amountIn = bal.sub(swapGasReserve)
   } else {
     info(`waiting for ${stableSym} on burner...`)
     amountIn = await waitTokenBalance(provider, U.stable, burner.address, ethers.BigNumber.from(1), 200)
@@ -1195,33 +1274,39 @@ async function cmdSwap(args) {
   ok('swap confirmed on Uniswap')
 
   // === Step 5: unwrap WETH -> ETH if ETH is the destination ===
+  let unwrapped = null
   if (!isEthOrigin) {
     info('unwrapping WETH -> ETH on burner...')
     const wethBal = await waitTokenBalance(provider, U.weth, burner.address, ethers.BigNumber.from(1), 60)
     const weth = new ethers.Contract(U.weth, ['function withdraw(uint256)'], burner)
     const uwPop = await weth.populateTransaction.withdraw(wethBal)
-    await broadcastAndWait(burner, provider, { ...uwPop, ...gasOv(60_000) }, { label: 'WETH unwrap' })
+    const uw = await broadcastAndWait(burner, provider, { ...uwPop, ...gasOv(60_000) }, { label: 'WETH unwrap' })
+    unwrapped = { amount: wethBal, block: uw.receipt.blockNumber }
     info('unwrap confirmed')
   }
 
   // === Step 6: figure out reshield amount + call /api/deposit/prepare ===
-  const destPool = isEthOrigin ? stablePool : 'eth'
+  const destPool = isEthOrigin ? stablePool : nativePool
   const destDec = isEthOrigin ? stableDecimals : 18
   let reshieldAmount
   if (isEthOrigin) {
     // Stablecoin destination: reshield the full stable balance (gas paid in the burner's reserved ETH).
     reshieldAmount = await waitTokenBalance(provider, U.stable, burner.address, ethers.BigNumber.from(1), 60)
-    // Make sure the reserved ETH survived the swap (it should — swap input excluded it).
-    if ((await provider.getBalance(burner.address)).lt(reshieldGasReserve.div(2))) {
-      info('topping up burner gas before reshield...')
+    // The relayer advances the approve + deposit gas (the burner now holds the stablecoin, which is what the
+    // top-up endpoint checks). Whatever is not used goes back to the relayer after the reshield.
+    if ((await provider.getBalance(burner.address)).lt(reshieldGasNeed)) {
+      info('relayer advancing reshield gas...')
       const g = await apiPost('/api/burner-gas', { signature: sig, burnerAddress: burner.address, chain, txCount: 2 }, { timeoutMs: 60_000 })
-      if (g.success) await waitEthBalance(provider, burner.address, ethers.BigNumber.from(1), 'reshield gas')
+      if (!g.success) fail('reshield gas top-up failed; the swapped funds are safe on the burner, run `blackpool recover`')
+      await waitEthBalance(provider, burner.address, reshieldGasNeed, 'reshield gas')
     }
   } else {
     // ETH destination: the deposit tx is payable (value = amount) AND pays its own gas from the same
-    // balance. Reserve the deposit gas at the chain cap.
-    const full = await waitEthBalance(provider, burner.address, ethers.utils.parseEther('0.0000001'), 'swap output')
-    const gasReserve = gasCap.mul(1_600_000)
+    // balance. Reserve the deposit gas at the live fee.
+    // Read at the unwrap's block and require at least the unwrapped amount: a node a block behind still shows only
+    // the gas top-up, and a reshield built from that would carry almost nothing.
+    const full = await settledBalance(provider, burner.address, { atBlock: unwrapped.block, min: unwrapped.amount, label: 'swap output' })
+    const gasReserve = feePerGas.mul(1_600_000).mul(12).div(10) // live fee, +20%
     if (full.lte(gasReserve)) fail(`swap output ${ethers.utils.formatEther(full)} ETH too small to reshield after gas`)
     reshieldAmount = full.sub(gasReserve)
   }
@@ -1270,17 +1355,20 @@ async function cmdSwap(args) {
   try { estGas = await provider.estimateGas({ to: prep.to, data: prep.data, value: reshieldVal, from: burner.address }) }
   catch { estGas = ethers.BigNumber.from(1_600_000) } // fallback
   const gasLimit = estGas.mul(12).div(10) // +20% headroom
-  // Cap at the chain's gas ceiling OR at what fits in burner ETH, whichever is lower.
-  let maxFee = gasCap
+  // The live fee OR what fits in burner ETH, whichever is lower.
+  let maxFee = feePerGas
   const maxAffordable = burnerEth.div(gasLimit)
   if (maxFee.gt(maxAffordable)) maxFee = maxAffordable.mul(9).div(10) // 90% of ceiling
+  // BNB Chain enforces a 0.05 gwei minimum on the effective price; an EIP-1559 tip of maxFee/10 falls below it.
+  const feeFields = C.legacyGas ? { gasPrice: maxFee } : { maxFeePerGas: maxFee, maxPriorityFeePerGas: maxFee.div(10) }
   const rtx = await broadcastAndWait(burner, provider, {
     to: prep.to, data: prep.data, value: reshieldVal,
     gasLimit,
-    maxFeePerGas: maxFee,
-    maxPriorityFeePerGas: maxFee.div(10),
+    ...feeFields,
   }, { label: 'reshield' })
 
+  await returnUnusedGas(burner, provider, chain, rtx.receipt.blockNumber)
+
   log('')
   ok(color(`swap complete: ${amount} ${from.toUpperCase()} -> ${reshieldFmt} ${toSym} (private) on ${C.label}`, c.green))
   info(`new private balance: ${prep.newBalance} ${prep.symbol}`)
@@ -1336,6 +1424,7 @@ async function cmdAssets() {
 }
 
 async function cmdSend(args) {
+  if (/^(max|all)$/i.test(String(args[1] || ''))) return cmdSendMax(args)
   const chain = resolveChain(args)
   const C = CHAINS[chain]
   const recipient = args[0]
@@ -1360,7 +1449,7 @@ async function cmdSend(args) {
   info('this can take ~30-90 seconds - you pay no gas.')
 
   const res = await apiPost('/api/withdraw', {
-    signature: sig, amount: n, recipient, pool, chain
+    signature: sig, amount: String(amount), recipient, pool, chain
   }, { timeoutMs: 180_000 })
 
   log('')
@@ -1371,6 +1460,80 @@ async function cmdSend(args) {
   result({ chain, pool, recipient, amount: n, received: res.recipientReceives, fee: res.fee, symbol: res.symbol, txHash: res.txHash, explorer: explorerTx(chain, res.txHash) })
 }
 
+// "max" for swap/bridge: the most one operation can spend (its two largest notes), as an exact decimal string.
+async function resolveMaxAmount(chain, pool, flow) {
+  if (!CHAINS[chain] || !CHAINS[chain].pools[pool]) fail(`unknown pool "${pool}" on ${CHAINS[chain] ? CHAINS[chain].label : chain}`)
+  const P = CHAINS[chain].pools[pool]
+  const sig = await ensureSignature(getWallet())
+  const bal = await apiPost('/api/balance', { signature: sig, pool, chain }, { timeoutMs: 120_000 })
+  const notes = (bal.utxos || []).map((u) => ethers.utils.parseUnits(String(u), P.decimals)).sort((a, b) => (b.gt(a) ? 1 : b.lt(a) ? -1 : 0))
+  if (!notes.length) fail(`no private ${P.symbol} on ${CHAINS[chain].label}`)
+  const spend = notes.slice(0, 2).reduce((s, n) => s.add(n), ethers.BigNumber.from(0))
+  const total = notes.reduce((s, n) => s.add(n), ethers.BigNumber.from(0))
+  const spendStr = ethers.utils.formatUnits(spend, P.decimals)
+  if (Number(spendStr) < minTxFor(chain, pool).min) fail(`private ${P.symbol} on ${CHAINS[chain].label} is ${ethers.utils.formatUnits(total, P.decimals)}, below the minimum ${flow}`)
+  info(`max: ${spendStr} ${P.symbol}` + (notes.length > 2 ? ` (of ${ethers.utils.formatUnits(total, P.decimals)} across ${notes.length} notes; run ${flow} max again for the rest)` : ''))
+  return spendStr
+}
+
+// send <recipient> max: empty one pool, every pool of a chain, or every pool everywhere into one address.
+async function cmdSendMax(args) {
+  const recipient = args[0]
+  if (!/^0x[a-fA-F0-9]{40}$/.test(String(recipient || ''))) fail(`invalid recipient address: ${recipient}`, 2)
+  const rawChain = (getFlag(args, '--chain') || 'base').toLowerCase()
+  const chains = rawChain === 'all' ? Object.keys(CHAINS) : [resolveChain(args)]
+  const poolFlag = (getFlag(args, '--pool') || 'all').toLowerCase()
+  if (rawChain === 'all' && poolFlag !== 'all') fail('with --chain all, use --pool all (pool names differ per chain)', 2)
+  if (poolFlag !== 'all' && !poolsForChain(chains[0]).includes(poolFlag)) fail(`unknown pool "${poolFlag}" on ${CHAINS[chains[0]].label} (supported: ${poolsForChain(chains[0]).join(', ')})`)
+
+  const wallet = getWallet()
+  const sig = await ensureSignature(wallet)
+  const sends = [], dust = [], errors = []
+  log('')
+  log(color(`  sending the whole private balance to ${recipient}`, c.bold))
+  for (const chain of chains) {
+    const pools = poolFlag === 'all' ? poolsForChain(chain) : [poolFlag]
+    for (const pool of pools) {
+      const P = CHAINS[chain].pools[pool]
+      const tag = `${CHAINS[chain].label} ${P.symbol}`
+      let behind = 0
+      for (let round = 0; round < 12; round++) {
+        let bal
+        try { bal = await apiPost('/api/balance', { signature: sig, pool, chain }, { timeoutMs: 120_000 }) }
+        catch (e) { errors.push({ chain, pool, error: cleanErr(e) }); info(`${tag}: could not read the balance (${cleanErr(e)})`); break }
+        const notes = (bal.utxos || []).map((u) => ethers.utils.parseUnits(String(u), P.decimals)).sort((a, b) => (b.gt(a) ? 1 : b.lt(a) ? -1 : 0))
+        if (!notes.length) { if (round === 0) info(`${tag}: empty`); break }
+        // one send spends at most the two largest notes
+        const spend = notes.slice(0, 2).reduce((s, n) => s.add(n), ethers.BigNumber.from(0))
+        const spendStr = ethers.utils.formatUnits(spend, P.decimals)
+        const total = ethers.utils.formatUnits(notes.reduce((s, n) => s.add(n), ethers.BigNumber.from(0)), P.decimals)
+        if (Number(spendStr) < minTxFor(chain, pool).min) { dust.push({ chain, pool, symbol: P.symbol, balance: total }); info(`${tag}: ${total} left as dust (under the minimum send)`); break }
+        info(`${tag}: sending ${spendStr}${notes.length > 2 ? ` (part ${round + 1}, ${notes.length} notes)` : ''}...`)
+        try {
+          const res = await apiPost('/api/withdraw', { signature: sig, amount: spendStr, recipient, pool, chain }, { timeoutMs: 180_000 })
+          sends.push({ chain, pool, symbol: res.symbol, amount: spendStr, received: res.recipientReceives, fee: res.fee, txHash: res.txHash, explorer: explorerTx(chain, res.txHash) })
+          ok(`${tag}: sent ${spendStr}, recipient gets ${res.recipientReceives} ${res.symbol}  ${color(explorerTx(chain, res.txHash), c.dim)}`)
+        } catch (e) {
+          const m = cleanErr(e)
+          // a send or deposit a moment ago is not in the balance view yet: wait and read it again
+          if (/already spent|unknown root|stale/i.test(m) && behind++ < 4) { info(`${tag}: balance view is catching up, retrying...`); await new Promise(r => setTimeout(r, 10_000)); continue }
+          if (/twice the fee/i.test(m)) { dust.push({ chain, pool, symbol: P.symbol, balance: total }); info(`${tag}: ${total} left as dust (at or below twice the fee)`) }
+          else { errors.push({ chain, pool, error: m }); info(`${tag}: not sent (${m})`) }
+          break
+        }
+      }
+    }
+  }
+  const received = {}
+  for (const s of sends) received[s.symbol] = (Number(received[s.symbol] || 0) + Number(s.received)).toString()
+  log('')
+  if (sends.length) ok(color(`${sends.length} send(s) done`, c.green) + (dust.length ? `, ${dust.length} pool(s) left with dust` : ''))
+  else info('nothing to send')
+  log('')
+  result({ recipient, amount: 'max', sends, received, dust, errors })
+  if (errors.length && !sends.length) fail(errors.map((e) => `${e.chain}/${e.pool}: ${e.error}`).join('; '))
+}
+
 function getFlag(args, name) {
   const i = args.indexOf(name)
   if (i === -1) return null
@@ -1393,6 +1556,8 @@ ${color('Commands:', c.bold)}
                                  --chain all shows every chain in one run.
   deposit <amount> [--pool] [--chain]   Shield public funds into private pool.
   send <to> <amount> [--pool] [--chain] Send privately to an address (no gas from you).
+                                 amount "max": the whole private balance (no --pool = every pool; --chain all).
+                                 swap/bridge also take "max" (the most one operation can move).
   swap <amount> --from <pool> [--chain] Private same-chain swap via Uniswap V3.
   bridge <asset> <to> <amount>   Bridge cross-chain privately via NEAR Intents (--no-wait: return once submitted)
                                  (--from ${Object.keys(BRIDGE_ORIGINS).join('|')}).
@@ -1485,7 +1650,10 @@ async function main() {
       case undefined: help();                    break
       default: if (!JSON_MODE) { log(`unknown command: ${cmd}\n`); help() } fail(`unknown command: ${cmd} (run blackpool help)`, 2)
     }
-    if (JSON_MODE) process.stdout.write(JSON.stringify({ ok: true, command: CMD, ...RESULT }) + '\n')
+    // Exit explicitly: the prover leaves worker threads alive, which would keep the process running after a
+    // deposit, send, swap or bridge has already finished.
+    if (JSON_MODE) process.stdout.write(JSON.stringify({ ok: true, command: CMD, ...RESULT }) + '\n', () => process.exit(0))
+    else process.stdout.write('', () => process.exit(0)) // flush piped output first
   } catch (e) {
     fail(cleanErr(e))
   }

package/bin/mcp.js

@@ -20,7 +20,7 @@ const SUPPORTED = ['2025-06-18', '2025-03-26', '2024-11-05']
 
 const CHAIN = { type: 'string', enum: ['base', 'robinhood', 'arbitrum', 'bsc'], description: 'Chain. Default base.' }
 const POOL = { type: 'string', description: 'Pool on that chain: eth|usdc (base, arbitrum), eth|usdg (robinhood), bnb|usdc|usdt (bsc). Default: the chain\'s stablecoin pool.' }
-const AMOUNT = { type: 'string', pattern: '^[0-9]+(\\.[0-9]+)?$', description: 'Decimal amount in token units, e.g. "10" or "0.25". Never wei.' }
+const AMOUNT = { type: 'string', pattern: '^([0-9]+(\\.[0-9]+)?|max)$', description: 'Decimal amount in token units, e.g. "10" or "0.25", or "max" (send: the whole pool balance; swap/bridge: the most one operation can move). Never wei.' }
 
 const TOOLS = [
   {
@@ -43,8 +43,8 @@ const TOOLS = [
   },
   {
     name: 'blackpool_send', title: 'Private send', destructive: true,
-    description: 'Pay any EVM address privately from the private balance. The relayer pays gas; the recipient receives amount minus the fee (flat + 0.35%). Takes 30-90 s. Never retry after a timeout without checking blackpool_balance.',
-    inputSchema: { type: 'object', properties: { recipient: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' }, amount: AMOUNT, pool: POOL, chain: CHAIN }, required: ['recipient', 'amount'], additionalProperties: false },
+    description: 'Pay any EVM address privately from the private balance. The relayer pays gas; the recipient receives amount minus the fee (flat + 0.35%). amount "max" sends the whole balance of the pool (or of every pool when pool is omitted), splitting across several sends when needed and leaving dust untouched. Takes 30-90 s per send. Never retry after a timeout without checking blackpool_balance.',
+    inputSchema: { type: 'object', properties: { recipient: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' }, amount: { type: 'string', pattern: '^([0-9]+(\\.[0-9]+)?|max)$', description: 'Decimal amount in token units, e.g. "10" or "0.25", or "max" for the whole private balance. Never wei.' }, pool: POOL, chain: CHAIN }, required: ['recipient', 'amount'], additionalProperties: false },
     args: (a) => ['send', a.recipient, String(a.amount), ...opt('--pool', a.pool), ...opt('--chain', a.chain)],
   },
   {

package/lib/localApi.js

@@ -48,9 +48,19 @@ function createLocalApi({ request, loadCircuit, snarkjs, singleThread = false, o
   const units = (P, v) => BigInt(U.parseUnits(String(v), P.decimals).toString())
   const fmt = (P, v) => U.formatUnits(v.toString(), P.decimals)
 
+  // A snapshot behind the chain (the API reports the pool's on-chain nextIndex) would show old notes right after a
+  // transaction; wait for it to catch up (normally a few seconds) before using it.
+  async function poolSnapshot(P, timeoutMs = 45_000) {
+    const until = Date.now() + timeoutMs
+    for (;;) {
+      const d = await request('GET', `/api/zk/pool?chain=${P.chain}&pool=${P.pool}`)
+      if (d.chainNextIndex == null || d.nextIndex >= d.chainNextIndex || Date.now() > until) return d
+      await new Promise((r) => setTimeout(r, 2500))
+    }
+  }
   async function account(keys, P) {
     onProgress({ stage: 'scan', pool: P.key })
-    const data = await request('GET', `/api/zk/pool?chain=${P.chain}&pool=${P.pool}`)
+    const data = await poolSnapshot(P)
     const indexed = new Set(data.nullifiers.map((n) => n.toLowerCase()))
     const pend = mem.pending.get(P.key) || new Set()
     for (const n of pend) if (indexed.has(n)) pend.delete(n)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackpool/cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Private payments for onchain agents. CLI for BLACKPOOL - shield, send, swap, bridge with zero-knowledge privacy on Base, Robinhood Chain, Arbitrum, and BNB Smart Chain.",
   "mcpName": "cash.blackpool/blackpool",
   "bin": {