@blackpool/cli 0.4.3 → 0.4.5

package/AGENTS.md

@@ -175,9 +175,9 @@ Bridge destinations and valid origins, live from the API.
 ```
 
 ### `recover [--to ADDR] [--chain C|all]`
-Sweep every registered burner that still holds funds to the agent wallet (or `--to`). Idempotent and safe at any time. Swept funds land in the **public** wallet; `deposit` again to make them private. ~10–60 s per chain.
+Sweep every registered burner that still holds funds to the agent wallet (or `--to`). Idempotent and safe at any time. Swept funds land in the **public** wallet; `deposit` again to make them private. ~10–60 s per chain. A burner that holds tokens but no gas gets a gas top-up from the relayer first; if that is refused, the result reports it in `needsGas` instead of claiming the chain is clean.
 ```json
-{"ok":true,"command":"recover","recovered":[{"chain":"base","to":"0x…","swept":1,"dust":0,"errors":0}]}
+{"ok":true,"command":"recover","recovered":[{"chain":"base","to":"0x…","swept":1,"dust":0,"errors":0,"needsGas":0}]}
 ```
 
 ### `login`, `logout`, `version`, `latest`, `help`
@@ -333,6 +333,15 @@ Implement it with the Node or Python wrapper above. Allow-list the first argumen
 
 Blackpool speaks the [Model Context Protocol](https://modelcontextprotocol.io), so any MCP-capable agent app can call it as tools instead of running shell commands. There are two servers.
 
+Both are listed publicly, so an agent app or directory can find them by name:
+
+| Listing | Name | What is listed |
+|---|---|---|
+| [Official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/cash.blackpool%2Fblackpool/versions/latest) | `cash.blackpool/blackpool` | The local server (npm package) and the hosted endpoint |
+| [Glama — server](https://glama.ai/mcp/servers/blackpooldev/blackpool) | `blackpooldev/blackpool` | The local server, built and tested from the open-source repository |
+| [Glama — connector](https://glama.ai/mcp/connectors/cash.blackpool/blackpool) | `cash.blackpool/blackpool` | The hosted endpoint, ownership verified and health-checked |
+| [npm](https://www.npmjs.com/package/@blackpool/cli) | `@blackpool/cli` | The package that runs the local server |
+
 ### 9.1 Local server — payments (recommended)
 
 Runs on your machine over stdio and exposes the full CLI as tools. The wallet key stays in the local environment; tools behave exactly like the commands in §4 and return the same JSON.

package/bin/blackpool.js

@@ -1040,13 +1040,30 @@ async function sweepBurner(privateKey, chain, dest) {
   log(color(`  burner ${burner.address}`, c.cyan))
   log(`    ${C.pools[C.nativePool].symbol} : ${ethers.utils.formatEther(ethB)}`)
   log(`    ${stableSym}: ${ethers.utils.formatUnits(uB, stableDecimals)}`)
-  let swept = false, error = false
-
-  // stablecoin first (needs ETH for gas). Chain-realistic gas so the burner's small top-up isn't drained.
+  let swept = false, error = false, needsGas = false
+  const nativeSym = C.pools[C.nativePool].symbol
+  const MIN_GAS = ethers.utils.parseEther('0.00001')
+
+  // stablecoin first (needs gas). A burner holding pool tokens qualifies for the relayer's gas top-up
+  // (/api/burner-gas only funds addresses that hold a pool token), so ask for it instead of making the
+  // user send gas by hand.
+  if (uB.gt(0) && ethB.lt(MIN_GAS)) {
+    info(`  burner has no ${nativeSym} for gas — asking the relayer for a gas top-up...`)
+    try {
+      const g = await apiPost('/api/burner-gas', { burnerAddress: burner.address, chain, txCount: 1 }, { timeoutMs: 60_000 })
+      if (g && g.success) {
+        for (let i = 0; i < 30 && ethB.lt(MIN_GAS); i++) {
+          await new Promise((res) => setTimeout(res, 2000))
+          ethB = await provider.getBalance(burner.address)
+        }
+      } else info(`  gas top-up declined: ${(g && (g.error || g.reason)) || 'no reason given'}`)
+    } catch (e) { info(`  gas top-up failed: ${(e.message || '').slice(0, 80)}`) }
+  }
   if (uB.gt(0)) {
     try {
-      if (ethB.lt(ethers.utils.parseEther('0.00001'))) {
-        info(`  burner has no ETH for gas — send it ~0.00002 ETH then re-run recover`)
+      if (ethB.lt(MIN_GAS)) {
+        needsGas = true
+        info(`  still no gas — send this burner ~0.00002 ${nativeSym}, then re-run recover`)
       } else {
         info(`  sweeping ${ethers.utils.formatUnits(uB, stableDecimals)} ${stableSym} to ${dest}...`)
         const t = new ethers.Contract(C.uni.stable, ['function transfer(address,uint256) returns (bool)'], burner)
@@ -1082,7 +1099,7 @@ async function sweepBurner(privateKey, chain, dest) {
       }
     }
   } catch (e) { info(`  ETH sweep failed: ${(e.message || '').slice(0, 80)}`); error = true }
-  return { swept, dust: false, error }
+  return { swept, dust: false, error, needsGas }
 }
 
 // Sweep registry burners for ONE chain. Shared by single-chain and --chain all.
@@ -1093,7 +1110,7 @@ async function recoverOneChain(chain, wallet, sig, dest) {
   log(color(`  sweeping to ${dest}`, c.dim))
   log('')
 
-  let swept = 0, dust = 0, errors = 0
+  let swept = 0, dust = 0, errors = 0, needsGas = 0
   const seen = new Set()
 
   // 1) Registry burners (random ephemeral, created by frontend OR this CLI). Primary path — random
@@ -1109,17 +1126,19 @@ async function recoverOneChain(chain, wallet, sig, dest) {
       if (r.swept) { swept++; await markBurnerSwept(authSig, b.address, chain) }
       if (r.dust) dust++
       if (r.error) errors++
+      if (r.needsGas) needsGas++
     }
   } catch (e) { info(`registry scan skipped: ${cleanErr(e)}`) }
 
   log('')
   if (swept > 0) ok(color(`recovered funds from ${swept} burner(s) on ${C.label}`, c.green))
-  else ok(`no stranded funds on ${C.label} — all burners clean`)
+  else if (needsGas === 0 && errors === 0) ok(`no stranded funds on ${C.label} — all burners clean`)
+  if (needsGas > 0) info(color(`${needsGas} burner(s) still hold funds but have no gas — see above, then re-run recover`, c.yellow))
   if (dust > 0) info(`(${dust} burner(s) hold only dust ETH below gas cost — not recoverable, safe to ignore)`)
   if (errors > 0) info(`${errors} burner(s) had errors — re-run recover to retry`)
   log('')
-  ;(RESULT.recovered ||= []).push({ chain, to: dest, swept, dust, errors })
-  return { swept, dust, errors }
+  ;(RESULT.recovered ||= []).push({ chain, to: dest, swept, dust, errors, needsGas })
+  return { swept, dust, errors, needsGas }
 }
 
 async function cmdRecover(args) {

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.3",
+  "version": "0.4.5",
   "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": {