openzoo 0.6.0 → 0.7.0

package/README.md

@@ -168,7 +168,7 @@ Pin the key with `OPENZOO_TUNNEL_TOKEN` if your IDE stores it. Keys never leave
 
   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.
-- **The same wallet file also holds an EVM key.** `npx openzoo address` prints both addresses: the Solana one, and the EVM one used by the Base and Robinhood Chain rails. Fund Base with plain **USDC on Base** (nothing is converted); for Robinhood Chain, deposit USDG at [x402.accrue.fund/start](https://x402.accrue.fund/start) so the wallet holds the settlement asset.
+- **The same wallet file also holds an EVM key.** `npx openzoo address` prints both addresses: the Solana one, and the EVM one used by the Base and Robinhood Chain rails. Fund Base with plain **USDC on Base** (nothing is converted); for Robinhood Chain, hold the plain token you want to pay with (USDG or a quoted memecoin) plus a sliver of RH ETH for gas — conversion happens automatically at payment time.
 - **Spend caps.** The proxy refuses any single quote above `OPENZOO_MAX_USD_PER_CALL` (default $0.50).
 - `npx openzoo balance` — funds on every rail, grouped per chain: Solana (USDC + TOKEN + SOL), Base (USDC + ETH), Robinhood Chain (USDG, the ODDBALLER / IOU / ROBINHOODS memecoins, ETH). USD value where a price is known; `$?` where not. `npx openzoo address` — both funding addresses.
 
@@ -189,7 +189,7 @@ All three rails have settled real payments (2026-08-14):
 |---|---|---|
 | **Solana** (default) | `solana:5eykt…` | **live** — Token-2022 `TransferChecked`, partial-signed, gateway pays fees. Settles daily; 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` | **live** — standard x402 EIP-3009 `transferWithAuthorization` against native USDC, batched settle through the facilitator. Fund the wallet's EVM address with USDC on Base; nothing is converted. |
-| Robinhood Chain | `eip155:4663` | **live** — EIP-3009 against the RH settlement asset, batched settle through the facilitator. There is no auto-conversion path here (conversion is Solana-only), so the wallet must hold the settlement asset itself: deposit USDG at [x402.accrue.fund/start](https://x402.accrue.fund/start). Default rail selection skips it unless `OPENZOO_ENABLE_RH=1`; `OPENZOO_RAIL=robinhood` forces it outright. |
+| Robinhood Chain | `eip155:4663` | **live** — EIP-3009, batched settle through the facilitator. Hold the plain token a row is quoted in (USDG, or the ODDBALLER / IOU / ROBINHOODS memecoins) and the shim converts exactly enough at payment time, automatically — two small on-chain steps paid from the wallet's own RH ETH. No gas? The error says exactly how much ETH to send and where. Default rail selection skips this chain unless `OPENZOO_ENABLE_RH=1`; `OPENZOO_RAIL=robinhood` forces it outright. |
 
 `npx openzoo` prints the rails off a live 402 at startup, and the funding line is derived from those rails — so a new chain (the wrapped RH memecoin twins are in-deploy, for example) shows up without this package shipping again.
 

package/lib/config.js

@@ -75,16 +75,20 @@ export function fundingLine(address) {
  * 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: the rail settles (real payments 2026-08-14), but it is quoted in
- *   a settlement asset with no conversion path in this shim (wrapping is
- *   Solana-only). To pay here, deposit USDG into the vault yourself at
- *   https://x402.accrue.fund/start so the wallet holds the settlement asset —
- *   there is no PLAIN balance the shim can auto-convert, hence no assets here.
+ * Robinhood: the rail settles (real payments 2026-08-14) and the shim
+ *   auto-converts at payment time (lib/evmwrap.js: approve + deposit into the
+ *   quoted vault, discovered on-chain via asset() — never hardcoded). Fund
+ *   with the PLAIN tokens; the two conversion txs are the wallet's own, so a
+ *   sliver of RH ETH for gas is also needed — the `note` rides the hint.
  */
 export const RAIL_FUNDING = {
   solana: { label: 'Solana', assets: ['USDC', 'TOKEN'] },
   base: { label: 'Base', assets: ['USDC'] },
-  robinhood: { label: 'Robinhood Chain', assets: [] },
+  robinhood: {
+    label: 'Robinhood Chain',
+    assets: ['USDG', 'ODDBALLER', 'ROBINHOODS'],
+    note: 'plus a sliver of RH ETH for the conversion gas',
+  },
 };
 
 /**
@@ -98,7 +102,7 @@ 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}`)
+    .map((spec) => `${spec.assets.join(' or ')} on ${spec.label}${spec.note ? ` (${spec.note})` : ''}`)
     .join(' · ');
 }
 

package/lib/evmwrap.js

@@ -0,0 +1,163 @@
+import { createPublicClient, createWalletClient, http, formatEther } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { evmChainId } from './x402.js';
+
+/**
+ * EVM auto-acquire — the Robinhood Chain mirror of wrap.js.
+ *
+ * The 402's settlement asset on eip155:4663 is an X402Wrapper twin: an
+ * ERC-4626-shaped vault + EIP-3009 over the plain token the user actually
+ * holds (source + deploy record: /Users/stacc/x402-wrappers, e.g. ODDBALLER /
+ * IOU / ROBINHOODS twins, and wUSDGx over USDG). Users hold the PLAIN token;
+ * this module converts exactly enough at payment time — approve + deposit —
+ * so the wrapper never appears in anything user-facing. Copy in every error
+ * names only the unwrapped token.
+ *
+ * Unlike Solana (where the gateway's feePayer can sponsor the conversion
+ * inside the payment tx), the approve+deposit here are the wallet's own
+ * transactions: the wallet must hold a sliver of native RH ETH. When it does
+ * not, the error says EXACTLY what to send and where.
+ */
+
+const WRAPPER_ABI = [
+  { type: 'function', name: 'asset', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+  { type: 'function', name: 'previewMint', stateMutability: 'view', inputs: [{ type: 'uint256' }], outputs: [{ type: 'uint256' }] },
+  { type: 'function', name: 'deposit', stateMutability: 'nonpayable', inputs: [{ type: 'uint256' }, { type: 'address' }], outputs: [{ type: 'uint256' }] },
+  { type: 'function', name: 'balanceOf', stateMutability: 'view', inputs: [{ type: 'address' }], outputs: [{ type: 'uint256' }] },
+];
+
+const ERC20_ABI = [
+  { type: 'function', name: 'balanceOf', stateMutability: 'view', inputs: [{ type: 'address' }], outputs: [{ type: 'uint256' }] },
+  { type: 'function', name: 'allowance', stateMutability: 'view', inputs: [{ type: 'address' }, { type: 'address' }], outputs: [{ type: 'uint256' }] },
+  { type: 'function', name: 'approve', stateMutability: 'nonpayable', inputs: [{ type: 'address' }, { type: 'uint256' }], outputs: [{ type: 'bool' }] },
+  { type: 'function', name: 'symbol', stateMutability: 'view', inputs: [], outputs: [{ type: 'string' }] },
+];
+
+/** Rough ceiling for approve + deposit on an Arbitrum-Orbit chain. */
+const ACQUIRE_GAS_UNITS = 400_000n;
+
+export class NeedsGasError extends Error {
+  constructor({ address, shortWei, symbol }) {
+    // round the ask up to a friendly margin so one top-up is enough
+    const ask = (shortWei * 3n) / 2n;
+    super(
+      `openzoo: converting your ${symbol} for this payment takes two small on-chain steps, `
+      + `and the wallet is short of gas. Send at least ${formatEther(ask)} ETH on Robinhood Chain `
+      + `(eip155:4663) to ${address}, then retry.`,
+    );
+    this.name = 'NeedsGasError';
+    this.address = address;
+    this.shortWei = shortWei;
+  }
+}
+
+export class UnderlyingShortError extends Error {
+  constructor({ symbol, haveRaw, needRaw, decimals, address }) {
+    const ui = (raw) => {
+      const d = BigInt(10) ** BigInt(decimals ?? 18);
+      return `${raw / d}.${(raw % d).toString().padStart(Number(decimals ?? 18), '0').slice(0, 4)}`;
+    };
+    super(
+      `openzoo wallet underfunded: this call needs ≈${ui(needRaw)} ${symbol} but the wallet `
+      + `holds ${ui(haveRaw)} ${symbol} (${address} on Robinhood Chain).`,
+    );
+    this.name = 'UnderlyingShortError';
+    this.symbol = symbol;
+    this.haveRaw = haveRaw;
+    this.needRaw = needRaw;
+  }
+}
+
+function chainFor(chainId, rpcUrl) {
+  return {
+    id: chainId,
+    name: `eip155:${chainId}`,
+    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    rpcUrls: { default: { http: [rpcUrl] } },
+  };
+}
+
+/**
+ * Ensure the wallet holds >= `need` raw units of the 402's settlement asset,
+ * converting the plain underlying token via approve + deposit when necessary.
+ *
+ * Resolution order:
+ *  - already funded -> { acquired: false }
+ *  - not a wrapper (no asset() view) -> { acquired: false, wrapper: false } —
+ *    the caller falls back to its plain underfunded message
+ *  - wrapper, wallet holds enough underlying + gas -> converts, waits for
+ *    receipts, returns { acquired: true, txs: [approveHash?, depositHash] }
+ *  - short of underlying -> UnderlyingShortError (names the plain token only)
+ *  - short of native gas -> NeedsGasError (says exactly what to send where)
+ */
+export async function acquireWrappedIfNeeded({ rpcUrl, accept, evmPrivateKey, onStage }) {
+  const chainId = evmChainId(accept.network);
+  const account = privateKeyToAccount(evmPrivateKey);
+  const pc = createPublicClient({ transport: http(rpcUrl) });
+  const need = BigInt(accept.maxAmountRequired);
+
+  const bal = await pc.readContract({ address: accept.asset, abi: WRAPPER_ABI, functionName: 'balanceOf', args: [account.address] });
+  if (bal >= need) return { acquired: false, wrapper: null };
+
+  let underlying;
+  try {
+    underlying = await pc.readContract({ address: accept.asset, abi: WRAPPER_ABI, functionName: 'asset', args: [] });
+  } catch {
+    return { acquired: false, wrapper: false }; // plain token — nothing to convert from
+  }
+
+  const short = need - bal;
+  // previewMint(short): underlying needed so the vault mints >= short shares
+  // (entry fee + rounding included by the contract itself — never re-derived here).
+  const assetsNeeded = await pc.readContract({ address: accept.asset, abi: WRAPPER_ABI, functionName: 'previewMint', args: [short] });
+
+  const symbol = await pc
+    .readContract({ address: underlying, abi: ERC20_ABI, functionName: 'symbol', args: [] })
+    .catch(() => 'underlying token');
+  const uBal = await pc.readContract({ address: underlying, abi: ERC20_ABI, functionName: 'balanceOf', args: [account.address] });
+  if (uBal < assetsNeeded) {
+    throw new UnderlyingShortError({
+      symbol,
+      haveRaw: uBal,
+      needRaw: assetsNeeded,
+      decimals: accept.extra?.decimals ?? 18,
+      address: account.address,
+    });
+  }
+
+  // Gas preflight — these two txs are the wallet's own, unlike the sponsored
+  // Solana path. Fail with the exact shortfall before signing anything.
+  const [gasPrice, native] = await Promise.all([pc.getGasPrice(), pc.getBalance({ address: account.address })]);
+  const gasBudget = ACQUIRE_GAS_UNITS * gasPrice;
+  if (native < gasBudget) {
+    throw new NeedsGasError({ address: account.address, shortWei: gasBudget - native, symbol });
+  }
+
+  onStage?.('funding');
+  const chain = chainFor(chainId, rpcUrl);
+  const wc = createWalletClient({ account, chain, transport: http(rpcUrl) });
+  const txs = [];
+
+  const allowance = await pc.readContract({
+    address: underlying, abi: ERC20_ABI, functionName: 'allowance', args: [account.address, accept.asset],
+  });
+  if (allowance < assetsNeeded) {
+    const approveHash = await wc.writeContract({
+      address: underlying, abi: ERC20_ABI, functionName: 'approve', args: [accept.asset, assetsNeeded],
+    });
+    await pc.waitForTransactionReceipt({ hash: approveHash });
+    txs.push(approveHash);
+  }
+
+  const depositHash = await wc.writeContract({
+    address: accept.asset, abi: WRAPPER_ABI, functionName: 'deposit', args: [assetsNeeded, account.address],
+  });
+  const receipt = await pc.waitForTransactionReceipt({ hash: depositHash });
+  txs.push(depositHash);
+  if (receipt.status !== 'success') throw new Error(`openzoo: converting ${symbol} for payment failed on-chain (tx ${depositHash})`);
+
+  const after = await pc.readContract({ address: accept.asset, abi: WRAPPER_ABI, functionName: 'balanceOf', args: [account.address] });
+  if (after < need) throw new Error(`openzoo: conversion landed but the balance still cannot cover the quote — retry, or fund more ${symbol}`);
+  if (process.env.OPENZOO_DEBUG) console.error(`[openzoo debug] evm acquire txs ${txs.join(', ')}`);
+  return { acquired: true, txs };
+}

package/lib/pay.js

@@ -7,6 +7,7 @@ import {
   receiptLine, decodeSettleHeader,
 } from './x402.js';
 import { buildEvmPayment, evmTokenBalance } from './evm.js';
+import { acquireWrappedIfNeeded } from './evmwrap.js';
 import { privateKeyToAccount } from 'viem/accounts';
 import {
   resolvePool, poolState, depositForShares, buildWrapInstructions, sendWrap,
@@ -85,10 +86,29 @@ export class PayClient {
       if (owner) {
         const bal = await evmTokenBalance({ rpcUrl, token: accept.asset, owner }).catch(() => null);
         if (bal !== null && bal < BigInt(accept.maxAmountRequired)) {
-          const line = rail === 'base'
-            ? `Send a few cents of USDC on Base to ${owner}.`
-            : `The wallet must hold the Robinhood Chain settlement asset — deposit USDG at https://x402.accrue.fund/start (wallet: ${owner}).`;
-          throw new UnderfundedError(accept, null, owner, { line });
+          if (rail === 'robinhood') {
+            // The RH settlement asset is a vault twin over the plain token the
+            // user actually holds. Convert exactly enough at payment time
+            // (approve + deposit) — the EVM mirror of the Solana top-up above.
+            // Throws NeedsGasError / UnderlyingShortError with exact, plain-
+            // token-named instructions when the wallet cannot convert. An RPC
+            // hiccup mid-probe falls through to the flat underfunded message.
+            let converted = null;
+            try {
+              converted = await acquireWrappedIfNeeded({
+                rpcUrl, accept, evmPrivateKey: this.evmPrivateKey, onStage,
+              });
+            } catch (e) {
+              if (e?.name === 'NeedsGasError' || e?.name === 'UnderlyingShortError' || /openzoo/.test(e?.message || '')) throw e;
+              converted = null;
+            }
+            if (!converted || converted.wrapper === false || (!converted.acquired && converted.wrapper !== null)) {
+              const line = `The wallet must hold the token this row is quoted in — fund ${owner} on Robinhood Chain, or see https://x402.accrue.fund/start.`;
+              throw new UnderfundedError(accept, null, owner, { line });
+            }
+          } else {
+            throw new UnderfundedError(accept, null, owner, { line: `Send a few cents of USDC on Base to ${owner}.` });
+          }
         }
       }
       return buildEvmPayment({ accept, evmPrivateKey: this.evmPrivateKey });

package/package.json

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