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

package/README.md

@@ -26,7 +26,7 @@ arguments this is still an MCP stdio server, which is what an MCP client wants.
 The server holds an idle line for **5000ms** and bills for that time. This client
 drops its own after **four tick intervals (1000ms)** of no use, so a pause costs
 you a reopen rather than four seconds of billing. So `closesAfterIdleMs: 5000` in
-`services.json` is the server's ceiling, not this client's behaviour — expect a
+`services.json` is the server's ceiling, not this client's behavior — expect a
 line to reopen during a slow session. `X402_LINE=off` pays per call instead.
 
 ## Why you need it
@@ -87,11 +87,9 @@ 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.
@@ -104,21 +102,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 serialise, 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:
 
@@ -132,7 +130,7 @@ If the server refuses a call because the line is gone — an ordinary rotate or
 idle close — the bridge **reopens the line and retries**, and only pays per call
 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,
-serialised behind one channel, and when those run out of road they become unpaid
+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.
@@ -146,10 +144,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
 
@@ -185,8 +182,8 @@ reaching it the line drops and further calls return
 Keep `X402_STATE_DIR` on disk. A client that reconnects to an existing channel
 with empty state pays a deposit it did not need, and can only recover if its
 signer can **read the chain** — so this bridge always gives the signer a reader.
-By default that reader is the upstream's own free `/bootstrap` surface, which
-means recovery costs nothing and needs no RPC of your own.
+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

package/index.mjs

@@ -54,7 +54,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.')
@@ -72,7 +71,7 @@ mkdirSync(stateDir, { recursive: true })
 const readers = [
   ...(process.env.X402_RPC_URL ? [process.env.X402_RPC_URL] : []),
   ...(chain.rpcUrls?.default?.http ?? []),
-  new URL('/bootstrap', UPSTREAM).toString(),
+  new URL('/verify', UPSTREAM).toString(),
 ]
 const pub = createPublicClient({ chain, transport: fallback(readers.map(u => http(u))) })
 log(`chain reads: ${readers.map(u => new URL(u).host).join(' -> ')}` +
@@ -95,11 +94,8 @@ 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$/, '')
@@ -116,8 +112,6 @@ let spentMicroUSD = 0
 let quoteMicroUSD = null                 // set from the seller's own terms
 let spendUnit = 'micro-USD'              // what the numbers we report actually ARE
 
-// 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]) {
@@ -128,8 +122,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)
@@ -191,6 +183,7 @@ log(`paying as ${account.address} -> ${UPSTREAM}`)
 const termsURL = new URL('/.well-known/x402', UPSTREAM).toString()
 let accepts = null
 let tickAccepts = null
+let lineFacts = { tickMs: 250, microUSDPerMs: null }
 const loadTerms = async () => {
   const r = await fetch(termsURL)
   const j = await r.json()
@@ -199,6 +192,13 @@ const loadTerms = async () => {
   tickAccepts = Array.isArray(j.tickAccepts) && j.tickAccepts.length
     ? { x402Version: j.x402Version ?? 1, accepts: j.tickAccepts }
     : accepts                                    // an upstream that does not sell time
+  const ln = j.limits?.line ?? j.payment?.limits?.line
+  lineFacts = {
+    tickMs: Number(ln?.tickMs) > 0 ? Number(ln.tickMs) : lineFacts.tickMs,
+    microUSDPerMs: Number(j.rate?.microUSDPerMillisecond) > 0
+      ? Number(j.rate.microUSDPerMillisecond) : lineFacts.microUSDPerMs,
+  }
+
   const q = quoteFromTerms(j)
   if (q !== null) {
     if (q !== quoteMicroUSD) log(`quote: ${q} micro-USD per call, from the seller's own terms`)
@@ -233,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
@@ -290,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
 }
@@ -345,22 +339,32 @@ const openLine = () => {
     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 = Number(m.tickMs) || 250
-        // 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.tickMs = lineFacts.tickMs
         line.lastUse = Date.now()
-        log(`line open — ${m.microUSDPerMs ?? 1} micro-USD/ms, collateral buys ${m.buysMs ?? '?'}ms`)
+        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)
@@ -394,12 +398,10 @@ 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.
-  if (name === 'tick') return payFirst('tick', line.credential ? { line: line.credential } : args)
+  if (name === 'tick') {
+    if (!line.credential && channelId) await openLine()
+    return payFirst('tick', line.credential ? { line: line.credential } : args)
+  }
   if (LINE_MODE === 'off') return payFirst(name, args)
 
   if (LINE_MODE === 'auto') {
@@ -469,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('--')) {
@@ -492,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 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeam-labs/x402-mcp-bridge",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "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": {