@metalntwx/metal-pay 0.2.0 → 0.3.1

package/dist/clearing-client.js

@@ -1,580 +1,439 @@
-// The payer's side of the clearing lane: a scheme plug-in for the official
-// x402 client. Register it next to the standard `exact` scheme and pass its
-// selector to the client:
-//
-//   const clearing = new ClearingDebitScheme(signer, {
-//     facilitator: "https://<facilitator host>/x402/facilitator",
-//   });
-//   const client = new x402Client(clearing.prefer)
-//     .register(network, new ExactEvmScheme(signer))
-//     .register(network, clearing);
-//   const pay = wrapFetchWithPayment(clearing.wrapFetch(fetch), client);
-//
-// A payment is a signed cumulative Debit: "I have now spent X in total this
-// epoch". It draws on funds the payer holds in the Clearing contract, which
-// the payer (or anyone funding it) puts there by calling the contract's
-// `deposit`; `depositToClearing` does that. While custody is short the
-// selector takes the standard offer instead.
-//
-// Where the next Debit starts comes from the facilitator the payer names
-// here, never from the seller: the client asks it, with a request it signs,
-// about every 20 seconds while it pays and after any refusal. A seller
-// therefore cannot make the payer sign for more than it spent. The client
-// also keeps its own record of the highest total it has signed each epoch
-// (`storage`; in memory by default, `FileClearingPositionStorage` from
-// `@metalntwx/metal-pay/file-storage` for one that survives a restart) and refuses to sign past a total the facilitator
-// reports above it.
-//
-// When a seller cannot say whether a Debit was admitted, or its answer never
-// reaches the payer (`wrapFetch` sees the request fail, or a server error
-// that says nothing about the Debit), the client presents that same Debit
-// again rather than signing a new one, so the payer is not charged twice for
-// one payment.
-import { decodePaymentSignatureHeader } from "@x402/core/http";
-import { createPublicClient, createWalletClient, encodeFunctionData, erc20Abi, http, } from "viem";
-import { ACCOUNT_REQUEST_TYPES, CLEARING_DEBIT, clearingDomain, DEBIT_TYPES, EXIT_TYPES, } from "./clearing.js";
-/** `next`, with `highestSigned` no lower than the one already stored. */
-export function keepHighest(existing, next) {
-    if (!existing)
-        return next;
-    return BigInt(existing.highestSigned) > BigInt(next.highestSigned)
-        ? { ...next, highestSigned: existing.highestSigned }
-        : next;
-}
-/** The default store: positions do not survive a process restart. */
-export class InMemoryClearingPositionStorage {
-    positions = new Map();
-    async get(key) {
-        return this.positions.get(key);
-    }
-    async set(key, position) {
-        this.positions.set(key, keepHighest(this.positions.get(key), position));
+import { BaseError, createPublicClient } from "viem";
+import { clearingAbi } from "./clearing-abi.js";
+import { CLEARING_REFERENCE, clearingUnits, decodeSend, encodeSend, invoiceMessage, outgoingRoot, verifyReceipt, } from "./clearing-codec.js";
+import { formatUsdz, rpcTransport, USDZ } from "./networks.js";
+/** A clearing payment the service did not take: `reason` says why, `retry`
+ * what to do, and the message both in words. */
+export class ClearingRefusal extends Error {
+    reason;
+    retry;
+    name = "ClearingRefusal";
+    constructor(reason, retry, message, options) {
+        super(message, options);
+        this.reason = reason;
+        this.retry = retry;
     }
 }
-function clearingExtraOf(requirements) {
-    const clearing = requirements.extra?.["clearing"];
-    if (!clearing?.contract || !clearing.ref)
-        throw new Error("clearing offer carries no contract or ref");
-    return clearing;
+/** The service takes no payment from an epoch's close until the next
+ * epoch's registration, a gap of a few seconds. The wait between tries,
+ * and before a held payment is sent again, is the 2 s the service waits
+ * after an epoch's admission before registering the next, plus a block to
+ * include the registration. */
+const BETWEEN_EPOCHS_RETRY_MS = 3_000;
+/** The most recipients the service's payment parser takes in a vector. */
+const MAX_ENTRIES = 1024;
+function betweenEpochs(cause) {
+    return new ClearingRefusal("between_epochs", { action: "retry_after_ms", ms: BETWEEN_EPOCHS_RETRY_MS }, `clearing is between epochs: from an epoch's close until the next one is registered, a gap of a few seconds that recurs every epoch, the service takes no payments; nothing was paid: send the request again after ${BETWEEN_EPOCHS_RETRY_MS} ms, and again after each further between_epochs refusal; if it lasts longer than an epoch, check that serviceUrl is the facilitator's extra.serviceUrl (a validator takes no payments), or the service is down`, cause === undefined ? {} : { cause });
 }
-const chainIdOf = (network) => {
-    const chainId = Number(network.slice("eip155:".length));
-    if (!network.startsWith("eip155:") || !Number.isSafeInteger(chainId))
-        throw new Error(`not an EVM network: ${network}`);
-    return chainId;
-};
-/** A request this account signs to ask the facilitator about itself. */
-async function accountRequest(signer, network, contract, nowMs) {
-    const deadline = BigInt(Math.floor(nowMs / 1000) + 60);
-    const signature = await signer.signTypedData({
-        domain: clearingDomain(chainIdOf(network), contract),
-        types: ACCOUNT_REQUEST_TYPES,
-        primaryType: "AccountRequest",
-        message: { account: signer.address, deadline },
-    });
-    return {
-        account: signer.address,
-        network,
-        deadline: deadline.toString(),
-        signature,
-    };
+/** The error for a faulted deployment; `sent` when the payment reached the
+ * service with its outcome unknown. */
+function faulted(cause, sent = false) {
+    return new Error(`the Clearing deployment has faulted, so its service takes no more payments; ${sent ? "whether this payment went through shows in the balance recovery pays out, and the wallet keeps it held, so a replacement deployment takes a new wallet" : "nothing was paid"}: take the account's funds out with recoverFromClearing`, cause === undefined ? {} : { cause });
 }
-async function post(doFetch, url, body) {
-    const res = await doFetch(url, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
-    });
-    const json = (await res.json().catch(() => ({})));
-    if (!res.ok)
-        throw new Error(`facilitator refused: ${json.error ?? res.status}`);
-    return json;
+/** A held payment, by its price and the URL it pays for. */
+function describe(pending) {
+    return `${pending.invoice.amount} base units ${pending.url === undefined ? `under invoice ${pending.invoice.id}` : `for ${pending.url}`}`;
 }
-/** Ask the facilitator where `signer`'s clearing position stands, with a
- * request `signer` signs. */
-async function fetchPosition(doFetch, facilitator, signer, network, contract, nowMs) {
-    const answer = await post(doFetch, `${facilitator}/clearing/position`, await accountRequest(signer, network, contract, nowMs));
-    if (answer.contract.toLowerCase() !== contract.toLowerCase())
-        throw new Error("the seller names a different Clearing contract than the facilitator");
-    return answer;
+function messageOf(cause) {
+    return cause instanceof BaseError
+        ? cause.shortMessage
+        : cause instanceof Error
+            ? cause.message
+            : String(cause);
 }
-const CUSTODY_SHORT = "clearing custody is short of the price: deposit into the Clearing contract first (see depositToClearing)";
-const SELLER_REFUSES_CLEARING = "this seller cannot take clearing payments (clearing_requires_seller_token) and offers no standard payment";
-/** How long a position from the facilitator is used before asking again:
- * well inside an epoch, so the client rarely signs for one that has closed. */
-const POSITION_TTL_MS = 20_000;
-/** How long the client pays the standard way after being told custody is
- * short, before trying clearing again. */
-const SHORT_MS = 60_000;
-/** What tells one Debit from another: its signature. */
-const signatureOf = (payload) => payload.signature;
-/** Reasons a seller gives that say a Debit may yet have been admitted. */
-const IN_DOUBT = new Set(["settlement_in_doubt", "payment_in_flight"]);
-export class ClearingDebitScheme {
-    signer;
-    scheme = CLEARING_DEBIT;
-    schemeHooks;
-    facilitator;
-    storage;
-    doFetch;
-    now;
-    /** Per payer and contract: the facilitator's last answer, adjusted for
-     * what this client has signed since. */
-    positions = new Map();
-    /** Per payer and contract: until when to pay the standard way. */
-    shortUntil = new Map();
-    /** Sellers the facilitator settles no clearing for, by network, contract
-     * and payee: a seller without Metal's seller token. That holds for as long
-     * as the client runs, so they are paid the standard way from then on. */
-    standardOnly = new Set();
-    /** Per payer and contract: the Debits whose outcome is in doubt, each to
-     * be presented again for its own offer. Only an answer about that Debit
-     * clears it. */
-    unresolved = new Map();
-    constructor(signer, options) {
-        this.signer = signer;
-        this.facilitator = options.facilitator.replace(/\/$/, "");
-        this.storage = options.storage ?? new InMemoryClearingPositionStorage();
-        this.doFetch = options.fetch ?? globalThis.fetch;
-        this.now = options.now ?? (() => Date.now());
-        this.schemeHooks = {
-            // How a paid request ended decides the retry the transport makes.
-            onPaymentResponse: async (ctx) => {
-                if (ctx.requirements.scheme !== CLEARING_DEBIT)
-                    return;
-                const key = this.key(ctx.requirements);
-                const payload = ctx.paymentPayload.payload;
-                if (ctx.settleResponse?.success) {
-                    // Settled by clearing: custody covered it, whatever was thought.
-                    this.release(key, payload);
-                    this.shortUntil.delete(key);
-                    return;
-                }
-                // No word about the Debit: `wrapFetch` holds it if it may have been
-                // admitted, and where the next one starts is asked afresh.
-                if (!ctx.settleResponse && !ctx.paymentRequired) {
-                    this.positions.delete(key);
-                    return;
-                }
-                const reason = ctx.settleResponse?.errorReason ?? ctx.paymentRequired?.error ?? "";
-                // Perhaps admitted: the retry presents the same Debit again.
-                if (IN_DOUBT.has(reason)) {
-                    this.hold(key, this.offerId(ctx.requirements), payload);
-                    return { recovered: true };
-                }
-                this.release(key, payload);
-                this.positions.delete(key);
-                if (reason === "insufficient_custody") {
-                    this.shortUntil.set(key, this.now() + SHORT_MS);
-                    return { recovered: true };
-                }
-                if (reason === "clearing_requires_seller_token") {
-                    this.standardOnly.add(this.sellerOf(ctx.requirements));
-                    return { recovered: true };
-                }
-                if (reason === "debit_out_of_sequence")
-                    return { recovered: true };
-                return undefined;
-            },
-        };
+/** A refusal naming the payment the wallet holds until it goes through:
+ * one held from before, one whose answer was lost, or one whose
+ * acknowledgment did not verify, all three held alike. */
+function held(kind, pending, cause) {
+    const payment = describe(pending);
+    const release = "if that URL no longer offers clearing at that price, pass the wallet's pendingInvoice() to its pay, which sends the held payment itself once more; the wallet pays others once it goes through or is refused";
+    return new ClearingRefusal(kind === "payment_held" ? "payment_held" : "answer_lost", {
+        action: "repeat_same_request",
+        url: pending.url ?? null,
+        amount: pending.invoice.amount,
+        ms: BETWEEN_EPOCHS_RETRY_MS,
+    }, kind === "unverified"
+        ? `the clearing service answered this payment, ${payment}, but its acknowledgment does not verify against this payment and the deployment's operator key, so serviceUrl may belong to another deployment: check it against the facilitator's /supported; the payment's outcome is unknown, and the wallet holds it and pays nothing else until it is sent once to the right service, which never pays it twice`
+        : kind === "answer_lost"
+            ? `no receipt this wallet could check came back for this payment, ${payment} (${messageOf(cause)}), so its outcome is unknown: the wallet holds it and pays nothing else until it goes through; send the same request again at the same price after ${BETWEEN_EPOCHS_RETRY_MS} ms, which sends this payment again and never pays it twice; if it is still held after an epoch, check that serviceUrl is the facilitator's extra.serviceUrl (a validator takes no payments); ${release}`
+            : `the wallet holds an earlier payment whose outcome is unknown, ${payment}, and pays nothing else until it goes through; nothing was paid for this request: send that request again after ${BETWEEN_EPOCHS_RETRY_MS} ms at that price first, which sends the same payment and never pays it twice; ${release}`, cause === undefined ? {} : { cause });
+}
+/** The error for a payment held for another deployment, network or asset
+ * than the wallet's: it can never be sent here. */
+function stranded(pending, which) {
+    return new Error(`the wallet holds a payment for ${which.what}${which.theirs}, which this wallet cannot send to ${which.ours}, so it can never go through here and the wallet pays nothing else: take the account's funds out of that deployment with withdrawFromClearing, or recoverFromClearing once it has faulted, given its settlement and service, and open a new wallet for ${which.ours}; the payment is ${describe(pending)}`);
+}
+/** A clearing service's refusal; `rejected` when it never takes the payment. */
+class ServiceRefused extends Error {
+    status;
+    rejected;
+    constructor(status, rejected) {
+        super(rejected
+            ? "clearing payment rejected before acknowledgment"
+            : `clearing service returned ${status}`);
+        this.status = status;
+        this.rejected = rejected;
     }
-    /** The selector to give `new x402Client(...)`: the clearing offer, unless
-     * custody was lately found short or the seller cannot take clearing, in
-     * which case the standard one. A Debit whose outcome is in doubt is always
-     * presented again by clearing. */
-    prefer = (_x402Version, accepts) => {
-        const clearing = accepts.find((a) => a.scheme === CLEARING_DEBIT);
-        const standard = accepts.find((a) => a.scheme !== CLEARING_DEBIT);
-        if (clearing && this.standardOnly.has(this.sellerOf(clearing))) {
-            if (standard)
-                return standard;
-            throw new Error(SELLER_REFUSES_CLEARING);
+}
+const unavailable = (error) => error instanceof ServiceRefused && error.status === 409 && !error.rejected;
+export function createClearingClient(config) {
+    const fetcher = config.fetch ?? globalThis.fetch;
+    const chain = createPublicClient({ transport: rpcTransport(config.rpcUrl) });
+    let tail = Promise.resolve();
+    let broken = false;
+    async function save(state) {
+        try {
+            await config.store.save(state);
         }
-        if (clearing) {
-            const key = this.key(clearing);
-            const offer = this.offerId(clearing);
-            const short = !this.unresolved.get(key)?.some((held) => held.offer === offer) &&
-                (this.shortUntil.get(key) ?? 0) > this.now();
-            if (!short)
-                return clearing;
-            if (standard)
-                return standard;
-            throw new Error(CUSTODY_SHORT);
+        catch (error) {
+            broken = true;
+            throw error;
         }
-        if (!standard)
-            throw new Error("no payable offer");
-        return standard;
-    };
-    /** One payment at a time per payer and contract: reading the position,
-     * signing and recording it must not interleave, or two payments would sign
-     * the same index. */
-    queues = new Map();
-    exclusive(key, job) {
-        const run = (this.queues.get(key) ?? Promise.resolve()).then(job, job);
-        this.queues.set(key, run.catch(() => undefined));
-        return run;
     }
-    key(requirements) {
-        const clearing = requirements.extra?.["clearing"];
-        return `${requirements.network}:${String(clearing?.contract).toLowerCase()}:${this.signer.address.toLowerCase()}`;
+    async function request(path, body) {
+        const response = await fetcher(new URL(path, config.serviceUrl), {
+            method: body ? "POST" : "GET",
+            ...(body
+                ? {
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify(body),
+                }
+                : {}),
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (!response.ok) {
+            const result = (await response.json().catch(() => null));
+            throw new ServiceRefused(response.status, result?.rejected === true);
+        }
+        return (await response.json());
     }
-    sellerOf(requirements) {
-        const clearing = requirements.extra?.["clearing"];
-        return `${requirements.network}:${String(clearing?.contract).toLowerCase()}:${requirements.payTo.toLowerCase()}`;
+    /** How `invoice` is for another network, deployment or asset than this
+     * wallet's, or undefined when it is not. */
+    function differs(invoice) {
+        if (invoice.network !== config.network)
+            return { what: "", theirs: invoice.network, ours: config.network };
+        if (invoice.settlement.toLowerCase() !== config.settlement.toLowerCase())
+            return { what: "deployment ", theirs: invoice.settlement, ours: config.settlement };
+        if (invoice.asset.toLowerCase() !== config.asset.toLowerCase())
+            return { what: "asset ", theirs: invoice.asset, ours: config.asset };
     }
-    /** The fetch to give `wrapFetchWithPayment`. A request carrying a Debit
-     * that fails without an answer, or ends in a server error that says
-     * nothing about the Debit (a proxy's 502 or 504), may still have been
-     * admitted, so its Debit is held in doubt: the next payment for that offer
-     * presents it again. It is held in memory, for as long as the client
-     * runs. */
-    wrapFetch(fetch) {
-        return async (input, init) => {
-            const headers = init?.headers
-                ? new Headers(init.headers)
-                : input instanceof Request
-                    ? input.headers
-                    : undefined;
-            const header = headers?.get("payment-signature");
-            let response;
-            try {
-                response = await fetch(input, init);
-            }
-            catch (error) {
-                this.holdSent(header);
-                throw error;
-            }
-            if (response.status >= 500 &&
-                !response.headers.has("payment-response") &&
-                !response.headers.has("x-payment-response"))
-                this.holdSent(header);
-            return response;
-        };
+    /** Why this wallet does not pay `invoice`, or undefined when it does;
+     * `aboveMaxAmount` when it is for this wallet's deployment at a price
+     * above its maxAmount. */
+    function refusal(invoice) {
+        const elsewhere = differs(invoice);
+        if (elsewhere)
+            return { reason: `offer is for ${elsewhere.what}${elsewhere.theirs}, not this wallet's ${elsewhere.ours}`, aboveMaxAmount: false };
+        if (!/^[1-9][0-9]*$/.test(invoice.amount))
+            return { reason: `offer of ${invoice.amount} base units is not a positive whole number in canonical form`, aboveMaxAmount: false };
+        const amount = BigInt(invoice.amount);
+        if (amount > config.maxAmount)
+            return {
+                reason: `offer ${formatUsdz(amount)} ${USDZ.symbol} is above this wallet's maxAmount ${formatUsdz(config.maxAmount)} ${USDZ.symbol}`,
+                aboveMaxAmount: true,
+            };
+    }
+    /** Why a service that takes no payments does not: the deployment has
+     * faulted, for good, or it is between epochs. */
+    async function closed(cause) {
+        const fault = await onChain(chain.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "fault",
+        }));
+        return fault ? faulted(cause) : betweenEpochs(cause);
     }
-    /** Holds the Debit a request carried, if it carried one of this client's. */
-    holdSent(header) {
-        let paid;
+    /** `reads` of the Clearing contract, once the RPC is known to serve
+     * `config.network`: on another chain they fail or mean nothing. */
+    async function onChain(reads) {
+        reads.catch(() => { });
+        const chainId = await chain.getChainId();
+        if (`eip155:${chainId}` !== config.network)
+            throw new Error(`the clearing client's rpcUrl serves eip155:${chainId}, not ${config.network}; nothing was paid: give it an RPC URL for ${config.network}`);
+        return reads;
+    }
+    /** Why the service refused a payment signed for `epoch` for good: the
+     * epoch closed as it was sent, or, while it is still open, the account's
+     * deposit does not cover the payment, or neither, which the service does
+     * not say. */
+    async function rejection(epoch, invoice, cause) {
+        let covered;
+        let opened = false;
         try {
-            paid = header ? decodePaymentSignatureHeader(header) : undefined;
+            const [context, fault] = await Promise.all([
+                request("/context"),
+                chain.readContract({
+                    address: config.settlement,
+                    abi: clearingAbi,
+                    functionName: "fault",
+                }),
+            ]);
+            if (fault)
+                return faulted(cause);
+            if (BigInt(context.epoch) !== epoch)
+                return betweenEpochs(cause);
+            opened = true;
+            const [{ amount }, unit] = await Promise.all([
+                request(`/spendable/${config.signer.publicKey}`),
+                chain.readContract({
+                    address: config.settlement,
+                    abi: clearingAbi,
+                    functionName: "unit",
+                }),
+            ]);
+            covered = BigInt(amount) >= clearingUnits(BigInt(invoice.amount), unit);
         }
-        catch {
-            // Not a payment this client made.
+        catch (error) {
+            if (!opened && unavailable(error))
+                return closed(cause);
+            return new Error(`the clearing service refused this payment of ${invoice.amount} base units, and reading why failed (${messageOf(error)}); nothing was paid and nothing is held: send the request again`, { cause });
         }
-        if (paid?.accepted.scheme === CLEARING_DEBIT)
-            this.hold(this.key(paid.accepted), this.offerId(paid.accepted), paid.payload);
-    }
-    hold(key, offer, payload) {
-        const held = this.unresolved.get(key) ?? [];
-        const same = held.find((h) => signatureOf(h.payload) === signatureOf(payload));
-        if (same)
-            same.unasked = true;
-        else
-            this.unresolved.set(key, [...held, { offer, payload, unasked: true }]);
-    }
-    /** Clears a Debit once a seller has answered about it. */
-    release(key, payload) {
-        const held = (this.unresolved.get(key) ?? []).filter((h) => signatureOf(h.payload) !== signatureOf(payload));
-        if (held.length)
-            this.unresolved.set(key, held);
-        else
-            this.unresolved.delete(key);
+        if (covered)
+            return new Error(`the clearing service refused this payment of ${invoice.amount} base units without saying why, though the account's deposit covers it; nothing was paid and nothing is held: send the request again, and if it is refused again this epoch, check that no other process pays from this wallet`, { cause });
+        return new ClearingRefusal("insufficient_deposit", { action: "deposit" }, `the clearing service refused this payment of ${invoice.amount} base units because the account's deposit does not cover it; nothing was paid: deposit more with depositToClearing, which pays from the next epoch, then send the request again`, { cause });
     }
-    /** What makes two offers the same payment: a Debit signed for one can be
-     * presented again for the other. */
-    offerId(requirements) {
-        const clearing = requirements.extra?.["clearing"];
-        return [
-            requirements.network,
-            requirements.asset,
-            requirements.payTo,
-            requirements.amount,
-            clearing?.contract,
-            clearing?.ref,
-        ]
-            .map((part) => String(part).toLowerCase())
-            .join("|");
+    /** What the service retained of a payment sent again without a usable
+     * answer: its receipt; `"released"` when it has no record of the payment
+     * and the epoch it was signed for is closed, or is no longer the live
+     * one on a service that is this wallet's deployment, so a later
+     * acceptance cannot overtake the answer; or nothing, when it cannot say.
+     * A refusal alone proves nothing: a proxy can answer one after the
+     * service accepted the payment. */
+    async function retained(pending) {
+        try {
+            const sent = decodeSend(pending.body);
+            // Read before the receipt: a closed epoch takes no payment after it.
+            const closed = await Promise.all([
+                chain.readContract({ address: config.settlement, abi: clearingAbi, functionName: "admittedCount" }),
+                request("/context"),
+            ]).then(([admitted, context]) => context.network !== config.network ||
+                context.settlement.toLowerCase() !== config.settlement.toLowerCase() ||
+                context.asset.toLowerCase() !== config.asset.toLowerCase()
+                ? undefined
+                : admitted > sent.epoch || BigInt(context.epoch) !== sent.epoch || context.anchor !== sent.anchor, () => undefined);
+            const found = await request(`/receipt/${config.signer.publicKey}/${encodeURIComponent(pending.invoice.id)}?epoch=${sent.epoch}`);
+            if (found)
+                return {
+                    paid: found,
+                    operator: await chain.readContract({ address: config.settlement, abi: clearingAbi, functionName: "operatorKey" }),
+                };
+            return closed ? "released" : undefined;
+        }
+        catch {
+            return undefined;
+        }
     }
-    /** Where the next Debit starts: the facilitator's answer while it is
-     * fresh, else a new one. */
-    async position(requirements, clearing) {
-        const key = this.key(requirements);
-        const known = this.positions.get(key);
-        if (known && this.now() - known.fetchedAt < POSITION_TTL_MS)
-            return known;
-        const answer = await fetchPosition(this.doFetch, this.facilitator, this.signer, requirements.network, clearing.contract, this.now());
-        const position = {
-            epoch: BigInt(answer.epoch),
-            index: BigInt(answer.index),
-            cumulative: BigInt(answer.cumulativeDebit),
-            available: BigInt(answer.available),
-            fetchedAt: this.now(),
+    async function pay(invoice, url) {
+        if (broken)
+            throw new Error("clearing wallet persistence failed; reopen the wallet");
+        const refused = refusal(invoice);
+        if (refused) {
+            const held = (await config.store.load())?.pending;
+            const elsewhere = held?.invoice.id === invoice.id ? differs(held.invoice) : undefined;
+            throw held && elsewhere
+                ? stranded(held, elsewhere)
+                : new Error(held?.invoice.id === invoice.id && refused.aboveMaxAmount
+                    ? `${refused.reason}; the wallet holds this payment and pays nothing else until it goes through: raise the wallet's maxAmount to send it`
+                    : refused.reason);
+        }
+        const amount = BigInt(invoice.amount);
+        let state = (await config.store.load()) ?? {
+            entries: [],
+            sequence: "0",
+            payments: {},
         };
-        // Every Debit this client signed it recorded first, so the true total
-        // cannot be above the highest it signed. A lower one is fine: a Debit
-        // that was never admitted.
-        const record = await this.storage.get(`${key}:${position.epoch}`);
-        if (record && position.cumulative > BigInt(record.highestSigned))
-            throw new Error("the facilitator reports a clearing total above what this client has signed; refusing to sign");
-        this.positions.set(key, position);
-        return position;
-    }
-    createPaymentPayload(x402Version, requirements) {
-        return this.exclusive(this.key(requirements), () => this.sign(x402Version, requirements));
-    }
-    async sign(x402Version, requirements) {
-        const key = this.key(requirements);
-        const offer = this.offerId(requirements);
-        // A Debit whose outcome is in doubt is presented again as it is: if it
-        // was admitted, the seller's facilitator answers with its receipt.
-        const held = this.unresolved.get(key) ?? [];
-        const pending = held.find((h) => h.offer === offer);
-        if (pending)
-            return { x402Version, payload: pending.payload };
-        // A different payment now. Whether a Debit held since the position was
-        // last asked for was admitted shows in a fresh one; it stays held for
-        // its own offer.
-        if (held.some((h) => h.unasked)) {
-            this.positions.delete(key);
-            for (const h of held)
-                h.unasked = false;
+        const paid = state.payments[invoice.id];
+        if (paid) {
+            if (invoiceMessage(paid.invoice, paid.receipt.body) !==
+                invoiceMessage(invoice, paid.receipt.body))
+                throw new Error("invoice id reused with different terms");
+            return paid;
         }
-        const clearing = clearingExtraOf(requirements);
-        const price = BigInt(requirements.amount);
-        const position = await this.position(requirements, clearing);
-        if (position.available < price) {
-            // Signed all the same: the seller refuses it as short, and the
-            // transport's retry takes the standard offer.
-            this.shortUntil.set(key, this.now() + SHORT_MS);
+        if (state.pending &&
+            invoiceMessage(state.pending.invoice, state.pending.body) !==
+                invoiceMessage(invoice, state.pending.body)) {
+            const elsewhere = differs(state.pending.invoice);
+            throw elsewhere ? stranded(state.pending, elsewhere) : held("payment_held", state.pending);
         }
-        const debit = {
-            payer: this.signer.address,
-            recipient: requirements.payTo,
-            epoch: position.epoch,
-            index: position.index,
-            cumulativeDebit: position.cumulative + price,
-            ref: clearing.ref,
-        };
-        // Recorded before it is released: a Debit the client has no record of
-        // signing would weaken every later check.
-        const recordKey = `${key}:${debit.epoch}`;
-        const record = await this.storage.get(recordKey);
-        const highest = record && BigInt(record.highestSigned) > debit.cumulativeDebit
-            ? BigInt(record.highestSigned)
-            : debit.cumulativeDebit;
-        await this.storage.set(recordKey, {
-            epoch: debit.epoch.toString(),
-            index: (debit.index + 1n).toString(),
-            cumulativeDebit: debit.cumulativeDebit.toString(),
-            highestSigned: highest.toString(),
-        });
-        const signature = await this.signer.signTypedData({
-            domain: clearingDomain(chainIdOf(requirements.network), clearing.contract),
-            types: DEBIT_TYPES,
-            primaryType: "Debit",
-            message: debit,
-        });
-        // The next Debit starts where this one ends, if it is admitted; if it is
-        // not, the seller's refusal says so and the position is asked again.
-        this.positions.set(key, {
-            ...position,
-            index: debit.index + 1n,
-            cumulative: debit.cumulativeDebit,
-            available: position.available - price,
-        });
-        const payload = {
-            signature,
-            debit: {
-                payer: debit.payer,
-                recipient: debit.recipient,
-                epoch: debit.epoch.toString(),
-                index: debit.index.toString(),
-                cumulativeDebit: debit.cumulativeDebit.toString(),
-                ref: debit.ref,
-            },
+        // A payment sent again has been sent before.
+        const resent = state.pending !== undefined;
+        if (!state.pending) {
+            const context = await request("/context").catch(async (error) => {
+                throw unavailable(error)
+                    ? await closed(error)
+                    : error instanceof ServiceRefused && [401, 403, 404].includes(error.status)
+                        ? new Error(`the clearing service answered ${error.status} for /context, so serviceUrl is not the clearing service the facilitator's /supported names (extra.serviceUrl); nothing was paid and nothing is held: set serviceUrl to it`, { cause: error })
+                        : new Error(`the clearing service did not give its epoch (${messageOf(error)}); nothing was paid and nothing is held: send the request again`, { cause: error });
+            });
+            if (context.reference !== CLEARING_REFERENCE ||
+                context.network !== config.network ||
+                context.settlement.toLowerCase() !== config.settlement.toLowerCase() ||
+                context.asset.toLowerCase() !== config.asset.toLowerCase())
+                throw new Error("unsupported clearing service deployment");
+            const epoch = BigInt(context.epoch);
+            const [registered, onchain, fault, admitted, block, unit] = await onChain(Promise.all([
+                chain.readContract({
+                    address: config.settlement,
+                    abi: clearingAbi,
+                    functionName: "registered",
+                }),
+                chain.readContract({
+                    address: config.settlement,
+                    abi: clearingAbi,
+                    functionName: "contextOf",
+                    args: [epoch],
+                }),
+                chain.readContract({
+                    address: config.settlement,
+                    abi: clearingAbi,
+                    functionName: "fault",
+                }),
+                chain.readContract({
+                    address: config.settlement,
+                    abi: clearingAbi,
+                    functionName: "admittedCount",
+                }),
+                chain.getBlock(),
+                chain.readContract({
+                    address: config.settlement,
+                    abi: clearingAbi,
+                    functionName: "unit",
+                }),
+            ]));
+            if (fault)
+                throw faulted();
+            // The contract has not registered the service's epoch yet, or has
+            // closed it to payments.
+            if (!registered ||
+                admitted !== epoch ||
+                block.timestamp >= onchain.admissionDeadline)
+                throw betweenEpochs();
+            if (onchain.anchor !== context.anchor ||
+                onchain.operatorKey !== context.operator)
+                throw new Error("clearing epoch is not registered");
+            if (state.epoch !== context.epoch)
+                state = { ...state, epoch: context.epoch, sequence: "0", entries: [] };
+            const entries = state.entries.map((e) => ({ ...e }));
+            let entry = entries.find((e) => e.recipient.toLowerCase() === invoice.recipient.toLowerCase());
+            if (!entry) {
+                entry = { recipient: invoice.recipient, cumulative: "0", count: "0" };
+                entries.push(entry);
+            }
+            // The invoice is in token base units; the vector counts clearing units.
+            entry.cumulative = (BigInt(entry.cumulative) + clearingUnits(amount, unit)).toString();
+            entry.count = (BigInt(entry.count) + 1n).toString();
+            // The service takes at most this many recipients in one payment's vector.
+            if (entries.length > MAX_ENTRIES)
+                throw new Error(`this wallet has paid ${MAX_ENTRIES} recipients in epoch ${context.epoch}, the most one payment's vector holds; nothing was paid and nothing is held: send the request again after the next epoch`);
+            entries.sort((a, b) => a.recipient.toLowerCase().localeCompare(b.recipient.toLowerCase()));
+            const vector = entries.map((e) => ({
+                ...e,
+                cumulative: BigInt(e.cumulative),
+                count: BigInt(e.count),
+            }));
+            const body = encodeSend({
+                anchor: context.anchor,
+                epoch,
+                payer: config.signer.publicKey,
+                sequence: BigInt(state.sequence),
+                debit: vector.reduce((sum, e) => sum + e.cumulative, 0n),
+                vector: outgoingRoot(vector),
+            });
+            state = {
+                ...state,
+                pending: {
+                    invoice,
+                    body,
+                    entries,
+                    payerSignature: await config.signer.sign("_COMMONWARE_CLEARING_VECTOR_SEND", body),
+                    invoiceSignature: await config.signer.sign("_METAL_CLEARING_INVOICE", invoiceMessage(invoice, body)),
+                    url,
+                },
+            };
+            await save(state);
+        }
+        const pending = state.pending;
+        let result;
+        let operator;
+        try {
+            result = await request("/payments", {
+                invoice: pending.invoice,
+                body: pending.body,
+                payerSignature: pending.payerSignature,
+                invoiceSignature: pending.invoiceSignature,
+                entries: pending.entries,
+            });
+            operator = await chain.readContract({
+                address: config.settlement,
+                abi: clearingAbi,
+                functionName: "operatorKey",
+            });
+        }
+        catch (error) {
+            if (error instanceof ServiceRefused && error.rejected) {
+                await save({ ...state, pending: undefined });
+                throw await rejection(decodeSend(pending.body).epoch, invoice, error);
+            }
+            // Once the deployment has faulted, recovery takes the account's
+            // funds whatever became of the payment.
+            const fault = await chain
+                .readContract({ address: config.settlement, abi: clearingAbi, functionName: "fault" })
+                .catch(() => 0);
+            if (fault)
+                throw faulted(error, true);
+            const kept = resent ? await retained(pending) : undefined;
+            if (kept === "released") {
+                // The vector it extended belongs to an epoch that is closed or gone.
+                await save({ ...state, epoch: undefined, entries: [], sequence: "0", pending: undefined });
+                throw new Error(`the clearing service has no record of this payment, ${describe(pending)}, and the epoch it was signed for has closed or is no longer the live one, so it can never be taken: it is released; nothing was paid and nothing is held: send the request again`, { cause: error });
+            }
+            if (!kept)
+                throw held("answer_lost", pending, error);
+            ({ paid: result, operator } = kept);
+        }
+        let verified = false;
+        try {
+            verified =
+                result.receipt.payerSignature === pending.payerSignature &&
+                    invoiceMessage(result.invoice, pending.body) === invoiceMessage(invoice, pending.body) &&
+                    verifyReceipt(result.receipt, operator);
+        }
+        catch {
+            // An answer that is no receipt does not verify.
+        }
+        if (!verified)
+            throw held("unverified", pending);
+        const settled = {
+            invoice,
+            receipt: result.receipt,
+            invoiceSignature: pending.invoiceSignature,
+            entries: pending.entries,
+            ...(result.previous ? { previous: result.previous } : {}),
         };
-        return { x402Version, payload };
-    }
-}
-const CLEARING_DEPOSIT_ABI = [
-    {
-        type: "function",
-        name: "deposit",
-        stateMutability: "nonpayable",
-        inputs: [
-            { name: "account", type: "address" },
-            { name: "amount", type: "uint256" },
-        ],
-        outputs: [],
-    },
-];
-/** Put funds into clearing custody. `from` pays and sends the transactions:
- * the agent's own wallet, or anyone funding it, in which case `account` is
- * the agent's address. The tokens go from `from` straight into custody under
- * `account`; only `account`'s signature can spend or withdraw them.
- *
- * Two transactions (an approval for exactly this amount, unless that much
- * is already approved, then the deposit), paid for in the network's fee token by `from`. Gas and
- * fees are set here because a Metal node cannot be asked to estimate them.
- *
- * The operator counts a deposit some seconds after its receipt, and refuses
- * clearing payments against it until then. Given `facilitator`, this waits
- * until the facilitator reports the deposit in the payer's position, so the
- * next payment can draw on it. */
-export async function depositToClearing(opts) {
-    if (opts.amount <= 0n)
-        throw new Error("deposit amount must be positive");
-    const credited = opts.account ?? opts.from.address;
-    if (opts.facilitator && credited.toLowerCase() !== opts.from.address.toLowerCase())
-        throw new Error("only the account itself can ask the facilitator about its custody; deposit without `facilitator` to fund another account");
-    const network = `eip155:${opts.chainId}`;
-    const facilitator = opts.facilitator?.replace(/\/$/, "");
-    const doFetch = opts.fetch ?? globalThis.fetch;
-    // What custody holds before this epoch's debits: `available` plus the
-    // epoch's running total. Paying by clearing moves value between the two,
-    // so only a deposit raises it.
-    const custody = async () => {
-        const position = await fetchPosition(doFetch, facilitator, opts.from, network, opts.contract, Date.now());
-        const available = BigInt(position.available);
-        return { epoch: position.epoch, available, held: available + BigInt(position.cumulativeDebit) };
-    };
-    // Read before depositing: an unreachable facilitator fails before any funds move.
-    let last = facilitator ? await custody() : undefined;
-    let before = last?.held ?? 0n;
-    const transport = http(opts.rpcUrl);
-    const pub = createPublicClient({ transport });
-    const wallet = createWalletClient({ account: opts.from, transport });
-    const send = async (to, data) => {
-        const [block, nonce] = await Promise.all([
-            pub.getBlock({ blockTag: "latest" }),
-            pub.getTransactionCount({
-                address: opts.from.address,
-                blockTag: "pending",
-            }),
-        ]);
-        const hash = await wallet.sendTransaction({
-            chain: null,
-            chainId: opts.chainId,
-            to,
-            data,
-            value: 0n,
-            gas: 500000n,
-            maxFeePerGas: (block.baseFeePerGas ?? 0n) * 2n + 1n,
-            maxPriorityFeePerGas: 1n,
-            nonce,
-            type: "eip1559",
+        await save({
+            ...state,
+            entries: pending.entries,
+            sequence: (decodeSend(pending.body).sequence + 1n).toString(),
+            pending: undefined,
+            payments: { ...state.payments, [invoice.id]: settled },
         });
-        const receipt = await pub.waitForTransactionReceipt({
-            hash,
-            timeout: 60_000,
-        });
-        if (receipt.status !== "success")
-            throw new Error(`transaction reverted: ${hash}`);
-        return hash;
-    };
-    const allowance = await pub.readContract({
-        address: opts.asset,
-        abi: erc20Abi,
-        functionName: "allowance",
-        args: [opts.from.address, opts.contract],
-    });
-    const approveTx = allowance >= opts.amount
-        ? null
-        : await send(opts.asset, encodeFunctionData({
-            abi: erc20Abi,
-            functionName: "approve",
-            args: [opts.contract, opts.amount],
-        }));
-    const deposit = {
-        abi: CLEARING_DEPOSIT_ABI,
-        functionName: "deposit",
-        args: [credited, opts.amount],
-    };
-    // Simulated first, so a deposit the contract would refuse (a short
-    // balance, a halted contract) fails with its reason and costs no gas.
-    await pub.simulateContract({
-        ...deposit,
-        account: opts.from,
-        address: opts.contract,
-        gas: 500000n,
-    });
-    const depositTx = await send(opts.contract, encodeFunctionData(deposit));
-    if (!facilitator)
-        return { approveTx, depositTx };
-    const deadline = Date.now() + (opts.timeoutMs ?? 60_000);
-    for (;;) {
-        const now = await custody();
-        // A close settles the epoch's debits out of custody: what the last
-        // reading had available is the new base.
-        if (last && now.epoch !== last.epoch)
-            before = last.available;
-        last = now;
-        if (now.held >= before + opts.amount)
-            return { approveTx, depositTx, available: now.available };
-        if (Date.now() >= deadline)
-            throw new Error(`deposit ${depositTx} landed, but the facilitator has not counted it yet; clearing payments are refused until it does`);
-        await new Promise((resolve) => setTimeout(resolve, opts.pollMs ?? 1_000));
+        return settled;
     }
-}
-/** Take funds out of clearing custody: a payer's unused deposit, or what a
- * seller has been paid. It asks the facilitator what can be withdrawn, signs
- * an Exit for that amount, and submits it; Metal's operator sends the two
- * transactions (request, then release) and pays their gas.
- *
- * Only this wallet's signature moves its funds, and only to the destination
- * it names, which defaults to the wallet itself. */
-export async function withdrawFromClearing(signer, facilitator, options) {
-    const doFetch = options.fetch ?? globalThis.fetch;
-    const base = facilitator.replace(/\/$/, "");
-    const now = options.now?.() ?? Date.now();
-    const listed = await doFetch(`${base}/supported`);
-    if (!listed.ok)
-        throw new Error(`facilitator refused: ${listed.status}`);
-    const supported = (await listed.json());
-    const kind = supported.kinds.find((item) => item.scheme === CLEARING_DEBIT && item.network === options.network);
-    const contract = kind?.extra?.contract;
-    if (!contract)
-        throw new Error(`no clearing on ${options.network} here`);
-    const quote = await post(doFetch, `${base}/clearing/exit/quote`, await accountRequest(signer, options.network, contract, now));
-    if (BigInt(quote.deadline) > BigInt(Math.floor(now / 1000) + 86_400))
-        throw new Error("the quoted deadline is too far away to sign");
-    const available = BigInt(quote.amount);
-    const amount = options.amount ?? available;
-    if (amount > available)
-        throw new Error(`only ${available} can be withdrawn now`);
-    if (amount <= 0n) {
-        // Custody becomes withdrawable once the epoch holding it has closed and
-        // passed its challenge window; until then it is only spendable.
-        const held = BigInt((await fetchPosition(doFetch, base, signer, options.network, contract, now))
-            .available);
-        throw new Error(held > 0n
-            ? `nothing to withdraw yet: ${held} (base units) is in custody and can be withdrawn once the epoch it is in has closed and passed its challenge window`
-            : "nothing to withdraw");
-    }
-    const exit = {
-        account: signer.address,
-        destination: options.destination ?? signer.address,
-        amount,
-        deadline: BigInt(quote.deadline),
-    };
-    const signature = await signer.signTypedData({
-        domain: clearingDomain(chainIdOf(options.network), contract),
-        types: EXIT_TYPES,
-        primaryType: "Exit",
-        message: exit,
-    });
-    const done = await post(doFetch, `${base}/clearing/exit`, {
-        network: options.network,
-        account: exit.account,
-        destination: exit.destination,
-        amount: exit.amount.toString(),
-        deadline: exit.deadline.toString(),
-        signature,
-    });
     return {
-        amount: BigInt(done.amount),
-        requestTx: done.requestTx,
-        // Null when another caller released the queued exit on chain first; the
-        // funds still went to the Exit's destination.
-        releaseTx: done.releaseTx ?? null,
+        account: config.signer.publicKey,
+        async pendingInvoice() {
+            return (await config.store.load())?.pending?.invoice ?? null;
+        },
+        /** Why this wallet does not pay `invoice`, or undefined when it does. */
+        unpayable: refusal,
+        /** Pay `invoice`; `url`, the request it pays for, is kept with a
+         * payment whose outcome is unknown, so a refusal can name it. A payment
+         * the service does not take throws a `ClearingRefusal`. */
+        pay(invoice, url) {
+            const result = tail.then(() => pay(invoice, url));
+            tail = result.catch(() => { });
+            return result;
+        },
+        request,
     };
 }