@metalntwx/metal-pay 0.2.0 → 0.3.1

package/dist/clearing-server.js

@@ -1,81 +1,101 @@
+import * as x402Server from "@x402/core/server";
+import { formatUnits, isAddress, sha256, stringToHex } from "viem";
+import { CLEARING_SCHEME, clearingAccount } from "./clearing-codec.js";
+import { CLEARING_MAX_AMOUNT } from "./clearing-custody.js";
 import { USDZ } from "./networks.js";
 import { dollarBaseUnits } from "./server.js";
-/** The clearing receipt in a settle response, or null when it has none. */
-export function clearingReceiptOf(response) {
-    const receipt = response.extra?.["receipt"];
-    return receipt &&
-        typeof receipt.receiptDigest === "string" &&
-        typeof receipt.receiptSignature === "string" &&
-        typeof receipt.receipt === "object" &&
-        receipt.receipt !== null
-        ? receipt
-        : null;
-}
-/** Metal's clearing lane on the seller's side. Register it next to the
- * standard scheme, and list both in a route's `accepts`:
- *
- *     server
- *       .register(network, new ExactEvmScheme().registerMoneyParser(metalUsd(network)))
- *       .register(network, new ClearingDebitServerScheme());
- *     accepts: [
- *       { scheme: "exact", network, payTo, price: "$0.01" },
- *       { scheme: "clearing-debit", network, payTo, price: "$0.001" },
- *     ]
+/**
+ * The `bajillion` scheme for an `x402ResourceServer`, registered beside
+ * `exact` on `network`. A route's `payTo` is the seller's clearing key,
+ * `signer.publicKey` of a wallet from `openClearingWallet`, and its `price`
+ * is dollars in `token`. The offer names the Clearing deployment the
+ * facilitator lists for the network in `/supported`, so a seller takes only
+ * payments its facilitator settles.
  *
- * A payer pays by signing a running total; the facilitator has Metal's
- * clearing operator admit it, and the seller is credited in clearing, from
- * which it withdraws whenever it likes. The Clearing contract comes from the
- * facilitator's list of what it supports.
- *
- * `onReceipt` is handed the operator's signed receipt for every payment
- * settled, and again with any later answer for the same payment; store it
- * by its `receiptDigest`. */
-export class ClearingDebitServerScheme {
+ *     server.register(network, new ClearingServerScheme(network));
+ */
+export class ClearingServerScheme {
+    network;
     token;
-    scheme = "clearing-debit";
-    schemeHooks;
-    constructor(token = USDZ, options = {}) {
+    scheme = CLEARING_SCHEME;
+    // The money moved when the clearing service issued the receipt, so the
+    // facilitator records it before the handler runs: a receipt presented
+    // again, or twice at once, is served at most once.
+    defaultAssetTransferMethod = "default";
+    paymentFlows = {
+        default: { supported: ["upfront"], default: "upfront" },
+    };
+    constructor(network, token = USDZ) {
+        this.network = network;
         this.token = token;
-        const onReceipt = options.onReceipt;
-        this.schemeHooks = onReceipt
-            ? {
-                onAfterSettle: async ({ result }) => {
-                    const receipt = clearingReceiptOf(result);
-                    if (receipt)
-                        await onReceipt(receipt);
-                },
-            }
-            : {};
+        if (!/^eip155:\d+$/.test(network))
+            throw new Error(`not a network: ${network}`);
+        // A server without payment flows ignores `paymentFlows` and settles after the handler.
+        if (!("resolvePaymentFlow" in x402Server))
+            throw new Error("ClearingServerScheme needs @x402/core 2.28 or later, which settles a clearing payment before the handler runs");
     }
     async parsePrice(price) {
-        if (typeof price === "object")
-            return price;
-        return {
-            amount: dollarBaseUnits(price, this.token),
-            asset: this.token.address,
-        };
+        if (typeof price === "object" && price !== null && "amount" in price) {
+            let amount;
+            try {
+                amount = BigInt(price.amount);
+            }
+            catch {
+                throw new Error(`not a price: ${price.amount}`);
+            }
+            if (amount <= 0n)
+                throw new Error(`not a price: ${price.amount}`);
+            return { amount: this.payable(amount).toString(), asset: price.asset ?? this.token.address, extra: price.extra ?? {} };
+        }
+        return { amount: this.payable(BigInt(dollarBaseUnits(price, this.token))).toString(), asset: this.token.address };
+    }
+    /** Clearing counts whole clearing units, at most 2^64 - 1 of them in all.
+     * The unit is the one `Clearing.unit()` derives from the token's decimals
+     * at deploy: a millionth of the token, or its base unit at six decimals or
+     * fewer. */
+    payable(amount) {
+        const decimals = this.token.decimals;
+        const unit = decimals > 6 ? 10n ** BigInt(decimals - 6) : 1n;
+        if (amount % unit !== 0n)
+            throw new Error(`a clearing price is a whole number of ${formatUnits(unit, decimals)} ${this.token.symbol}`);
+        if (amount / unit > CLEARING_MAX_AMOUNT)
+            throw new Error(`a clearing price is at most ${formatUnits(CLEARING_MAX_AMOUNT * unit, decimals)} ${this.token.symbol}`);
+        return amount;
     }
     getAssetDecimals() {
         return this.token.decimals;
     }
     async enhancePaymentRequirements(requirements, supportedKind) {
-        const contract = supportedKind.extra?.["contract"];
-        if (typeof contract !== "string")
-            throw new Error(`the facilitator offers no Clearing contract on ${requirements.network}`);
-        return {
-            ...requirements,
-            extra: {
-                ...requirements.extra,
-                // The EIP-712 domain the payer signs its Debit under.
-                name: "MetalClearing",
-                version: "1",
-                clearing: {
-                    contract,
-                    // Binds a Debit to this seller. The same in the 402 and when the
-                    // paid request is matched against it, so it must not vary.
-                    ref: `0x${"0".repeat(24)}${requirements.payTo.slice(2).toLowerCase()}`,
-                },
-            },
-        };
+        if (requirements.network !== this.network)
+            throw new Error(`this clearing scheme is on ${this.network}; the route offers it on ${requirements.network}`);
+        try {
+            clearingAccount(requirements.payTo);
+        }
+        catch {
+            throw new Error(`a clearing offer's payTo is the seller's clearing key (signer.publicKey of a wallet from openClearingWallet); got ${requirements.payTo}`);
+        }
+        if (requirements.asset.toLowerCase() !== this.token.address.toLowerCase())
+            throw new Error(`this clearing scheme prices in ${this.token.address}; the route offers ${requirements.asset}`);
+        const prefix = requirements.extra?.invoicePrefix;
+        if (prefix !== undefined && (typeof prefix !== "string" || !/^0x[0-9a-f]{64}$/.test(prefix)))
+            throw new Error(`a route's invoicePrefix is 32 bytes of lowercase hex; got ${String(prefix)}`);
+        const { settlement, asset, serviceUrl } = supportedKind.extra ?? {};
+        if (typeof settlement !== "string" ||
+            !isAddress(settlement) ||
+            typeof asset !== "string" ||
+            asset.toLowerCase() !== this.token.address.toLowerCase() ||
+            typeof serviceUrl !== "string" ||
+            !URL.canParse(serviceUrl))
+            throw new Error(`the facilitator settles no clearing deployment in ${this.token.symbol} on ${this.network}`);
+        return { ...requirements, extra: { ...requirements.extra, settlement, serviceUrl } };
+    }
+    /** Binds this network's offers' invoices to the resource asked for, at
+     * the challenge and again when a payment for it is verified. A route that
+     * sets its own `invoicePrefix` keeps it. */
+    async enrichPaymentRequiredResponse(ctx) {
+        const invoicePrefix = sha256(stringToHex(ctx.resourceInfo.url));
+        return ctx.requirements.map((offer) => offer.scheme === CLEARING_SCHEME && offer.network === this.network && offer.extra?.invoicePrefix === undefined
+            ? { ...offer, extra: { ...offer.extra, invoicePrefix } }
+            : offer);
     }
 }

package/dist/clearing-x402.d.ts

@@ -0,0 +1,38 @@
+import type { PaymentRequirements, PaymentPayload } from "@x402/core/types";
+import type { x402Client } from "@x402/core/client";
+import { type Hex } from "viem";
+import { type ClearingInvoice } from "./clearing-codec.js";
+import type { ClearingPaid, createClearingClient } from "./clearing-client.js";
+export interface ClearingSeller {
+    network: `eip155:${number}`;
+    asset: Hex;
+    settlement: Hex;
+    recipient: Hex;
+    serviceUrl: string;
+}
+/** A resource-bound invoice namespace; the payer appends a unique payment id. */
+export declare function clearingRequirements(seller: ClearingSeller, amount: bigint, resource: string): PaymentRequirements;
+export declare function clearingInvoice(requirements: PaymentRequirements, id: string): ClearingInvoice;
+export declare function clearingPaymentOf(payload: Pick<PaymentPayload, "payload">): ClearingPaid | null;
+export declare function clearingPaymentMismatch(paid: ClearingPaid, requirements: PaymentRequirements): string | null;
+export declare function clearingPaymentId(paid: ClearingPaid): string;
+/** Both the RPC and service URL must come from the seller's trusted configuration. */
+export declare function verifyClearingPayment(paid: ClearingPaid, requirements: PaymentRequirements, config: {
+    rpcUrl: string;
+    serviceUrl: string;
+    settlement: Hex;
+}): Promise<{
+    payer: `0x${string}`;
+    id: string;
+    status: "preconfirmed";
+}>;
+/** 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

@@ -0,0 +1,249 @@
+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)
+        throw new Error("invalid clearing price");
+    return {
+        scheme: CLEARING_SCHEME,
+        network: seller.network,
+        asset: seller.asset,
+        amount: amount.toString(),
+        payTo: seller.recipient,
+        maxTimeoutSeconds: 60,
+        extra: {
+            settlement: seller.settlement,
+            serviceUrl: seller.serviceUrl,
+            invoicePrefix: sha256(stringToHex(resource)),
+        },
+    };
+}
+export function clearingInvoice(requirements, id) {
+    const extra = requirements.extra;
+    if (requirements.scheme !== CLEARING_SCHEME ||
+        !/^0x[0-9a-fA-F]{66}$/.test(requirements.payTo) ||
+        typeof extra?.settlement !== "string" ||
+        !/^0x[0-9a-fA-F]{40}$/.test(extra.settlement) ||
+        typeof extra.invoicePrefix !== "string" ||
+        !/^0x[0-9a-f]{64}$/.test(extra.invoicePrefix) ||
+        !id.startsWith(extra.invoicePrefix + ":"))
+        throw new Error("invalid clearing requirement");
+    return {
+        id,
+        network: requirements.network,
+        asset: requirements.asset,
+        settlement: extra.settlement,
+        recipient: requirements.payTo,
+        amount: requirements.amount,
+    };
+}
+export function clearingPaymentOf(payload) {
+    try {
+        const paid = payload.payload;
+        const body = decodeSend(paid.receipt.body);
+        invoiceMessage(paid.invoice, paid.receipt.body);
+        const entries = paid.entries.map((e) => ({
+            ...e,
+            cumulative: BigInt(e.cumulative),
+            count: BigInt(e.count),
+        }));
+        if (entries.length > 1024 ||
+            outgoingRoot(entries) !== body.vector ||
+            entries.reduce((n, e) => n + e.cumulative, 0n) !== body.debit ||
+            !verifyClearingSignature(body.payer, "_METAL_CLEARING_INVOICE", invoiceMessage(paid.invoice, paid.receipt.body), paid.invoiceSignature))
+            return null;
+        return paid;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearingPaymentMismatch(paid, requirements) {
+    try {
+        return invoiceMessage(clearingInvoice(requirements, paid.invoice.id), paid.receipt.body) === invoiceMessage(paid.invoice, paid.receipt.body)
+            ? null
+            : "invoice";
+    }
+    catch {
+        return "invoice";
+    }
+}
+export function clearingPaymentId(paid) {
+    return `${paid.invoice.network}:bajillion:${paid.invoice.settlement.toLowerCase()}:${sha256(paid.receipt.body)}`;
+}
+/** Both the RPC and service URL must come from the seller's trusted configuration. */
+export async function verifyClearingPayment(paid, requirements, config) {
+    if (clearingPaymentMismatch(paid, requirements) ||
+        paid.invoice.settlement.toLowerCase() !== config.settlement.toLowerCase())
+        throw new Error("clearing invoice mismatch");
+    if (!clearingPaymentOf({ payload: paid }))
+        throw new Error("invalid clearing payment");
+    const send = decodeSend(paid.receipt.body);
+    const client = createPublicClient({ transport: rpcTransport(config.rpcUrl) });
+    const [context, fault, asset, chainId, unit] = await Promise.all([
+        client.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "contextOf",
+            args: [send.epoch],
+        }),
+        client.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "fault",
+        }),
+        client.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "token",
+        }),
+        client.getChainId(),
+        client.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "unit",
+        }),
+    ]);
+    if (fault ||
+        `eip155:${chainId}` !== paid.invoice.network ||
+        asset.toLowerCase() !== paid.invoice.asset.toLowerCase() ||
+        context.anchor !== send.anchor ||
+        !verifyReceipt(paid.receipt, context.operatorKey))
+        throw new Error("invalid clearing receipt");
+    const previous = paid.previous;
+    let before = [];
+    if (send.sequence === 0n) {
+        if (previous)
+            throw new Error("unexpected predecessor receipt");
+    }
+    else {
+        if (!previous || !verifyReceipt(previous.receipt, context.operatorKey))
+            throw new Error("missing predecessor receipt");
+        const prior = decodeSend(previous.receipt.body);
+        before = previous.entries;
+        if (prior.epoch !== send.epoch ||
+            prior.anchor !== send.anchor ||
+            prior.payer !== send.payer ||
+            prior.sequence + 1n !== send.sequence ||
+            outgoingRoot(before.map((e) => ({
+                ...e,
+                cumulative: BigInt(e.cumulative),
+                count: BigInt(e.count),
+            }))) !== prior.vector)
+            throw new Error("invalid predecessor vector");
+    }
+    const expected = new Map(before.map((e) => [e.recipient.toLowerCase(), { ...e }]));
+    const key = paid.invoice.recipient.toLowerCase();
+    const old = expected.get(key);
+    // The invoice is in token base units; the vector counts clearing units.
+    expected.set(key, {
+        recipient: paid.invoice.recipient,
+        cumulative: ((old ? BigInt(old.cumulative) : 0n) +
+            clearingUnits(BigInt(paid.invoice.amount), unit)).toString(),
+        count: ((old ? BigInt(old.count) : 0n) + 1n).toString(),
+    });
+    if (expected.size !== paid.entries.length ||
+        paid.entries.some((e) => {
+            const wanted = expected.get(e.recipient.toLowerCase());
+            return (!wanted ||
+                wanted.count !== e.count ||
+                wanted.cumulative !== e.cumulative);
+        }))
+        throw new Error("invoice is not the incremental payment");
+    // The operator's durable invoice journal attests the incremental charge,
+    // which cannot be inferred from a cumulative vector alone.
+    const response = await fetch(new URL(`/receipt/${send.payer}/${encodeURIComponent(paid.invoice.id)}?epoch=${send.epoch}`, config.serviceUrl), { signal: AbortSignal.timeout(10_000) });
+    if (!response.ok)
+        throw new Error("clearing receipt unavailable");
+    const recorded = (await response.json());
+    if (!recorded ||
+        recorded.receipt.body !== paid.receipt.body ||
+        recorded.receipt.operatorSignature !== paid.receipt.operatorSignature ||
+        invoiceMessage(recorded.invoice, recorded.receipt.body) !==
+            invoiceMessage(paid.invoice, paid.receipt.body))
+        throw new Error("clearing invoice not retained");
+    return {
+        payer: send.payer,
+        id: clearingPaymentId(paid),
+        status: "preconfirmed",
+    };
+}
+/** 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();
+            // 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,
+            };
+        },
+    });
+    // The stock client keeps only `authorization` offers when any remain after
+    // 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) => {
+        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 {
+                invoice = clearingInvoice(offer, `${offer.extra?.invoicePrefix}:`);
+            }
+            catch {
+                return { reason: "offer is malformed (invalid clearing requirement)", aboveMaxAmount: false };
+            }
+            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

@@ -1,7 +1,7 @@
 import { x402Client } from "@x402/core/client";
 import { wrapFetchWithPayment } from "@x402/fetch";
 import type { ClientEvmSigner } from "@x402/evm";
-import type { ClearingDebitScheme } from "./clearing-client.js";
+import type { Network } from "@x402/core/types";
 import { type MetalNetwork, type MetalNetworkName } from "./networks.js";
 /**
  * What signs a payment: a viem local account (`privateKeyToAccount`) or
@@ -17,8 +17,8 @@ export interface RegisterMetalNetworksConfig {
  * Register Metal's devnet and testnet with an `@x402/core` client for the
  * `exact` scheme. The client signs an `exact` offer on `eip155:1337` or
  * `eip155:63825` only when it is in `*USDZ` under USDZ's EIP-712 domain, and
- * refuses any other before signing. Offers in other schemes, such as
- * clearing, are left to the schemes registered for them.
+ * refuses any other before signing. Offers in other schemes are left to
+ * the schemes explicitly registered for them.
  */
 export declare function registerMetalNetworks(client: x402Client, { signer, networks }: RegisterMetalNetworksConfig): x402Client;
 /** The most a payment client pays for one offer unless told otherwise: 1 `*USDZ`, in base units. */
@@ -31,21 +31,16 @@ 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;
-    /**
-     * Metal clearing, for sellers that offer it: the client pays by clearing
-     * and, while custody is short, by `exact` instead.
-     */
-    clearing?: ClearingDebitScheme;
 }
 /**
- * `@x402/core` from 2.23 pays only assets in its own table unless its spend
- * controls list others. This lists `asset` on `network`, capped at
- * `maxAmountPerPayment` base units when one is given.
+ * The stock client pays only assets in its own table unless its spend
+ * controls list others. This lists `asset` on `network`.
  */
-export declare function allowAsset(client: x402Client, network: string, asset: string, maxAmountPerPayment?: bigint): void;
+export declare function allowAsset(client: x402Client, network: Network, asset: string): void;
 /**
  * `fetch` that follows the redirects of a request carrying a payment only
  * within the origin it was made for, and answers a redirect to any other
@@ -53,10 +48,14 @@ export declare function allowAsset(client: x402Client, network: string, asset: s
  */
 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;
 }
 /** One call to pay: `const { fetchWithPayment } = createMetalPaymentClient({ account, network: "devnet" })`. */
-export declare function createMetalPaymentClient({ account, network, fetch, maxAmount, clearing, }: MetalPaymentClientConfig): MetalPaymentClient;
+export declare function createMetalPaymentClient({ account, network, fetch, maxAmount, }: MetalPaymentClientConfig): MetalPaymentClient;

package/dist/client.js

@@ -1,13 +1,15 @@
-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
  * `exact` scheme. The client signs an `exact` offer on `eip155:1337` or
  * `eip155:63825` only when it is in `*USDZ` under USDZ's EIP-712 domain, and
- * refuses any other before signing. Offers in other schemes, such as
- * clearing, are left to the schemes registered for them.
+ * refuses any other before signing. Offers in other schemes are left to
+ * the schemes explicitly registered for them.
  */
 export function registerMetalNetworks(client, { signer, networks }) {
     const scheme = new ExactEvmScheme(signer);
@@ -19,7 +21,10 @@ export function registerMetalNetworks(client, { signer, networks }) {
         if (scheme !== "exact" || !registered.includes(network))
             return;
         if (asset.toLowerCase() !== USDZ.address.toLowerCase()) {
-            return { abort: true, reason: `offer is in ${asset}, not ${USDZ.symbol} (${USDZ.address})` };
+            return {
+                abort: true,
+                reason: `offer is in ${asset}, not ${USDZ.symbol} (${USDZ.address})`,
+            };
         }
         if (extra?.name !== USDZ.name || extra?.version !== USDZ.version) {
             return {
@@ -33,15 +38,11 @@ export function registerMetalNetworks(client, { signer, networks }) {
 /** The most a payment client pays for one offer unless told otherwise: 1 `*USDZ`, in base units. */
 export const DEFAULT_MAX_PAYMENT = BigInt(usdzBaseUnits("1"));
 /**
- * `@x402/core` from 2.23 pays only assets in its own table unless its spend
- * controls list others. This lists `asset` on `network`, capped at
- * `maxAmountPerPayment` base units when one is given.
+ * The stock client pays only assets in its own table unless its spend
+ * controls list others. This lists `asset` on `network`.
  */
-export function allowAsset(client, network, asset, maxAmountPerPayment) {
-    const controlled = client;
-    controlled.setSpendControls?.({
-        allowedAssets: [{ network, asset, ...(maxAmountPerPayment !== undefined && { maxAmountPerPayment: maxAmountPerPayment.toString() }) }],
-    });
+export function allowAsset(client, network, asset) {
+    client.setSpendControls({ allowedAssets: [{ network, asset }] });
 }
 const REDIRECTS = new Set([301, 302, 303, 307, 308]);
 /**
@@ -73,27 +74,57 @@ export function keepPaymentOnOrigin(fetch) {
     };
 }
 /** One call to pay: `const { fetchWithPayment } = createMetalPaymentClient({ account, network: "devnet" })`. */
-export function createMetalPaymentClient({ account, network, fetch = globalThis.fetch, maxAmount = DEFAULT_MAX_PAYMENT, clearing, }) {
+export function createMetalPaymentClient({ account, network, fetch = globalThis.fetch, maxAmount = DEFAULT_MAX_PAYMENT, }) {
     const resolved = resolveNetwork(network);
-    // The clearing scheme's selector chooses between its offer and the standard one.
-    const client = registerMetalNetworks(new x402Client(clearing?.prefer), {
+    const client = registerMetalNetworks(new x402Client(), {
         signer: account,
         networks: [resolved],
     });
-    if (clearing)
-        client.register(resolved.network, clearing);
-    allowAsset(client, resolved.network, USDZ.address, maxAmount);
-    // @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)
+    // 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. 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(clearing ? clearing.wrapFetch(keepPaymentOnOrigin(fetch)) : 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/index.d.ts

@@ -1,6 +1,9 @@
 export { METAL_NETWORKS, USDZ, formatUsdz, metalNetwork, usdzBaseUnits, accountFactoryFor, rpcUrlFor, type DollarToken, type MetalNetwork, type MetalNetworkName, } from "./networks.js";
 export { DEFAULT_MAX_PAYMENT, createMetalPaymentClient, registerMetalNetworks, type MetalPaymentClient, type MetalPaymentClientConfig, type MetalPaymentSigner, type RegisterMetalNetworksConfig, } from "./client.js";
 export { metalUsd, registerMetalScheme, sellerToken, type RegisterMetalSchemeConfig, } from "./server.js";
-export * from "./clearing.js";
+export * from "./clearing-codec.js";
+export { clearingAbi } from "./clearing-abi.js";
 export * from "./clearing-client.js";
+export * from "./clearing-x402.js";
 export * from "./clearing-server.js";
+export * from "./clearing-custody.js";