@metalntwx/metal-pay 0.3.0 → 0.3.2

package/dist/clearing-custody.js

@@ -1,7 +1,8 @@
-import { BaseError, ContractFunctionRevertedError, concatHex, createPublicClient, createWalletClient, encodeFunctionData, erc20Abi, FeeCapTooHighError, FeeCapTooLowError, http, InsufficientFundsError, IntrinsicGasTooHighError, IntrinsicGasTooLowError, keccak256, NonceMaxValueError, NonceTooHighError, parseEventLogs, sha256, stringToHex, TipAboveFeeCapError, TransactionTypeNotSupportedError, } from "viem";
+import { BaseError, ContractFunctionRevertedError, concatHex, createPublicClient, createWalletClient, encodeFunctionData, erc20Abi, FeeCapTooHighError, FeeCapTooLowError, InsufficientFundsError, IntrinsicGasTooHighError, IntrinsicGasTooLowError, keccak256, NonceMaxValueError, NonceTooHighError, parseEventLogs, sha256, stringToHex, TipAboveFeeCapError, TransactionTypeNotSupportedError, } from "viem";
 import { getNodeError } from "viem/utils";
 import { clearingAbi } from "./clearing-abi.js";
 import { clearingUint64, clearingUnits } from "./clearing-codec.js";
+import { formatUsdz, rpcTransport, USDZ } from "./networks.js";
 export function clearingLogProof(proof) {
     return {
         ...proof,
@@ -44,19 +45,24 @@ export async function clearingClose(signer, deployment, balance, destination, de
  * counts `uint64` units of `Clearing.unit()` token base units each, a
  * millionth of the token (its base unit at six decimals or fewer). */
 export const CLEARING_MAX_AMOUNT = 2n ** 64n - 1n;
+/** A clearing service that gave no answer, or a 5xx. */
+class ServiceUnreachable extends Error {
+}
 async function serviceGet(serviceUrl, path, fetcher) {
     const response = await fetcher(new URL(path, serviceUrl), {
         signal: AbortSignal.timeout(30_000),
+    }).catch((error) => {
+        throw new ServiceUnreachable(`clearing service gave no answer for ${path} (${error instanceof Error ? error.message : String(error)})`, { cause: error });
     });
     if (!response.ok)
-        throw new Error(`clearing service returned ${response.status} for ${path}`);
+        throw new (response.status >= 500 ? ServiceUnreachable : Error)(`clearing service returned ${response.status} for ${path}`);
     return (await response.json());
 }
 /** What `account` can still spend in the open epoch, in the token's base
  * units: the operator's estimate from the balance and deposits it has
  * counted and the payments it has acknowledged. */
 export async function clearingSpendable(opts) {
-    const pub = createPublicClient({ transport: http(opts.rpcUrl) });
+    const pub = createPublicClient({ transport: rpcTransport(opts.rpcUrl) });
     const [{ amount }, unit] = await Promise.all([
         serviceGet(opts.serviceUrl, `/spendable/${opts.account}`, opts.fetch ?? globalThis.fetch),
         pub.readContract({ address: opts.settlement, abi: clearingAbi, functionName: "unit" }),
@@ -85,7 +91,7 @@ const REFUSALS = [
 /** Gas and fees are set here: on Metal, a fee-carrying `eth_estimateGas`
  * from an account with no native balance fails. */
 function chainClients({ rpcUrl, chainId, from, timeoutMs = 60_000, pollMs = 500 }) {
-    const transport = http(rpcUrl);
+    const transport = rpcTransport(rpcUrl);
     const pub = createPublicClient({ transport });
     const wallet = createWalletClient({ account: from, transport });
     // The dry run first, under the gas the transaction is sent with, so a
@@ -143,6 +149,12 @@ function succeeded(functionName, receipt) {
         throw new Error(`${functionName} reverted: ${receipt.transactionHash}`);
     return receipt.transactionHash;
 }
+/** A withdrawal's queue or claim refused, by its dry run or as a mined
+ * revert (`tx`), because an epoch finalized after the service proved it:
+ * the contract checks a proof against its finalized state alone. */
+function finalizedUnder(functionName, tx, cause) {
+    return new Error(`${tx ? `${functionName} ${tx} reverted` : `${functionName} was refused`} because an epoch finalized under it, so the service's proof is for the state before; nothing was lost${tx ? " but its gas" : ""}: make the same call again after the next epoch`, cause === undefined ? {} : { cause });
+}
 /** Put `amount` token base units into clearing custody under `account`, a
  * clearing key; it must be a whole number of the contract's clearing
  * units. `from` pays: an approval for the amount unless one that covers it
@@ -150,8 +162,10 @@ function succeeded(functionName, receipt) {
  * registrations, so the deposit waits for that window and is sent again
  * if the window closes under it, up to `timeoutMs` (default 60 s). It
  * refuses at once a contract that holds another token, and a deposit past
- * what the contract holds in all. A deposit whose outcome is unknown is not
- * sent again: the error names it. */
+ * what the contract holds in all. A deposit the token refuses because
+ * `from` holds less fails naming what `from` holds and what the deposit
+ * needs. A deposit whose outcome is unknown is not sent again: the error
+ * names it. */
 export async function depositToClearing(opts) {
     if (opts.amount <= 0n)
         throw new Error("deposit amount must be positive");
@@ -194,6 +208,14 @@ export async function depositToClearing(opts) {
     // A full contract reverts the same way, and `assertRoom` tells them apart.
     const windowClosed = (error) => error instanceof BaseError &&
         error.walk((e) => e instanceof ContractFunctionRevertedError && e.data?.errorName === "InvalidBoundary") !== null;
+    // The token refuses a transfer past what `from` holds with the reason
+    // "balance"; what it holds is read after the refusal.
+    const shortOf = async (error) => {
+        if (!(error instanceof BaseError && error.walk((e) => e instanceof ContractFunctionRevertedError && e.reason === "balance")))
+            return undefined;
+        const held = await pub.readContract({ address: opts.asset, abi: erc20Abi, functionName: "balanceOf", args: [opts.from.address] });
+        return `${opts.from.address} holds ${formatUsdz(held)} ${USDZ.symbol} and the deposit needs ${formatUsdz(opts.amount)} ${USDZ.symbol}; fund it or deposit less`;
+    };
     for (;;) {
         // A deposit that reverts deposited nothing, and the next dry run says
         // why: if the window closed under it, the next round waits for the next
@@ -205,12 +227,16 @@ export async function depositToClearing(opts) {
             const why = await pub
                 .simulateContract({ ...deposit, account: opts.from.address, gas: depositGas })
                 .then(() => undefined, (error) => error);
-            if (!windowClosed(why))
-                throw new Error(`deposit ${receipt.transactionHash} reverted${why instanceof BaseError ? `: ${why.shortMessage}` : ", and its dry run now passes"}`);
+            if (!windowClosed(why)) {
+                const short = await shortOf(why);
+                throw new Error(`deposit ${receipt.transactionHash} reverted${short ? `: ${short}` : why instanceof BaseError ? `: ${why.shortMessage}` : ", and its dry run now passes"}`);
+            }
         }
         catch (error) {
-            if (!windowClosed(error))
-                throw error;
+            if (!windowClosed(error)) {
+                const short = await shortOf(error);
+                throw short ? new Error(`the deposit was refused, and nothing was deposited: ${short}`, { cause: error }) : error;
+            }
         }
         await assertRoom();
         if (Date.now() >= deadline)
@@ -224,6 +250,7 @@ const accountKey = (account) => sha256(concatHex([stringToHex("_COMMONWARE_CLEAR
  * `serviceUrls` that proves it. */
 async function lookupPayout(serviceUrls, fetcher, epoch, account, destination) {
     const failures = [];
+    const unreachable = [];
     for (const serviceUrl of serviceUrls) {
         try {
             const payout = await serviceGet(serviceUrl, `/payout/${epoch}/${account}`, fetcher);
@@ -235,10 +262,14 @@ async function lookupPayout(serviceUrls, fetcher, epoch, account, destination) {
                 return payout;
         }
         catch (error) {
+            if (error instanceof ServiceUnreachable)
+                unreachable.push(error);
             failures.push(`${serviceUrl}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    throw new Error(`no clearing service named proves the payout of this account's withdrawal in epoch ${epoch}; a validator proves it once it has retained that epoch (${failures.join("; ")})`);
+    throw new Error(`no clearing service named proves the payout of this account's withdrawal in epoch ${epoch}; a validator proves it once it has retained that epoch (${failures.join("; ")})`, 
+    // None of them answered.
+    unreachable.length === serviceUrls.length ? { cause: unreachable[0] } : {});
 }
 /** Claims `payout` to `destination` unless it is 0 or claimed already. The
  * claim is pushed to `claimed` as it lands. */
@@ -250,7 +281,14 @@ async function claimPayout({ pub, send, settlement, unit }, payout, destination,
     const consumed = await pub.readContract({ ...contract, functionName: "claimedPayouts", args: [position >> 8n] });
     if (consumed & (1n << (position & 255n)))
         return;
-    const receipt = await send({ ...contract, functionName: "claim", args: [destination, BigInt(payout.amount), clearingLogProof(payout.proof)] }, 1000000n);
+    // The proof is for the payouts log the service read as finalized; once a
+    // later epoch finalizes, the contract's log is longer and refuses it.
+    const moved = async () => (await pub.readContract({ ...contract, functionName: "finalizedPayouts" }))[1] !== BigInt(payout.proof.leaves);
+    const receipt = await send({ ...contract, functionName: "claim", args: [destination, BigInt(payout.amount), clearingLogProof(payout.proof)] }, 1000000n).catch(async (error) => {
+        throw revertOf(error) === "InvalidProof" && (await moved()) ? finalizedUnder("claim", undefined, error) : error;
+    });
+    if (receipt.status !== "success" && (await moved()))
+        throw finalizedUnder("claim", receipt.transactionHash);
     const tx = succeeded("claim", receipt);
     const deferred = parseEventLogs({ abi: clearingAbi, eventName: "PayoutDeferred", logs: receipt.logs }).length > 0;
     claimed.push({ amount: BigInt(payout.amount) * unit, tx, deferred });
@@ -260,7 +298,9 @@ async function claimPayout({ pub, send, settlement, unit }, payout, destination,
  * withdrawal of whatever finalized balance remains, to `destination` (`from` itself
  * unless given). A payer's unused deposit and a seller's earnings leave the
  * same way. Call again after the queued withdrawal's epoch finalizes. A
- * failure after a claim names the claims made before it. */
+ * failure after a claim names the claims made before it. A queue or claim
+ * refused because an epoch finalized under its proof moved nothing: the
+ * error says to call again after the next epoch. */
 export async function withdrawFromClearing(opts) {
     const { pub, send } = chainClients(opts);
     const fetcher = opts.fetch ?? globalThis.fetch;
@@ -276,18 +316,33 @@ export async function withdrawFromClearing(opts) {
     ]);
     const [encodedHash, epochPlusOne, , , queuedTo] = status;
     if (encodedHash !== `0x${"00".repeat(32)}` && (epochPlusOne === 0n || epochPlusOne > finalized)) {
-        if (epochPlusOne > 0n)
-            return { status: "waiting", epoch: epochPlusOne - 1n };
-        // Not yet registered: the next registration carries it.
         const [registered, admitted] = await Promise.all([
             pub.readContract({ ...contract, functionName: "registered" }),
             pub.readContract({ ...contract, functionName: "admittedCount" }),
         ]);
+        // A service that has missed a deadline may never finalize the epoch.
+        for (const call of faultCalls(admitted, opts.signer.publicKey)) {
+            const missed = await pub.simulateContract({ ...contract, ...call, account: opts.from.address }).then(() => true, (error) => {
+                if (revertOf(error) !== "InvalidDeadline")
+                    throw error;
+                return false;
+            });
+            if (missed)
+                throw new Error(`the clearing service has missed a deadline (${call.functionName} would fault the deployment), so the withdrawal may never finalize: take the account's funds out with recoverFromClearing`);
+        }
+        if (epochPlusOne > 0n)
+            return { status: "waiting", epoch: epochPlusOne - 1n };
+        // Not yet registered: the next registration carries it.
         return { status: "waiting", epoch: registered ? admitted + 1n : admitted };
     }
     const claimed = [];
     try {
-        return await claimThenQueue();
+        return await claimThenQueue().catch((error) => {
+            const gone = error instanceof ServiceUnreachable ? error : error instanceof Error && error.cause instanceof ServiceUnreachable ? error.cause : undefined;
+            if (!gone)
+                throw error;
+            throw new Error(`the clearing service could not be reached (${gone.message}): call withdrawFromClearing again once it answers; if it has stopped, pass a validator's URL from the facilitator's /supported extra.validatorUrls as serviceUrl`, { cause: error });
+        });
     }
     catch (error) {
         if (claimed.length === 0)
@@ -298,11 +353,14 @@ export async function withdrawFromClearing(opts) {
     async function claimThenQueue() {
         if (epochPlusOne > 0n)
             await claimPayout({ pub, send, settlement: opts.settlement, unit }, await lookupPayout([opts.serviceUrl], fetcher, epochPlusOne - 1n, opts.signer.publicKey, queuedTo), queuedTo, claimed);
+        const unqueued = () => (claimed.length > 0 ? { status: "sent", claimed, queued: null } : { status: "empty" });
         // The service proves balances only against a finalized epoch.
         if (finalized === 0n)
-            return { status: "sent", claimed, queued: null };
+            return unqueued();
         const balance = await clearingBalance(opts.serviceUrl, opts.signer.publicKey, fetcher);
-        if (BigInt(balance.amount) === 0n || !balance.opening)
+        if (BigInt(balance.amount) === 0n)
+            return unqueued();
+        if (!balance.opening)
             return { status: "sent", claimed, queued: null };
         const [deployment, policy, block] = await Promise.all([
             pub.readContract({ ...contract, functionName: "deployment" }),
@@ -313,14 +371,23 @@ export async function withdrawFromClearing(opts) {
         // The balance is proven against the finalized state: an epoch that
         // finalizes before the withdrawal lands moves it, and the contract
         // refuses the withdrawal with `InvalidBoundary`.
-        const receipt = await send({ ...contract, functionName: "queueWithdrawal", args: [close.withdrawal, close.opening] }, 2000000n).catch((error) => {
-            if (revertOf(error) !== "InvalidBoundary")
-                throw error;
-            throw new Error("the withdrawal was refused because an epoch finalized under it: call withdrawFromClearing again", { cause: error });
+        const moved = async () => (await pub.readContract({ ...contract, functionName: "finalizedState" })).toLowerCase() !== close.withdrawal.state.toLowerCase();
+        const receipt = await send({ ...contract, functionName: "queueWithdrawal", args: [close.withdrawal, close.opening] }, 2000000n).catch(async (error) => {
+            throw revertOf(error) === "InvalidBoundary" && (await moved()) ? finalizedUnder("queueWithdrawal", undefined, error) : error;
         });
+        if (receipt.status !== "success" && (await moved()))
+            throw finalizedUnder("queueWithdrawal", receipt.transactionHash);
         return { status: "sent", claimed, queued: { tx: succeeded("queueWithdrawal", receipt) } };
     }
 }
+/** The calls that fault a deployment whose service has missed a deadline:
+ * to admit the epoch it registered, `account`'s queued withdrawal, or its
+ * deposit. Each reverts `InvalidDeadline` until its deadline passes. */
+const faultCalls = (admitted, account) => [
+    { functionName: "faultRegistration", args: [] },
+    { functionName: "faultWithdrawal", args: [account] },
+    { functionName: "faultDeposit", args: [admitted, account] },
+];
 const revertOf = (error) => {
     if (!(error instanceof BaseError))
         return undefined;
@@ -371,12 +438,7 @@ export async function recoverFromClearing(opts) {
     let faulted = null;
     if ((await pub.readContract({ ...contract, functionName: "fault" })) === 0) {
         const admitted = await pub.readContract({ ...contract, functionName: "admittedCount" });
-        const faults = [
-            { functionName: "faultRegistration", args: [] },
-            { functionName: "faultWithdrawal", args: [account] },
-            { functionName: "faultDeposit", args: [admitted, account] },
-        ];
-        for (const call of faults) {
+        for (const call of faultCalls(admitted, account)) {
             try {
                 faulted = succeeded(call.functionName, await send({ ...contract, ...call }, 200000n));
                 break;

package/dist/clearing-x402.d.ts

@@ -26,4 +26,13 @@ export declare function verifyClearingPayment(paid: ClearingPaid, requirements:
     id: string;
     status: "preconfirmed";
 }>;
-export declare function registerClearingClient(client: x402Client, network: `eip155:${number}`, payer: Pick<ReturnType<typeof createClearingClient>, "pay" | "payable" | "pendingInvoice">): x402Client;
+/** 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 declare function registerClearingClient(client: x402Client, network: `eip155:${number}`, payer: Pick<ReturnType<typeof createClearingClient>, "pay" | "unpayable" | "pendingInvoice">, { exactFallback }?: {
+    exactFallback?: boolean;
+}): x402Client;

package/dist/clearing-x402.js

@@ -1,6 +1,7 @@
-import { createPublicClient, http, sha256, stringToHex } from "viem";
+import { createPublicClient, sha256, stringToHex } from "viem";
 import { clearingAbi } from "./clearing-abi.js";
 import { CLEARING_SCHEME, clearingUnits, decodeSend, invoiceMessage, verifyClearingSignature, verifyReceipt, outgoingRoot, } from "./clearing-codec.js";
+import { rpcTransport } from "./networks.js";
 /** A resource-bound invoice namespace; the payer appends a unique payment id. */
 export function clearingRequirements(seller, amount, resource) {
     if (amount <= 0n)
@@ -80,7 +81,7 @@ export async function verifyClearingPayment(paid, requirements, config) {
     if (!clearingPaymentOf({ payload: paid }))
         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,
@@ -169,14 +170,32 @@ export async function verifyClearingPayment(paid, requirements, config) {
         status: "preconfirmed",
     };
 }
-export function registerClearingClient(client, network, payer) {
+/** 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, network, payer, { exactFallback = false } = {}) {
+    // 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();
     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();
-            const invoice = clearingInvoice(requirements, pending?.id ?? `${requirements.extra?.invoicePrefix}:${suffix}`);
-            const paid = await payer.pay(invoice);
+            // 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.startsWith(prefix)
+                ? pending.id
+                : prefix + globalThis.crypto.randomUUID());
+            const paid = await payer.pay(invoice, urls.get(requirements));
             return {
                 x402Version,
                 payload: paid,
@@ -187,17 +206,44 @@ export function registerClearingClient(client, network, payer) {
     // 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) => {
+            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;
             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/dist/client.d.ts

@@ -31,7 +31,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;
 }
@@ -47,7 +48,11 @@ export declare function allowAsset(client: x402Client, network: Network, asset:
  */
 export declare function keepPaymentOnOrigin(fetch: typeof globalThis.fetch): typeof globalThis.fetch;
 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;

package/dist/client.js

@@ -1,6 +1,8 @@
-import { x402Client } from "@x402/core/client";
+import { x402Client, x402HTTPClient } from "@x402/core/client";
 import { wrapFetchWithPayment } from "@x402/fetch";
 import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { ClearingRefusal } from "./clearing-client.js";
+import { CLEARING_SCHEME } from "./clearing-codec.js";
 import { METAL_NETWORKS, USDZ, formatUsdz, usdzBaseUnits, resolveNetwork, } from "./networks.js";
 /**
  * Register Metal's devnet and testnet with an `@x402/core` client for the
@@ -81,17 +83,48 @@ export function createMetalPaymentClient({ account, network, fetch = globalThis.
     // 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.
-    client.onBeforePaymentCreation(async ({ selectedRequirements: { amount } }) => {
-        if (BigInt(amount) <= maxAmount)
+    // @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: { 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;
+            // 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;
+            const sending = (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) => {
+                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/dist/mandates/account.d.ts

@@ -70,6 +70,9 @@ export declare const metalAccountAbi: readonly [{
     }, {
         readonly type: "uint256";
         readonly name: "nonce";
+    }, {
+        readonly type: "uint64";
+        readonly name: "validUntil";
     }, {
         readonly type: "bytes";
         readonly name: "signature";
@@ -84,7 +87,9 @@ export declare function assertMetalAccount(client: PublicClient, account: Addres
 /** The gas an executeSigned adds to the call it carries, by the quorum signature's signers. */
 export declare 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 declare 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 declare function authorizeMandateCall(client: PublicClient, factory: Address, call: MandateCall | readonly MandateCall[], validUntil: bigint, signQuorum: (digest: Hex) => Promise<Hex>): Promise<MandateCall>;

package/dist/mandates/account.js

@@ -6,7 +6,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";
 /** Exact immutable ERC-1167 clone emitted by MetalAccountFactory. */
@@ -56,10 +56,12 @@ export function quorumGas(signature) {
     return gas;
 }
 /** 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, factory, call, signQuorum) {
+ * 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, factory, call, validUntil, signQuorum) {
     const chainId = client.chain?.id;
     if (chainId === undefined)
         throw new Error("the RPC client names no chain");
@@ -71,9 +73,11 @@ export async function authorizeMandateCall(client, factory, call, signQuorum) {
     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, factory, call, signQuorum) {
     // 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/dist/mandates/seller.js

@@ -1,8 +1,8 @@
 // The seller's side of a signed order: a check, before the facilitator is
 // asked to verify, that a payment under a mandate carries the agent's signed
 // offer for this very offer, under the agent key the payer's account binds.
-import { createPublicClient, getAddress, http, isAddress, isHex, isAddressEqual } from "viem";
-import { accountFactoryFor, metalNetwork } from "../networks.js";
+import { 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";
@@ -20,7 +20,7 @@ import { asksSignedOffer, mandateRefOf, signedOfferOf } from "./extension.js";
  * route that does not ask is left to the facilitator.
  */
 export function requireSignedOffer(server, config) {
-    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) => ({ abort: true, 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