openzoo 0.50.13 → 0.50.15

package/lib/pay.js

@@ -339,10 +339,72 @@ export class PayClient {
       });
     }
     onStage?.('paying');
-    const response = await fetchHeaders(url, {
+    let response = await fetchHeaders(url, {
       ...init,
       headers: { ...stripAuthorization(init.headers || {}), ...paymentHeaders(payment.header) },
     });
+
+    // A REFUSED ATOMIC ROW MUST NOT TAKE THE WHOLE CALL DOWN.
+    //
+    // The candidate loop above only recovers from UnderfundedError; a payment
+    // the SERVER refuses happens out here, and used to surface as
+    // "zoo returned HTTP 402" with no second attempt. That is survivable for a
+    // row every client has always paid, and not survivable for the AtomicSettle
+    // row, which is newer, opt-in, and asks for a different signature — one
+    // gateway-side disagreement and every Base caller is dead in the water.
+    //
+    // So: if the row we chose was the atomic one and the server would not take
+    // it, drop back to the ordinary rows and pay again. We lose the
+    // response-bound receipt for this call and keep the call. Only the atomic
+    // row gets this treatment — a plain row being refused is a real failure and
+    // still surfaces.
+    if (response.status === 402 && accept?.extra?.settlement === 'atomic') {
+      const plain = candidates.filter((c) => c?.extra?.settlement !== 'atomic');
+      for (const cand of plain) {
+        try {
+          const retry = await this.buildPaymentFor(cand, onStage, quote);
+          const again = await fetchHeaders(url, {
+            ...init,
+            headers: { ...stripAuthorization(init.headers || {}), ...paymentHeaders(retry.header) },
+          });
+          if (again.status !== 402) {
+            accept = cand; payment = retry; response = again;
+            lastGoodAsset = memoKey(cand);
+            break;
+          }
+        } catch (e) {
+          if (!(e instanceof UnderfundedError)) throw e;
+        }
+      }
+    }
+
+    // A SOLANA BLOCKHASH EXPIRES, AND THE GATEWAY EXPECTS US TO REBUILD.
+    //
+    // Its failed-settle branch says so in as many words: "clean 402, retryable:
+    // the client rebuilds (fresh blockhash / topped-up balance) and pays against
+    // the re-quote". We never did. One expired blockhash was one dead request,
+    // and it surfaced to the user as a bare HTTP 402.
+    //
+    // MEASURED 2026-08-28, with the facilitator finally reporting the reason:
+    //   blockhash CmHMKGre… valid=false | feePayer 1.167 SOL | ixs 4 | bytes 526
+    // Not funding, not size — the signature had simply aged out. A client on a
+    // slow uplink sending a 109KB body round-trips past the ~60s window every
+    // single time, so it never recovered on its own: every call failed, for
+    // forty minutes, on a wallet holding $111.
+    //
+    // ONE retry, and only on a re-quote. Re-sending the SAME signed payment
+    // would carry the same dead blockhash; the point is to sign a new one
+    // against a fresh quote. More than once would turn a genuinely broken rail
+    // into a silent spend loop.
+    if (response.status === 402 && !this._rebuilt) {
+      this._rebuilt = true;
+      try {
+        const fresh = await this.fetch(url, init, { onStage });
+        return fresh;
+      } finally {
+        this._rebuilt = false;
+      }
+    }
     // NEVER PRESENT OUR OWN SIGNATURE AS THE TRANSACTION.
     //
     // This fell back to `{ signature: payment.ownerSignature }`, and on Solana

package/lib/x402.js

@@ -320,10 +320,33 @@ export function buildPayment({ accept, decimals, programId, recentBlockhash, key
   };
 }
 
-/** Resolve chain state (decimals, blockhash) and build the payment payload. */
+/**
+ * Resolve chain state (decimals, blockhash) and build the payment payload.
+ *
+ * FINALIZED, NOT CONFIRMED — WE SIGN HERE AND SOMEONE ELSE SENDS.
+ *
+ * A blockhash is only useful to the node that ultimately submits the
+ * transaction, and that is the FACILITATOR, on its own RPC. `confirmed` gives
+ * the freshest hash our RPC knows, which is precisely the problem: if our node
+ * is even slightly ahead, that block does not exist yet for theirs, and
+ * `isBlockhashValid` returns false for "never seen" exactly as it does for
+ * "expired". A finalized hash is known cluster-wide by definition.
+ *
+ * MEASURED 2026-08-28, once the facilitator was made to report the reason:
+ *   blockhash CmHMKGre… valid=false | feePayer 1.167 SOL | ixs 4 | bytes 526
+ * Not funding, not size. And the round trip was ~10s against a ~60s window, so
+ * it was not aging out either — the hash was simply never recognised. Every
+ * settle from one client failed for forty minutes on a wallet holding $111.
+ *
+ * The cost is ~13s of a ~60s window, which is the right trade when the whole
+ * round trip is ~10s: a slightly older hash that always works beats a fresher
+ * one that sometimes does not. Override with OPENZOO_BLOCKHASH_COMMITMENT if a
+ * future facilitator wants otherwise.
+ */
 export async function buildPaymentOnline(connection, keypair, accept) {
   const { programId, decimals } = await getMintInfo(connection, accept.asset);
-  const { blockhash } = await connection.getLatestBlockhash('confirmed');
+  const commitment = process.env.OPENZOO_BLOCKHASH_COMMITMENT || 'finalized';
+  const { blockhash } = await connection.getLatestBlockhash(commitment);
   return buildPayment({ accept, decimals, programId, recentBlockhash: blockhash, keypair });
 }
 

package/package.json

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