@metalntwx/metal-pay 0.2.0 → 0.3.1

package/src/clearing-x402.test.ts

@@ -0,0 +1,181 @@
+import { x402Client } from "@x402/core/client";
+import { describe, it, expect } from "vitest";
+import {
+  registerClearingClient,
+  clearingRequirements,
+  clearingInvoice,
+  clearingPaymentOf,
+  clearingPaymentMismatch,
+  clearingPaymentId,
+} from "./clearing-x402.js";
+import {
+  createClearingSigner,
+  clearingUnits,
+  decodeSend,
+  encodeSend,
+  outgoingRoot,
+  invoiceMessage,
+} from "./clearing-codec.js";
+import type { ClearingInvoice } from "./clearing-codec.js";
+import type { ClearingPaid } from "./clearing-client.js";
+
+describe("native x402 invoice binding", () => {
+  const payer = createClearingSigner(`0x${"12".repeat(32)}`);
+  const operator = createClearingSigner(`0x${"23".repeat(32)}`);
+  const requirements = clearingRequirements(
+    {
+      network: "eip155:1337",
+      asset: `0x${"11".repeat(20)}`,
+      settlement: `0x${"22".repeat(20)}`,
+      recipient: operator.publicKey,
+      serviceUrl: "http://localhost:7091",
+    },
+    5n,
+    "/coffee/cart-1",
+  );
+  const invoice = clearingInvoice(
+    requirements,
+    `${requirements.extra!.invoicePrefix}:purchase-1`,
+  );
+  const entries = [
+    { recipient: operator.publicKey, cumulative: "5", count: "1" },
+  ];
+  const body = encodeSend({
+    anchor: `0x${"00".repeat(32)}`,
+    epoch: 1n,
+    payer: payer.publicKey,
+    sequence: 0n,
+    debit: 5n,
+    vector: outgoingRoot([
+      { recipient: operator.publicKey, cumulative: 5n, count: 1n },
+    ]),
+  });
+  const paid: ClearingPaid = {
+    invoice,
+    entries,
+    invoiceSignature: payer.sign(
+      "_METAL_CLEARING_INVOICE",
+      invoiceMessage(invoice, body),
+    ),
+    receipt: {
+      body,
+      payerSignature: payer.sign("_COMMONWARE_CLEARING_VECTOR_SEND", body),
+      operatorSignature: operator.sign("_COMMONWARE_CLEARING_VECTOR_ACK", body),
+    },
+  };
+  it.each([
+    { amount: 19n * 10n ** 18n, unit: 10n ** 12n },
+    { amount: ((1n << 64n) - 1n) * 10n ** 30n, unit: 10n ** 30n },
+  ])("binds a $amount base-unit invoice", ({ amount, unit }) => {
+    const largeInvoice = { ...invoice, amount: amount.toString() };
+    const cumulative = clearingUnits(amount, unit);
+    const vector = [{ recipient: operator.publicKey, cumulative, count: 1n }];
+    const largeBody = encodeSend({
+      ...decodeSend(body),
+      debit: cumulative,
+      vector: outgoingRoot(vector),
+    });
+    const largePaid: ClearingPaid = {
+      invoice: largeInvoice,
+      entries: [{ ...entries[0]!, cumulative: cumulative.toString() }],
+      invoiceSignature: payer.sign(
+        "_METAL_CLEARING_INVOICE",
+        invoiceMessage(largeInvoice, largeBody),
+      ),
+      receipt: {
+        body: largeBody,
+        payerSignature: payer.sign("_COMMONWARE_CLEARING_VECTOR_SEND", largeBody),
+        operatorSignature: operator.sign(
+          "_COMMONWARE_CLEARING_VECTOR_ACK",
+          largeBody,
+        ),
+      },
+    };
+    expect(clearingPaymentOf({ payload: largePaid as never })).toEqual(largePaid);
+    expect(
+      clearingPaymentMismatch(largePaid, {
+        ...requirements,
+        amount: amount.toString(),
+      }),
+    ).toBeNull();
+    expect(
+      clearingPaymentOf({
+        payload: {
+          ...largePaid,
+          invoice: { ...largeInvoice, amount: (amount + 1n).toString() },
+        },
+      }),
+    ).toBeNull();
+  });
+  it.each([-1n, 1n << 256n])(
+    "rejects an invoice amount outside uint256: %s",
+    (amount) => {
+      expect(() =>
+        invoiceMessage({ ...invoice, amount: amount.toString() }, body),
+      ).toThrow();
+    },
+  );
+  it("rejects altered invoice amounts and cross-resource reuse", () => {
+    expect(clearingPaymentOf({ payload: paid as never })).toEqual(paid);
+    expect(
+      clearingPaymentOf({
+        payload: { ...paid, invoice: { ...invoice, amount: "6" } },
+      }),
+    ).toBeNull();
+    expect(clearingPaymentMismatch(paid, requirements)).toBeNull();
+    expect(
+      clearingPaymentMismatch(paid, {
+        ...requirements,
+        extra: { ...requirements.extra, invoicePrefix: `0x${"33".repeat(32)}` },
+      }),
+    ).toBe("invoice");
+    expect(clearingPaymentId(paid)).toBe(
+      clearingPaymentId({
+        ...paid,
+        invoice: { ...invoice, id: invoice.id + "other" },
+      }),
+    );
+  });
+  it("rejects a different vector or cumulative debit", () => {
+    expect(
+      clearingPaymentOf({
+        payload: { ...paid, entries: [{ ...entries[0], cumulative: "6" }] },
+      }),
+    ).toBeNull();
+  });
+  it("retries the pending invoice after the x402 adapter loses a response", async () => {
+    let pending: ClearingInvoice | null = null;
+    const ids: string[] = [];
+    const payer = {
+      async pendingInvoice() {
+        return pending;
+      },
+      unpayable: () => undefined,
+      async pay(next: ClearingInvoice) {
+        ids.push(next.id);
+        if (!pending) {
+          pending = next;
+          throw new Error("response lost");
+        }
+        expect(next).toEqual(pending);
+        pending = null;
+        return { ...paid, invoice: next };
+      },
+    };
+    const client = registerClearingClient(
+      new x402Client().setSpendControls({ allowedAssets: true }),
+      "eip155:1337",
+      payer as never,
+    );
+    const offer = {
+      x402Version: 2,
+      resource: { url: "/coffee/cart-1" },
+      accepts: [requirements],
+    };
+    await expect(client.createPaymentPayload(offer)).rejects.toThrow(
+      "response lost",
+    );
+    await client.createPaymentPayload(offer);
+    expect(ids[0]).toBe(ids[1]);
+  });
+});

package/src/clearing-x402.ts

@@ -0,0 +1,328 @@
+import type { PaymentRequirements, PaymentPayload } from "@x402/core/types";
+import type { x402Client } from "@x402/core/client";
+import { createPublicClient, sha256, stringToHex, type Hex } from "viem";
+import { clearingAbi } from "./clearing-abi.js";
+import {
+  CLEARING_SCHEME,
+  clearingUnits,
+  decodeSend,
+  invoiceMessage,
+  verifyClearingSignature,
+  verifyReceipt,
+  outgoingRoot,
+  type ClearingInvoice,
+} from "./clearing-codec.js";
+import type { ClearingPaid, createClearingClient } from "./clearing-client.js";
+import { rpcTransport } from "./networks.js";
+
+export interface ClearingSeller {
+  network: `eip155:${number}`;
+  asset: Hex;
+  settlement: Hex;
+  recipient: Hex;
+  serviceUrl: string;
+}
+/** A resource-bound invoice namespace; the payer appends a unique payment id. */
+export function clearingRequirements(
+  seller: ClearingSeller,
+  amount: bigint,
+  resource: string,
+): PaymentRequirements {
+  if (amount <= 0n) throw new Error("invalid clearing price");
+  return {
+    scheme: CLEARING_SCHEME,
+    network: seller.network,
+    asset: seller.asset,
+    amount: amount.toString(),
+    payTo: seller.recipient,
+    maxTimeoutSeconds: 60,
+    extra: {
+      settlement: seller.settlement,
+      serviceUrl: seller.serviceUrl,
+      invoicePrefix: sha256(stringToHex(resource)),
+    },
+  };
+}
+export function clearingInvoice(
+  requirements: PaymentRequirements,
+  id: string,
+): ClearingInvoice {
+  const extra = requirements.extra;
+  if (
+    requirements.scheme !== CLEARING_SCHEME ||
+    !/^0x[0-9a-fA-F]{66}$/.test(requirements.payTo) ||
+    typeof extra?.settlement !== "string" ||
+    !/^0x[0-9a-fA-F]{40}$/.test(extra.settlement) ||
+    typeof extra.invoicePrefix !== "string" ||
+    !/^0x[0-9a-f]{64}$/.test(extra.invoicePrefix) ||
+    !id.startsWith(extra.invoicePrefix + ":")
+  )
+    throw new Error("invalid clearing requirement");
+  return {
+    id,
+    network: requirements.network,
+    asset: requirements.asset as Hex,
+    settlement: extra.settlement as Hex,
+    recipient: requirements.payTo as Hex,
+    amount: requirements.amount,
+  };
+}
+export function clearingPaymentOf(
+  payload: Pick<PaymentPayload, "payload">,
+): ClearingPaid | null {
+  try {
+    const paid = payload.payload as unknown as ClearingPaid;
+    const body = decodeSend(paid.receipt.body);
+    invoiceMessage(paid.invoice, paid.receipt.body);
+    const entries = paid.entries.map((e) => ({
+      ...e,
+      cumulative: BigInt(e.cumulative),
+      count: BigInt(e.count),
+    }));
+    if (
+      entries.length > 1024 ||
+      outgoingRoot(entries) !== body.vector ||
+      entries.reduce((n, e) => n + e.cumulative, 0n) !== body.debit ||
+      !verifyClearingSignature(
+        body.payer,
+        "_METAL_CLEARING_INVOICE",
+        invoiceMessage(paid.invoice, paid.receipt.body),
+        paid.invoiceSignature,
+      )
+    )
+      return null;
+    return paid;
+  } catch {
+    return null;
+  }
+}
+export function clearingPaymentMismatch(
+  paid: ClearingPaid,
+  requirements: PaymentRequirements,
+): string | null {
+  try {
+    return invoiceMessage(
+      clearingInvoice(requirements, paid.invoice.id),
+      paid.receipt.body,
+    ) === invoiceMessage(paid.invoice, paid.receipt.body)
+      ? null
+      : "invoice";
+  } catch {
+    return "invoice";
+  }
+}
+export function clearingPaymentId(paid: ClearingPaid): string {
+  return `${paid.invoice.network}:bajillion:${paid.invoice.settlement.toLowerCase()}:${sha256(paid.receipt.body)}`;
+}
+/** Both the RPC and service URL must come from the seller's trusted configuration. */
+export async function verifyClearingPayment(
+  paid: ClearingPaid,
+  requirements: PaymentRequirements,
+  config: { rpcUrl: string; serviceUrl: string; settlement: Hex },
+) {
+  if (
+    clearingPaymentMismatch(paid, requirements) ||
+    paid.invoice.settlement.toLowerCase() !== config.settlement.toLowerCase()
+  )
+    throw new Error("clearing invoice mismatch");
+  if (
+    !clearingPaymentOf({ payload: paid as unknown as Record<string, unknown> })
+  )
+    throw new Error("invalid clearing payment");
+  const send = decodeSend(paid.receipt.body);
+  const client = createPublicClient({ transport: rpcTransport(config.rpcUrl) });
+  const [context, fault, asset, chainId, unit] = await Promise.all([
+    client.readContract({
+      address: config.settlement,
+      abi: clearingAbi,
+      functionName: "contextOf",
+      args: [send.epoch],
+    }),
+    client.readContract({
+      address: config.settlement,
+      abi: clearingAbi,
+      functionName: "fault",
+    }),
+    client.readContract({
+      address: config.settlement,
+      abi: clearingAbi,
+      functionName: "token",
+    }),
+    client.getChainId(),
+    client.readContract({
+      address: config.settlement,
+      abi: clearingAbi,
+      functionName: "unit",
+    }),
+  ]);
+  if (
+    fault ||
+    `eip155:${chainId}` !== paid.invoice.network ||
+    asset.toLowerCase() !== paid.invoice.asset.toLowerCase() ||
+    context.anchor !== send.anchor ||
+    !verifyReceipt(paid.receipt, context.operatorKey)
+  )
+    throw new Error("invalid clearing receipt");
+  const previous = paid.previous;
+  let before: ClearingPaid["entries"] = [];
+  if (send.sequence === 0n) {
+    if (previous) throw new Error("unexpected predecessor receipt");
+  } else {
+    if (!previous || !verifyReceipt(previous.receipt, context.operatorKey))
+      throw new Error("missing predecessor receipt");
+    const prior = decodeSend(previous.receipt.body);
+    before = previous.entries;
+    if (
+      prior.epoch !== send.epoch ||
+      prior.anchor !== send.anchor ||
+      prior.payer !== send.payer ||
+      prior.sequence + 1n !== send.sequence ||
+      outgoingRoot(
+        before.map((e) => ({
+          ...e,
+          cumulative: BigInt(e.cumulative),
+          count: BigInt(e.count),
+        })),
+      ) !== prior.vector
+    )
+      throw new Error("invalid predecessor vector");
+  }
+  const expected = new Map(
+    before.map((e) => [e.recipient.toLowerCase(), { ...e }]),
+  );
+  const key = paid.invoice.recipient.toLowerCase();
+  const old = expected.get(key);
+  // The invoice is in token base units; the vector counts clearing units.
+  expected.set(key, {
+    recipient: paid.invoice.recipient,
+    cumulative: (
+      (old ? BigInt(old.cumulative) : 0n) +
+      clearingUnits(BigInt(paid.invoice.amount), unit)
+    ).toString(),
+    count: ((old ? BigInt(old.count) : 0n) + 1n).toString(),
+  });
+  if (
+    expected.size !== paid.entries.length ||
+    paid.entries.some((e) => {
+      const wanted = expected.get(e.recipient.toLowerCase());
+      return (
+        !wanted ||
+        wanted.count !== e.count ||
+        wanted.cumulative !== e.cumulative
+      );
+    })
+  )
+    throw new Error("invoice is not the incremental payment");
+  // The operator's durable invoice journal attests the incremental charge,
+  // which cannot be inferred from a cumulative vector alone.
+  const response = await fetch(
+    new URL(
+      `/receipt/${send.payer}/${encodeURIComponent(paid.invoice.id)}?epoch=${send.epoch}`,
+      config.serviceUrl,
+    ),
+    { signal: AbortSignal.timeout(10_000) },
+  );
+  if (!response.ok) throw new Error("clearing receipt unavailable");
+  const recorded = (await response.json()) as ClearingPaid | null;
+  if (
+    !recorded ||
+    recorded.receipt.body !== paid.receipt.body ||
+    recorded.receipt.operatorSignature !== paid.receipt.operatorSignature ||
+    invoiceMessage(recorded.invoice, recorded.receipt.body) !==
+      invoiceMessage(paid.invoice, paid.receipt.body)
+  )
+    throw new Error("clearing invoice not retained");
+  return {
+    payer: send.payer,
+    id: clearingPaymentId(paid),
+    status: "preconfirmed" as const,
+  };
+}
+/** Pay by clearing through `client` on `network`. A request with an offer on
+ * `network` but none the wallet can pay fails, unless `exactFallback` is
+ * true: then it is paid by another offer of the request on `network`,
+ * `exact` from its EVM account, and fails when it has none. A request with
+ * no offer on `network` is left to the
+ * client's other registrations. A payment the clearing service does not take
+ * throws a `ClearingRefusal`. */
+export function registerClearingClient(
+  client: x402Client,
+  network: `eip155:${number}`,
+  payer: Pick<
+    ReturnType<typeof createClearingClient>,
+    "pay" | "unpayable" | "pendingInvoice"
+  >,
+  { exactFallback = false }: { exactFallback?: boolean } = {},
+) {
+  // The URL each offer was asked for, kept with a payment whose outcome is
+  // unknown so a refusal names the request to send again.
+  const urls = new WeakMap<PaymentRequirements, string>();
+  client.register(network, {
+    scheme: CLEARING_SCHEME,
+    schemeHooks: {
+      async onBeforePaymentCreation({ paymentRequired, selectedRequirements }) {
+        urls.set(selectedRequirements, paymentRequired.resource.url);
+      },
+    },
+    async createPaymentPayload(x402Version, requirements) {
+      const pending = await payer.pendingInvoice();
+      // A payment held for another URL is the wallet's to refuse, naming it.
+      const prefix = `${requirements.extra?.invoicePrefix}:`;
+      const invoice = clearingInvoice(
+        requirements,
+        pending?.id.startsWith(prefix)
+          ? pending.id
+          : prefix + globalThis.crypto.randomUUID(),
+      );
+      const paid = await payer.pay(invoice, urls.get(requirements));
+      return {
+        x402Version,
+        payload: paid as unknown as Record<string, unknown>,
+      };
+    },
+  });
+  // The stock client keeps only `authorization` offers when any remain after
+  // its policies, and a clearing offer is `upfront`: so a payer set up for
+  // clearing keeps the clearing offers its wallet can pay, when there are any.
+  client.registerPolicy((_, offers) => {
+    if (!offers.some((offer) => offer.network === network)) return offers;
+    const offered = offers.filter((offer) => offer.scheme === CLEARING_SCHEME && offer.network === network);
+    // Why the wallet does not pay `offer`, or undefined when it does.
+    const unpaid = (offer: PaymentRequirements) => {
+      if (!/^[0-9]+$/.test(offer.amount) || BigInt(offer.amount) === 0n)
+        return { reason: `offer is priced at "${offer.amount}", not a positive whole number of base units`, aboveMaxAmount: false };
+      let invoice: ClearingInvoice;
+      try {
+        invoice = clearingInvoice(offer, `${offer.extra?.invoicePrefix}:`);
+      } catch {
+        return { reason: "offer is malformed (invalid clearing requirement)", aboveMaxAmount: false };
+      }
+      return payer.unpayable(invoice);
+    };
+    const reasons = offered.map(unpaid);
+    const clearing = offered.filter((_, i) => reasons[i] === undefined);
+    if (clearing.length > 0) return clearing;
+    if (exactFallback) {
+      // The offers this wallet just refused stay out: the stock selector can
+      // choose them again, since a clearing offer with no extra.paymentFlow
+      // is otherwise indistinguishable from one it can pay. The fallback is
+      // for this request's offers on `network`; with none left, it fails.
+      if (offers.some((offer) => offer.network === network && !offered.includes(offer)))
+        return offers.filter((offer) => !offered.includes(offer));
+    }
+    const why =
+      offered.length > 0
+        ? `this clearing wallet pays none of the clearing offers here (${[...new Set(reasons.map((r) => r?.reason))].join("; ")})`
+        : `this request offers no clearing payment on ${network}`;
+    // An offer above the wallet's maxAmount is for its own deployment: the
+    // limit or the seller is what to change, not the scheme.
+    throw new Error(
+      reasons.some((r) => r?.aboveMaxAmount)
+        ? `${why}; nothing was paid: raise the wallet's maxAmount or pay another seller`
+        : exactFallback
+          ? `${why}, and this request offers no other way to pay it; nothing was paid`
+          : `${why}, and paying by exact is off; nothing was paid: pass exactFallback: true to registerClearingClient to pay such a request by exact`,
+    );
+  });
+  return client;
+}