x402-safe-fetch 0.8.0 → 0.9.0

package/README.md

@@ -45,7 +45,7 @@ try {
 
 Solana works the same way: `network: "solana"` and register an `ExactSvmScheme` from `@x402/svm/exact/client` with a `@solana/kit` signer.
 
-Algorand and the XRP Ledger work the same way, and only their dollar stablecoin is ever paid. On Algorand that is USDC (ASA 31566704), never ALGO or another ASA. On the XRP Ledger it is RLUSD from Ripple's issuer, never XRP or a look-alike token. RLUSD prices are decimal dollars, so the budget is checked in dollars. The Doctor preflight is paid on the same network.
+Algorand and the XRP Ledger work the same way, and only their dollar stablecoin is ever paid. On Algorand that is USDC (ASA 31566704), never ALGO or another ASA. Sellers name Algorand mainnet either by the whole genesis hash or by its CAIP-2 id (`algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k`); both are paid, also with `@x402/avm` 2.29.0, which on its own accepts only the short id. On the XRP Ledger it is RLUSD from Ripple's issuer, never XRP or a look-alike token. RLUSD prices are decimal dollars, so the budget is checked in dollars. The Doctor preflight is paid on the same network.
 
 ```js
 import { toClientAvmSigner } from "@x402/avm";
@@ -65,6 +65,27 @@ const safeFetch = createSafeFetch({
 // facilitator (PayAI) pays the gas.
 ```
 
+### Escrowed payments (auth-capture)
+
+Some sellers on Base take payment through Coinbase's escrow instead of a direct transfer: the x402 scheme
+`auth-capture`. Your wallet signs once, the USDC is held, and the seller captures it only after it has delivered
+(Atom's domain checkout, for instance, captures once the domain is registered, and releases it if registration
+fails). Register that scheme next to the exact one to pay such sellers (`@x402/evm` 2.27 or later):
+
+```js
+import { AuthCaptureEvmScheme } from "@x402/evm/auth-capture/client";
+
+const safeFetch = createSafeFetch({
+  register: (client) => {
+    client.register("eip155:8453", new ExactEvmScheme(account));
+    client.register("eip155:8453", new AuthCaptureEvmScheme(account));
+  },
+  maxUsd: 25, // the budget caps the most that can be captured
+});
+```
+
+When a seller offers both, the exact option is paid. The preflight and the budget apply the same way.
+
 ## Options
 
 | Option | Default | |

package/index.d.ts

@@ -16,6 +16,8 @@ export declare const XLAYER: "eip155:196";
 /** The option paid on `network`: on Algorand only USDC, on Stellar only Circle's USDC contract within maxUsd, on X Layer only USD₮0 or USDC within maxUsd, on the XRP Ledger only RLUSD from Ripple's issuer within maxUsd (in dollars); null when there is none. */
 /** What a 402 offers (per x402 option: scheme, network, asset, amount, payTo) as a stable string; null without a readable x402 challenge. Consumes the body. */
 export declare function offerFingerprint(res: Response): Promise<string | null>;
+/** Wraps an Algorand scheme (e.g. @x402/avm's ExactAvmScheme) so it pays sellers that name Algorand by the whole genesis hash as well as by the CAIP-2 id. createSafeFetch does this for you. */
+export declare function anyAlgorandId<S extends object>(scheme: S): S;
 export declare function payableOption<A extends { network: string; asset?: unknown; amount?: unknown; extra?: Record<string, unknown> }>(accepts: A[], network: string, maxUsd: number | string): A | null;
 
 /** The x402 Doctor preflight: see https://x402-doctor.fizzl.eu/openapi.json */

package/index.js

@@ -34,7 +34,7 @@ export { verifyReceipt, recoverSigner, canonicalJson, inputHash, certMessage, DO
 export const DOCTOR_URL = "https://x402-doctor.fizzl.eu";
 export const PREFLIGHT_CAP = "$0.002"; // the preflight costs $0.001; never more than twice that
 export const DIAGNOSE_CAP = "$0.02"; // the diagnosis costs $0.01; never more than twice that
-export const VERSION = "0.8.0";
+export const VERSION = "0.9.0";
 // Doctor sees which calls come from this package (in its usage counts), nothing more.
 const DOCTOR_HEADERS = { accept: "application/json", "user-agent": `x402-safe-fetch/${VERSION}` };
 export const BASE = "eip155:8453";
@@ -50,7 +50,7 @@ const NETWORK_ALIASES = { base: BASE, solana: SOLANA, algorand: ALGORAND, "algor
 
 // On Algorand and the XRP Ledger only the dollar stablecoin is paid: USDC (an ASA) on Algorand, RLUSD from
 // Ripple's issuer on the XRP Ledger. Never ALGO, XRP or another token, so the dollar budget always holds.
-const ALGORAND_USDC = { [ALGORAND]: "31566704", [ALGORAND_TESTNET]: "10458941" };
+const ALGORAND_USDC = { [algorandId(ALGORAND)]: "31566704", [algorandId(ALGORAND_TESTNET)]: "10458941" };
 const RLUSD_HEX = "524C555344000000000000000000000000000000";
 const RLUSD_ISSUER = { [XRPL]: "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De", [XRPL_TESTNET]: "rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV" };
 // On Stellar only Circle's USDC token contract (7 decimals), never XLM or another token named USDC.
@@ -62,6 +62,23 @@ const XLAYER_DOLLARS = {
   [XLAYER]: ["0x779ded0c9e1022225f8e0630b35a9b54be713736", "0x74b7f16337b8972027f6196a17a631ac6de26d22"],
 };
 
+// Algorand by its CAIP-2 id: the first 32 characters of the genesis hash. Sellers name it either way (the whole hash,
+// or since @x402/avm 2.29.0 only the short id), so networks are compared by this.
+function algorandId(network) {
+  return typeof network === "string" && network.startsWith("algorand:") ? network.slice(0, 41) : network;
+}
+
+// @x402/avm 2.29.0's ExactAvmScheme refuses the whole-hash form, which most Algorand sellers still use (2.28.0 took
+// both). This hands the scheme the short id; the payment still names the seller's own network (x402 puts the
+// seller's option in `accepted`), so either kind of seller can be paid. createSafeFetch wraps Algorand schemes in it.
+export function anyAlgorandId(scheme) {
+  return Object.assign(Object.create(scheme), {
+    createPaymentPayload: (version, requirements, context) =>
+      scheme.createPaymentPayload(version, { ...requirements, network: algorandId(requirements.network) }, context),
+    ...(typeof scheme.findDefaultAsset === "function" && { findDefaultAsset: (asset, network) => scheme.findDefaultAsset(asset, algorandId(network)) }),
+  });
+}
+
 // The option to pay on `network`, or null. RLUSD prices are decimal dollars ("0.001", and "2" is two dollars),
 // which x402's spend controls would read as base units, so the budget is checked here in dollars.
 // What a 402 offers, as a stable string: per x402 option its scheme, network, asset, amount and payout address
@@ -85,8 +102,9 @@ const UNREAD_OFFER_MS = 10 * 60 * 1000;
 
 export function payableOption(accepts, network, maxUsd) {
   const cap = Number(String(maxUsd).replace(/^\$/, ""));
-  const on = (accepts ?? []).filter((a) => a?.network === network);
-  if (ALGORAND_USDC[network]) return on.find((a) => String(a.asset) === ALGORAND_USDC[network]) ?? null;
+  const on = (accepts ?? []).filter((a) => algorandId(a?.network) === algorandId(network));
+  const usdc = ALGORAND_USDC[algorandId(network)];
+  if (usdc) return on.find((a) => String(a.asset) === usdc) ?? null;
   // x402's spend controls cap Stellar USDC too; the budget is checked here as well, in dollars.
   if (STELLAR_USDC[network]) {
     return on.find((a) => a.asset === STELLAR_USDC[network] && /^\d+$/.test(String(a.amount)) && Number(a.amount) > 0 && Number(a.amount) / 1e7 <= cap) ?? null;
@@ -99,7 +117,11 @@ export function payableOption(accepts, network, maxUsd) {
     return on.find((a) => String(a.asset ?? "").toUpperCase() === RLUSD_HEX && a.extra?.issuer === RLUSD_ISSUER[network]
       && /^\d+(\.\d+)?$/.test(String(a.amount)) && Number(a.amount) > 0 && Number(a.amount) <= cap) ?? null;
   }
-  return on[0] ?? null;
+  // Base and other EVM chains: "exact" first (what most clients register), then "auth-capture" (Coinbase's escrow:
+  // the buyer signs once, the USDC is held and only captured when the seller delivers, e.g. Atom's domain checkout).
+  // Either is paid only if your register() added its scheme, and both stay within the budget (x402's spend controls
+  // read the amount, which for auth-capture is the most that can be captured).
+  return on.find((a) => a?.scheme === "exact") ?? on.find((a) => a?.scheme === "auth-capture") ?? on[0] ?? null;
 }
 
 export class SafePayError extends Error {
@@ -228,10 +250,23 @@ export function createSafeFetch({
   const makePayingFetch = createPayingFetch ?? ((cap) => {
     const client = new x402Client((_version, accepts) => {
       const pick = payableOption(accepts, payNetwork, cap);
-      if (!pick) throw new SafePayError(`no payment option on ${payNetwork}${ALGORAND_USDC[payNetwork] ? " in USDC" : STELLAR_USDC[payNetwork] ? ` in USDC within ${cap}` : XLAYER_DOLLARS[payNetwork] ? ` in USD₮0 or USDC within ${cap}` : RLUSD_ISSUER[payNetwork] ? ` in RLUSD within ${cap}` : ""}`, { code: "no_option" });
+      if (!pick) throw new SafePayError(`no payment option on ${payNetwork}${ALGORAND_USDC[algorandId(payNetwork)] ? " in USDC" : STELLAR_USDC[payNetwork] ? ` in USDC within ${cap}` : XLAYER_DOLLARS[payNetwork] ? ` in USD₮0 or USDC within ${cap}` : RLUSD_ISSUER[payNetwork] ? ` in RLUSD within ${cap}` : ""}`, { code: "no_option" });
       return pick;
     }).setSpendControls({ maxAmountPerPayment: cap, ...xlayerAllowance(payNetwork, cap) });
-    register(client);
+    // Algorand schemes get anyAlgorandId, so sellers with either network id can be paid.
+    const registering = new Proxy(client, {
+      get(target, prop) {
+        if (prop === "register") {
+          return (network, scheme) => {
+            target.register(network, String(network).startsWith("algorand:") ? anyAlgorandId(scheme) : scheme);
+            return registering;
+          };
+        }
+        const value = Reflect.get(target, prop);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+    register(registering);
     return wrapFetchWithPayment(baseFetch, client);
   });
   let preflightFetch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A fetch for AI agents that checks an unknown x402 endpoint ($0.001 x402 Doctor preflight) before paying it, and never pays above your budget.",
   "type": "module",
   "exports": {
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@algorandfoundation/algokit-utils": "^10.0.0-alpha.46",
-    "@x402/avm": "^2.28.0",
+    "@x402/avm": "^2.29.0",
     "@x402/evm": "^2.27.0",
     "@x402/fetch": "^2.27.0",
     "@x402/stellar": "^2.28.0",