@blackpool/cli 0.4.2 → 0.4.4

package/bin/blackpool.js

@@ -847,28 +847,51 @@ async function waitTokenBalance(provider, tokenAddr, addr, min, retries = 60) {
 // 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) {
+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
-    const bal = await provider.getBalance(burner.address)
+    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
-    const keep = gasLimit.mul(fee).add(l1Cushion)
-    if (bal.lte(keep.mul(2))) return // nothing worth moving
-    const value = bal.sub(keep)
-    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)`)
+    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)
@@ -1251,17 +1274,19 @@ 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) {
@@ -1278,7 +1303,9 @@ async function cmdSwap(args) {
   } 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 live fee.
-    const full = await waitEthBalance(provider, burner.address, ethers.utils.parseEther('0.0000001'), 'swap output')
+    // 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)
@@ -1340,7 +1367,7 @@ async function cmdSwap(args) {
     ...feeFields,
   }, { label: 'reshield' })
 
-  await returnUnusedGas(burner, provider, chain)
+  await returnUnusedGas(burner, provider, chain, rtx.receipt.blockNumber)
 
   log('')
   ok(color(`swap complete: ${amount} ${from.toUpperCase()} -> ${reshieldFmt} ${toSym} (private) on ${C.label}`, c.green))
@@ -1469,6 +1496,7 @@ async function cmdSendMax(args) {
     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 }) }
@@ -1487,6 +1515,8 @@ async function cmdSendMax(args) {
           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

package/bin/mcp.js

@@ -31,8 +31,8 @@ const TOOLS = [
   },
   {
     name: 'blackpool_balance', title: 'Balances', readOnly: true,
-    description: 'Private (shielded) and public balances. With pool: one private pool only. wait=true polls up to 30 s while a private balance reads 0 (right after a deposit).',
-    inputSchema: { type: 'object', properties: { chain: { ...CHAIN, enum: [...CHAIN.enum, 'all'], description: 'Chain, or "all". Default base.' }, pool: POOL, wait: { type: 'boolean' } }, additionalProperties: false },
+    description: 'Read the agent wallet\'s private (shielded) and public balances. Without pool: both pools of the chain (native coin and stablecoin) with their note (UTXO) counts; chain "all" covers every chain. With pool: that one private pool only. Read-only; needs BLACKPOOL_KEY. Use wait=true right after a deposit or send, when the private balance may still read 0. Returns {balances: [{chain, address, private: {SYMBOL: {balance, utxos}}, public: {SYMBOL: balance}}]}, or with pool {chain, pool, balance, symbol, utxos}.',
+    inputSchema: { type: 'object', properties: { chain: { ...CHAIN, enum: [...CHAIN.enum, 'all'], description: 'Chain, or "all" for every chain. Default base.' }, pool: POOL, wait: { type: 'boolean', description: 'Poll up to 30 s while a private balance reads 0, e.g. right after a deposit. Default false.' } }, additionalProperties: false },
     args: (a) => ['balance', ...opt('--chain', a.chain), ...opt('--pool', a.pool), ...(a.wait ? ['--wait'] : [])],
   },
   {
@@ -67,14 +67,14 @@ const TOOLS = [
   },
   {
     name: 'blackpool_assets', title: 'Bridge assets', readOnly: true,
-    description: 'Bridge destination assets and valid origins.',
+    description: 'List what the private bridge can deliver and which private pools can fund a bridge. Returns {assets: {KEY: {chain, symbol, decimals, isNative}}, origins: [...]} where origins are pool keys such as base_eth, hood_usdg or bsc_usdt. Use an assets KEY as dest_asset and an origins entry as from in blackpool_bridge. Read-only; needs no key and no gas.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     args: () => ['assets'],
   },
   {
     name: 'blackpool_recover', title: 'Recover', idempotent: true,
-    description: 'Sweep every registered burner that still holds funds back to the agent wallet (or to). Safe to run any time.',
-    inputSchema: { type: 'object', properties: { chain: { ...CHAIN, enum: [...CHAIN.enum, 'all'] }, to: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' } }, additionalProperties: false },
+    description: 'Find the one-time burner wallets from earlier private swaps and bridges that still hold funds (for example after an interrupted swap) and sweep them to the agent wallet, or to the address in to. Idempotent and safe to run any time: empty burners are skipped and amounts too small to cover gas are reported as dust. Needs BLACKPOOL_KEY. Returns {recovered: [{chain, to, swept, dust, errors}]}.',
+    inputSchema: { type: 'object', properties: { chain: { ...CHAIN, enum: [...CHAIN.enum, 'all'], description: 'Chain to scan, or "all" for every chain. Default all.' }, to: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$', description: 'Address to sweep to. Default: the agent wallet.' } }, additionalProperties: false },
     args: (a) => ['recover', ...opt('--chain', a.chain || 'all'), ...opt('--to', a.to)],
   },
 ]

package/lib/localApi.js

@@ -194,8 +194,8 @@ function createLocalApi({ request, loadCircuit, snarkjs, singleThread = false, o
   return {
     handles: (path) => LOCAL_PATHS.has(path),
     async handle(path, body) {
-      const h = handlers[path]
-      if (!h) throw new Error(`no local handler for ${path}`)
+      const h = LOCAL_PATHS.has(path) && Object.prototype.hasOwnProperty.call(handlers, path) ? handlers[path] : null
+      if (typeof h !== 'function') throw new Error(`no local handler for ${path}`)
       if (!body || !body.signature) throw new Error('missing signature')
       return h(body)
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackpool/cli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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": {