openzoo 0.50.37 → 0.50.39

package/lib/pay.js

@@ -53,21 +53,16 @@ export class UnderfundedError extends Error {
  * that gets funded mid-session recovers on its own.
  */
 /**
- * BALANCE CACHE — checked semi-frequently in the background, not per call.
+ * BALANCE CACHE — positive balances SWR for a few seconds; zeros are live.
  *
- * MEASURED: a per-request balance probe put a mainnet round trip on the critical
- * path of EVERY inference — 4.52s of the 7s a one-line completion took, most of
- * it the since-deleted conversion probe a short row triggered. Balances do not
- * move at request rate; a wallet spending $0.00004 a call has the same balance
- * it had a minute ago.
- *
- * Stale-while-revalidate: a cached value is returned IMMEDIATELY and a refresh is
- * kicked off in the background when it is older than the TTL, so no request ever
- * waits on the network for it. Only a cold cache (first call of the process)
- * blocks. A payment decrements the cached figure locally so a burst of calls
- * cannot overdraw between refreshes.
+ * A per-request probe used to add seconds to every call. A 60s SWR of $0 is
+ * worse: `openzoo balance` is live, so a TOKEN top-up shows in the CLI while
+ * the still-running proxy keeps throwing "underfunded" until the TTL dies.
+ * Restarting Grok Bot does not restart the proxy, so four app restarts do
+ * nothing. Re-read zeros (the just-funded case) and keep a short TTL on the
+ * rest. A payment still decrements the cached figure so a burst cannot overdraw.
  */
-const BALANCE_TTL_MS = Number(process.env.OPENZOO_BALANCE_TTL_MS || 60_000);
+const BALANCE_TTL_MS = Number(process.env.OPENZOO_BALANCE_TTL_MS || 8_000);
 const balanceCache = new Map();   // key -> { raw, ui, at, refreshing }
 
 const balKey = (owner, mint) => `${owner}|${mint}`;
@@ -75,14 +70,14 @@ const balKey = (owner, mint) => `${owner}|${mint}`;
 async function cachedTokenBalance(connection, owner, mint, { force = false } = {}) {
   const key = balKey(owner.toBase58 ? owner.toBase58() : String(owner), mint);
   const hit = balanceCache.get(key);
-  const fresh = hit && !force && (Date.now() - hit.at) < BALANCE_TTL_MS;
-  if (hit && !force) {
+  const zero = !!(hit && hit.raw === 0n);
+  const fresh = hit && !force && !zero && (Date.now() - hit.at) < BALANCE_TTL_MS;
+  if (hit && !force && !zero) {
     if (!fresh && !hit.refreshing) {
-      // SEMI-FREQUENT REFRESH: fire and forget, so the caller is never blocked.
       hit.refreshing = true;
       tokenBalance(connection, owner, mint)
         .then((b) => balanceCache.set(key, { raw: b.raw, ui: b.ui, at: Date.now(), refreshing: false }))
-        .catch(() => { hit.refreshing = false; });   // keep the last good value
+        .catch(() => { hit.refreshing = false; });
     }
     return { raw: hit.raw, ui: hit.ui, cached: true, ageMs: Date.now() - hit.at };
   }
@@ -101,7 +96,7 @@ function debitCachedBalance(owner, mint, amount) {
 /** Test seam. */
 export function resetBalanceCache() { balanceCache.clear(); }
 
-const RAIL_MEMO_MS = Number(process.env.OPENZOO_RAIL_MEMO_MS || 120_000);
+const RAIL_MEMO_MS = Number(process.env.OPENZOO_RAIL_MEMO_MS || 15_000);
 const underfundedUntil = new Map();   // asset -> epoch ms after which to re-try it
 let lastGoodAsset = null;
 
@@ -213,12 +208,7 @@ export class PayClient {
     const rail = railOf(accept);
     if (rail === 'solana') {
       const need = BigInt(accept.maxAmountRequired);
-      let bal = await cachedTokenBalance(this.connection, this.keypair.publicKey, accept.asset);
-      // Never declare a wallet short on a STALE read — the expensive top-up path
-      // and the underfunded error both deserve a live number.
-      if (bal.raw < need && bal.cached) {
-        bal = await cachedTokenBalance(this.connection, this.keypair.publicKey, accept.asset, { force: true });
-      }
+      const bal = await cachedTokenBalance(this.connection, this.keypair.publicKey, accept.asset, { force: true });
       // SHORT IS SHORT. The 402 quotes the raw native mint, so there is nothing
       // to convert and no pool to walk: the wallet either holds the asset or it
       // does not. This branch used to run resolvePool + poolState + a wrap
@@ -463,6 +453,9 @@ export class PayClient {
       // operator spent an evening searching Solscan for it as a tx hash —
       // an id a machine can log must be one a human can look up.
       tx: settle?.transaction || settle?.txHash || settle?.signature || null,
+      // SVM memo actually placed on the transfer (seller extra.memo, else the
+      // 16-byte hex uniqueness nonce). Never the ownerSignature.
+      memo: payment?.memo || accept?.extra?.memo || null,
       rail: railOf(accept),
       billedUsd: accept.extra?.billedUsd,
       directUsd: accept.extra?.directUsd,

package/lib/proxy.js

@@ -7,6 +7,7 @@ import { Readable } from 'node:stream';
 import {
   config, FUNDING_ASSETS, EVM_FUNDING_ASSETS, evmRpcFor, fundingLine, liveRails, railFundingHint, railFundingAddresses, unfundableRails, RAIL_FUNDING,
 } from './config.js';
+import { execSync } from 'node:child_process';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { withOnrampLink } from './stripeOnramp.js';
 import { tokenBalance } from './x402.js';
@@ -35,6 +36,22 @@ import { creditBalance, quotedPrices } from './info.js';
 import { priceHoldings } from './livestatus.js';
 import { receiptUsedCogs, receiptDirectUsd, pairActualBilled } from './racesettle.js';
 import { fetchHeaders } from './fetch.js';
+import { attachX402Proof } from './spendProof.js';
+
+/** Kill whatever is LISTEN on this port except this process. */
+export function killListen(port, run = execSync) {
+  try {
+    const pids = run(`lsof -nP -iTCP:${Number(port)} -sTCP:LISTEN -t`, {
+      encoding: 'utf8', timeout: 2000,
+    }).trim().split('\n').map(Number).filter((n) => Number.isInteger(n) && n > 0 && n !== process.pid);
+    for (const pid of pids) {
+      try { run(`kill ${pid}`, { stdio: 'ignore', timeout: 2000 }); } catch { /* already gone */ }
+    }
+    return pids;
+  } catch {
+    return [];
+  }
+}
 
 // THE SHIM IS A FACILITATOR, NOT A MIDDLEBOX.
 //
@@ -668,7 +685,7 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
 
     try {
       const result = await client.fetch(url, init);
-      const { response, paid, receipt } = result;
+      const { response, paid, receipt, accept } = result;
       if (paid && receipt) {
         if (receipt.ok && typeof receipt.billedUsd === 'number') {
           sessionSpent += receipt.billedUsd;
@@ -723,6 +740,13 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
           say(`credit -> $${x.billedUsd.toFixed(6)}  ·  session $${sessionSpent.toFixed(6)}`);
         }
         if (data?.object === 'chat.completion') {
+          if (paid && receipt) {
+            attachX402Proof(data, {
+              tx: receipt.tx,
+              memo: receipt.memo || accept?.extra?.memo,
+              rail: receipt.rail,
+            });
+          }
           if (rKey) replayPut(rKey, data, response.headers.get('x-payment-response'));
           if (wantsStream) { serveAsSse(res, data, response); return; }
           const h = { 'content-type': 'application/json' };
@@ -809,9 +833,8 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
   const bindHost = process.env.OPENZOO_BIND || '127.0.0.1';
   // SELF-HEAL A TAKEN PORT. Walk up to the next free port instead of dying;
   // the caller reads config.port back out, so every URL printed afterwards is
-  // the one we actually bound. EXCEPTION: if the thing already on the port is
-  // a HEALTHY openzoo proxy, reuse it rather than starting a rival that splits
-  // spend across two wallets.
+  // the one we actually bound. A healthy proxy already on the port is KILLED
+  // — reusing it left a stale PayClient serving $0 after a TOKEN top-up.
   const wanted = config.port;
   for (let attempt = 0; ; attempt++) {
     try {
@@ -824,13 +847,12 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
     } catch (e) {
       if (e?.code !== 'EADDRINUSE' || attempt >= 12) throw e;
       if (attempt === 0) {
-        try {
-          const probe = await fetch(`http://127.0.0.1:${config.port}/v1/models`, { signal: AbortSignal.timeout(2500) });
-          if (probe.ok) {
-            say(`openzoo: a healthy proxy is already on :${config.port} — reusing it`);
-            return { server: null, client, reused: true, port: config.port, spent: () => 0, publicUrl: null, tunnelToken: null, tunnelError: null };
-          }
-        } catch { /* not ours, or wedged — take the next port */ }
+        const pids = killListen(config.port);
+        if (pids.length) {
+          say(`openzoo: killed proxy on :${config.port} (pids ${pids.join(',')})`);
+          await new Promise((r) => setTimeout(r, 400));
+          continue;
+        }
       }
       config.port += 1;
       say(`openzoo: :${config.port - 1} busy — trying :${config.port}`);

package/lib/spendProof.js

@@ -0,0 +1,307 @@
+/**
+ * Spend-footer proof lines: explorer URL for the settle signature, decoded
+ * payment memo, one layman sentence of what that memo proves.
+ *
+ * The settle id is receipt.tx (facilitator transaction / txHash / signature).
+ * Never the SVM ownerSignature — that id is not on chain.
+ */
+
+const SOLSCAN = 'https://solscan.io/tx/';
+const BASESCAN = 'https://basescan.org/tx/';
+
+export function isRealTx(tx) {
+  if (typeof tx !== 'string') return false;
+  const s = tx.trim();
+  if (!s) return false;
+  if (s === 'null' || s === 'undefined' || s === '0' || s === '0x') return false;
+  return true;
+}
+
+export function collectTxs(src = {}) {
+  const out = [];
+  const seen = new Set();
+  const add = (t) => {
+    if (!isRealTx(t)) return;
+    const s = String(t).trim();
+    if (seen.has(s)) return;
+    seen.add(s);
+    out.push(s);
+  };
+  add(src.tx);
+  if (Array.isArray(src.txs)) src.txs.forEach(add);
+  return out;
+}
+
+function railName(rail, network) {
+  const r = String(rail || '').toLowerCase();
+  const net = String(network || '').toLowerCase();
+  if (r === 'base' || r === 'base-sepolia' || net === 'base' || net === 'base-sepolia'
+      || net.startsWith('eip155:8453') || /\bbase\b/.test(net)) return 'base';
+  if (r === 'solana' || net.startsWith('solana:') || net === 'solana') return 'solana';
+  if (r === 'robinhood' || net.includes('4663') || net.includes('robinhood')) return 'robinhood';
+  if (r === 'evm') return 'evm';
+  return r || '';
+}
+
+/** Explorer URL for a real settle signature. Null if missing or rail unknown-and-ambiguous. */
+export function explorerUrl(tx, { rail, network } = {}) {
+  try {
+    if (!isRealTx(tx)) return null;
+    const sig = String(tx).trim();
+    const r = railName(rail, network);
+    if (r === 'base') return BASESCAN + sig;
+    if (r === 'solana') return SOLSCAN + sig;
+    if (r === 'robinhood' || r === 'evm') return null;
+    if (/^0x[0-9a-fA-F]{64}$/.test(sig)) return null;
+    if (!sig.startsWith('0x') && sig.length >= 32 && sig.length <= 128) return SOLSCAN + sig;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function shortId(s, keep = 12) {
+  const t = String(s || '');
+  if (t.length <= keep * 2 + 1) return t;
+  return `${t.slice(0, keep)}…${t.slice(-keep)}`;
+}
+
+function parseOfferSet(raw) {
+  const s = String(raw || '').trim();
+  if (!/^x402:/i.test(s)) return null;
+  const parts = s.slice(s.indexOf(':') + 1).split('/');
+  if (parts.length < 6) return null;
+  const [v, scheme, network, payTo, asset, amount] = parts;
+  const tail = parts.slice(6);
+  let resource = '';
+  let timeout = '';
+  let quote = '';
+  if (tail.length >= 2 && /^\d+$/.test(tail[tail.length - 2])) {
+    quote = tail[tail.length - 1];
+    timeout = tail[tail.length - 2];
+    resource = tail.slice(0, -2).join('/');
+  } else if (tail.length) {
+    resource = tail.join('/');
+  }
+  return { v, scheme, network, payTo, asset, amount, resource, timeout, quote };
+}
+
+function isMerkleJson(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return false;
+  const leaf = obj.leaf || obj.merkleLeaf || obj.merkle_leaf;
+  const proof = obj.proof || obj.merkleProof || obj.merkle_proof;
+  const root = obj.root || obj.merkleRoot || obj.merkle_root;
+  if (leaf && (Array.isArray(proof) || root)) return true;
+  if (String(obj.kind || '').toLowerCase() === 'merkle' && leaf) return true;
+  return false;
+}
+
+const LABELED_LEAF = /^(?:leaf|merkle[-_]?leaf)[:\s=]+(?:0x)?([0-9a-f]{64})$/i;
+
+function jsonMeaningful(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj || {})) {
+    if (v == null) continue;
+    if (typeof v === 'string' && v.length > 120) out[k] = `${v.slice(0, 48)}…`;
+    else if (Array.isArray(v)) out[k] = v.length > 8 ? `[${v.length}]` : v;
+    else if (typeof v === 'object') out[k] = Object.keys(v).length > 12 ? '{…}' : v;
+    else out[k] = v;
+  }
+  try { return JSON.stringify(out); } catch { return String(obj); }
+}
+
+/**
+ * Decode a payment memo. Never claims a merkle membership proof unless the
+ * bytes actually encode a leaf/proof/root (JSON) or a labeled 32-byte leaf.
+ */
+export function decodeMemo(memo) {
+  try {
+    if (memo == null) return { kind: 'empty', decoded: null, proves: null };
+    const raw = Buffer.isBuffer(memo) ? memo.toString('utf8') : String(memo);
+    const trimmed = raw.trim();
+    if (!trimmed) return { kind: 'empty', decoded: null, proves: null };
+
+    if ((trimmed.startsWith('{') && trimmed.endsWith('}'))
+        || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+      try {
+        const obj = JSON.parse(trimmed);
+        if (isMerkleJson(obj)) {
+          const leaf = obj.leaf || obj.merkleLeaf || obj.merkle_leaf;
+          return {
+            kind: 'merkle',
+            decoded: jsonMeaningful(obj),
+            proves: `This hash (${shortId(leaf)}) is the leaf of a merkle tree; publishing it in the memo binds this payment to that leaf so anyone with the tree can verify inclusion.`,
+          };
+        }
+        return {
+          kind: 'json',
+          decoded: jsonMeaningful(obj),
+          proves: 'The payment memo is this JSON; it records what the payer attached, not a merkle membership proof unless a leaf/proof/root is present.',
+        };
+      } catch { /* not JSON */ }
+    }
+
+    const offer = parseOfferSet(trimmed);
+    if (offer) {
+      const who = offer.payTo || 'the listed payTo';
+      const asset = offer.asset || 'the listed asset';
+      const amt = offer.amount || '?';
+      const res = offer.resource || 'the listed resource';
+      const net = offer.network || 'the listed network';
+      return {
+        kind: 'offer_set',
+        decoded: `paid ${amt} of ${shortId(asset)} to ${shortId(who)} for ${res} on ${net}`
+          + (offer.scheme ? ` (${offer.scheme})` : ''),
+        proves: `This memo is the x402 offer: ${amt} units of asset ${asset} were paid to ${who} for ${res} on ${net}. Anyone can check it against the mint's on-chain offer; a server 402 that disagrees is lying.`,
+      };
+    }
+
+    const labeled = LABELED_LEAF.exec(trimmed);
+    if (labeled) {
+      const leaf = labeled[1];
+      return {
+        kind: 'merkle',
+        decoded: `merkle leaf ${leaf}`,
+        proves: `This hash is the leaf of a merkle tree; publishing it in the memo binds this payment to that leaf so anyone with the tree can verify inclusion.`,
+      };
+    }
+
+    const hex = trimmed.startsWith('0x') || trimmed.startsWith('0X') ? trimmed.slice(2) : trimmed;
+    if (/^[0-9a-fA-F]{32}$/.test(hex) && !/\s/.test(trimmed)) {
+      return {
+        kind: 'nonce',
+        decoded: `uniqueness nonce ${hex.toLowerCase()}`,
+        proves: 'This is a uniqueness nonce so two identical payments in the same blockhash window are distinct transactions — it is not a secret and not a merkle membership proof.',
+      };
+    }
+
+    if (/^[0-9a-fA-F]{64}$/.test(hex) && !/\s/.test(trimmed)) {
+      const leaf = hex.toLowerCase();
+      return {
+        kind: 'leaf',
+        decoded: `x402 leaf ${leaf}`,
+        proves: `x402-tokens Solana work-commitment: sha256(JSON.stringify([v, model, promptHash, gross, asset, resource])). Same Memo instruction as the token transfer; binds the payment to that quoted deal (model, prompt hash, price, mint, endpoint). The completion is not in the preimage — it did not exist at quote time. Not a merkle-tree membership proof. Preimage: https://x402-tokens.fly.dev/v1/receipts/proof?leaf=${leaf}`,
+      };
+    }
+
+    if (/^[\x20-\x7e\u00a0-\uffff]+$/.test(trimmed)) {
+      return {
+        kind: 'utf8',
+        decoded: trimmed.length > 240 ? `${trimmed.slice(0, 237)}…` : trimmed,
+        proves: 'The payment memo is this UTF-8 string; it was not an x402 offer-set record or a structured proof.',
+      };
+    }
+
+    return {
+      kind: 'unknown',
+      decoded: `undecodable (${Buffer.byteLength(raw)} bytes)`,
+      proves: 'The memo could not be decoded; it is not claimed as a merkle proof.',
+    };
+  } catch {
+    return {
+      kind: 'unknown',
+      decoded: 'undecodable',
+      proves: 'The memo could not be decoded; it is not claimed as a merkle proof.',
+    };
+  }
+}
+
+/** Copy settle tx / memo / rail onto the JSON body's x402 object (mutates). */
+export function attachX402Proof(data, proof = {}) {
+  try {
+    if (!data || typeof data !== 'object') return data;
+    if (!data.x402 || typeof data.x402 !== 'object') data.x402 = {};
+    const x = data.x402;
+    const txs = collectTxs({ tx: proof.tx ?? x.tx, txs: [...(Array.isArray(x.txs) ? x.txs : []), ...(Array.isArray(proof.txs) ? proof.txs : [])] });
+    if (txs.length) {
+      x.tx = txs[txs.length - 1];
+      x.txs = txs;
+    }
+    const memo = proof.memo;
+    if (typeof memo === 'string' && memo.length) x.memo = memo;
+    if (proof.rail) x.rail = proof.rail;
+    return data;
+  } catch {
+    return data;
+  }
+}
+
+/** Merge x402 proof fields across the several paid calls of one Grok Bot turn. */
+export function mergeTurnProof(prev, data) {
+  try {
+    const incoming = (data && typeof data === 'object' && data.x402 && typeof data.x402 === 'object')
+      ? data.x402
+      : {};
+    const base = prev && typeof prev === 'object' ? prev : {};
+    const txs = collectTxs({
+      tx: incoming.tx || base.tx,
+      txs: [...(Array.isArray(base.txs) ? base.txs : []), ...(Array.isArray(incoming.txs) ? incoming.txs : [])],
+    });
+    const out = { ...base, ...incoming };
+    if (txs.length) {
+      out.tx = txs[txs.length - 1];
+      out.txs = txs;
+    }
+    if (!out.memo && base.memo) out.memo = base.memo;
+    if (!out.rail && base.rail) out.rail = base.rail;
+    return out;
+  } catch {
+    return (data && data.x402) || prev || {};
+  }
+}
+
+/**
+ * Two leading newlines, then the existing spend lines, then optional
+ * tx / memo / proves. Never throws.
+ */
+export function formatSpendFooter({
+  billedUsd,
+  directUsd,
+  spent = 0,
+  would = 0,
+  saved = 0,
+  pct = 0,
+  balance = null,
+  x402 = {},
+  tx,
+  txs,
+  memo,
+  rail,
+  network,
+} = {}) {
+  try {
+    const lines = ['', ''];
+    const x = (x402 && typeof x402 === 'object') ? x402 : {};
+    if (billedUsd != null && Number.isFinite(Number(billedUsd))) {
+      lines.push(`this call $${Number(billedUsd).toFixed(6)} · OpenRouter $${Number(directUsd || 0).toFixed(6)}`);
+    }
+    const spentN = Number.isFinite(Number(spent)) ? Number(spent) : 0;
+    const wouldN = Number.isFinite(Number(would)) ? Number(would) : 0;
+    const savedN = Number.isFinite(Number(saved)) ? Number(saved) : 0;
+    const pctN = Number.isFinite(Number(pct)) ? Number(pct) : 0;
+    const bal = balance != null && Number.isFinite(Number(balance)) ? Number(balance) : null;
+    const balTxt = bal != null ? ` · balance $${bal.toFixed(2)}` : '';
+    lines.push(`spent $${spentN.toFixed(4)}${balTxt} · OpenRouter would $${wouldN.toFixed(4)} · saved $${savedN.toFixed(4)} (${pctN.toFixed(0)}%)`);
+
+    const sigs = collectTxs({ tx: tx ?? x.tx, txs: txs ?? x.txs });
+    const r = rail || x.rail;
+    const net = network || x.network;
+    for (const sig of sigs) {
+      const url = explorerUrl(sig, { rail: r, network: net });
+      if (url) lines.push(`tx ${url}`);
+    }
+    const mem = memo ?? x.memo;
+    if (mem != null && String(mem).length) {
+      const d = decodeMemo(mem);
+      if (d.decoded) lines.push(`memo ${d.decoded}`);
+      if (d.proves) lines.push(`proves ${d.proves}`);
+    }
+    const body = lines.filter((l) => l !== '').join('\n');
+    const billedN = Number(billedUsd);
+    const tagN = Number.isFinite(billedN) && billedN > 0.00005 ? billedN : spentN;
+    const tag = `$${tagN.toFixed(4)}`;
+    return `\n\n::oz-spend::${tag}\n${body}`;
+  } catch {
+    return '\n\n';
+  }
+}

package/lib/x402.js

@@ -309,10 +309,11 @@ export function buildPayment({ accept, decimals, programId, recentBlockhash, key
   // The seller's memo when they set one — some price it into the settlement —
   // else a random 16-byte hex nonce, which is what makes two concurrent
   // identical payments distinct messages.
+  const memo = String(accept.extra?.memo || crypto.randomBytes(16).toString('hex'));
   tx.add(new TransactionInstruction({
     keys: [],
     programId: MEMO_PROGRAM_ID,
-    data: Buffer.from(accept.extra?.memo || crypto.randomBytes(16).toString('hex'), 'utf8'),
+    data: Buffer.from(memo, 'utf8'),
   }));
   if (tx.instructions.length < 3 || tx.instructions.length > 7) {
     throw new Error(`x402 svm payment has ${tx.instructions.length} instructions, outside the required 3..7`);
@@ -337,6 +338,7 @@ export function buildPayment({ accept, decimals, programId, recentBlockhash, key
     amount,
     source,
     dest,
+    memo,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzoo",
-  "version": "0.50.37",
+  "version": "0.50.39",
   "description": "Local x402-paying proxy + MCP server for openzoo.fun — point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
   "license": "MIT",
   "type": "module",