@metalntwx/metal-pay 0.3.0 → 0.3.2

package/src/clearing-server.test.ts

@@ -3,12 +3,12 @@ import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import { Hono } from "hono";
 import { paymentMiddleware } from "@x402/hono";
 import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
-import { decodePaymentRequiredHeader, decodePaymentResponseHeader, encodePaymentSignatureHeader } from "@x402/core/http";
+import { decodePaymentRequiredHeader, decodePaymentResponseHeader, decodePaymentSignatureHeader, encodePaymentSignatureHeader } from "@x402/core/http";
 import type { PaymentPayload, PaymentRequirements } from "@x402/core/types";
 import { sha256, stringToHex } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { createClearingSigner, encodeSend, invoiceMessage, outgoingRoot, type ClearingInvoice } from "./clearing-codec.js";
-import type { ClearingPaid } from "./clearing-client.js";
+import { ClearingRefusal, type ClearingPaid } from "./clearing-client.js";
 import { ClearingServerScheme } from "./clearing-server.js";
 import { clearingPaymentMismatch, clearingPaymentOf, registerClearingClient } from "./clearing-x402.js";
 import { createMetalPaymentClient } from "./client.js";
@@ -82,8 +82,8 @@ const fakePayer = {
   async pendingInvoice() {
     return null;
   },
-  payable() {
-    return true;
+  unpayable() {
+    return undefined;
   },
   async pay(invoice: ClearingInvoice): Promise<ClearingPaid> {
     const entries = [{ recipient: invoice.recipient, cumulative: invoice.amount, count: "1" }];
@@ -260,16 +260,78 @@ describe("ClearingServerScheme under the stock middleware", () => {
     expect(served).toBe(1);
   });
 
-  it("pays with clearing when offered clearing and exact, in either order, and with exact when it cannot pay the clearing offer", async () => {
+  it("pays with clearing when offered clearing and exact, in either order", async () => {
     const accepts = await challenge("http://seller.local/chunk");
-    const chosen = async (payer: typeof fakePayer, offers: PaymentRequirements[]) => {
+    const chosen = async (offers: PaymentRequirements[]) => {
       const { client } = createMetalPaymentClient({ account: privateKeyToAccount(`0x${"45".repeat(32)}`), network: "devnet" });
-      registerClearingClient(client, NETWORK, payer);
+      registerClearingClient(client, NETWORK, fakePayer);
       return (await client.createPaymentPayload({ x402Version: 2, resource: { url: "http://seller.local/chunk" }, accepts: offers })).accepted.scheme;
     };
-    expect(await chosen(fakePayer, accepts)).toBe("bajillion");
-    expect(await chosen(fakePayer, [...accepts].reverse())).toBe("bajillion");
-    expect(await chosen({ ...fakePayer, payable: () => false }, accepts)).toBe("exact");
+    expect(await chosen(accepts)).toBe("bajillion");
+    expect(await chosen([...accepts].reverse())).toBe("bajillion");
+  });
+
+  /** The Metal client over the seller, and the schemes of the payments it sent. */
+  const paying = (options: { maxAmount?: bigint } = {}) => {
+    const sent: string[] = [];
+    const { client, fetchWithPayment } = createMetalPaymentClient({
+      account: privateKeyToAccount(`0x${"45".repeat(32)}`),
+      network: "devnet",
+      ...options,
+      fetch: async (input, init) => {
+        const request = new Request(input as RequestInfo, init);
+        const header = request.headers.get("payment-signature");
+        if (header) sent.push(decodePaymentSignatureHeader(header).accepted.scheme);
+        return app.request(request);
+      },
+    });
+    return { client, fetchWithPayment, sent };
+  };
+  const unpayable = { ...fakePayer, unpayable: () => ({ reason: "offer is for deployment 0x1, not this wallet's 0x2", aboveMaxAmount: false }) };
+
+  it("pays a request it cannot pay by clearing by exact only with exactFallback: unset, the request fails and sends no payment", async () => {
+    const accepts = await challenge("http://seller.local/chunk");
+    const refused = paying();
+    registerClearingClient(refused.client, NETWORK, unpayable);
+    await expect(refused.fetchWithPayment("http://seller.local/chunk")).rejects.toThrow(
+      /pays none of the clearing offers here \(offer is for deployment 0x1, not this wallet's 0x2\), and paying by exact is off; nothing was paid: pass exactFallback: true/,
+    );
+    await expect(
+      refused.client.createPaymentPayload({ x402Version: 2, resource: { url: "http://seller.local/chunk" }, accepts: [accepts[1]!] }),
+    ).rejects.toThrow(/offers no clearing payment on eip155:1337, and paying by exact is off/);
+    expect(refused.sent).toEqual([]);
+    const fallback = paying();
+    registerClearingClient(fallback.client, NETWORK, unpayable, { exactFallback: true });
+    await fallback.fetchWithPayment("http://seller.local/chunk");
+    expect(fallback.sent).toEqual(["exact"]);
+  });
+
+  it("caps exact payments, not clearing ones, by the payment client's maxAmount", async () => {
+    // k12-visual's outer limit of 0, set to block the exact fallback.
+    const clearing = paying({ maxAmount: 0n });
+    registerClearingClient(clearing.client, NETWORK, fakePayer);
+    expect((await clearing.fetchWithPayment("http://seller.local/chunk")).status).toBe(200);
+    expect(clearing.sent).toEqual(["bajillion"]);
+    const exact = paying({ maxAmount: 0n });
+    registerClearingClient(exact.client, NETWORK, unpayable, { exactFallback: true });
+    await expect(exact.fetchWithPayment("http://seller.local/chunk")).rejects.toThrow(/offer of 0.01 \*USDZ is above the 0 \*USDZ limit per payment/);
+    expect(exact.sent).toEqual([]);
+  });
+
+  it("fails a request whose clearing payment is refused with the refusal as its error's cause, sending no payment", async () => {
+    const refusal = new ClearingRefusal("between_epochs", { action: "retry_after_ms", ms: 1000 }, "clearing is between epochs");
+    const refused = paying();
+    registerClearingClient(refused.client, NETWORK, {
+      ...fakePayer,
+      async pay() {
+        throw refusal;
+      },
+    });
+    const error = await refused.fetchWithPayment("http://seller.local/chunk").catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toBe("Failed to create payment payload: clearing is between epochs");
+    expect((error as Error).cause).toBe(refusal);
+    expect(refused.sent).toEqual([]);
   });
 });
 

package/src/clearing-x402.test.ts

@@ -150,7 +150,7 @@ describe("native x402 invoice binding", () => {
       async pendingInvoice() {
         return pending;
       },
-      payable: () => true,
+      unpayable: () => undefined,
       async pay(next: ClearingInvoice) {
         ids.push(next.id);
         if (!pending) {

package/src/clearing-x402.ts

@@ -1,6 +1,6 @@
 import type { PaymentRequirements, PaymentPayload } from "@x402/core/types";
 import type { x402Client } from "@x402/core/client";
-import { createPublicClient, http, sha256, stringToHex, type Hex } from "viem";
+import { createPublicClient, sha256, stringToHex, type Hex } from "viem";
 import { clearingAbi } from "./clearing-abi.js";
 import {
   CLEARING_SCHEME,
@@ -13,6 +13,7 @@ import {
   type ClearingInvoice,
 } from "./clearing-codec.js";
 import type { ClearingPaid, createClearingClient } from "./clearing-client.js";
+import { rpcTransport } from "./networks.js";
 
 export interface ClearingSeller {
   network: `eip155:${number}`;
@@ -129,7 +130,7 @@ export async function verifyClearingPayment(
   )
     throw new Error("invalid clearing payment");
   const send = decodeSend(paid.receipt.body);
-  const client = createPublicClient({ transport: http(config.rpcUrl) });
+  const client = createPublicClient({ transport: rpcTransport(config.rpcUrl) });
   const [context, fault, asset, chainId, unit] = await Promise.all([
     client.readContract({
       address: config.settlement,
@@ -237,24 +238,43 @@ export async function verifyClearingPayment(
     status: "preconfirmed" as const,
   };
 }
+/** Pay by clearing through `client` on `network`. A request with an offer on
+ * `network` but none the wallet can pay fails, unless `exactFallback` is
+ * true: then it is paid by another offer of the request on `network`,
+ * `exact` from its EVM account, and fails when it has none. A request with
+ * no offer on `network` is left to the
+ * client's other registrations. A payment the clearing service does not take
+ * throws a `ClearingRefusal`. */
 export function registerClearingClient(
   client: x402Client,
   network: `eip155:${number}`,
   payer: Pick<
     ReturnType<typeof createClearingClient>,
-    "pay" | "payable" | "pendingInvoice"
+    "pay" | "unpayable" | "pendingInvoice"
   >,
+  { exactFallback = false }: { exactFallback?: boolean } = {},
 ) {
+  // The URL each offer was asked for, kept with a payment whose outcome is
+  // unknown so a refusal names the request to send again.
+  const urls = new WeakMap<PaymentRequirements, string>();
   client.register(network, {
     scheme: CLEARING_SCHEME,
+    schemeHooks: {
+      async onBeforePaymentCreation({ paymentRequired, selectedRequirements }) {
+        urls.set(selectedRequirements, paymentRequired.resource.url);
+      },
+    },
     async createPaymentPayload(x402Version, requirements) {
       const pending = await payer.pendingInvoice();
-      const suffix = globalThis.crypto.randomUUID();
+      // A payment held for another URL is the wallet's to refuse, naming it.
+      const prefix = `${requirements.extra?.invoicePrefix}:`;
       const invoice = clearingInvoice(
         requirements,
-        pending?.id ?? `${requirements.extra?.invoicePrefix}:${suffix}`,
+        pending?.id.startsWith(prefix)
+          ? pending.id
+          : prefix + globalThis.crypto.randomUUID(),
       );
-      const paid = await payer.pay(invoice);
+      const paid = await payer.pay(invoice, urls.get(requirements));
       return {
         x402Version,
         payload: paid as unknown as Record<string, unknown>,
@@ -265,15 +285,44 @@ export function registerClearingClient(
   // its policies, and a clearing offer is `upfront`: so a payer set up for
   // clearing keeps the clearing offers its wallet can pay, when there are any.
   client.registerPolicy((_, offers) => {
-    const clearing = offers.filter((offer) => {
-      if (offer.scheme !== CLEARING_SCHEME || offer.network !== network) return false;
+    if (!offers.some((offer) => offer.network === network)) return offers;
+    const offered = offers.filter((offer) => offer.scheme === CLEARING_SCHEME && offer.network === network);
+    // Why the wallet does not pay `offer`, or undefined when it does.
+    const unpaid = (offer: PaymentRequirements) => {
+      if (!/^[0-9]+$/.test(offer.amount) || BigInt(offer.amount) === 0n)
+        return { reason: `offer is priced at "${offer.amount}", not a positive whole number of base units`, aboveMaxAmount: false };
+      let invoice: ClearingInvoice;
       try {
-        return payer.payable(clearingInvoice(offer, `${offer.extra?.invoicePrefix}:`));
+        invoice = clearingInvoice(offer, `${offer.extra?.invoicePrefix}:`);
       } catch {
-        return false;
+        return { reason: "offer is malformed (invalid clearing requirement)", aboveMaxAmount: false };
       }
-    });
-    return clearing.length > 0 ? clearing : offers;
+      return payer.unpayable(invoice);
+    };
+    const reasons = offered.map(unpaid);
+    const clearing = offered.filter((_, i) => reasons[i] === undefined);
+    if (clearing.length > 0) return clearing;
+    if (exactFallback) {
+      // The offers this wallet just refused stay out: the stock selector can
+      // choose them again, since a clearing offer with no extra.paymentFlow
+      // is otherwise indistinguishable from one it can pay. The fallback is
+      // for this request's offers on `network`; with none left, it fails.
+      if (offers.some((offer) => offer.network === network && !offered.includes(offer)))
+        return offers.filter((offer) => !offered.includes(offer));
+    }
+    const why =
+      offered.length > 0
+        ? `this clearing wallet pays none of the clearing offers here (${[...new Set(reasons.map((r) => r?.reason))].join("; ")})`
+        : `this request offers no clearing payment on ${network}`;
+    // An offer above the wallet's maxAmount is for its own deployment: the
+    // limit or the seller is what to change, not the scheme.
+    throw new Error(
+      reasons.some((r) => r?.aboveMaxAmount)
+        ? `${why}; nothing was paid: raise the wallet's maxAmount or pay another seller`
+        : exactFallback
+          ? `${why}, and this request offers no other way to pay it; nothing was paid`
+          : `${why}, and paying by exact is off; nothing was paid: pass exactFallback: true to registerClearingClient to pay such a request by exact`,
+    );
   });
   return client;
 }

package/src/client.test.ts

@@ -318,6 +318,14 @@ describe("usdz amounts", () => {
     expect(formatUsdz("2000000000000000000")).toBe("2");
   });
 
+  it("formats a negative amount, as clearingSpendable can read, with one leading sign", () => {
+    expect(formatUsdz(-100000000000000000n)).toBe("-0.1");
+    expect(formatUsdz(-1500000000000000000n)).toBe("-1.5");
+    expect(formatUsdz(-1n)).toBe("-0.000000000000000001");
+    expect(formatUsdz("-2000000000000000000")).toBe("-2");
+    expect(formatUsdz(0n)).toBe("0");
+  });
+
   it("rejects malformed and over-precise amounts", () => {
     expect(() => usdzBaseUnits("1e3")).toThrow();
     expect(() => usdzBaseUnits("0." + "1".repeat(19))).toThrow(/decimals/);

package/src/client.ts

@@ -1,8 +1,10 @@
-import { x402Client } from "@x402/core/client";
+import { x402Client, x402HTTPClient } from "@x402/core/client";
 import { wrapFetchWithPayment } from "@x402/fetch";
 import type { ClientEvmSigner } from "@x402/evm";
 import type { Network } from "@x402/core/types";
 import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { ClearingRefusal } from "./clearing-client.js";
+import { CLEARING_SCHEME } from "./clearing-codec.js";
 import {
   METAL_NETWORKS,
   USDZ,
@@ -76,7 +78,8 @@ export interface MetalPaymentClientConfig {
   fetch?: typeof globalThis.fetch;
   /**
    * The most one payment may cost, in `*USDZ` base units; `DEFAULT_MAX_PAYMENT`
-   * by default. An offer above it is refused before anything is signed.
+   * by default. An offer above it is refused before anything is signed. A
+   * clearing payment is capped by its wallet's own `maxAmount` instead.
    */
   maxAmount?: bigint;
 }
@@ -117,7 +120,11 @@ export function keepPaymentOnOrigin(fetch: typeof globalThis.fetch): typeof glob
 }
 
 export interface MetalPaymentClient {
-  /** `fetch` that answers a 402 by paying and retrying, once. */
+  /**
+   * `fetch` that answers a 402 by paying and retrying, once. When the
+   * clearing service does not take a payment, the error's `cause` is the
+   * `ClearingRefusal`.
+   */
   fetchWithPayment: ReturnType<typeof wrapFetchWithPayment>;
   client: x402Client;
   network: MetalNetwork;
@@ -138,18 +145,50 @@ export function createMetalPaymentClient({
   // The hooks are the guard: the client's own spend controls would refuse
   // first, naming nothing of the offer, so they stand aside on this client.
   client.setSpendControls({ allowedAssets: true });
-  // @x402/fetch signs whatever amount an offer asks; this hook is the payer's spending guard.
+  // @x402/fetch signs whatever amount an offer asks; this hook is the payer's
+  // spending guard. A clearing wallet guards its own payments.
   client.onBeforePaymentCreation(
-    async ({ selectedRequirements: { amount } }) => {
-      if (BigInt(amount) <= maxAmount) return;
+    async ({ selectedRequirements: { scheme, amount } }) => {
+      if (scheme === CLEARING_SCHEME || BigInt(amount) <= maxAmount) return;
       return {
         abort: true,
         reason: `offer of ${formatUsdz(amount)} ${USDZ.symbol} is above the ${formatUsdz(maxAmount)} ${USDZ.symbol} limit per payment`,
       };
     },
   );
+  const paid = keepPaymentOnOrigin(fetch);
   return {
-    fetchWithPayment: wrapFetchWithPayment(keepPaymentOnOrigin(fetch), client),
+    // @x402/fetch rethrows a failure to pay as a new Error with the message
+    // alone; each request keeps its clearing refusal to give as the cause.
+    fetchWithPayment: async (input, init) => {
+      let refused: ClearingRefusal | undefined;
+      // A clearing payment records the URL this request went to, as the
+      // fetch resolved it, for a refusal to name: behind a proxy, the
+      // seller's own name for the resource can differ from it. The seller
+      // receives its own name back.
+      let url: string | undefined;
+      const sending: typeof globalThis.fetch = (request, options) => {
+        url ??= request instanceof Request ? request.url : String(request);
+        return paid(request, options);
+      };
+      const paying = new x402HTTPClient(client);
+      paying.createPaymentPayload = (paymentRequired) =>
+        client
+          .createPaymentPayload({ ...paymentRequired, resource: { ...paymentRequired.resource, url: url ?? paymentRequired.resource.url } })
+          .then(
+            (payload) => ({ ...payload, resource: paymentRequired.resource }),
+            (error: unknown) => {
+              if (error instanceof ClearingRefusal) refused = error;
+              throw error;
+            },
+          );
+      try {
+        return await wrapFetchWithPayment(sending, paying)(input, init);
+      } catch (error) {
+        if (!refused) throw error;
+        throw new Error(`Failed to create payment payload: ${refused.message}`, { cause: refused });
+      }
+    },
     client,
     network: resolved,
   };

package/src/mandates/account.ts

@@ -8,7 +8,7 @@ export const metalAccountFactoryAbi = parseAbi([
 ]);
 export const metalAccountAbi = parseAbi([
   "function nonces(address owner, uint192 key) view returns (uint256)",
-  "function executeSigned(bytes32 mode, bytes executionData, uint256 nonce, bytes signature)",
+  "function executeSigned(bytes32 mode, bytes executionData, uint256 nonce, uint64 validUntil, bytes signature)",
 ]);
 export const ACCOUNT_BATCH_MODE = "0x0100000000000000000000000000000000000000000000000000000000000000";
 
@@ -59,10 +59,12 @@ export function quorumGas(signature: Hex): bigint {
 }
 
 /** Self-calls approved by the account's existing ERC-7913 quorum, in one batch
- * that runs whole or not at all. The signing callback may collect mixed keys,
- * weights and passkeys; it returns the normal abi.encode(bytes[] signers,
- * bytes[] signatures) account signature. */
-export async function authorizeMandateCall(client: PublicClient, factory: Address, call: MandateCall | readonly MandateCall[], signQuorum: (digest: Hex) => Promise<Hex>): Promise<MandateCall> {
+ * that runs whole or not at all. The account refuses the signed batch once the
+ * chain's block timestamp passes `validUntil` (unix seconds): pick a deadline
+ * just long enough to collect the signatures and submit. The signing callback
+ * may collect mixed keys, weights and passkeys; it returns the normal
+ * abi.encode(bytes[] signers, bytes[] signatures) account signature. */
+export async function authorizeMandateCall(client: PublicClient, factory: Address, call: MandateCall | readonly MandateCall[], validUntil: bigint, signQuorum: (digest: Hex) => Promise<Hex>): Promise<MandateCall> {
   const chainId = client.chain?.id;
   if (chainId === undefined) throw new Error("the RPC client names no chain");
   const calls = Array.isArray(call) ? (call as readonly MandateCall[]) : [call as MandateCall];
@@ -71,9 +73,11 @@ export async function authorizeMandateCall(client: PublicClient, factory: Addres
   const account = first.to;
   if (calls.some((c) => !isAddressEqual(c.to, account))) throw new Error("every call in one batch goes to the same account");
   await assertMetalAccount(client, account, factory);
-  // A fresh 192-bit nonce lane per call: two administration calls in flight,
-  // or one beside the owner's own operations on lane 0, never claim one nonce.
-  const lane = hexToBigInt(bytesToHex(crypto.getRandomValues(new Uint8Array(24))));
+  // A fresh nonce lane per call: two administration calls in flight, or one
+  // beside the owner's own operations on lane 0, never claim one nonce. A
+  // quorum's lane keeps the key's top bit clear; set, it is a lane for
+  // signatures below the threshold, which the account refuses for the quorum.
+  const lane = hexToBigInt(bytesToHex(crypto.getRandomValues(new Uint8Array(24)))) >> 1n;
   const sequence = await client.readContract({ address: account, abi: metalAccountAbi, functionName: "nonces", args: [account, lane] });
   const nonce = (lane << 64n) | sequence;
   const executionData = encodeAbiParameters(parseAbiParameters("(address target, uint256 value, bytes callData)[]"), [calls.map((c) => ({ target: account, value: 0n, callData: c.data }))]);
@@ -81,11 +85,11 @@ export async function authorizeMandateCall(client: PublicClient, factory: Addres
   // it could have the quorum sign a batch of its own choosing.
   const digest = hashTypedData({
     domain: { name: "MetalAccount", version: "1", chainId, verifyingContract: account },
-    types: { Execute: [{ name: "mode", type: "bytes32" }, { name: "executionData", type: "bytes" }, { name: "nonce", type: "uint256" }] },
+    types: { Execute: [{ name: "mode", type: "bytes32" }, { name: "executionData", type: "bytes" }, { name: "nonce", type: "uint256" }, { name: "validUntil", type: "uint64" }] },
     primaryType: "Execute",
-    message: { mode: ACCOUNT_BATCH_MODE, executionData, nonce },
+    message: { mode: ACCOUNT_BATCH_MODE, executionData, nonce, validUntil },
   });
   const signature = await signQuorum(digest);
   const gas = calls.reduce((sum, c) => sum + c.gas, 0n) + quorumGas(signature);
-  return { ...first, gas, data: encodeFunctionData({ abi: metalAccountAbi, functionName: "executeSigned", args: [ACCOUNT_BATCH_MODE, executionData, nonce, signature] }) };
+  return { ...first, gas, data: encodeFunctionData({ abi: metalAccountAbi, functionName: "executeSigned", args: [ACCOUNT_BATCH_MODE, executionData, nonce, validUntil, signature] }) };
 }

package/src/mandates/seller.ts

@@ -3,8 +3,8 @@
 // offer for this very offer, under the agent key the payer's account binds.
 
 import type { x402ResourceServer } from "@x402/core/server";
-import { type Address, type Hex, type PublicClient, createPublicClient, getAddress, http, isAddress, isHex, isAddressEqual } from "viem";
-import { accountFactoryFor, metalNetwork } from "../networks.js";
+import { type Address, type Hex, type PublicClient, createPublicClient, getAddress, isAddress, isHex, isAddressEqual } from "viem";
+import { accountFactoryFor, metalNetwork, rpcTransport } from "../networks.js";
 import { assertMetalAccount } from "./account.js";
 import { referencePrefix } from "./binding.js";
 import { decodeMandateBlob } from "./l3a.js";
@@ -32,7 +32,7 @@ export type RequireSignedOfferConfig = { accountFactory?: Address } & ({ publicC
  * route that does not ask is left to the facilitator.
  */
 export function requireSignedOffer(server: x402ResourceServer, config: RequireSignedOfferConfig): x402ResourceServer {
-  const publicClient = "publicClient" in config ? config.publicClient : createPublicClient({ transport: http(config.rpcUrl) });
+  const publicClient = "publicClient" in config ? config.publicClient : createPublicClient({ transport: rpcTransport(config.rpcUrl) });
   const refuse = (reason: string) => ({ abort: true as const, reason });
   // x402 treats a hook that throws as one that passed, so a check that cannot
   // finish refuses the payment instead. The refusal reaches the payer, so it