agent402-openclaw 0.5.2 → 0.5.4

package/README.md

@@ -76,7 +76,10 @@ export AGENT402_MAX_PER_CALL_USD=2   # per-call ceiling checked before signing (
 ```
 
 With no credits key present the proxy signs an x402 payment per call from that
-wallet. The key never leaves the machine.
+wallet. The key never leaves the machine. The ceiling is checked on the payment
+option that is signed, priced from the known decimals of its asset (USDC or
+USDG on a known network); an option in any other asset is not signed while a
+ceiling is set.
 
 Two ways the wallet can pay a metered call:
 

package/index.js

@@ -8,6 +8,8 @@ import { join } from "node:path";
 import { buildProvider, setActiveProxy, setCachedRoutes, DEFAULT_PORT, PLUGIN_ID } from "./provider.js";
 import { startProxy, loadRoutes, DEFAULT_UPSTREAM } from "./proxy.js";
 import { stripTrailingSlashes } from "./models.js";
+import { acceptUsd } from "./known-assets.js";
+export { acceptUsd, KNOWN_ASSETS } from "./known-assets.js";
 
 export const STATE_DIR = () => join(process.env.AGENT402_OPENCLAW_HOME || join(homedir(), ".openclaw"), "agent402");
 export const CREDITS_KEY_FILE = () => join(STATE_DIR(), "credits.key");
@@ -63,17 +65,12 @@ export function maxPerCallUsd(pluginConfig = {}) {
   const n = Number(raw);
   return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_PER_CALL_USD;
 }
-/** Dollar value of an accept's quote: `amount` (v2) or `maxAmountRequired` (v1)
- *  in base units over the asset's `extra.decimals` (USDC on Base: 6). Unknown
- *  shape reads as null, and null is REFUSED under a finite ceiling: a quote we
- *  cannot read is not one we sign. */
-export function acceptUsd(accept) {
-  const raw = accept?.amount ?? accept?.maxAmountRequired;
-  if (raw == null || !/^\d+$/.test(String(raw))) return null;
-  const dec = Number(accept?.extra?.decimals ?? 6);
-  if (!Number.isInteger(dec) || dec < 0 || dec > 36) return null;
-  return Number(raw) / 10 ** dec;
-}
+// The dollar value of an accept's quote is acceptUsd (./known-assets.js):
+// `amount` (v2) or `maxAmountRequired` (v1) in base units over the KNOWN
+// decimals of its asset, never a decimals value the seller sends, since the
+// signer signs the raw amount. An accept in an asset outside the table, or
+// with no whole-number amount, reads as null, and null is REFUSED under a
+// finite ceiling: a quote we cannot price is not one we sign.
 export function selectAccept(accepts, { preferUpto = true, maxUsd = Infinity } = {}) {
   const list = Array.isArray(accepts) ? accepts : [];
   const pick = (preferUpto && list.find((a) => a?.scheme === "upto" && a?.network === BASE_CAIP2))
@@ -106,7 +103,7 @@ export async function resolvePayFetch(pluginConfig = {}, log = () => {}) {
       upto = uptoReady(allowance);
       const maxUsd = maxPerCallUsd(pluginConfig);
       const client = new x402Client((v, accepts) => selectAccept(accepts, { preferUpto: upto, maxUsd }));
-      client.setSpendControls?.(false); // the vendor default ($1, pegged assets only) would refuse USDG and any quote over $1; selectAccept enforces our own maxPerCallUsd (same $1 default) instead
+      client.setSpendControls?.(false); // the vendor default ($1, its own default assets only) would refuse USDG and any quote over $1; selectAccept holds the accept that is signed to our own maxPerCallUsd instead
       registerExactEvmScheme(client, { signer });
       if (upto) client.register(BASE_CAIP2, new UptoEvmScheme(signer));
       log(upto
@@ -117,7 +114,7 @@ export async function resolvePayFetch(pluginConfig = {}, log = () => {}) {
       // The allowance read or the upto scheme failed: exact still works.
       log(`[agent402-openclaw] upto unavailable (${String(e?.message || e).slice(0, 120)}) - paying exact`);
       const client = new x402Client((v, accepts) => selectAccept(accepts, { preferUpto: false, maxUsd: maxPerCallUsd(pluginConfig) }));
-      client.setSpendControls?.(false); // the vendor default ($1, pegged assets only) would refuse USDG and any quote over $1; selectAccept enforces our own maxPerCallUsd (same $1 default) instead
+      client.setSpendControls?.(false); // the vendor default ($1, its own default assets only) would refuse USDG and any quote over $1; selectAccept holds the accept that is signed to our own maxPerCallUsd instead
       registerExactEvmScheme(client, { signer });
       return wrapFetchWithPayment(fetch, client);
     }

package/known-assets.js

@@ -0,0 +1,120 @@
+// Known payment assets, and the USD value of an x402 accept priced from them.
+//
+// An x402 "exact" signer signs the accept's raw base-unit `amount` for the
+// accept's `asset`. A spending cap therefore has to price that amount with the
+// asset's real decimals, and a decimals hint the seller sends beside it (for
+// example `extra.decimals`) is not evidence of anything. So the price of an
+// accept comes from this table alone: the stablecoins each network settles on
+// the Agent402 rails, with their on-chain decimals. An accept whose
+// (network, asset) pair is not in the table cannot be priced, and a buyer with
+// a cap does not sign it.
+//
+// The same file ships in agent402-client, agent402-mcp and agent402-openclaw;
+// the parent repo's scripts/test-known-assets.js keeps the copies identical and
+// checks the table against the assets the server offers.
+
+/** network (CAIP-2) -> the assets a buyer may price there. */
+export const KNOWN_ASSETS = Object.freeze({
+  // EVM: USDC (native Circle) unless named otherwise.
+  "eip155:8453": [{ asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", decimals: 6, symbol: "USDC" }], // Base
+  "eip155:84532": [{ asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", decimals: 6, symbol: "USDC" }], // Base Sepolia
+  "eip155:137": [{ asset: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", decimals: 6, symbol: "USDC" }], // Polygon
+  "eip155:42161": [{ asset: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", decimals: 6, symbol: "USDC" }], // Arbitrum
+  "eip155:143": [{ asset: "0x754704Bc059F8C67012fEd69BC8A327a5aafb603", decimals: 6, symbol: "USDC" }], // Monad
+  "eip155:42220": [{ asset: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C", decimals: 6, symbol: "USDC" }], // Celo
+  "eip155:43114": [{ asset: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", decimals: 6, symbol: "USDC" }], // Avalanche
+  "eip155:1329": [{ asset: "0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392", decimals: 6, symbol: "USDC" }], // Sei
+  "eip155:10": [{ asset: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", decimals: 6, symbol: "USDC" }], // Optimism
+  "eip155:5042": [{ asset: "0x3600000000000000000000000000000000000000", decimals: 6, symbol: "USDC" }], // Arc
+  "eip155:4663": [{ asset: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", decimals: 6, symbol: "USDG" }], // Robinhood Chain
+  // Solana: the USDC mint.
+  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": [{ asset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", decimals: 6, symbol: "USDC" }],
+  "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": [{ asset: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", decimals: 6, symbol: "USDC" }], // devnet
+  // Stellar: the USDC Stellar Asset Contract (7 decimals on Stellar).
+  "stellar:pubnet": [{ asset: "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75", decimals: 7, symbol: "USDC" }],
+  // Algorand: USDC is ASA 31566704.
+  "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=": [{ asset: "31566704", decimals: 6, symbol: "USDC" }],
+});
+
+const EVM_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+// EVM addresses compare without case (checksum casing is presentation);
+// base58, Stellar and Algorand identifiers compare exactly.
+const sameAsset = (a, b) => (EVM_ADDRESS.test(a) && EVM_ADDRESS.test(b) ? a.toLowerCase() === b.toLowerCase() : a === b);
+
+/** The table entry for (network, asset), or null when it is not a known asset. */
+export function knownAsset(network, asset) {
+  if (typeof network !== "string" || typeof asset !== "string" || !asset) return null;
+  const list = KNOWN_ASSETS[network];
+  if (!list) return null;
+  return list.find((e) => sameAsset(e.asset, asset)) || null;
+}
+
+/** The USD value of one accept: its base-unit amount (`amount` in x402 v2,
+ *  `maxAmountRequired` in v1) over the KNOWN decimals of its asset. null when
+ *  the asset is not known or the amount is not a whole number of base units. */
+export function acceptUsd(accept) {
+  if (!accept || typeof accept !== "object") return null;
+  const raw = accept.amount ?? accept.maxAmountRequired;
+  if (raw == null || !/^\d+$/.test(String(raw))) return null;
+  const entry = knownAsset(accept.network, accept.asset);
+  if (!entry) return null;
+  return Number(raw) / 10 ** entry.decimals;
+}
+
+/** The USD values of a 402's accepts: `max` and `min` over the accepts that can
+ *  be priced, and `unknown`, the count that cannot. null when there are none. */
+export function quoteOf(accepts) {
+  if (!Array.isArray(accepts) || !accepts.length) return null;
+  let max = null, min = null, unknown = 0;
+  for (const a of accepts) {
+    const usd = acceptUsd(a);
+    if (usd == null) { unknown++; continue; }
+    if (max == null || usd > max) max = usd;
+    if (min == null || usd < min) min = usd;
+  }
+  return { max, min, unknown, total: accepts.length };
+}
+
+/** Enforce a USD allowance at signing on an @x402/core x402Client.
+ *
+ *  `allowance()` is the most this buyer may sign for the payment being built
+ *  (a per-call cap, a remaining budget, or the smaller of the two; Infinity
+ *  for none). A registered policy drops every accept that cannot be priced or
+ *  is over the allowance, so the client selects among the ones that fit, and a
+ *  hook before payload creation checks the selected accept again and passes
+ *  its USD value to `onSign`. A refusal throws (from the policy) or aborts
+ *  (from the hook) before any signature exists; `onRefuse` hears why first. */
+export function guardSigning(client, { allowance, onSign = null, onRefuse = null }) {
+  if (!client || typeof client.registerPolicy !== "function" || typeof client.onBeforePaymentCreation !== "function") {
+    throw new TypeError("guardSigning needs an @x402/core x402Client (registerPolicy and onBeforePaymentCreation)");
+  }
+  if (typeof allowance !== "function") throw new TypeError("guardSigning needs an allowance() function");
+  const refuse = (detail) => { try { onRefuse?.(detail); } catch { /* the refusal stands */ } return detail; };
+  client.registerPolicy((version, accepts) => {
+    const cap = allowance();
+    const kept = accepts.filter((a) => { const usd = acceptUsd(a); return usd != null && usd <= cap; });
+    if (!kept.length) {
+      const q = quoteOf(accepts);
+      const d = refuse({ reason: q && q.min != null ? "over-allowance" : "unknown-asset", priceUsd: q ? q.min : null, allowanceUsd: cap });
+      throw new Error(d.reason === "unknown-asset"
+        ? "spending guard: no payment option is in a known asset, so none can be priced; nothing was signed"
+        : `spending guard: the cheapest payment option asks $${d.priceUsd}, above the $${cap} this buyer may sign; nothing was signed`);
+    }
+    return kept;
+  });
+  client.onBeforePaymentCreation(async ({ selectedRequirements: r }) => {
+    const usd = acceptUsd(r);
+    const cap = allowance();
+    if (usd == null) {
+      refuse({ reason: "unknown-asset", priceUsd: null, allowanceUsd: cap });
+      return { abort: true, reason: "spending guard: the selected payment option is not in a known asset; nothing was signed" };
+    }
+    if (usd > cap) {
+      refuse({ reason: "over-allowance", priceUsd: usd, allowanceUsd: cap });
+      return { abort: true, reason: `spending guard: the selected payment option asks $${usd}, above the $${cap} this buyer may sign; nothing was signed` };
+    }
+    onSign?.(usd, r);
+    return undefined;
+  });
+  return client;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent402-openclaw",
-  "version": "0.5.2",
-  "description": "OpenClaw model provider for Agent402: an auto-routed tier at a flat per-call price and explicit LLM models priced per request, paid in USDC over x402 or with a prepaid credits key through a local proxy. Zero dependencies; x402 wallet payment is an optional peer.",
+  "version": "0.5.4",
+  "description": "OpenClaw model provider for Agent402: an auto-routed tier at a flat per-call price and explicit LLM models priced per request, paid in USDC over x402, or with a prepaid credits key already issued, through a local proxy. Zero dependencies; x402 wallet payment is an optional peer.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "index.js",
+    "known-assets.js",
     "provider.js",
     "models.js",
     "proxy.js",

package/proxy.js

@@ -47,9 +47,52 @@ export const DEFAULT_UPSTREAM = "https://agent402.tools";
 export const PKG_VERSION = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
 const MAX_BODY = 2 * 1024 * 1024;
 
+// The model catalog read (GET /v1/models) settles nothing, so a 503 the
+// server sheds under load is safe to repeat. It is retried only when it names
+// its own delay (a Retry-After header or a retryAfterSeconds body field), at
+// most DISCOVERY_ATTEMPTS tries in all, each wait capped at
+// DISCOVERY_MAX_WAIT_MS. A paid call never goes through here: a repeat of
+// one could settle twice.
+const DISCOVERY_ATTEMPTS = 3;
+const DISCOVERY_MAX_WAIT_MS = 5000;
+
+async function shedRetryWaitMs(r) {
+  if (!r || r.status !== 503) return null;
+  const header = r.headers && typeof r.headers.get === "function" ? r.headers.get("retry-after") : null;
+  let seconds = header != null && String(header).trim() !== "" ? Number(header) : NaN;
+  if (!Number.isFinite(seconds)) {
+    try {
+      const body = await (typeof r.clone === "function" ? r.clone() : r).json();
+      seconds = Number(body && body.retryAfterSeconds);
+    } catch { seconds = NaN; }
+  }
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  return Math.min(seconds * 1000, DISCOVERY_MAX_WAIT_MS);
+}
+
+// Resolves with the 2xx response, or throws `${label}: HTTP <status>` (plus
+// "after N attempts" when it retried) with `.status` and `.attempts` set.
+// `init` may be a function, so each attempt gets its own timeout signal.
+async function discoveryFetch(fetchImpl, label, url, init) {
+  let r;
+  let attempts = 0;
+  for (;;) {
+    attempts++;
+    r = await fetchImpl(url, typeof init === "function" ? init() : init);
+    if (r.ok) return r;
+    if (attempts >= DISCOVERY_ATTEMPTS) break;
+    const wait = await shedRetryWaitMs(r);
+    if (wait == null) break;
+    await new Promise((resolve) => setTimeout(resolve, wait));
+  }
+  const err = new Error(`${label}: HTTP ${r.status}${attempts > 1 ? ` after ${attempts} attempts` : ""}`);
+  err.status = r.status;
+  err.attempts = attempts;
+  throw err;
+}
+
 export async function loadRoutes(upstream, fetchImpl = fetch, { pricing = "metered" } = {}) {
-  const r = await fetchImpl(`${upstream}/v1/models`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(15_000) });
-  if (!r.ok) throw new Error(`GET /v1/models -> HTTP ${r.status}`);
+  const r = await discoveryFetch(fetchImpl, "GET /v1/models", `${upstream}/v1/models`, () => ({ headers: { accept: "application/json" }, signal: AbortSignal.timeout(15_000) }));
   return routesFromCatalog(await r.json(), { pricing });
 }
 
@@ -130,7 +173,15 @@ export async function startProxy({ upstream = DEFAULT_UPSTREAM, creditsKey = nul
     const clientIdem = typeof req.headers["idempotency-key"] === "string" && /^[\w.:-]{8,128}$/.test(req.headers["idempotency-key"]) ? req.headers["idempotency-key"] : null;
     const headers = { "content-type": "application/json", accept: req.headers.accept || "application/json", "idempotency-key": clientIdem || randomUUID(), "user-agent": `agent402-openclaw/${PKG_VERSION}`, ...extraHeaders };
     if (key) headers.authorization = `Bearer ${key}`;
-    const up = await paid(`${upstream}${endpoint}`, { method: "POST", headers, body: JSON.stringify(outbound), signal: AbortSignal.timeout(300_000) });
+    // A paid request never follows a redirect: followed, it would pay another
+    // origin's 402 or carry a signature (or the credits key) to another host.
+    const up = await paid(`${upstream}${endpoint}`, { method: "POST", headers, body: JSON.stringify(outbound), redirect: "manual", signal: AbortSignal.timeout(300_000) });
+    if (up.type === "opaqueredirect" || (up.status >= 300 && up.status < 400)) {
+      stats.errors++;
+      const loc = up.headers.get("location");
+      const to = loc ? new URL(loc, `${upstream}${endpoint}`).href : null;
+      return json(res, 502, { error: { message: `refused to follow a redirect on a paid call: ${upstream}${endpoint} answered HTTP ${up.status || "redirect"}${to ? ` pointing to ${to}` : ""}. Paid requests never follow redirects${to ? `; if that is the address you meant, set the upstream to ${new URL(to).origin}` : ""}.`, type: "upstream_redirect_refused" } });
+    }
     stats.forwarded++;
     const passthrough = {};
     // payment-response / x-payment-response carry the x402 settlement receipt