openzoo 0.3.0 → 0.4.0

package/README.md

@@ -96,7 +96,7 @@ bound once in 14.8s: 3.7MB → context ctx_01KZZY8YQE…
 quote for the ask: $0.000480 · pricing=markup (3× a tiny body — the 3.7MB corpus is not re-priced)
 ```
 
-If the wallet is funded with USDC it pays (capped at `OPENZOO_DEMO_MAX_USD`, default $0.01) and prints the answer, the tokens the model actually read, and the receipt. If not, it prints exactly what to fund. Long waits (the one-time upload, pricing, payment, the answer) show a live progress line with stage + elapsed seconds.
+If the wallet is funded with USDC or TOKEN it pays (capped at `OPENZOO_DEMO_MAX_USD`, default $0.01) and prints the answer, the tokens the model actually read, and the receipt. If not, it prints exactly what to fund. Long waits (the one-time upload, pricing, payment, the answer) show a live progress line with stage + elapsed seconds.
 
 **Run it twice.** The second run finds the corpus in the local manifest and never uploads it:
 
@@ -129,10 +129,14 @@ Opt out with `OPENZOO_NO_CONTEXT_CACHE=1` (always ship the full body); tune the
 ## The wallet model
 
 - **Burner, local, yours.** A keypair in `~/.openzoo/wallet.json`, created on first run, chmod 600. Keys never leave your machine — the zoo only ever sees signed transfers.
-- **Fund it with plain USDC.** Send a few cents of USDC to the address `npx openzoo address` prints. That's the whole funding story — the shim converts whatever the 402 quotes internally, at payment time, for exactly the amount needed.
+- **Fund it with USDC or TOKEN.** Send a few cents of either to the address `npx openzoo address` prints:
+  - **USDC** — `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
+  - **TOKEN** — `EVULoNF4DeMBN4dGiZiDfpiiTfNZgoCvXWWgaV3epump`
+
+  Both are first-class: each is the underlying of a live Solana rail the zoo quotes (USDC → yUSDCx, TOKEN → wTOKENx). That's the whole funding story — the shim converts whichever the 402 quotes internally, at payment time, for exactly the amount needed.
 - **SOL is optional but nice.** The gateway sponsors payment-transaction fees. If the wallet holds a pinch of SOL (~0.003), the internal conversion settles as its own transaction first; with zero SOL the conversion rides inside the gateway-sponsored payment transaction instead.
 - **Spend caps.** The proxy refuses any single quote above `OPENZOO_MAX_USD_PER_CALL` (default $0.50).
-- `npx openzoo balance` / `npx openzoo address` — check funds (USDC + SOL + USD value) / print the address.
+- `npx openzoo balance` / `npx openzoo address` — check funds (USDC + TOKEN + SOL + USD value) / print the address.
 
 ## Honest pricing note
 
@@ -147,7 +151,7 @@ The receipt names which base you got; `extra.directUsd` / `extra.savesVsDirect`
 
 | rail | network | status |
 |---|---|---|
-| **Solana** (default) | `solana:5eykt…` | **live** — Token-2022 `TransferChecked`, partial-signed, gateway pays fees. Tested end-to-end against the production 402. Settlement uses a wrapped settlement mint as internal plumbing; you only ever hold and send USDC. |
+| **Solana** (default) | `solana:5eykt…` | **live** — Token-2022 `TransferChecked`, partial-signed, gateway pays fees. Tested end-to-end against the production 402. Settlement uses a wrapped settlement mint as internal plumbing; you only ever hold and send USDC or TOKEN. |
 | Base | `eip155:8453` | implemented (standard x402 EIP-3009 `transferWithAuthorization`), **live-untested** — the zoo's 402s currently offer only Solana rows. |
 | Robinhood Chain | `eip155:4663` | experimental, behind `OPENZOO_ENABLE_RH=1` — the zoo ships this rail dark and facilitator settlement there is unverified. |
 

package/bin/openzoo.js

@@ -10,7 +10,7 @@ usage:
                          (run it twice — the second run reuses the bound corpus and is near-free)
   npx openzoo contexts   list corpora bound to the zoo (never re-uploaded)
   npx openzoo contexts --forget <hash|all>   drop manifest entries
-  npx openzoo balance    wallet balance (USDC + SOL, with USD value)
+  npx openzoo balance    wallet balance (USDC + TOKEN + SOL, with USD value)
   npx openzoo address    print the funding address
   npx openzoo help       this text
 

package/lib/config.js

@@ -13,3 +13,49 @@ export const config = {
   // Demo will only actually pay if the quote is at or below this.
   demoMaxUsd: Number(process.env.OPENZOO_DEMO_MAX_USD || 0.01),
 };
+
+/**
+ * Assets a user can fund the burner wallet with. Both are first-class: each is
+ * the underlying of a live Solana rail the zoo quotes (USDC -> yUSDCx,
+ * TOKEN -> wTOKENx), and the shim wraps whichever one it needs at payment time,
+ * for exactly the amount needed. Never mention one of these without the other.
+ */
+export const FUNDING_ASSETS = [
+  { symbol: 'USDC', mint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' },
+  { symbol: 'TOKEN', mint: 'EVULoNF4DeMBN4dGiZiDfpiiTfNZgoCvXWWgaV3epump' },
+];
+
+export const USDC_MINT = FUNDING_ASSETS[0].mint;
+export const TOKEN_MINT = FUNDING_ASSETS[1].mint;
+
+/** The one canonical way to tell a user how to fund. */
+export function fundingLine(address) {
+  return `send a few cents of USDC (${USDC_MINT}) or TOKEN (${TOKEN_MINT}) to ${address}`;
+}
+
+/**
+ * What the resource will actually settle, right now, read off a live 402 —
+ * never a hardcoded claim. Rails the code implements but the zoo is not
+ * currently offering are reported separately so nobody funds a dead lane.
+ * Underlying assets only: the wrapped settlement mints are internal plumbing.
+ */
+export async function liveRails() {
+  const r = await fetch(`${config.apiBase}/v1/chat/completions`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ model: 'nvidia/nemotron-3.5-lightning', messages: [{ role: 'user', content: 'ping' }], max_tokens: 1 }),
+  });
+  if (r.status !== 402) { await r.text().catch(() => {}); return null; }
+  const body = await r.json();
+  const rows = Array.isArray(body?.accepts) ? body.accepts : [];
+  const live = new Set();
+  for (const a of rows) {
+    const net = a?.network || '';
+    if (net.startsWith('solana:')) live.add('solana');
+    else if (/^eip155:8453$/.test(net)) live.add('base');
+    else if (/^eip155:4663$/.test(net)) live.add('robinhood');
+    else if (net) live.add(net);
+  }
+  const implemented = ['solana', 'base', 'robinhood'];
+  return { live: [...live], dark: implemented.filter((x) => !live.has(x)) };
+}

package/lib/demo.js

@@ -1,4 +1,4 @@
-import { config } from './config.js';
+import { config, fundingLine } from './config.js';
 import { PayClient, UnderfundedError } from './pay.js';
 import { parse402, pickAccept, tokenBalance } from './x402.js';
 import { startSpinner, postWithUploadSignal } from './spinner.js';
@@ -133,7 +133,7 @@ export async function runDemo() {
     console.log('3) wallet not funded yet, so stopping before payment.');
     console.log(`   quote : ≈ $${Number(x.billedUsd).toFixed(6)}`);
     console.log(`   wallet: $${(cov.usdcUi ?? 0).toFixed(2)} USDC`);
-    console.log(`   fund  : send a few cents of USDC to ${pub}`);
+    console.log(`   fund  : ${fundingLine(pub)}`);
     console.log('   then re-run `npx openzoo demo`.');
     return;
   }

package/lib/info.js

@@ -1,11 +1,9 @@
 import { Connection } from '@solana/web3.js';
 import { privateKeyToAccount } from 'viem/accounts';
-import { config } from './config.js';
+import { config, FUNDING_ASSETS, fundingLine } from './config.js';
 import { loadOrCreateWallet } from './wallet.js';
 import { tokenBalance } from './x402.js';
 
-const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
-
 export function printAddress() {
   const { keypair, evmPrivateKey, created, path } = loadOrCreateWallet();
   if (created) console.log(`new burner wallet created at ${path} (chmod 600)`);
@@ -16,16 +14,18 @@ export function printAddress() {
 export async function printBalance() {
   const { keypair } = loadOrCreateWallet();
   const connection = new Connection(config.rpcUrl, 'confirmed');
-  const [usdc, lamports] = await Promise.all([
-    tokenBalance(connection, keypair.publicKey, USDC),
+  const [balances, lamports] = await Promise.all([
+    Promise.all(FUNDING_ASSETS.map((a) => tokenBalance(connection, keypair.publicKey, a.mint))),
     connection.getBalance(keypair.publicKey),
   ]);
-  const usdcUi = usdc.ui ?? 0;
+  const usdcUi = balances[0].ui ?? 0;
   console.log(`wallet : ${keypair.publicKey.toBase58()}`);
-  console.log(`USDC   : ${usdcUi}`);
+  FUNDING_ASSETS.forEach((a, i) => {
+    console.log(`${a.symbol.padEnd(7)}: ${balances[i].ui ?? 0}`);
+  });
   console.log(`SOL    : ${lamports / 1e9}`);
-  console.log(`value  : ≈ $${usdcUi.toFixed(2)}`);
-  if (!usdc.raw) {
-    console.log(`fund   : send a few cents of USDC to ${keypair.publicKey.toBase58()}`);
+  console.log(`value  : ≈ $${usdcUi.toFixed(2)} (USDC leg; TOKEN valued at the 402)`);
+  if (!balances.some((b) => b.raw)) {
+    console.log(`fund   : ${fundingLine(keypair.publicKey.toBase58())}`);
   }
 }

package/lib/mcp.js

@@ -2,14 +2,13 @@ import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { config } from './config.js';
+import { config, FUNDING_ASSETS } from './config.js';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
 import { askWithContext, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
 import { listContexts } from './contexts.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
 const DEFAULT_MODEL = process.env.OPENZOO_DEMO_MODEL || 'nvidia/nemotron-3.5-lightning';
 
 function text(obj) {
@@ -89,14 +88,17 @@ export async function startMcp() {
     description: 'The local burner wallet: funding address, balances, and this session\'s payment receipts.',
     inputSchema: {},
   }, async () => {
-    const [usdc, lamports] = await Promise.all([
-      tokenBalance(client.connection, client.keypair.publicKey, USDC),
+    const [bals, lamports] = await Promise.all([
+      Promise.all(FUNDING_ASSETS.map((a) => tokenBalance(client.connection, client.keypair.publicKey, a.mint))),
       client.connection.getBalance(client.keypair.publicKey),
     ]);
+    const balances = { SOL: lamports / 1e9 };
+    FUNDING_ASSETS.forEach((a, i) => { balances[a.symbol] = bals[i].ui ?? 0; });
     return text({
       solanaAddress: client.address,
-      fundWith: 'USDC — send a few cents of USDC to this address',
-      balances: { USDC: usdc.ui ?? 0, SOL: lamports / 1e9, usdValue: usdc.ui ?? 0 },
+      fundWith: FUNDING_ASSETS.map((a) => `${a.symbol} (${a.mint})`).join(' or '),
+      fundHint: 'send a few cents of either to this address — the shim wraps whichever the 402 quotes, at payment time',
+      balances,
       receipts: client.receipts.map((r) => ({ at: r.at, line: r.line })),
     });
   });

package/lib/pay.js

@@ -1,6 +1,6 @@
 import { Connection, PublicKey } from '@solana/web3.js';
 import { getAssociatedTokenAddressSync } from '@solana/spl-token';
-import { config } from './config.js';
+import { config, fundingLine } from './config.js';
 import { loadOrCreateWallet } from './wallet.js';
 import {
   parse402, pickAccept, railOf, buildPaymentOnline, tokenBalance,
@@ -24,7 +24,7 @@ export class UnderfundedError extends Error {
     const usd = Number(accept?.extra?.billedUsd);
     const needs = Number.isFinite(usd) ? `this call needs ≈$${usd.toFixed(6)}` : 'this call needs more than the wallet holds';
     const holds = usdcUi != null ? ` — the wallet holds $${Number(usdcUi).toFixed(2)} USDC` : '';
-    super(`openzoo wallet underfunded: ${needs}${holds}. Send a few cents of USDC to ${address}.`);
+    super(`openzoo wallet underfunded: ${needs}${holds}. ${fundingLine(address).replace(/^s/, 'S')}.`);
     this.accept = accept;
     this.usdcUi = usdcUi;
     this.address = address;

package/lib/proxy.js

@@ -1,6 +1,6 @@
 import http from 'node:http';
 import { Readable } from 'node:stream';
-import { config } from './config.js';
+import { config, FUNDING_ASSETS, fundingLine, liveRails } from './config.js';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
 import { bindCorpus, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
@@ -179,13 +179,27 @@ export async function startProxy({ silent = false } = {}) {
     if (client.walletCreated) console.log(`new burner wallet created at ${client.walletPath} (chmod 600)`);
     console.log(`wallet (fund me): ${client.address}`);
     try {
-      const usdc = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
-      const bal = await tokenBalance(client.connection, client.keypair.publicKey, usdc);
-      console.log(`balance: ${bal.ui ?? 0} USDC (≈ $${(bal.ui ?? 0).toFixed(2)})`);
-      if (!bal.raw) {
-        console.log('fund it: send a few cents of USDC to the address above — a few cents goes a long way.');
+      const bals = await Promise.all(
+        FUNDING_ASSETS.map((a) => tokenBalance(client.connection, client.keypair.publicKey, a.mint)),
+      );
+      const parts = FUNDING_ASSETS.map((a, i) => `${bals[i].ui ?? 0} ${a.symbol}`);
+      console.log(`balance: ${parts.join('  ·  ')}`);
+      if (!bals.some((b) => b.raw)) {
+        console.log(`fund it: ${fundingLine('the address above')} — a few cents goes a long way.`);
       }
     } catch { /* RPC hiccup: balance is advisory */ }
+    // Which rails the zoo will actually settle right now, straight off a live
+    // 402 — so nobody funds a lane the resource is not currently offering.
+    try {
+      const rails = await liveRails();
+      if (rails) {
+        console.log(`rails live now: ${rails.live.join(' · ')}  (fund with USDC or TOKEN on solana)`);
+        if (rails.dark.length) {
+          const rh = rails.dark.includes('robinhood') ? ' — robinhood also needs OPENZOO_ENABLE_RH=1' : '';
+          console.log(`rails implemented but not offered by the zoo right now: ${rails.dark.join(' · ')}${rh}`);
+        }
+      }
+    } catch { /* quote probe is advisory */ }
     console.log('');
     console.log('point any OpenAI-compatible harness at:');
     console.log(`  base_url = http://localhost:${config.port}/v1`);

package/lib/wrap.js

@@ -2,7 +2,8 @@
  * Internal funding plumbing for Solana 402 rails.
  *
  * The zoo's Solana quotes settle in a NAV-wrapped Token-2022 mint issued by
- * the wrap-nav program (FrSER…). Users only ever hold and send plain USDC —
+ * the wrap-nav program (FrSER…). Users only ever hold and send plain USDC or
+ * TOKEN (EVULoNF4DeMBN4dGiZiDfpiiTfNZgoCvXWWgaV3epump) —
  * this module converts the exact amount needed, at payment time, inside the
  * shim. Nothing here is user-facing; never surface wrapped tickers or mints
  * in messages that reach the user.
@@ -18,7 +19,7 @@
  *   authority = PDA(['mint_authority', wrappedMint]); escrow = ATA(underlying,
  *   authority); registry = PDA(['backpointer', wrappedMint]) when present.
  */
-import { PublicKey, Transaction, TransactionInstruction, sendAndConfirmTransaction } from '@solana/web3.js';
+import { PublicKey, Transaction, TransactionInstruction } from '@solana/web3.js';
 import {
   TOKEN_PROGRAM_ID,
   TOKEN_2022_PROGRAM_ID,
@@ -200,9 +201,45 @@ export function buildWrapInstructions({ pool, owner, depositRaw, rentPayer = own
   ];
 }
 
+/**
+ * Confirm a signature by polling getSignatureStatuses over HTTP. Deliberately
+ * avoids connection.confirmTransaction: that path opens a websocket
+ * signatureSubscribe, and some RPC providers (fluxrpc) send a notification
+ * shape web3.js's schema rejects — the StructError fires inside the ws
+ * callback where no caller can catch it and takes down the whole process.
+ */
+export async function confirmSignatureByPolling(connection, signature, {
+  commitment = 'confirmed',
+  timeoutMs = 90000,
+  pollMs = 1500,
+} = {}) {
+  const accept = commitment === 'finalized' ? ['finalized'] : ['confirmed', 'finalized'];
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    let status = null;
+    try {
+      const res = await connection.getSignatureStatuses([signature]);
+      status = res?.value?.[0] ?? null;
+    } catch { /* transient RPC hiccup — keep polling until the deadline */ }
+    if (status) {
+      if (status.err) throw new Error(`transaction ${signature} failed on-chain: ${JSON.stringify(status.err)}`);
+      if (accept.includes(status.confirmationStatus)) return signature;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(`timed out after ${timeoutMs}ms waiting for confirmation of ${signature}`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
 /** Send a self-paid conversion tx and wait for confirmation. Returns the signature. */
 export async function sendWrap(connection, keypair, pool, depositRaw) {
   const ixs = buildWrapInstructions({ pool, owner: keypair.publicKey, depositRaw });
   const tx = new Transaction().add(...ixs);
-  return sendAndConfirmTransaction(connection, tx, [keypair], { commitment: 'confirmed' });
+  const { blockhash } = await connection.getLatestBlockhash('confirmed');
+  tx.recentBlockhash = blockhash;
+  tx.feePayer = keypair.publicKey;
+  tx.sign(keypair);
+  const sig = await connection.sendRawTransaction(tx.serialize());
+  return confirmSignatureByPolling(connection, sig, { commitment: 'confirmed' });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzoo",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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 rail live; Base/Robinhood rails experimental.",
   "license": "MIT",
   "type": "module",