openzoo 0.20.6 → 0.20.7

package/lib/pay.js

@@ -41,6 +41,82 @@ export class UnderfundedError extends Error {
  * The proxy, the demo, and the MCP server all go through PayClient.fetch:
  * request → 402 → pick rail (Solana first) → sign → retry with X-PAYMENT.
  */
+/**
+ * Which offered asset last paid, and which are known underfunded — see the
+ * comment at the call site in fetch(). Process-lifetime with a TTL so a wallet
+ * that gets funded mid-session recovers on its own.
+ */
+/**
+ * BALANCE CACHE — checked semi-frequently in the background, not per call.
+ *
+ * MEASURED: a per-request balance probe put a mainnet round trip (and, when the
+ * row came back short, a full top-up probe: resolvePool + poolState + rent) on
+ * the critical path of EVERY inference — 4.52s of the 7s a one-line completion
+ * took. 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.
+ */
+const BALANCE_TTL_MS = Number(process.env.OPENZOO_BALANCE_TTL_MS || 60_000);
+const balanceCache = new Map();   // key -> { raw, ui, at, refreshing }
+
+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) {
+    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
+    }
+    return { raw: hit.raw, ui: hit.ui, cached: true, ageMs: Date.now() - hit.at };
+  }
+  const b = await tokenBalance(connection, owner, mint);
+  balanceCache.set(key, { raw: b.raw, ui: b.ui, at: Date.now(), refreshing: false });
+  return { ...b, cached: false, ageMs: 0 };
+}
+
+/** Debit what we just spent so a burst cannot overdraw a cached figure. */
+function debitCachedBalance(owner, mint, amount) {
+  const key = balKey(owner.toBase58 ? owner.toBase58() : String(owner), mint);
+  const hit = balanceCache.get(key);
+  if (hit) hit.raw = hit.raw > amount ? hit.raw - amount : 0n;
+}
+
+/** Test seam. */
+export function resetBalanceCache() { balanceCache.clear(); }
+
+const RAIL_MEMO_MS = Number(process.env.OPENZOO_RAIL_MEMO_MS || 120_000);
+const underfundedUntil = new Map();   // asset -> epoch ms after which to re-try it
+let lastGoodAsset = null;
+
+const memoKey = (a) => `${a?.network || ''}|${a?.asset || ''}`;
+
+/** lastGood first, known-underfunded last (never dropped — only deprioritised). */
+export function orderCandidatesByMemory(cands, now = Date.now()) {
+  const skip = (c) => (underfundedUntil.get(memoKey(c)) ?? 0) > now;
+  const good = (c) => lastGoodAsset && memoKey(c) === lastGoodAsset;
+  // Stable partition: proven payer, then untried, then recently-underfunded. The
+  // last group is KEPT so a wallet funded seconds ago is still reachable in the
+  // same call if nothing else works.
+  return [...cands].sort((a, b) => (good(b) - good(a)) || (skip(a) - skip(b)));
+}
+
+/** Test seam: forget everything the rail memory learned. */
+export function resetRailMemory() {
+  underfundedUntil.clear();
+  lastGoodAsset = null;
+}
+
 export class PayClient {
   constructor() {
     const w = loadOrCreateWallet();
@@ -65,7 +141,12 @@ export class PayClient {
     const rail = railOf(accept);
     if (rail === 'solana') {
       const need = BigInt(accept.maxAmountRequired);
-      const bal = await tokenBalance(this.connection, this.keypair.publicKey, accept.asset);
+      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 });
+      }
       if (bal.raw < need) {
         const topUp = await this.topUpQuotedAsset(accept, need, onStage);
         if (topUp.preInstructions) {
@@ -188,7 +269,18 @@ export class PayClient {
     // it HOLDS: every offered row is tried best-first, and only when NONE is
     // affordable does the call fail — never because the first-choice asset
     // alone ran dry while another funded one sat in the wallet.
-    const candidates = orderAccepts(quote, config.token, { allowRH: this.allowRH, forceRail: config.rail });
+    const ordered = orderAccepts(quote, config.token, { allowRH: this.allowRH, forceRail: config.rail });
+    // RAIL MEMORY — the single biggest source of per-call latency.
+    // MEASURED: the first offered row (yUSDCx) was underfunded, and finding that
+    // out costs 4.52s, because an underfunded Solana row attempts a top-up first
+    // (resolvePool + poolState + balances + rent-exemption lookups). The row that
+    // actually pays (wTOKENx) then builds in 0.36s. That 4.5s was being re-paid on
+    // EVERY request to rediscover a fact that had not changed.
+    // So: remember which asset just paid and try it first, and skip assets known
+    // underfunded within the TTL. Bounded and self-healing — the memo expires, a
+    // funded wallet is re-tried automatically, and if every row is memoized we fall
+    // back to the full list rather than manufacturing a dead end.
+    const candidates = orderCandidatesByMemory(ordered);
     onStage?.('quoted');
     let accept = null;
     let payment = null;
@@ -203,11 +295,18 @@ export class PayClient {
       try {
         payment = await this.buildPaymentFor(cand, onStage);
         accept = cand;
+        lastGoodAsset = memoKey(cand);
+        underfundedUntil.delete(memoKey(cand));
+        if (railOf(cand) === 'solana') {
+          try { debitCachedBalance(this.keypair.publicKey, cand.asset, BigInt(cand.maxAmountRequired)); } catch { /* advisory */ }
+        }
         break;
       } catch (e) {
         const funding = e instanceof UnderfundedError
           || e?.name === 'UnderlyingShortError' || e?.name === 'NeedsGasError';
         if (!funding) throw e;
+        // Remember it so the next call does not re-pay the discovery cost.
+        underfundedUntil.set(memoKey(cand), Date.now() + RAIL_MEMO_MS);
         fundErrs.push({ sym: cand?.extra?.symbol || cand?.asset, err: e });
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzoo",
-  "version": "0.20.6",
+  "version": "0.20.7",
   "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",