openzoo 0.4.1 → 0.4.2

package/README.md

@@ -152,8 +152,10 @@ 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 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. |
+| Base | `eip155:8453` | **offered by the zoo** — standard x402 EIP-3009 `transferWithAuthorization` against native USDC. Fund the wallet's EVM address with USDC on Base; nothing is converted. Settlement from this package is live-untested. |
+| Robinhood Chain | `eip155:4663` | experimental, behind `OPENZOO_ENABLE_RH=1`. The zoo quotes it, but its settlement asset has no conversion path here (conversion is Solana-only), so there is no plain balance you can fund and have the shim spend — use Solana or Base. |
+
+`npx openzoo` prints the rails off a live 402 at startup, and the funding line is derived from those rails — so a new chain shows up without this package shipping again.
 
 The rail is chosen from the 402's `accepts[]` itself (Solana first). Amounts are always taken as raw units from the 402, and Solana decimals are read from the mint **on-chain** — never hardcoded. (The zoo's own pasted prompt hardcodes `decimals = 6`; that's wrong for 18-decimal mints and this package deliberately does not copy the bug.)
 

package/lib/config.js

@@ -28,9 +28,57 @@ export const FUNDING_ASSETS = [
 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. */
+/**
+ * The one canonical way to tell a user how to fund the SOLANA rail. Callers
+ * pass the Solana address; the rail is named explicitly because the wallet
+ * also has an EVM address for the Base / Robinhood rails.
+ */
 export function fundingLine(address) {
-  return `send a few cents of USDC (${USDC_MINT}) or TOKEN (${TOKEN_MINT}) to ${address}`;
+  return `send a few cents of USDC (${USDC_MINT}) or TOKEN (${TOKEN_MINT}) on Solana to ${address}`;
+}
+
+/**
+ * What a user funds each rail with — UNDERLYING assets only, and only assets
+ * this shim can actually spend from. The settlement mints the 402 quotes are
+ * internal plumbing and never appear in user-facing copy.
+ *
+ * Solana: quoted in settlement mints, converted from plain USDC / TOKEN at
+ *   payment time (lib/wrap.js).
+ * Base:   quoted in native USDC — funded and spent as-is, no conversion.
+ * Robinhood: quoted in a settlement asset with no conversion path on EVM
+ *   (wrapping is Solana-only), so there is no plain balance a user can fund
+ *   and have the shim pay from — hence no assets, and no funding line.
+ */
+export const RAIL_FUNDING = {
+  solana: { label: 'Solana', assets: ['USDC', 'TOKEN'] },
+  base: { label: 'Base', assets: ['USDC'] },
+  robinhood: { label: 'Robinhood Chain', assets: [] },
+};
+
+/**
+ * "USDC or TOKEN on Solana · USDC on Base" — the funding hint for exactly the
+ * rails a live 402 is offering, derived from liveRails().live. Rails with no
+ * fundable underlying, and networks we have no funding copy for (an
+ * unrecognised chain the zoo starts quoting), are left out rather than guessed
+ * at. Returns '' when nothing is fundable.
+ */
+export function railFundingHint(liveRailNames) {
+  return (liveRailNames || [])
+    .map((rail) => RAIL_FUNDING[rail])
+    .filter((spec) => spec?.assets.length)
+    .map((spec) => `${spec.assets.join(' or ')} on ${spec.label}`)
+    .join(' · ');
+}
+
+/**
+ * Rails the zoo is quoting right now that this shim cannot pay from a plain
+ * funded balance — named so a live rail never silently disappears from the
+ * funding advice.
+ */
+export function unfundableRails(liveRailNames) {
+  return (liveRailNames || [])
+    .filter((rail) => RAIL_FUNDING[rail] && !RAIL_FUNDING[rail].assets.length)
+    .map((rail) => RAIL_FUNDING[rail].label);
 }
 
 /**

package/lib/info.js

@@ -8,7 +8,7 @@ export function printAddress() {
   const { keypair, evmPrivateKey, created, path } = loadOrCreateWallet();
   if (created) console.log(`new burner wallet created at ${path} (chmod 600)`);
   console.log(keypair.publicKey.toBase58());
-  console.log(`(evm, for Base/RH rails — untested: ${privateKeyToAccount(evmPrivateKey).address})`);
+  console.log(`(evm, for the Base / Robinhood rails: ${privateKeyToAccount(evmPrivateKey).address})`);
 }
 
 export async function printBalance() {

package/lib/mcp.js

@@ -2,7 +2,7 @@ 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, FUNDING_ASSETS } from './config.js';
+import { config, FUNDING_ASSETS, liveRails, railFundingHint } from './config.js';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
 import { askWithContext, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
@@ -94,10 +94,17 @@ export async function startMcp() {
     ]);
     const balances = { SOL: lamports / 1e9 };
     FUNDING_ASSETS.forEach((a, i) => { balances[a.symbol] = bals[i].ui ?? 0; });
+    // Funding advice follows the rails the zoo is quoting right now, not a
+    // hardcoded Solana assumption. Fail soft: the probe is advisory.
+    const rails = await liveRails().catch(() => null);
+    const hint = rails ? railFundingHint(rails.live) : '';
     return text({
       solanaAddress: client.address,
-      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',
+      evmAddress: client.evmAddress,
+      railsLiveNow: rails?.live ?? null,
+      fundWith: hint || `${FUNDING_ASSETS.map((a) => a.symbol).join(' or ')} on Solana`,
+      solanaMints: Object.fromEntries(FUNDING_ASSETS.map((a) => [a.symbol, a.mint])),
+      fundHint: 'send a few cents of a listed asset to the address for that rail — Solana assets to solanaAddress, Base assets to evmAddress. The shim converts to whatever the 402 quotes, at payment time.',
       balances,
       receipts: client.receipts.map((r) => ({ at: r.at, line: r.line })),
     });

package/lib/proxy.js

@@ -1,6 +1,8 @@
 import http from 'node:http';
 import { Readable } from 'node:stream';
-import { config, FUNDING_ASSETS, fundingLine, liveRails } from './config.js';
+import {
+  config, FUNDING_ASSETS, fundingLine, liveRails, railFundingHint, unfundableRails, RAIL_FUNDING,
+} from './config.js';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
 import { bindCorpus, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
@@ -194,7 +196,17 @@ export async function startProxy({ silent = false } = {}) {
     try {
       const rails = await liveRails();
       if (rails) {
-        console.log(`rails live now: ${rails.live.join(' · ')}  (fund with USDC or TOKEN on solana)`);
+        console.log(`rails live now: ${rails.live.join(' · ')}`);
+        // Funding advice is derived from those rails, never hardcoded — the
+        // zoo can add a chain without this package shipping again.
+        const hint = railFundingHint(rails.live);
+        if (hint) console.log(`fund with:      ${hint}`);
+        const unfundable = unfundableRails(rails.live);
+        if (unfundable.length) {
+          const fundable = rails.live.filter((r) => RAIL_FUNDING[r]?.assets.length).map((r) => RAIL_FUNDING[r].label);
+          const instead = fundable.length ? `pay from ${fundable.join(' or ')} instead` : 'no fundable rail is offered right now';
+          console.log(`note:           ${unfundable.join(' / ')} is offered by the zoo but not fundable from a plain balance here — ${instead}.`);
+        }
         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}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openzoo",
-  "version": "0.4.1",
-  "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.",
+  "version": "0.4.2",
+  "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",
   "bin": {