@metalntwx/metal-pay 0.3.0 → 0.3.2

package/src/clearing-client.ts

@@ -1,4 +1,4 @@
-import { createPublicClient, http, type Hex } from "viem";
+import { BaseError, createPublicClient, type Hex } from "viem";
 import { clearingAbi } from "./clearing-abi.js";
 import {
   CLEARING_REFERENCE,
@@ -11,6 +11,7 @@ import {
   type ClearingInvoice,
   type ClearingReceipt,
 } from "./clearing-codec.js";
+import { formatUsdz, rpcTransport, USDZ } from "./networks.js";
 
 export interface ClearingSigner {
   publicKey: Hex;
@@ -36,10 +37,12 @@ export interface ClearingPaid {
   previous?: { receipt: ClearingReceipt; entries: ClearingEntry[] };
 }
 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. */
@@ -59,11 +62,143 @@ export interface ClearingClientConfig {
   fetch?: typeof globalThis.fetch;
 }
 
-class PaymentRejected extends Error {}
+/** 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 class ClearingRefusal extends Error {
+  override readonly name = "ClearingRefusal";
+  constructor(
+    readonly reason: ClearingRefusalReason,
+    readonly retry: ClearingRetry,
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+  }
+}
+
+/** 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?: unknown) {
+  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?: unknown, 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: NonNullable<ClearingClientState["pending"]>) {
+  return `${pending.invoice.amount} base units ${pending.url === undefined ? `under invoice ${pending.invoice.id}` : `for ${pending.url}`}`;
+}
+
+function messageOf(cause: unknown) {
+  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: "payment_held" | "answer_lost" | "unverified",
+  pending: NonNullable<ClearingClientState["pending"]>,
+  cause?: unknown,
+) {
+  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: NonNullable<ClearingClientState["pending"]>, which: { what: string; theirs: string; ours: string }) {
+  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 {
+  constructor(
+    readonly status: number,
+    readonly rejected: boolean,
+  ) {
+    super(
+      rejected
+        ? "clearing payment rejected before acknowledgment"
+        : `clearing service returned ${status}`,
+    );
+  }
+}
+const unavailable = (error: unknown) =>
+  error instanceof ServiceRefused && error.status === 409 && !error.rejected;
 
 export function createClearingClient(config: ClearingClientConfig) {
   const fetcher = config.fetch ?? globalThis.fetch;
-  const chain = createPublicClient({ transport: http(config.rpcUrl) });
+  const chain = createPublicClient({ transport: rpcTransport(config.rpcUrl) });
   let tail: Promise<unknown> = Promise.resolve();
   let broken = false;
   async function save(state: ClearingClientState) {
@@ -89,31 +224,155 @@ export function createClearingClient(config: ClearingClientConfig) {
       const result = (await response.json().catch(() => null)) as {
         rejected?: boolean;
       } | 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()) as T;
   }
-  /** Why this wallet does not pay `invoice`, or undefined when it does. */
-  function refusal(invoice: ClearingInvoice) {
-    if (
-      invoice.network !== config.network ||
-      invoice.asset.toLowerCase() !== config.asset.toLowerCase() ||
-      invoice.settlement.toLowerCase() !== config.settlement.toLowerCase()
-    )
-      return "clearing invoice deployment mismatch";
+  /** How `invoice` is for another network, deployment or asset than this
+   * wallet's, or undefined when it is not. */
+  function differs(invoice: ClearingInvoice) {
+    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: ClearingInvoice): { reason: string; aboveMaxAmount: boolean } | undefined {
+    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: unknown) {
+    const fault = await onChain(
+      chain.readContract({
+        address: config.settlement,
+        abi: clearingAbi,
+        functionName: "fault",
+      }),
+    );
+    return fault ? faulted(cause) : betweenEpochs(cause);
+  }
+  /** `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<T>(reads: Promise<T>): Promise<T> {
+    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: bigint, invoice: ClearingInvoice, cause: unknown) {
+    let covered: boolean;
+    let opened = false;
+    try {
+      const [context, fault] = await Promise.all([
+        request<{ epoch: string }>("/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<{ amount: string }>(`/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 },
+    );
   }
-  async function pay(invoice: ClearingInvoice) {
+  /** 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: NonNullable<ClearingClientState["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<{ network: string; settlement: Hex; asset: Hex; epoch: string; anchor: Hex }>("/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<ClearingPaid | null>(
+        `/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" as const) : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  async function pay(invoice: ClearingInvoice, url?: string) {
     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: [],
@@ -133,10 +392,12 @@ export function createClearingClient(config: ClearingClientConfig) {
       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",
-      );
+    ) {
+      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<{
         reference: string;
@@ -146,7 +407,19 @@ export function createClearingClient(config: ClearingClientConfig) {
         operator: Hex;
         epoch: string;
         anchor: Hex;
-      }>("/context");
+      }>("/context").catch(async (error: unknown) => {
+        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 ||
@@ -155,8 +428,8 @@ export function createClearingClient(config: ClearingClientConfig) {
       )
         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,
@@ -173,7 +446,6 @@ export function createClearingClient(config: ClearingClientConfig) {
             abi: clearingAbi,
             functionName: "fault",
           }),
-          chain.getChainId(),
           chain.readContract({
             address: config.settlement,
             abi: clearingAbi,
@@ -185,13 +457,17 @@ export function createClearingClient(config: ClearingClientConfig) {
             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 ||
+        block.timestamp >= onchain.admissionDeadline
+      )
+        throw betweenEpochs();
+      if (
         onchain.anchor !== context.anchor ||
         onchain.operatorKey !== context.operator
       )
@@ -211,6 +487,11 @@ export function createClearingClient(config: ClearingClientConfig) {
         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()),
       );
@@ -241,34 +522,60 @@ export function createClearingClient(config: ClearingClientConfig) {
             "_METAL_CLEARING_INVOICE",
             invoiceMessage(invoice, body),
           ),
+          url,
         },
       };
       await save(state);
     }
     const pending = state.pending!;
     let result: ClearingPaid;
+    let operator: Hex;
     try {
-      result = await request<ClearingPaid>("/payments", pending);
+      result = await request<ClearingPaid>("/payments", {
+        invoice: pending.invoice,
+        body: pending.body,
+        payerSignature: pending.payerSignature,
+        invoiceSignature: pending.invoiceSignature,
+        entries: pending.entries,
+      } satisfies ClearingPayment);
+      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,
@@ -290,11 +597,13 @@ export function createClearingClient(config: ClearingClientConfig) {
     async pendingInvoice() {
       return (await config.store.load())?.pending?.invoice ?? null;
     },
-    payable(invoice: ClearingInvoice) {
-      return refusal(invoice) === undefined;
-    },
-    pay(invoice: ClearingInvoice) {
-      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: ClearingInvoice, url?: string) {
+      const result = tail.then(() => pay(invoice, url));
       tail = result.catch(() => {});
       return result;
     },