@zeam-labs/x402-mcp-bridge 2.0.3 → 2.0.5

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/
@@ -87,16 +86,13 @@ accept EIP-3009, which needs no approval at all.
 
 The stock x402 flow sends every call **unpaid**, reads the 402 it comes back
 with, and then sends the same call again carrying payment. Two network round
-trips for one call. At a 130ms round trip that is 260ms instead of 130ms — and on
-a meter that bills time on the line, the buyer pays for a handshake nobody
-needed. Those 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.
+trips for one call. At a 130ms round trip that is 260ms instead of 130ms. Those
+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
@@ -104,21 +100,21 @@ old probe-then-pay path rather than dropping your call.
 
 ## Holding a line
 
-Upstream sells **time**, not calls, and there is a cheaper way to buy it than
-paying per call.
+A server may sell **time** rather than calls, with a cheaper path than paying
+per call. The pricing is the server's — read it in its published terms — and this
+bridge drives it for you:
 
 1. Deposit once — your first paid call does it for you.
-2. Open a line on the endpoint's `/pay` websocket. It hands back a credential.
+2. Open a line on the endpoint's `/pay` websocket. If the server challenges,
+   the bridge signs the challenge with your key to prove the channel is yours,
+   and gets back a credential.
 3. Call the `tick` tool on a steady cadence, passing `{line: "<credential>"}`.
-   That is an ordinary paid call and it buys the milliseconds since your previous
-   tick.
-4. Every other call carries only `{line: "<credential>"}` and costs **nothing** —
-   no signature per call, nothing to serialize, and as many calls in flight at
-   once as you like.
+   That is an ordinary paid call and it pays the server for more time.
+4. Every other call carries only `{line: "<credential>"}` and no payment, and as
+   many can be in flight at once as you like.
 
-Stop ticking and the line closes. An open line bills the whole time it is open,
-so a line you forget costs at most one idle-close window past your last tick and
-then stops existing.
+Stop ticking and the line lapses. What the server charges, when a line lapses,
+and whether unused time is kept are the server's to state, not this bridge's.
 
 **This bridge drives a line for you.** `X402_LINE` controls it:
 
@@ -134,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
@@ -146,10 +141,9 @@ it happens once; lose it, or run the same key on a second machine, and it happen
 again on the next call and then not after.
 
 Two things worth knowing if you write your own client. Pay a tick against
-`tickAccepts` from `/.well-known/x402` — same figure as a call, and the ceiling on
-one tick. And never send two ticks at once: a voucher signs a cumulative total, so
-a channel carries one payment at a time and an overlapping tick is refused as
-`channel_busy`.
+`tickAccepts` from `/.well-known/x402`, not `accepts`. And never send two ticks at
+once: a voucher signs a cumulative total, so a channel carries one payment at a
+time and an overlapping tick is refused as `channel_busy`.
 
 ## Configuration
 
@@ -164,7 +158,7 @@ a channel carries one payment at a time and an overlapping tick is refused as
 | `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` | `400` | collateral a deposit locks in escrow, as a multiple of the seller's quote for the opening call. That opening quote carries the one-time open fee, so against zeamprism the default locks ~$0.70 of **refundable** collateral — it leaves your wallet when you open the channel and returns on refund. Lower it if that is more than you want committed; the scheme refuses below 3x. |
 
 ## It stops spending when you stop watching
 
@@ -188,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,10 @@ 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 (default 400; the deposit is this times the seller\'s',
+    '     quote for the OPENING call, held as refundable collateral — against',
+    '     zeamprism ~$0.70, since the opening quote carries the one-time open',
+    '     fee), 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',
@@ -54,7 +56,6 @@ if (has('--help') || has('-h')) {
   process.exit(0)
 }
 
-
 if (!KEY || !/^0x[0-9a-fA-F]{64}$/.test(KEY)) {
   log('set X402_PRIVATE_KEY to a 0x-prefixed 32-byte key. It stays on this machine;')
   log('it signs payment vouchers locally and is never sent anywhere.')
@@ -69,8 +70,6 @@ const stateDir = process.env.X402_STATE_DIR ??
   join(homedir(), '.x402-mcp-bridge', new URL(UPSTREAM).host, account.address.toLowerCase())
 mkdirSync(stateDir, { recursive: true })
 
-// The seller's free scoped RPC, last. It reaches their node without a wallet,
-// which is what makes it usable before you have paid them anything.
 const readers = [
   ...(process.env.X402_RPC_URL ? [process.env.X402_RPC_URL] : []),
   ...(chain.rpcUrls?.default?.http ?? []),
@@ -97,15 +96,12 @@ let channelId = null
 const watchedStorage = {
   get: (k) => storage.get(k),
   delete: (k) => storage.delete(k),
-  // Every write carries the seller's running total for this channel, so this is
-  // also where we learn what we have been billed -- see noteBilled below.
   set: (k, ctx) => { channelId = k; noteBilled(ctx); return storage.set(k, ctx) },
 }
-// And across restarts: the scheme persists one file per channel.
 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) }
 
@@ -115,14 +111,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'
 
-// Liberal in where it looks, strict about giving up. A server that does not say
-// what a call costs in USD gets NO GUESS.
 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
   }
@@ -130,8 +124,6 @@ const quoteFromTerms = (j) => {
 }
 
 const microUSDOf = (units) => {
-  // The entry the selector actually chose. Not accepts[0] -- that is USDC, and
-  // converting WETH units by a USDC quote is the same units bug in a new hat.
   const quoted = Number(chosenAccept?.amount ?? 0)
   if (quoteMicroUSD === null || !(quoted > 0)) return units
   return units * (quoteMicroUSD / quoted)
@@ -144,7 +136,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 ` +
@@ -166,15 +158,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,
@@ -193,8 +184,6 @@ log(`paying as ${account.address} -> ${UPSTREAM}`)
 const termsURL = new URL('/.well-known/x402', UPSTREAM).toString()
 let accepts = null
 let tickAccepts = null
-// The seller's line facts: how often to tick, and what a millisecond costs.
-// They belong to the service, not to one line, so they come from the manifest.
 let lineFacts = { tickMs: 250, microUSDPerMs: null }
 const loadTerms = async () => {
   const r = await fetch(termsURL)
@@ -203,7 +192,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,
@@ -218,8 +207,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
 }
@@ -229,7 +217,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
 }
 
@@ -245,8 +233,6 @@ if (coldStart) log('no local channel state — probing once to learn where this
 const payNow = async (name, args) => {
   if (coldStart) {
     coldStart = false
-    // autoPayment handles the 402 and pays the retry, and the 402 is what
-    // carries the channel state the client is missing.
     return upstream.callTool(name, args)
   }
   const terms = name === 'tick' ? tickAccepts : accepts
@@ -258,13 +244,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 {}
     }
   }
 }
@@ -302,19 +288,15 @@ const AUTO_SLOW_RUN = Number(process.env.X402_AUTO_SLOW_RUN ?? 4)
 
 const line = { credential: null, socket: null, timer: null, tickMs: 250, lastUse: 0, opening: null }
 
-// Rolling view of how fast the caller is actually going.
 const rate = { lastCallAt: 0, fastRun: 0, slowRun: 0 }
 
 function holdingIsCheaper() {
   const now = Date.now()
   const gap = rate.lastCallAt ? now - rate.lastCallAt : Infinity
   rate.lastCallAt = now
-  // <=, not <: at exactly one call per hold window the two cost the same, and
-  // holding avoids a signature and a settlement per call.
   if (gap <= line.tickMs) { rate.fastRun += 1; rate.slowRun = 0 }
   else { rate.slowRun += 1; rate.fastRun = 0 }
 
-  // Already holding? Keep holding until several gaps in a row say otherwise.
   if (line.credential) return rate.slowRun < AUTO_SLOW_RUN
   return rate.fastRun >= AUTO_FAST_RUN
 }
@@ -329,7 +311,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
@@ -352,28 +334,37 @@ 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) }
     const give_up = setTimeout(() => { try { socket.close() } catch {} ; resolve(null) }, 10_000)
-    socket.onmessage = (ev) => {
+    socket.onmessage = async (ev) => {
       let m; try { m = JSON.parse(String(ev.data)) } catch { return }
+      if (m.op === 'challenge') {
+        try {
+          const signature = await account.signMessage({ message: m.message })
+          socket.send(JSON.stringify({ op: 'prove', signature }))
+        } catch (e) {
+          clearTimeout(give_up); log(`line: cannot sign open challenge — ${e.message}`)
+          try { socket.close() } catch {}; resolve(null)
+        }
+        return
+      }
+      if (m.op === 'open_failed') {
+        clearTimeout(give_up); log(`line: open refused — ${m.error ?? m.why}`)
+        try { socket.close() } catch {}; resolve(null); return
+      }
       if (m.op === 'opened') {
         clearTimeout(give_up)
         line.socket = socket
         line.credential = m.credential
         line.tickMs = lineFacts.tickMs
-        // A line that has just opened has not been idle. lastUse starts at 0, so
-        // without this the first timer fire sees an age of Date.now() and drops
-        // the line before anything can use it.
         line.lastUse = Date.now()
         log(`line open — ${lineFacts.microUSDPerMs ?? '?'} micro-USD/ms, ` +
             `collateral buys ${m.buysMs ?? '?'}ms`)
         const first = tick()
         line.timer = setInterval(() => {
-          // Stop paying for a line nobody is using. The server closes an unused
-          // line on its own; this is us not paying for the window before it does.
           if (LINE_MODE === 'auto' && Date.now() - line.lastUse > line.tickMs * 4) return dropLine('idle')
           tick()
         }, line.tickMs)
@@ -388,7 +379,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
 }
@@ -407,15 +398,6 @@ const callOnLine = async (name, args) => {
         'Raise it, set X402_MAX_SPEND=0 to remove it, or restart the bridge.' }) }] }
   }
   line.lastUse = Date.now()
-  // TICK IS THE PAYMENT. The catalog publishes it, so a client can call it, and
-  // it went down the line path like any other tool -- sent with a credential and
-  // no payment, which is the one thing it cannot be. The server answered 402,
-  // and the retry dropped a working line. It also has to share the queue with
-  // our own ticker, or the two race and the channel refuses the loser as busy.
-  // A TICK NEEDS A LINE TO PAY FOR. Routing it straight to payFirst kept it off
-  // the line path, which is also the only thing that opens one -- so a client
-  // that funded and then only ticked never got a line and every tick was
-  // refused as matching none.
   if (name === 'tick') {
     if (!line.credential && channelId) await openLine()
     return payFirst('tick', line.credential ? { line: line.credential } : args)
@@ -489,7 +471,6 @@ if (has('--tools')) {
 if (has('--call')) {
   const tool = flag('--call')
   if (!tool) { process.stderr.write('--call needs a tool name\n'); process.exit(2) }
-  // The JSON argument is optional: several tools take none.
   const rawArgs = argv[argv.indexOf('--call') + 2]
   let args = {}
   if (rawArgs && !rawArgs.startsWith('--')) {
@@ -512,9 +493,6 @@ if (has('--call')) {
 if (has('--refund')) {
   if (!channelId) { process.stderr.write('no channel to refund — nothing has been bought with this key and salt\n'); process.exit(2) }
 
-  // The channel is proved by signing for it, not by holding a session open. No
-  // line, no tick, no keep-warm: one message, one answer. Under a gift card the
-  // key here is the payerAuthorizer, which the server accepts for the same reason.
   const issued = new Date().toISOString()
   const message = `ZEAM Prism refund\nchannel: ${String(channelId).toLowerCase()}\nissued: ${issued}`
   const signature = await account.signMessage({ message })
@@ -541,10 +519,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.3",
+  "version": "2.0.5",
   "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": {