@zeam-labs/x402-mcp-bridge 2.0.4 → 2.0.6

package/README.md

@@ -62,9 +62,8 @@ settlement contract, withdrawable by your side of the channel alone: the
 for most clients is the same key but need not be.
 
 That escrow is not the seller's. It is x402's own batch-settlement contract,
-hardcoded in [`@x402/evm`](https://www.npmjs.com/package/@x402/evm) and published
-to npm by Coinbase in `2.12.0` on 2026-05-13 — two days before the contract
-existed on Base. No owner, no pause, no upgrade, no sweep.
+hardcoded in [`@x402/evm`](https://www.npmjs.com/package/@x402/evm), published by
+Coinbase. No owner, no pause, no upgrade, no sweep.
 
 ```
 npm pack @x402/evm@2.12.0 && grep -rl 0x4020074e9dF2ce1deE5A9C1b5c3f541D02a10003 package/
@@ -92,9 +91,8 @@ probes are also unpaid calls, and a server may cap how many of those it will
 answer, which is how a funded wallet gets locked out of a channel it has money in.
 
 The terms are static and published, so this bridge reads them once from
-`/.well-known/x402` at connect and attaches payment to its **first** request.
-Measured against the same server: six calls issued six 402 challenges the old
-way, and zero the new way.
+`/.well-known/x402` at connect and attaches payment to its **first** request —
+no unpaid probe, no extra round trip.
 
 A refused payment re-reads the terms and retries once, because quotes for
 non-stable assets move with the oracle. Anything still failing falls back to the
@@ -132,8 +130,7 @@ if that fails too. That ordering matters: falling straight through to per-call
 payment turns one closed line into a signed payment per in-flight call,
 serialized behind one channel, and when those run out of road they become unpaid
 requests that burn the hourly ceiling and lock a funded wallet out of its own
-channel. Measured before the fix, at 25-way concurrency: 3 of 12 calls served.
-After: 200 of 200 across 8 line deaths.
+channel.
 
 **Cold starts.** A voucher signs a *cumulative* total, and that total is not on
 the chain — the escrow knows your balance and what has been claimed, not what has
@@ -161,7 +158,7 @@ time and an overlapping tick is refused as `channel_busy`.
 | `X402_STATE_DIR` | `~/.x402-mcp-bridge/<host>/<address>` | channel state |
 | `X402_SALT` | scheme default | open a distinct channel. Any string; it is hashed to bytes32 |
 | `X402_MAX_SPEND` | `10000000` (=$10) | ceiling on what **this run** may spend, in micro-USD. `0` removes it — see below |
-| `X402_DEPOSIT_MULTIPLIER` | `400` | how much collateral a deposit puts in escrow, as a multiple of the quote. **The quote is 250 micro-USD, so the default deposit is 400 x 250 = 100,000 micro-USD = $0.10.** That is refundable collateral, not a charge — but it leaves your wallet the moment you open a channel, and no page said the number out loud until a cold buyer had to multiply two figures from two documents to find out what plugging in the config would cost it. Lower it if $0.10 is more than you want committed; the scheme refuses below 3x. |
+| `X402_DEPOSIT_MULTIPLIER` | *scheme default* | how much **refundable** collateral to lock, as a multiple of the seller's quote for the opening call. Unset, the x402 scheme sizes it (minimum 3); raise it to top up less often, lower it to commit less. It leaves your wallet when you open the channel and comes back on refund — it is not the price. |
 
 ## It stops spending when you stop watching
 
@@ -185,9 +182,9 @@ signer can **read the chain** — so this bridge always gives the signer a reade
 By default that reader is the upstream's own free `/verify` surface, which means
 recovery costs nothing and needs no RPC of your own.
 
-Measured against `mcp.zeamprism.com`: fresh channel, first call 2.6s (one
-on-chain deposit) then ~180ms per call. State deliberately wiped: healed and
-served in 3.9s, then ~150ms.
+The first call also makes the on-chain deposit, so it is slower than the rest;
+every call after it is fast. Losing state adds one more deposit-time call, then
+it is fast again.
 
 ## What it does not do
 

package/index.mjs

@@ -42,8 +42,9 @@ if (has('--help') || has('-h')) {
     '',
     'Env: X402_PRIVATE_KEY (required), X402_MCP_URL (X402_UPSTREAM also accepted),',
     '     X402_MAX_SPEND (0 = no cap; base units of the paid asset if the server publishes no price),',
-    '     X402_DEPOSIT_MULTIPLIER (default 400 × the SELLER\'S quoted per-call amount; against',
-    '     zeamprism that is 400 × 250 = $0.10 of refundable collateral), X402_LINE=auto|on|off,',
+    '     X402_DEPOSIT_MULTIPLIER (refundable collateral to lock, as a multiple of',
+    '     the opening quote; unset uses the x402 scheme default, minimum 3),',
+    '     X402_LINE=auto|on|off,',
     '     X402_SALT.',
 '     auto: buy per-call minimum holds until calls arrive faster than the',
 '     server minimum hold, then hold a line while that lasts. A held line',
@@ -99,9 +100,11 @@ const watchedStorage = {
 try {
   const f = readdirSync(join(stateDir, 'client')).find((n) => n.endsWith('.json'))
   if (f) channelId = f.replace(/\.json$/, '')
-} catch { /* first run, nothing to recover */ }
+} catch {}
 
-const depositPolicy = { depositMultiplier: Number(process.env.X402_DEPOSIT_MULTIPLIER ?? 400) }
+const depositPolicy = process.env.X402_DEPOSIT_MULTIPLIER
+  ? { depositMultiplier: Number(process.env.X402_DEPOSIT_MULTIPLIER) }
+  : {}
 
 const MAX_SPEND = Number(process.env.X402_MAX_SPEND ?? 10_000_000)
 let capReached = false
@@ -109,12 +112,12 @@ let capReached = false
 let startedAt = null
 let spentMicroUSD = 0
 
-let quoteMicroUSD = null                 // set from the seller's own terms
-let spendUnit = 'micro-USD'              // what the numbers we report actually ARE
+let quoteMicroUSD = null
+let spendUnit = 'micro-USD'
 
 const quoteFromTerms = (j) => {
   for (const c of [j?.rate?.deposit?.tickQuoteMicroUSD, j?.rate?.tickQuoteMicroUSD,
-                   j?.rate?.microUSDPerCall, j?.quoteMicroUSD]) {
+                   j?.rate?.microUSDPerCall, j?.rate?.microUSDPerBlock, j?.quoteMicroUSD]) {
     const n = Number(c)
     if (Number.isFinite(n) && n > 0) return n
   }
@@ -134,7 +137,7 @@ const noteBilled = (ctx) => {
     if (startedAt === null) startedAt = charged
     const spent = microUSDOf(charged - startedAt)
     if (spent > spentMicroUSD) spentMicroUSD = spent
-  } catch { /* a record we cannot read is not a reason to stop paying */ }
+  } catch {}
   if (!MAX_SPEND || capReached || spentMicroUSD < MAX_SPEND) return
   capReached = true
   log(`SPEND CAP REACHED — this run has spent ${spentMicroUSD} ${spendUnit} against a cap of ` +
@@ -156,15 +159,14 @@ const cardSigner = CARD_PAYER ? {
   readContract: pub.readContract.bind(pub),
   signTypedData: () => {
     throw new Error(
-      'this is a gift card and it cannot add funds: it holds a spending key, not ' +
-      `the key to ${CARD_PAYER}. The card is out of money — ask whoever funded it ` +
-      'to top it up (agent-wallet fund) or issue a new one.')
+      `this key spends ${CARD_PAYER}'s channel but cannot add funds to it — it is a ` +
+      'spending key, not that wallet\'s key. Top up from the wallet that owns the channel.')
   },
 } : null
 
 if (CARD_PAYER) {
-  log(`gift card mode — spending ${CARD_PAYER}'s channel, authorized as ${account.address}`)
-  log('this key can spend the card and send it home; it cannot move the money anywhere else')
+  log(`spending ${CARD_PAYER}'s channel, authorized as ${account.address}`)
+  log('this key can spend that channel and return it; it cannot move the money elsewhere')
 }
 
 const payments = new x402Client(selector).register(NETWORK,
@@ -191,7 +193,7 @@ const loadTerms = async () => {
   accepts = { x402Version: j.x402Version ?? 1, accepts: j.accepts }
   tickAccepts = Array.isArray(j.tickAccepts) && j.tickAccepts.length
     ? { x402Version: j.x402Version ?? 1, accepts: j.tickAccepts }
-    : accepts                                    // an upstream that does not sell time
+    : accepts
   const ln = j.limits?.line ?? j.payment?.limits?.line
   lineFacts = {
     tickMs: Number(ln?.tickMs) > 0 ? Number(ln.tickMs) : lineFacts.tickMs,
@@ -206,8 +208,7 @@ const loadTerms = async () => {
   } else if (quoteMicroUSD === null) {
     spendUnit = 'base units of the paid asset'
     log(`quote: this server publishes no micro-USD price, so X402_MAX_SPEND is read as ` +
-        `BASE UNITS OF THE ASSET, not dollars. Guessing a price here is how a spend cap ` +
-        `silently stops capping.`)
+        `base units of the asset, not dollars.`)
   }
   return accepts
 }
@@ -217,7 +218,7 @@ catch (e) { log(`could not cache terms (${e.message}); falling back to probe-the
 let paymentQueue = Promise.resolve()
 const oneAtATime = (fn) => {
   const run = paymentQueue.then(fn, fn)
-  paymentQueue = run.then(() => {}, () => {})       // a failure must not poison the queue
+  paymentQueue = run.then(() => {}, () => {})
   return run
 }
 
@@ -244,13 +245,13 @@ const payNow = async (name, args) => {
       if (explainPermit2(out)) return out
       if (refusedPayment(out)) {
         log('payment refused as stale — dropping the local channel record and resyncing')
-        if (channelId) { try { await watchedStorage.delete(channelId) } catch { /* it will be rebuilt */ } }
+        if (channelId) { try { await watchedStorage.delete(channelId) } catch {} }
         return upstream.callTool(name, args)
       }
       return out
     } catch (e) {
       if (attempt === 2) { log(`pay-first failed twice (${e.message}); using probe path`); return upstream.callTool(name, args) }
-      try { await loadTerms() } catch { /* keep the old terms and let attempt 2 decide */ }
+      try { await loadTerms() } catch {}
     }
   }
 }
@@ -264,7 +265,7 @@ const explainPermit2 = (out) => {
   if (!token || approvalToldFor === token) return true
   approvalToldFor = token
   const per = Number(chosenAccept?.amount ?? 0)
-  const mult = Number(process.env.X402_DEPOSIT_MULTIPLIER ?? 400)
+  const mult = Number(process.env.X402_DEPOSIT_MULTIPLIER ?? 5)
   const suggested = per > 0 ? BigInt(Math.ceil(per * mult * 4)) : 0n
   log(`${token} moves through Permit2 and your wallet has not approved it.`)
   log(`  send once, from your wallet:  approve(${PERMIT2}, ${suggested || '<amount>'})  on ${token}`)
@@ -311,7 +312,7 @@ const wsURL = () => {
 
 const dropLine = (why) => {
   if (line.timer) { clearInterval(line.timer); line.timer = null }
-  try { line.socket?.close() } catch { /* already gone */ }
+  try { line.socket?.close() } catch {}
   if (line.credential) log(`line closed (${why})`)
   line.socket = null
   line.credential = null
@@ -334,7 +335,7 @@ const tick = async () => {
 
 const openLine = () => {
   if (line.credential || line.opening) return line.opening
-  if (!channelId) return null                    // no channel yet; the first paid call makes one
+  if (!channelId) return null
   line.opening = new Promise((resolve) => {
     let socket
     try { socket = new WebSocket(wsURL()) } catch (e) { log(`line: ${e.message}`); return resolve(null) }
@@ -379,7 +380,7 @@ const openLine = () => {
     }
     socket.onopen = () => socket.send(JSON.stringify({ op: 'open', channelId }))
     socket.onclose = () => { clearTimeout(give_up); dropLine('socket closed'); resolve(null) }
-    socket.onerror = () => { /* onclose follows and does the work */ }
+    socket.onerror = () => {}
   }).finally(() => { line.opening = null })
   return line.opening
 }
@@ -421,7 +422,7 @@ const callOnLine = async (name, args) => {
     dropLine(reasonFrom(out) ?? 'refused by the server')
     if (attempt === 2) {
       log('the line was refused twice; paying for this call directly. If the reason above ' +
-        'is collateral, raise X402_DEPOSIT_MULTIPLIER — the minimum of 3 buys under a second of line.')
+        'is collateral, raise X402_DEPOSIT_MULTIPLIER — the scheme minimum is 3.')
     }
   }
   return payFirst(name, args)
@@ -519,10 +520,9 @@ if (has('--refund')) {
       'The exit that always works needs nothing from us:',
       '  initiateWithdraw(config, amount)   then, after the delay, finalizeWithdraw(config)',
       'We also watch for that first call and return the collateral ourselves, at our gas,',
-      'so you usually do not have to send the second transaction. We do NOT promise when:',
-      'a third-party auditor measured 920 seconds on 2026-08-26, i.e. just after the delay',
-      'elapsed. Plan against the delay. The escrow gates withdrawal to you alone, so your',
-      'unspent collateral is safe either way.',
+      'so you usually do not have to send the second transaction — but not on a promised',
+      'schedule; it can lag until just past the delay window. Plan against the delay. The',
+      'escrow gates withdrawal to you alone, so your unspent collateral is safe either way.',
       '',
     ].join('\n'))
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeam-labs/x402-mcp-bridge",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Put a wallet in front of any x402-paid MCP server, and hold a metered line on the ones that sell time. Stock MCP clients cannot construct x402 payments; this one does, and proxies your existing client through it.",
   "type": "module",
   "bin": {