@metalntwx/metal-pay 0.2.0 → 0.3.1

package/src/clearing-client.ts

@@ -0,0 +1,612 @@
+import { BaseError, createPublicClient, type Hex } from "viem";
+import { clearingAbi } from "./clearing-abi.js";
+import {
+  CLEARING_REFERENCE,
+  clearingUnits,
+  decodeSend,
+  encodeSend,
+  invoiceMessage,
+  outgoingRoot,
+  verifyReceipt,
+  type ClearingInvoice,
+  type ClearingReceipt,
+} from "./clearing-codec.js";
+import { formatUsdz, rpcTransport, USDZ } from "./networks.js";
+
+export interface ClearingSigner {
+  publicKey: Hex;
+  sign(namespace: string, message: Hex): Hex | Promise<Hex>;
+}
+export interface ClearingEntry {
+  recipient: Hex;
+  cumulative: string;
+  count: string;
+}
+export interface ClearingPayment {
+  invoice: ClearingInvoice;
+  body: Hex;
+  payerSignature: Hex;
+  invoiceSignature: Hex;
+  entries: ClearingEntry[];
+}
+export interface ClearingPaid {
+  invoice: ClearingInvoice;
+  receipt: ClearingReceipt;
+  invoiceSignature: Hex;
+  entries: ClearingEntry[];
+  previous?: { receipt: ClearingReceipt; entries: ClearingEntry[] };
+}
+export interface ClearingClientState {
+  epoch?: string | undefined;
+  entries: ClearingEntry[];
+  sequence: string;
+  /** 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. */
+export interface ClearingClientStore {
+  load(): Promise<ClearingClientState | null>;
+  save(state: ClearingClientState): Promise<void>;
+}
+export interface ClearingClientConfig {
+  serviceUrl: string;
+  rpcUrl: string;
+  network: `eip155:${number}`;
+  settlement: Hex;
+  asset: Hex;
+  signer: ClearingSigner;
+  store: ClearingClientStore;
+  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 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: rpcTransport(config.rpcUrl) });
+  let tail: Promise<unknown> = Promise.resolve();
+  let broken = false;
+  async function save(state: ClearingClientState) {
+    try {
+      await config.store.save(state);
+    } catch (error) {
+      broken = true;
+      throw error;
+    }
+  }
+  async function request<T>(path: string, body?: unknown): Promise<T> {
+    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)) as {
+        rejected?: boolean;
+      } | null;
+      throw new ServiceRefused(response.status, result?.rejected === true);
+    }
+    return (await response.json()) as T;
+  }
+  /** 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 > 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 },
+    );
+  }
+  /** 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) {
+      const held = (await config.store.load())?.pending;
+      const elsewhere = held?.invoice.id === invoice.id ? differs(held.invoice) : undefined;
+      throw held && elsewhere
+        ? stranded(held, elsewhere)
+        : new Error(
+            held?.invoice.id === invoice.id && refused.aboveMaxAmount
+              ? `${refused.reason}; the wallet holds this payment and pays nothing else until it goes through: raise the wallet's maxAmount to send it`
+              : refused.reason,
+          );
+    }
+    const amount = BigInt(invoice.amount);
+    let state = (await config.store.load()) ?? {
+      entries: [],
+      sequence: "0",
+      payments: {},
+    };
+    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;
+    }
+    if (
+      state.pending &&
+      invoiceMessage(state.pending.invoice, state.pending.body) !==
+        invoiceMessage(invoice, state.pending.body)
+    ) {
+      const elsewhere = differs(state.pending.invoice);
+      throw elsewhere ? stranded(state.pending, elsewhere) : held("payment_held", state.pending);
+    }
+    // A payment sent again has been sent before.
+    const resent = state.pending !== undefined;
+    if (!state.pending) {
+      const context = await request<{
+        reference: string;
+        network: string;
+        settlement: Hex;
+        asset: Hex;
+        operator: Hex;
+        epoch: string;
+        anchor: Hex;
+      }>("/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 ||
+        context.settlement.toLowerCase() !== config.settlement.toLowerCase() ||
+        context.asset.toLowerCase() !== config.asset.toLowerCase()
+      )
+        throw new Error("unsupported clearing service deployment");
+      const epoch = BigInt(context.epoch);
+      const [registered, onchain, fault, admitted, block, unit] =
+        await onChain(Promise.all([
+          chain.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "registered",
+          }),
+          chain.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "contextOf",
+            args: [epoch],
+          }),
+          chain.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "fault",
+          }),
+          chain.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "admittedCount",
+          }),
+          chain.getBlock(),
+          chain.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "unit",
+          }),
+        ]));
+      if (fault) throw faulted();
+      // The contract has not registered the service's epoch yet, or has
+      // closed it to payments.
+      if (
+        !registered ||
+        admitted !== epoch ||
+        block.timestamp >= onchain.admissionDeadline
+      )
+        throw betweenEpochs();
+      if (
+        onchain.anchor !== context.anchor ||
+        onchain.operatorKey !== context.operator
+      )
+        throw new Error("clearing epoch is not registered");
+      if (state.epoch !== context.epoch)
+        state = { ...state, epoch: context.epoch, sequence: "0", entries: [] };
+      const entries = state.entries.map((e) => ({ ...e }));
+      let entry = entries.find(
+        (e) => e.recipient.toLowerCase() === invoice.recipient.toLowerCase(),
+      );
+      if (!entry) {
+        entry = { recipient: invoice.recipient, cumulative: "0", count: "0" };
+        entries.push(entry);
+      }
+      // The invoice is in token base units; the vector counts clearing units.
+      entry.cumulative = (
+        BigInt(entry.cumulative) + clearingUnits(amount, unit)
+      ).toString();
+      entry.count = (BigInt(entry.count) + 1n).toString();
+      // The service takes at most this many recipients in one payment's vector.
+      if (entries.length > MAX_ENTRIES)
+        throw new Error(
+          `this wallet has paid ${MAX_ENTRIES} recipients in epoch ${context.epoch}, the most one payment's vector holds; nothing was paid and nothing is held: send the request again after the next epoch`,
+        );
+      entries.sort((a, b) =>
+        a.recipient.toLowerCase().localeCompare(b.recipient.toLowerCase()),
+      );
+      const vector = entries.map((e) => ({
+        ...e,
+        cumulative: BigInt(e.cumulative),
+        count: BigInt(e.count),
+      }));
+      const body = encodeSend({
+        anchor: context.anchor,
+        epoch,
+        payer: config.signer.publicKey,
+        sequence: BigInt(state.sequence),
+        debit: vector.reduce((sum, e) => sum + e.cumulative, 0n),
+        vector: outgoingRoot(vector),
+      });
+      state = {
+        ...state,
+        pending: {
+          invoice,
+          body,
+          entries,
+          payerSignature: await config.signer.sign(
+            "_COMMONWARE_CLEARING_VECTOR_SEND",
+            body,
+          ),
+          invoiceSignature: await config.signer.sign(
+            "_METAL_CLEARING_INVOICE",
+            invoiceMessage(invoice, body),
+          ),
+          url,
+        },
+      };
+      await save(state);
+    }
+    const pending = state.pending!;
+    let result: ClearingPaid;
+    let operator: Hex;
+    try {
+      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 ServiceRefused && error.rejected) {
+        await save({ ...state, pending: undefined });
+        throw await rejection(decodeSend(pending.body).epoch, invoice, error);
+      }
+      // Once the deployment has faulted, recovery takes the account's
+      // funds whatever became of the payment.
+      const fault = await chain
+        .readContract({ address: config.settlement, abi: clearingAbi, functionName: "fault" })
+        .catch(() => 0);
+      if (fault) throw faulted(error, true);
+      const kept = resent ? await retained(pending) : undefined;
+      if (kept === "released") {
+        // The vector it extended belongs to an epoch that is closed or gone.
+        await save({ ...state, epoch: undefined, entries: [], sequence: "0", pending: undefined });
+        throw new Error(
+          `the clearing service has no record of this payment, ${describe(pending)}, and the epoch it was signed for has closed or is no longer the live one, so it can never be taken: it is released; nothing was paid and nothing is held: send the request again`,
+          { cause: error },
+        );
+      }
+      if (!kept) throw held("answer_lost", pending, error);
+      ({ paid: result, operator } = kept);
+    }
+    let verified = false;
+    try {
+      verified =
+        result.receipt.payerSignature === pending.payerSignature &&
+        invoiceMessage(result.invoice, pending.body) === invoiceMessage(invoice, pending.body) &&
+        verifyReceipt(result.receipt, operator);
+    } catch {
+      // An answer that is no receipt does not verify.
+    }
+    if (!verified) throw held("unverified", pending);
+    const settled = {
+      invoice,
+      receipt: result.receipt,
+      invoiceSignature: pending.invoiceSignature,
+      entries: pending.entries,
+      ...(result.previous ? { previous: result.previous } : {}),
+    };
+    await save({
+      ...state,
+      entries: pending.entries,
+      sequence: (decodeSend(pending.body).sequence + 1n).toString(),
+      pending: undefined,
+      payments: { ...state.payments, [invoice.id]: settled },
+    });
+    return settled;
+  }
+  return {
+    account: config.signer.publicKey,
+    async pendingInvoice() {
+      return (await config.store.load())?.pending?.invoice ?? null;
+    },
+    /** Why this wallet does not pay `invoice`, or undefined when it does. */
+    unpayable: refusal,
+    /** Pay `invoice`; `url`, the request it pays for, is kept with a
+     * payment whose outcome is unknown, so a refusal can name it. A payment
+     * the service does not take throws a `ClearingRefusal`. */
+    pay(invoice: ClearingInvoice, url?: string) {
+      const result = tail.then(() => pay(invoice, url));
+      tail = result.catch(() => {});
+      return result;
+    },
+    request,
+  };
+}

package/src/clearing-codec.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { clearingUnits, decodeSend, outgoingRoot, verifyReceipt } from "./clearing-codec.js";
+
+const fixture = JSON.parse(
+  readFileSync(new URL("./clearing-fixture.json", import.meta.url), "utf8"),
+);
+
+describe("native Bajillion wire parity", () => {
+  it("verifies a receipt produced by the pinned Rust implementation", () => {
+    expect(verifyReceipt(fixture.receipt, fixture.operator)).toBe(true);
+    const body = decodeSend(fixture.receipt.body);
+    expect(body.debit).toBe(600n);
+    expect(
+      outgoingRoot([
+        {
+          recipient: fixture.receipt.entry.recipient,
+          cumulative: 600n,
+          count: 1n,
+        },
+      ]),
+    ).toBe(body.vector);
+  });
+
+  it("rejects tampered bodies and operator keys", () => {
+    expect(
+      verifyReceipt(
+        { ...fixture.receipt, body: fixture.receipt.body.slice(0, -2) + "00" },
+        fixture.operator,
+      ),
+    ).toBe(false);
+    expect(verifyReceipt(fixture.receipt, fixture.receipt.payer)).toBe(false);
+  });
+
+  it("rejects noncanonical vectors and out-of-range amounts", () => {
+    const entry = {
+      recipient: fixture.receipt.entry.recipient,
+      cumulative: 600n,
+      count: 1n,
+    };
+    expect(() => outgoingRoot([entry, entry])).toThrow();
+    expect(() => outgoingRoot([{ ...entry, cumulative: 1n << 64n }])).toThrow();
+    expect(() => outgoingRoot([{ ...entry, cumulative: 0n }])).toThrow();
+    expect(() =>
+      decodeSend((fixture.receipt.body + "00") as `0x${string}`),
+    ).toThrow();
+  });
+});
+
+describe("clearing units", () => {
+  it("counts an amount in a deployment's units and refuses a fraction of one", () => {
+    expect(clearingUnits(5n * 10n ** 12n, 10n ** 12n)).toBe(5n);
+    expect(clearingUnits(7n, 1n)).toBe(7n);
+    expect(() => clearingUnits(10n ** 12n + 1n, 10n ** 12n)).toThrow(/whole number of clearing units/);
+    expect(() => clearingUnits(5n, 0n)).toThrow();
+  });
+});