@metalntwx/metal-pay 0.1.1 → 0.3.0

package/dist/clearing-client.js

@@ -1,580 +1,207 @@
-// 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;
+import { createPublicClient, http } from "viem";
+import { clearingAbi } from "./clearing-abi.js";
+import { CLEARING_REFERENCE, clearingUnits, decodeSend, encodeSend, invoiceMessage, outgoingRoot, verifyReceipt, } from "./clearing-codec.js";
+class PaymentRejected extends Error {
 }
-/** 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));
-    }
-}
-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;
-}
-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,
-    };
-}
-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;
-}
-/** 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;
-}
-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;
-            },
-        };
-    }
-    /** 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);
+export function createClearingClient(config) {
+    const fetcher = config.fetch ?? globalThis.fetch;
+    const chain = createPublicClient({ transport: http(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()}`;
-    }
-    sellerOf(requirements) {
-        const clearing = requirements.extra?.["clearing"];
-        return `${requirements.network}:${String(clearing?.contract).toLowerCase()}:${requirements.payTo.toLowerCase()}`;
-    }
-    /** 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;
+    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));
+            if (result?.rejected === true)
+                throw new PaymentRejected("clearing payment rejected before acknowledgment");
+            throw new Error(`clearing service returned ${response.status}`);
+        }
+        return (await response.json());
+    }
+    /** Why this wallet does not pay `invoice`, or undefined when it does. */
+    function refusal(invoice) {
+        if (invoice.network !== config.network ||
+            invoice.asset.toLowerCase() !== config.asset.toLowerCase() ||
+            invoice.settlement.toLowerCase() !== config.settlement.toLowerCase())
+            return "clearing invoice deployment mismatch";
+        const amount = BigInt(invoice.amount);
+        if (amount <= 0n || amount > config.maxAmount)
+            return "clearing payment exceeds spending limit";
+    }
+    async function pay(invoice) {
+        if (broken)
+            throw new Error("clearing wallet persistence failed; reopen the wallet");
+        const refused = refusal(invoice);
+        if (refused)
+            throw new Error(refused);
+        const amount = BigInt(invoice.amount);
+        let state = (await config.store.load()) ?? {
+            entries: [],
+            sequence: "0",
+            payments: {},
         };
-    }
-    /** Holds the Debit a request carried, if it carried one of this client's. */
-    holdSent(header) {
-        let paid;
-        try {
-            paid = header ? decodePaymentSignatureHeader(header) : undefined;
+        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;
         }
-        catch {
-            // Not a payment this client made.
+        if (state.pending &&
+            invoiceMessage(state.pending.invoice, state.pending.body) !==
+                invoiceMessage(invoice, state.pending.body))
+            throw new Error("an earlier clearing payment has an unknown outcome; retry that invoice first");
+        if (!state.pending) {
+            const context = await request("/context");
+            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, chainId, admitted, block, unit] = await 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.getChainId(),
+                chain.readContract({
+                    address: config.settlement,
+                    abi: clearingAbi,
+                    functionName: "admittedCount",
+                }),
+                chain.getBlock(),
+                chain.readContract({
+                    address: config.settlement,
+                    abi: clearingAbi,
+                    functionName: "unit",
+                }),
+            ]);
+            if (!registered ||
+                fault ||
+                admitted !== epoch ||
+                block.timestamp >= onchain.admissionDeadline ||
+                `eip155:${chainId}` !== config.network ||
+                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();
+            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)),
+                },
+            };
+            await save(state);
         }
-        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);
-    }
-    /** 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("|");
-    }
-    /** 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(),
-        };
-        // 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 pending = state.pending;
+        let result;
+        try {
+            result = await request("/payments", pending);
         }
-        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);
+        catch (error) {
+            if (error instanceof PaymentRejected)
+                await save({ ...state, pending: undefined });
+            throw error;
         }
-        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 operator = await chain.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "operatorKey",
         });
-        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,
-            },
+        if (result.receipt.body !== pending.body ||
+            result.receipt.payerSignature !== pending.payerSignature ||
+            invoiceMessage(result.invoice, pending.body) !==
+                invoiceMessage(invoice, pending.body) ||
+            !verifyReceipt(result.receipt, operator))
+            throw new Error("invalid clearing acknowledgment; retain pending payment");
+        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;
+        },
+        payable(invoice) {
+            return refusal(invoice) === undefined;
+        },
+        pay(invoice) {
+            const result = tail.then(() => pay(invoice));
+            tail = result.catch(() => { });
+            return result;
+        },
+        request,
     };
 }