@metalntwx/metal-pay 0.3.0 → 0.3.2

package/README.md

@@ -15,7 +15,8 @@ client; `registerMetalNetworks(client, { signer, networks? })`
 registers the scheme on an `x402Client` you already have. Both refuse,
 before signing, a Metal `exact` offer in any token but `*USDZ` or under any
 EIP-712 domain but USDZ's. `createMetalPaymentClient` also refuses any offer
-above `maxAmount`, a `bigint` in `*USDZ` base units. The default is
+above `maxAmount`, a `bigint` in `*USDZ` base units, except a clearing
+offer, which its wallet's own `maxAmount` caps. The default is
 `DEFAULT_MAX_PAYMENT`, 1 `*USDZ`. It works with `@x402/core`, `@x402/evm`
 and `@x402/fetch` from 2.28 up to the next major, installed as its peers
 (npm 7+ and pnpm do that themselves). The stock client pays only tokens in
@@ -91,14 +92,28 @@ pending authorization across transport errors. Supply trusted `serviceUrl`,
 `openClearingWallet(directory)` from `@metalntwx/metal-pay/node` supplies a
 persistent signer and store with exclusive
 process ownership. Preserve that directory across restarts; call `close()` on
-shutdown. Retry an unknown outcome using the same invoice before another payment.
+shutdown. A payment the service does not take throws a `ClearingRefusal`,
+whose `reason` is `between_epochs`, `insufficient_deposit`, `answer_lost`
+or `payment_held` and whose `retry` says what to do: wait `retry.ms`
+(again after each further `between_epochs`), deposit, or send the held
+request, `retry.url` at `retry.amount`, again after `retry.ms` before any
+other. If that URL no longer offers clearing at that price, pass the
+client's `pendingInvoice()` to its `pay`. A held payment sent again is
+settled from the service's receipt when it kept one, and released when it
+has none and its epoch has closed or is no longer the service's live one.
+A wallet's record is for one Clearing deployment: open a new wallet for a
+replacement. Through `createMetalPaymentClient`'s `fetchWithPayment` it is
+the thrown error's `cause`.
 
 `clearingRequirements` and `clearingInvoice` bind an invoice to a resource,
 recipient, amount and deployment. `registerClearingClient` adds the `bajillion`
 scheme to an official x402 client, which then pays by clearing wherever its
-wallet can pay the offer. Behind the stock middleware, Metal's facilitator
-verifies and deduplicates clearing payments before the handler runs. A seller that
-verifies them itself calls `verifyClearingPayment` with its own trusted
+wallet can pay the offer and refuses any other request on that
+registration's network, unless given `{ exactFallback: true }` to pay it by
+`exact`. Behind the stock middleware,
+Metal's facilitator verifies and deduplicates clearing payments before the
+handler runs. A seller that verifies them itself calls
+`verifyClearingPayment` with its own trusted
 RPC/service configuration and deduplicates `clearingPaymentId` in durable
 storage before delivering. The returned receipt is **preconfirmed**;
 watch `Clearing.finalizedCount` before labeling its epoch finalized. It is not
@@ -106,19 +121,25 @@ an EVM transaction hash.
 
 `depositToClearing` funds a clearing account from an EVM account, waiting
 for the contract's deposit window; `clearingSpendable` reads the service's
-estimate of what the account can spend, in token base units, and
+estimate of what the account can spend, in token base units, which counts
+a deposit from the epoch after it lands and can read low around an
+epoch's close, and
 `clearingBalance` the finalized balance and its proof, in clearing units
 (`Clearing.unit()` base units each, a millionth of `*USDZ`);
 `withdrawFromClearing` queues a withdrawal of the finalized balance and,
-once its epoch has finalized, claims it, for payer and seller alike.
+once its epoch has finalized, claims it, for payer and seller alike; it
+answers `empty` when there is nothing finalized to claim or queue. A
+queue or claim refused because an epoch finalized under its proof moved
+nothing, and its error says to call again after the next epoch.
 `clearingClose` and `clearingLogProof` are the pieces it is built from.
 `recoverFromClearing` takes an account's funds out of a deployment whose
 service has missed a deadline: it faults the deployment, starts recovery,
 and takes the payout of the account's finalized withdrawal, its last
 finalized balance and its uncounted deposits, with proofs from the service
-or the first of several validators that retained the epoch. The
-[service README](../../apps/clearing-service/README.md) describes
-operator/validator setup, receipt retention and proof endpoints.
+or the first of several validators that retained the epoch. The clearing
+service's README, `apps/clearing-service/README.md` in the Metal
+repository, describes operator/validator setup, receipt retention and proof
+endpoints.
 
 **Mandates.** `@metalntwx/metal-pay/mandates` lets an agent pay from its
 owner's account with a P-256 key of its own, within limits Metal enforces on
@@ -127,11 +148,13 @@ budget, how many payments, an expiry) as a Verifiable Intent mandate;
 `ingestCredential` verifies one against the issuers the owner trusts, and
 `bindCall`, `replaceCall` and `revokeCall` build the owner's transactions to its own
 MetalAccount. Wrap those calls with `authorizeMandateCall(client, trustedFactory,
-call, signQuorum)` to authorize an account self-call, or a list of them as one
+call, validUntil, signQuorum)` to authorize an account self-call, or a list of them as one
 batch that runs whole or not at all, with its existing weighted quorum. The
-client must name its chain: the digest the quorum signs is computed from it,
-never read from the RPC endpoint. The callback supports the same EOA, P-256 and passkey signatures as
-ordinary account execution. Factory-created clones share an immutable VI
+account refuses the signed batch after `validUntil` (unix seconds, a `bigint`), so
+give it a short deadline. The client must name its chain: the digest the quorum
+signs is computed from it, never read from the RPC endpoint. The callback
+supports the same EOA, P-256 and passkey signatures as ordinary account
+execution. Factory-created clones share an immutable VI
 verifier; budgets and replay protection live in each account. `createMandatePaymentClient({ credential, signDigest, network })`
 is the payer, and `MandateExactScheme` the same payer as a scheme for an
 `x402Client` of your own: each payment is an ERC-3009 authorization from the
@@ -146,6 +169,10 @@ are decimal, to the cent. `verifyMandate` and `verifyMandatePayment` trust the
 MetalAccountFactory `METAL_NETWORKS` names for the chain, or the
 `accountFactory` given, check the account's clone code against the
 factory's current implementation, and match the successful token transfer to the seller's requirements.
+`verifyMandatePayment` checks a `checkoutMandate` against the payment, failing one of another
+payment as such; its step 4 says when none was given, so no order was checked.
+An event under the mandate that the SDK does not decode, as an account of
+another version emits, fails the verification with its topic and the account.
 The module runs on Node only.
 
 **RPC.** Neither payers nor payees need one. Each network's `rpc` is its

package/dist/clearing-client.d.ts

@@ -27,10 +27,14 @@ export interface ClearingPaid {
     };
 }
 export interface ClearingClientState {
-    epoch?: string;
+    epoch?: string | undefined;
     entries: ClearingEntry[];
     sequence: string;
-    pending?: ClearingPayment | undefined;
+    /** The payment sent whose outcome is unknown, with the URL it pays for
+     * when `pay` was given one. */
+    pending?: (ClearingPayment & {
+        url?: string | undefined;
+    }) | undefined;
     payments: Record<string, ClearingPaid>;
 }
 /** save must complete an atomic durability barrier; one process owns each payer. */
@@ -49,10 +53,53 @@ export interface ClearingClientConfig {
     maxAmount: bigint;
     fetch?: typeof globalThis.fetch;
 }
+/** Why a clearing payment was not made. */
+export type ClearingRefusalReason = "between_epochs" | "insufficient_deposit" | "payment_held" | "answer_lost";
+/** What to do after a `ClearingRefusal`. */
+export type ClearingRetry = 
+/** Nothing was paid: send the request again after `ms`, and wait `ms`
+ * again after each further `between_epochs` refusal. */
+{
+    action: "retry_after_ms";
+    ms: number;
+}
+/** Nothing was paid: deposit more, then send the request again. */
+ | {
+    action: "deposit";
+}
+/** The wallet holds a payment whose outcome is unknown, `amount` base
+ * units for `url` (`null` when `pay` was given none; through
+ * `fetchWithPayment`, the URL the request was sent to), and pays nothing
+ * else until it goes through: send that request again at that price
+ * after `ms`, which sends the same payment, so it is never paid twice. 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. */
+ | {
+    action: "repeat_same_request";
+    url: string | null;
+    amount: string;
+    ms: number;
+};
+/** A clearing payment the service did not take: `reason` says why, `retry`
+ * what to do, and the message both in words. */
+export declare class ClearingRefusal extends Error {
+    readonly reason: ClearingRefusalReason;
+    readonly retry: ClearingRetry;
+    readonly name = "ClearingRefusal";
+    constructor(reason: ClearingRefusalReason, retry: ClearingRetry, message: string, options?: ErrorOptions);
+}
 export declare function createClearingClient(config: ClearingClientConfig): {
     account: `0x${string}`;
     pendingInvoice(): Promise<ClearingInvoice | null>;
-    payable(invoice: ClearingInvoice): boolean;
-    pay(invoice: ClearingInvoice): Promise<ClearingPaid>;
+    /** Why this wallet does not pay `invoice`, or undefined when it does. */
+    unpayable: (invoice: ClearingInvoice) => {
+        reason: string;
+        aboveMaxAmount: boolean;
+    } | undefined;
+    /** 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: ClearingInvoice, url?: string): Promise<ClearingPaid>;
     request: <T>(path: string, body?: unknown) => Promise<T>;
 };

package/dist/clearing-client.js

@@ -1,11 +1,84 @@
-import { createPublicClient, http } from "viem";
+import { BaseError, createPublicClient } 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 {
+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;
+    }
+}
+/** 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 });
+}
+/** 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 });
+}
+/** 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}`}`;
+}
+function messageOf(cause) {
+    return cause instanceof BaseError
+        ? cause.shortMessage
+        : cause instanceof Error
+            ? cause.message
+            : String(cause);
+}
+/** 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;
+    }
+}
+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: http(config.rpcUrl) });
+    const chain = createPublicClient({ transport: rpcTransport(config.rpcUrl) });
     let tail = Promise.resolve();
     let broken = false;
     async function save(state) {
@@ -30,28 +103,139 @@ export function createClearingClient(config) {
         });
         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}`);
+            throw new ServiceRefused(response.status, result?.rejected === true);
         }
         return (await response.json());
     }
-    /** Why this wallet does not pay `invoice`, or undefined when it does. */
+    /** 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 };
+    }
+    /** 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) {
-        if (invoice.network !== config.network ||
-            invoice.asset.toLowerCase() !== config.asset.toLowerCase() ||
-            invoice.settlement.toLowerCase() !== config.settlement.toLowerCase())
-            return "clearing invoice deployment mismatch";
+        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 <= 0n || amount > config.maxAmount)
-            return "clearing payment exceeds spending limit";
+        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);
     }
-    async function pay(invoice) {
+    /** `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 {
+            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 (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 (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 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;
+        }
+    }
+    async function pay(invoice, url) {
         if (broken)
             throw new Error("clearing wallet persistence failed; reopen the wallet");
         const refused = refusal(invoice);
-        if (refused)
-            throw new Error(refused);
+        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: [],
@@ -67,17 +251,27 @@ export function createClearingClient(config) {
         }
         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");
+                invoiceMessage(invoice, state.pending.body)) {
+            const elsewhere = differs(state.pending.invoice);
+            throw elsewhere ? stranded(state.pending, elsewhere) : held("payment_held", state.pending);
+        }
+        // A payment sent again has been sent before.
+        const resent = state.pending !== undefined;
         if (!state.pending) {
-            const context = await request("/context");
+            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, chainId, admitted, block, unit] = await Promise.all([
+            const [registered, onchain, fault, admitted, block, unit] = await onChain(Promise.all([
                 chain.readContract({
                     address: config.settlement,
                     abi: clearingAbi,
@@ -94,7 +288,6 @@ export function createClearingClient(config) {
                     abi: clearingAbi,
                     functionName: "fault",
                 }),
-                chain.getChainId(),
                 chain.readContract({
                     address: config.settlement,
                     abi: clearingAbi,
@@ -106,13 +299,16 @@ export function createClearingClient(config) {
                     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 ||
-                fault ||
                 admitted !== epoch ||
-                block.timestamp >= onchain.admissionDeadline ||
-                `eip155:${chainId}` !== config.network ||
-                onchain.anchor !== context.anchor ||
+                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)
@@ -126,6 +322,9 @@ export function createClearingClient(config) {
             // 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,
@@ -148,31 +347,62 @@ export function createClearingClient(config) {
                     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", pending);
+            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 PaymentRejected)
+            if (error instanceof ServiceRefused && error.rejected) {
                 await save({ ...state, pending: undefined });
-            throw error;
+                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);
         }
-        const operator = await chain.readContract({
-            address: config.settlement,
-            abi: clearingAbi,
-            functionName: "operatorKey",
-        });
-        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");
+        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,
@@ -194,11 +424,13 @@ export function createClearingClient(config) {
         async pendingInvoice() {
             return (await config.store.load())?.pending?.invoice ?? null;
         },
-        payable(invoice) {
-            return refusal(invoice) === undefined;
-        },
-        pay(invoice) {
-            const result = tail.then(() => pay(invoice));
+        /** 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;
         },

package/dist/clearing-custody.d.ts

@@ -84,8 +84,10 @@ export interface ClearingChain {
  * registrations, so the deposit waits for that window and is sent again
  * if the window closes under it, up to `timeoutMs` (default 60 s). It
  * refuses at once a contract that holds another token, and a deposit past
- * what the contract holds in all. A deposit whose outcome is unknown is not
- * sent again: the error names it. */
+ * what the contract holds in all. A deposit the token refuses because
+ * `from` holds less fails naming what `from` holds and what the deposit
+ * needs. A deposit whose outcome is unknown is not sent again: the error
+ * names it. */
 export declare function depositToClearing(opts: ClearingChain & {
     asset: Address;
     account: Hex;
@@ -104,15 +106,22 @@ type ClearingClaim = {
 };
 export type ClearingWithdrawal = 
 /** A withdrawal is queued and `epoch`, the one that carries it, has not
- * finalized; nothing can be sent until it does. */
+ * finalized; nothing can be sent until it does. Once the service has
+ * missed a deadline, the call fails instead, naming `recoverFromClearing`. */
 {
     status: "waiting";
     epoch: bigint;
 }
+/** Nothing to withdraw: no payout to claim, and no finalized balance.
+ * What the account holds in an epoch not yet finalized can leave once
+ * it is. */
+ | {
+    status: "empty";
+}
 /** What this call sent: the account's payout it claimed, to the
  * destination the finalized withdrawal named, and the withdrawal it
- * queued for the account's finalized balance, or `null` when that balance
- * is zero. A
+ * queued for the account's finalized balance, or `null` when nothing
+ * finalized is left to queue. A
  * deferred payout is one the destination refused: it waits in the
  * contract's `unclaimedPayout` until the destination calls
  * `withdrawUnclaimed`. */
@@ -128,7 +137,9 @@ export type ClearingWithdrawal =
  * withdrawal of whatever finalized balance remains, to `destination` (`from` itself
  * unless given). A payer's unused deposit and a seller's earnings leave the
  * same way. Call again after the queued withdrawal's epoch finalizes. A
- * failure after a claim names the claims made before it. */
+ * failure after a claim names the claims made before it. A queue or claim
+ * refused because an epoch finalized under its proof moved nothing: the
+ * error says to call again after the next epoch. */
 export declare function withdrawFromClearing(opts: ClearingChain & {
     signer: ClearingSigner;
     serviceUrl: string;