openzoo 0.50.14 → 0.50.16

package/lib/pay.js

@@ -377,6 +377,34 @@ export class PayClient {
         }
       }
     }
+
+    // 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

@@ -3,6 +3,7 @@ import {
   ComputeBudgetProgram,
   Connection,
   PublicKey,
+  SystemProgram,
   Transaction,
   TransactionInstruction,
 } from '@solana/web3.js';
@@ -271,7 +272,7 @@ export const MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqX
  * them in one window under 10 workers). The spec now puts uniqueness in the
  * memo, so the CU limit is a plain constant and the nonce is the memo body.
  */
-export function buildPayment({ accept, decimals, programId, recentBlockhash, keypair }) {
+export function buildPayment({ accept, decimals, programId, recentBlockhash, keypair, nonce = null }) {
   const mint = new PublicKey(accept.asset);
   const payTo = new PublicKey(accept.payTo);
   const feePayer = new PublicKey(accept.extra.feePayer);
@@ -281,6 +282,25 @@ export function buildPayment({ accept, decimals, programId, recentBlockhash, key
   const dest = getAssociatedTokenAddressSync(mint, payTo, true, programId);
 
   const tx = new Transaction({ feePayer, recentBlockhash });
+  // A DURABLE NONCE, WHEN THE FACILITATOR OFFERS ONE — and `nonceAdvance` MUST
+  // be the first instruction, which is why this precedes the compute budget.
+  //
+  // `recentBlockhash` is inside the signed message and expires after ~150 slots
+  // (~60s). x402 signs here and settles over there, so a slow uplink or a large
+  // body kills a valid payment and nobody downstream can refresh the hash.
+  // MEASURED 2026-08-28: every settle from one client failed for forty minutes
+  // with `blockhash … valid=false`, funded fee payer, 526 bytes — nothing wrong
+  // with it but age. With a nonce in that slot the transaction never expires.
+  //
+  // The authority is a dedicated facilitator key, NOT the fee payer:
+  // scheme_exact_svm forbids the fee payer from appearing in any instruction's
+  // accounts, and an advance names its authority as a signer.
+  if (nonce?.account && nonce?.authority) {
+    tx.add(SystemProgram.nonceAdvance({
+      noncePubkey: new PublicKey(nonce.account),
+      authorizedPubkey: new PublicKey(nonce.authority),
+    }));
+  }
   tx.add(ComputeBudgetProgram.setComputeUnitLimit({ units: 200_000 }));
   tx.add(ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1 }));
   tx.add(createTransferCheckedInstruction(
@@ -294,8 +314,8 @@ export function buildPayment({ accept, decimals, programId, recentBlockhash, key
     programId: MEMO_PROGRAM_ID,
     data: Buffer.from(accept.extra?.memo || crypto.randomBytes(16).toString('hex'), 'utf8'),
   }));
-  if (tx.instructions.length < 3 || tx.instructions.length > 6) {
-    throw new Error(`x402 svm payment has ${tx.instructions.length} instructions, outside the required 3..6`);
+  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`);
   }
   // THE FEE PAYER MUST NOT APPEAR IN ANY INSTRUCTION'S ACCOUNTS. It is the
   // facilitator's gas signer; letting it in means their signature can be made
@@ -320,11 +340,63 @@ 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');
-  return buildPayment({ accept, decimals, programId, recentBlockhash: blockhash, keypair });
+
+  // PREFER A DURABLE NONCE. The facilitator leases one from a pool; with it in
+  // the blockhash slot the signed payment never expires, which removes the
+  // whole class of "valid=false, no logs" failures. Best-effort by design: no
+  // nonce, a slow facilitator, or an exhausted pool all fall through to a
+  // recent blockhash, because a 60-second window beats no payment at all.
+  let nonce = null;
+  const facilitator = accept?.extra?.facilitator;
+  // OPT-IN UNTIL IT HAS SETTLED ONCE FOR REAL.
+  //
+  // The fallback below covers a missing/slow/exhausted nonce, but NOT a
+  // malformed nonce transaction — if the instruction order or the account metas
+  // are wrong, the payment fails and the fallback never runs, because we only
+  // learn at settle time. This has not yet settled a single real payment, and
+  // shipping it on by default would bet every Solana payer on that. Set
+  // OPENZOO_NONCE=1 to use it; the default stays on recent blockhashes.
+  if (facilitator && process.env.OPENZOO_NONCE === '1') {
+    try {
+      const r = await fetch(`${facilitator}/nonce?network=${encodeURIComponent(accept.network)}`, {
+        signal: AbortSignal.timeout(4000),
+      });
+      if (r.ok) {
+        const j = await r.json();
+        if (j?.account && j?.nonce && j?.authority) nonce = j;
+      }
+    } catch { /* fall through to a blockhash */ }
+  }
+
+  const recentBlockhash = nonce
+    ? nonce.nonce
+    : (await connection.getLatestBlockhash(process.env.OPENZOO_BLOCKHASH_COMMITMENT || 'finalized')).blockhash;
+  return buildPayment({ accept, decimals, programId, recentBlockhash, keypair, nonce });
 }
 
 /** Token balance of our ATA for a mint. Returns { raw: bigint, ui: number|null }. */

package/package.json

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