@metalntwx/metal-pay 0.2.0 → 0.3.0

package/src/clearing-fixture.json

@@ -0,0 +1,37 @@
+{
+  "operator": "0x03871d350cbe37fa4ea973c3ab837df73a5aecb0d39771798ebb183e7175f8310a",
+  "receipt": {
+    "body": "0x6842b636532bed19771b0e7216acfb53de4dde53c6f988c4348f18b85c85ad5100000000000000000258b2faa97c091b3fde391789a65dc1f9cefaed8a8e7b48d614efc5f49ac82a900000000000000000000000000000025852aec30aced3eff085db19802648a6409a4fdca76f0701f0ec0afebafbce4c6f",
+    "entry": {
+      "amount": 600,
+      "count": 1,
+      "length": 1,
+      "nativeRoot": "0x035f9453736cbc9c0a5883f3e27450012421dd3af52a1801a2448e81bf0ee45e",
+      "position": 0,
+      "recipient": "0x021df9ccf407d5b7465b74a0584f337ee72295e6ba773eb29283117eeefc2ca963",
+      "siblings": []
+    },
+    "fork": {
+      "operatorSignature": "0x93779ea219b93bf2426636b882214d456efd087ab1b65b71aa27ff16cb97d0936e7753f77d2d5708895b61188fefb3efc16f9e133fae4d8ede7219bc8b59caac",
+      "payerSignature": "0xf40a218fe56c263d9716a120240e9dc0f22ea9bfeea7e787feae73fd0083d0034dd2fc8656b541358bd5aec70c6446ddff142223f6cdf221ecca1d5c230c7eea"
+    },
+    "higherEntry": {
+      "entry": {
+        "amount": 601,
+        "count": 2,
+        "length": 1,
+        "nativeRoot": "0xd9f437456571741f3c125c1baf9f7dae29ec43a28dd9af5aeca5a5e954aa3b9f",
+        "position": 0,
+        "recipient": "0x021df9ccf407d5b7465b74a0584f337ee72295e6ba773eb29283117eeefc2ca963",
+        "siblings": []
+      },
+      "operatorSignature": "0x4fc438c68684c20d5734d6b6d96f1904b8e41656903fc319a038f1ce07cb6a1849b1a0bd5bcdc901a403bbd0293bfcce207aac9584ee31b03e6a458c5876c4f4",
+      "payerSignature": "0xde3a8a79cf180e4e669bb0464f7b9b62a1cd2326c153fad279fb3a9c8c84aded5631c791aa19c009258ccde6fde66b439d7b70f6489aa6b741ea1db9eeb99352",
+      "vector": "0xa4c558752c2682689ccd38349967da6f567c293cea615f779e821125929d3981"
+    },
+    "operatorSignature": "0xa27ba7d942eef63a4b371ddaa123050ea334dd49ff9ffd2d709adc4602fa612236fcf2075fb53e44f8b487f92081c27dc90923f91bce365cc5f52ed274264866",
+    "payer": "0x0258b2faa97c091b3fde391789a65dc1f9cefaed8a8e7b48d614efc5f49ac82a90",
+    "payerSignature": "0x99f45a7b1ffbdbde8e5a0d070e1565bf7bc52b08a3de28fd37065e76f73e02e43c32fb291574db333df1efac1385dfc5b655d987926c102c6c2c3117ab15b55a",
+    "vector": "0x52aec30aced3eff085db19802648a6409a4fdca76f0701f0ec0afebafbce4c6f"
+  }
+}

package/src/clearing-server.test.ts

@@ -0,0 +1,388 @@
+import { createServer, type Server } from "node:http";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { Hono } from "hono";
+import { paymentMiddleware } from "@x402/hono";
+import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
+import { decodePaymentRequiredHeader, decodePaymentResponseHeader, encodePaymentSignatureHeader } from "@x402/core/http";
+import type { PaymentPayload, PaymentRequirements } from "@x402/core/types";
+import { sha256, stringToHex } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { createClearingSigner, encodeSend, invoiceMessage, outgoingRoot, type ClearingInvoice } from "./clearing-codec.js";
+import type { ClearingPaid } from "./clearing-client.js";
+import { ClearingServerScheme } from "./clearing-server.js";
+import { clearingPaymentMismatch, clearingPaymentOf, registerClearingClient } from "./clearing-x402.js";
+import { createMetalPaymentClient } from "./client.js";
+import { USDZ } from "./networks.js";
+import { registerMetalScheme } from "./server.js";
+
+const NETWORK = "eip155:1337";
+const SETTLEMENT = "0x2222222222222222222222222222222222222222";
+const SERVICE_URL = "http://clearing.local:7091";
+/** The facilitator's /supported entry for clearing: the deployment it settles. */
+const KIND = {
+  x402Version: 2,
+  scheme: "bajillion",
+  network: NETWORK,
+  extra: { settlement: SETTLEMENT, asset: USDZ.address, serviceUrl: SERVICE_URL },
+} as const;
+const seller = createClearingSigner(`0x${"23".repeat(32)}`);
+const payer = createClearingSigner(`0x${"12".repeat(32)}`);
+const operator = createClearingSigner(`0x${"34".repeat(32)}`);
+
+/** What the facilitator does with a clearing payment before its chain reads: the same checks, from the same module,
+ * at verify and again at settle, and a receipt it recorded before refused as `already_settled` at both. */
+const checked: { requirements: PaymentRequirements; payload: PaymentPayload }[] = [];
+const settled = new Set<string>();
+const facilitator = createServer((req, res) => {
+  const chunks: Buffer[] = [];
+  req.on("data", (c: Buffer) => chunks.push(c));
+  req.on("end", () => {
+    const body = (chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) : {}) as {
+      paymentPayload?: PaymentPayload;
+      paymentRequirements?: PaymentRequirements;
+    };
+    const reply = (status: number, json: unknown) => {
+      res.writeHead(status, { "content-type": "application/json" });
+      res.end(JSON.stringify(json));
+    };
+    if (req.url === "/supported")
+      return reply(200, {
+        kinds: [
+          { x402Version: 2, scheme: "exact", network: NETWORK },
+          KIND,
+        ],
+        extensions: [],
+        signers: { "eip155:*": ["0x00000000000000000000000000000000000000fa"] },
+      });
+    const { paymentPayload, paymentRequirements } = body;
+    if (!paymentPayload || !paymentRequirements) return reply(400, {});
+    const paid = clearingPaymentOf(paymentPayload);
+    const mismatch =
+      !paid ||
+      clearingPaymentMismatch(paid, paymentRequirements) ||
+      clearingPaymentMismatch(paid, paymentPayload.accepted as PaymentRequirements);
+    checked.push({ requirements: paymentRequirements, payload: paymentPayload });
+    if (req.url === "/verify") {
+      if (mismatch) return reply(200, { isValid: false, invalidReason: "invalid clearing invoice" });
+      if (settled.has(paid.invoice.id)) return reply(200, { isValid: false, invalidReason: "already_settled" });
+      return reply(200, { isValid: true, payer: payer.publicKey });
+    }
+    if (req.url === "/settle") {
+      if (mismatch) return reply(200, { success: false, errorReason: "invalid_clearing_payment", transaction: "", network: NETWORK });
+      const first = !settled.has(paid.invoice.id);
+      settled.add(paid.invoice.id);
+      return reply(200, { success: first, ...(first ? {} : { errorReason: "already_settled" }), transaction: "", network: NETWORK, payer: payer.publicKey });
+    }
+    reply(404, {});
+  });
+});
+
+/** A payer whose wallet signs a first payment for whatever invoice it is given. */
+const fakePayer = {
+  async pendingInvoice() {
+    return null;
+  },
+  payable() {
+    return true;
+  },
+  async pay(invoice: ClearingInvoice): Promise<ClearingPaid> {
+    const entries = [{ recipient: invoice.recipient, cumulative: invoice.amount, count: "1" }];
+    const body = encodeSend({
+      anchor: `0x${"00".repeat(32)}`,
+      epoch: 1n,
+      payer: payer.publicKey,
+      sequence: 0n,
+      debit: BigInt(invoice.amount),
+      vector: outgoingRoot([{ recipient: invoice.recipient, cumulative: BigInt(invoice.amount), count: 1n }]),
+    });
+    return {
+      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),
+      },
+    };
+  },
+};
+
+let app: Hono;
+let served = 0;
+
+beforeAll(async () => {
+  const facilitatorUrl = await listen(facilitator);
+  const server = registerMetalScheme(new x402ResourceServer(new HTTPFacilitatorClient({ url: facilitatorUrl })), {
+    networks: ["devnet"],
+  }).register(NETWORK, new ClearingServerScheme(NETWORK));
+  app = new Hono();
+  app.use(
+    paymentMiddleware(
+      {
+        "GET /chunk": {
+          accepts: [
+            { scheme: "bajillion", network: NETWORK, payTo: seller.publicKey, price: "0.001" },
+            { scheme: "exact", network: NETWORK, payTo: "0x000000000000000000000000000000000000b22b", price: "0.01" },
+          ],
+          description: "one chunk",
+        },
+        "GET /other": {
+          accepts: { scheme: "bajillion", network: NETWORK, payTo: seller.publicKey, price: "0.001", extra: { note: "kept" } },
+        },
+      },
+      server,
+    ),
+  );
+  app.get("/chunk", (c) => {
+    served++;
+    return c.json({ chunk: 1 });
+  });
+  app.get("/other", (c) => c.json({ other: 1 }));
+});
+
+afterAll(() => new Promise<void>((resolve) => facilitator.close(() => resolve())));
+
+const prefixOf = (url: string) => sha256(stringToHex(url));
+
+async function challenge(url: string): Promise<PaymentRequirements[]> {
+  const unpaid = await app.request(url);
+  expect(unpaid.status).toBe(402);
+  return decodePaymentRequiredHeader(unpaid.headers.get("payment-required") as string).accepts as PaymentRequirements[];
+}
+
+describe("ClearingServerScheme under the stock middleware", () => {
+  it("offers clearing beside exact, in the token's base units, bound to the resource", async () => {
+    const accepts = await challenge("http://seller.local/chunk");
+    expect(accepts).toHaveLength(2);
+    expect(accepts[0]).toEqual({
+      scheme: "bajillion",
+      network: NETWORK,
+      asset: USDZ.address,
+      amount: (10n ** 15n).toString(),
+      payTo: seller.publicKey,
+      maxTimeoutSeconds: 300,
+      extra: { settlement: SETTLEMENT, serviceUrl: SERVICE_URL, invoicePrefix: prefixOf("http://seller.local/chunk"), paymentFlow: "upfront" },
+    });
+    expect(accepts[1]).toMatchObject({ scheme: "exact", amount: (10n ** 16n).toString() });
+    const [other] = await challenge("http://seller.local/other");
+    expect(other?.extra?.invoicePrefix).toBe(prefixOf("http://seller.local/other"));
+    expect(other?.extra?.invoicePrefix).not.toBe(accepts[0]?.extra?.invoicePrefix);
+    // The route's own extra stays beside the deployment's.
+    expect(other?.extra).toMatchObject({ note: "kept", settlement: SETTLEMENT, serviceUrl: SERVICE_URL });
+  });
+
+  it("serves a payment the facilitator verifies against the offer it was made for", async () => {
+    // The payer's recipe: the Metal client, with the clearing payer registered on it.
+    const { client, fetchWithPayment } = createMetalPaymentClient({
+      account: privateKeyToAccount(`0x${"45".repeat(32)}`),
+      network: "devnet",
+      fetch: async (input, init) => app.request(input as string, init),
+    });
+    registerClearingClient(client, NETWORK, fakePayer);
+    checked.length = 0;
+    const paid = await fetchWithPayment("http://seller.local/chunk");
+    expect(paid.status).toBe(200);
+    expect(await paid.json()).toEqual({ chunk: 1 });
+    expect(decodePaymentResponseHeader(paid.headers.get("payment-response") as string)).toMatchObject({
+      success: true,
+      network: NETWORK,
+    });
+    const { requirements, payload } = checked.at(-1)!;
+    const prefix = prefixOf("http://seller.local/chunk");
+    expect(requirements.extra?.invoicePrefix).toBe(prefix);
+    expect((payload.accepted as PaymentRequirements).extra?.invoicePrefix).toBe(prefix);
+    expect(clearingPaymentOf(payload)?.invoice).toMatchObject({
+      recipient: seller.publicKey,
+      amount: (10n ** 15n).toString(),
+      settlement: SETTLEMENT,
+      network: NETWORK,
+      asset: USDZ.address,
+    });
+    expect(clearingPaymentOf(payload)?.invoice.id.startsWith(`${prefix}:`)).toBe(true);
+  });
+
+  it("refuses a receipt made for another resource even under this resource's offer", async () => {
+    // The payer presents a receipt whose invoice was issued for /other with
+    // /chunk's offer as what it accepted: the middleware matches, and the
+    // facilitator's invoice check refuses.
+    const { client } = createMetalPaymentClient({ account: privateKeyToAccount(`0x${"45".repeat(32)}`), network: "devnet" });
+    registerClearingClient(client, NETWORK, fakePayer);
+    const [other] = await challenge("http://seller.local/other");
+    const [chunk] = await challenge("http://seller.local/chunk");
+    const forOther = await client.createPaymentPayload({ x402Version: 2, resource: { url: "http://seller.local/other" }, accepts: [other!] });
+    checked.length = 0;
+    const refused = await app.request("http://seller.local/chunk", {
+      headers: { "payment-signature": encodePaymentSignatureHeader({ ...forOther, accepted: chunk! }) },
+    });
+    expect(refused.status).toBe(402);
+    expect(checked).toHaveLength(1);
+  });
+
+  it("refuses a payment made for another resource", async () => {
+    const { client } = createMetalPaymentClient({ account: privateKeyToAccount(`0x${"45".repeat(32)}`), network: "devnet" });
+    registerClearingClient(client, NETWORK, fakePayer);
+    const [offer] = await challenge("http://seller.local/other");
+    const payload = await client.createPaymentPayload({
+      x402Version: 2,
+      resource: { url: "http://seller.local/other" },
+      accepts: [offer!],
+    });
+    checked.length = 0;
+    const refused = await app.request("http://seller.local/chunk", {
+      headers: { "payment-signature": encodePaymentSignatureHeader(payload) },
+    });
+    expect(refused.status).toBe(402);
+    expect(checked).toHaveLength(0);
+  });
+
+  it("refuses a receipt presented again, before serving it", async () => {
+    const { client } = createMetalPaymentClient({ account: privateKeyToAccount(`0x${"45".repeat(32)}`), network: "devnet" });
+    registerClearingClient(client, NETWORK, fakePayer);
+    const [offer] = await challenge("http://seller.local/chunk");
+    const payload = await client.createPaymentPayload({ x402Version: 2, resource: { url: "http://seller.local/chunk" }, accepts: [offer!] });
+    const headers = { "payment-signature": encodePaymentSignatureHeader(payload) };
+    served = 0;
+    expect((await app.request("http://seller.local/chunk", { headers })).status).toBe(200);
+    expect((await app.request("http://seller.local/chunk", { headers })).status).toBe(402);
+    expect(served).toBe(1);
+  });
+
+  it("serves one of two overlapping presentations of a receipt", async () => {
+    const { client } = createMetalPaymentClient({ account: privateKeyToAccount(`0x${"45".repeat(32)}`), network: "devnet" });
+    registerClearingClient(client, NETWORK, fakePayer);
+    const [offer] = await challenge("http://seller.local/chunk");
+    const payload = await client.createPaymentPayload({ x402Version: 2, resource: { url: "http://seller.local/chunk" }, accepts: [offer!] });
+    const headers = { "payment-signature": encodePaymentSignatureHeader(payload) };
+    served = 0;
+    const statuses = await Promise.all([1, 2].map(async () => (await app.request("http://seller.local/chunk", { headers })).status));
+    expect(statuses.sort()).toEqual([200, 402]);
+    expect(served).toBe(1);
+  });
+
+  it("pays with clearing when offered clearing and exact, in either order, and with exact when it cannot pay the clearing offer", async () => {
+    const accepts = await challenge("http://seller.local/chunk");
+    const chosen = async (payer: typeof fakePayer, offers: PaymentRequirements[]) => {
+      const { client } = createMetalPaymentClient({ account: privateKeyToAccount(`0x${"45".repeat(32)}`), network: "devnet" });
+      registerClearingClient(client, NETWORK, payer);
+      return (await client.createPaymentPayload({ x402Version: 2, resource: { url: "http://seller.local/chunk" }, accepts: offers })).accepted.scheme;
+    };
+    expect(await chosen(fakePayer, accepts)).toBe("bajillion");
+    expect(await chosen(fakePayer, [...accepts].reverse())).toBe("bajillion");
+    expect(await chosen({ ...fakePayer, payable: () => false }, accepts)).toBe("exact");
+  });
+});
+
+describe("ClearingServerScheme on its own", () => {
+  const scheme = new ClearingServerScheme(NETWORK);
+
+  it("prices dollars in the token's base units and refuses a price of zero", async () => {
+    expect(await scheme.parsePrice("$0.001")).toEqual({ amount: (10n ** 15n).toString(), asset: USDZ.address });
+    expect(await scheme.parsePrice({ amount: "5000000000000", asset: USDZ.address })).toMatchObject({ amount: "5000000000000" });
+    await expect(scheme.parsePrice(0)).rejects.toThrow("not a price: 0");
+    await expect(scheme.parsePrice({ amount: "0", asset: USDZ.address })).rejects.toThrow("not a price: 0");
+    await expect(scheme.parsePrice({ amount: "-5", asset: USDZ.address })).rejects.toThrow("not a price: -5");
+    await expect(scheme.parsePrice({ amount: "abc", asset: USDZ.address })).rejects.toThrow("not a price: abc");
+  });
+
+  it("refuses a price above what a Clearing contract can hold, or a fraction of its unit", async () => {
+    // Clearing counts uint64 units of a millionth of *USDZ: at most about 1.8e13 *USDZ.
+    const unit = 10n ** 12n;
+    expect(await scheme.parsePrice("19")).toMatchObject({ amount: (19n * 10n ** 18n).toString() });
+    const most = (2n ** 64n - 1n) * unit;
+    expect(await scheme.parsePrice({ amount: most.toString(), asset: USDZ.address })).toMatchObject({ amount: most.toString() });
+    await expect(scheme.parsePrice({ amount: (most + unit).toString(), asset: USDZ.address })).rejects.toThrow(/at most/);
+    await expect(scheme.parsePrice({ amount: (unit + 1n).toString(), asset: USDZ.address })).rejects.toThrow(
+      /whole number of 0.000001 \*USDZ/,
+    );
+  });
+
+  it("offers the deployment its facilitator settles, and refuses a facilitator that settles none in its token", async () => {
+    const offer = { scheme: "bajillion", network: NETWORK, asset: USDZ.address, amount: "1", payTo: seller.publicKey, maxTimeoutSeconds: 60, extra: { note: "kept" } } as const;
+    expect((await scheme.enhancePaymentRequirements(offer, KIND)).extra).toEqual({ note: "kept", settlement: SETTLEMENT, serviceUrl: SERVICE_URL });
+    const { extra: _, ...bare } = KIND;
+    await expect(scheme.enhancePaymentRequirements(offer, bare)).rejects.toThrow(/settles no clearing deployment/);
+    await expect(
+      scheme.enhancePaymentRequirements(offer, { ...KIND, extra: { ...KIND.extra, asset: "0x000000000000000000000000000000000000c0de" } }),
+    ).rejects.toThrow(/settles no clearing deployment/);
+    await expect(
+      scheme.enhancePaymentRequirements(offer, { ...KIND, extra: { ...KIND.extra, settlement: "0x1234" } }),
+    ).rejects.toThrow(/settles no clearing deployment/);
+  });
+
+  it("binds and offers only on its own network", async () => {
+    const offer = {
+      scheme: "bajillion",
+      network: "eip155:63825",
+      asset: USDZ.address,
+      amount: "1",
+      payTo: seller.publicKey,
+      maxTimeoutSeconds: 60,
+      extra: {},
+    } as const;
+    await expect(scheme.enhancePaymentRequirements(offer, KIND)).rejects.toThrow(/on eip155:1337/);
+    const enriched = await scheme.enrichPaymentRequiredResponse({
+      requirements: [offer, { ...offer, network: NETWORK }, { ...offer, network: NETWORK, extra: { invoicePrefix: `0x${"ab".repeat(32)}` } }],
+      resourceInfo: { url: "http://seller.local/chunk" },
+    } as never);
+    expect(enriched[0]!.extra).toEqual({});
+    expect(enriched[1]!.extra).toEqual({ invoicePrefix: prefixOf("http://seller.local/chunk") });
+    expect(enriched[2]!.extra).toEqual({ invoicePrefix: `0x${"ab".repeat(32)}` });
+  });
+
+  it("refuses an @x402/core before 2.28, whose server settles after the handler runs", async () => {
+    vi.resetModules();
+    vi.doMock("@x402/core/server", async () => {
+      const { resolvePaymentFlow: _, ...older } = await vi.importActual<Record<string, unknown>>("@x402/core/server");
+      return older;
+    });
+    try {
+      const { ClearingServerScheme: Scheme } = await import("./clearing-server.js");
+      expect(() => new Scheme(NETWORK)).toThrow(/@x402\/core 2\.28/);
+    } finally {
+      vi.doUnmock("@x402/core/server");
+      vi.resetModules();
+    }
+  });
+
+  it("refuses a payTo that is not a clearing key, an offer in another asset or with a malformed invoicePrefix, and a network that is not one", async () => {
+    await expect(
+      scheme.enhancePaymentRequirements({
+        scheme: "bajillion",
+        network: NETWORK,
+        asset: USDZ.address,
+        amount: "1",
+        payTo: "0x000000000000000000000000000000000000b22b",
+        maxTimeoutSeconds: 60,
+        extra: {},
+      }, KIND),
+    ).rejects.toThrow(/clearing key/);
+    // The right length, but no P-256 point: x is past the field.
+    await expect(
+      scheme.enhancePaymentRequirements({
+        scheme: "bajillion",
+        network: NETWORK,
+        asset: USDZ.address,
+        amount: "1",
+        payTo: `0x02${"ff".repeat(32)}`,
+        maxTimeoutSeconds: 60,
+        extra: {},
+      }, KIND),
+    ).rejects.toThrow(/clearing key/);
+    const offer = { scheme: "bajillion", network: NETWORK, asset: USDZ.address, amount: "1", payTo: seller.publicKey, maxTimeoutSeconds: 60, extra: {} } as const;
+    await expect(scheme.enhancePaymentRequirements({ ...offer, asset: "0x000000000000000000000000000000000000c0de" }, KIND)).rejects.toThrow(/prices in/);
+    await expect(scheme.enhancePaymentRequirements({ ...offer, extra: { invoicePrefix: `0x${"AB".repeat(32)}` } }, KIND)).rejects.toThrow(/invoicePrefix/);
+    expect(() => new ClearingServerScheme("mainnet" as never)).toThrow(/network/);
+  });
+});
+
+function listen(server: Server): Promise<string> {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") return reject(new Error("no port"));
+      resolve(`http://127.0.0.1:${address.port}`);
+    });
+  });
+}

package/src/clearing-server.ts

@@ -0,0 +1,123 @@
+// The seller's side of native clearing for the official x402 server
+// packages: a scheme the stock middleware prices and offers like `exact`,
+// and settles before the handler runs. The offer names the Clearing
+// contract and the service the facilitator settles against, and binds the
+// invoice namespace to the resource the payer asked for, so the
+// facilitator's `verifyClearingPayment` finds every field it checks.
+import type {
+  AssetAmount,
+  PaymentRequirements,
+  Price,
+  SchemeNetworkServer,
+  SchemePaymentRequiredContext,
+  SupportedKind,
+} from "@x402/core/types";
+import * as x402Server from "@x402/core/server";
+import { formatUnits, isAddress, sha256, stringToHex, type Hex } from "viem";
+import { CLEARING_SCHEME, clearingAccount } from "./clearing-codec.js";
+import { CLEARING_MAX_AMOUNT } from "./clearing-custody.js";
+import { USDZ, type DollarToken } from "./networks.js";
+import { dollarBaseUnits } from "./server.js";
+
+/**
+ * The `bajillion` scheme for an `x402ResourceServer`, registered beside
+ * `exact` on `network`. A route's `payTo` is the seller's clearing key,
+ * `signer.publicKey` of a wallet from `openClearingWallet`, and its `price`
+ * is dollars in `token`. The offer names the Clearing deployment the
+ * facilitator lists for the network in `/supported`, so a seller takes only
+ * payments its facilitator settles.
+ *
+ *     server.register(network, new ClearingServerScheme(network));
+ */
+export class ClearingServerScheme implements SchemeNetworkServer {
+  readonly scheme = CLEARING_SCHEME;
+  // The money moved when the clearing service issued the receipt, so the
+  // facilitator records it before the handler runs: a receipt presented
+  // again, or twice at once, is served at most once.
+  readonly defaultAssetTransferMethod = "default";
+  readonly paymentFlows = {
+    default: { supported: ["upfront"], default: "upfront" },
+  } as const;
+
+  constructor(
+    private readonly network: `eip155:${number}`,
+    private readonly token: DollarToken = USDZ,
+  ) {
+    if (!/^eip155:\d+$/.test(network)) throw new Error(`not a network: ${network}`);
+    // A server without payment flows ignores `paymentFlows` and settles after the handler.
+    if (!("resolvePaymentFlow" in x402Server))
+      throw new Error("ClearingServerScheme needs @x402/core 2.28 or later, which settles a clearing payment before the handler runs");
+  }
+
+  async parsePrice(price: Price): Promise<AssetAmount> {
+    if (typeof price === "object" && price !== null && "amount" in price) {
+      let amount: bigint;
+      try {
+        amount = BigInt(price.amount);
+      } catch {
+        throw new Error(`not a price: ${price.amount}`);
+      }
+      if (amount <= 0n) throw new Error(`not a price: ${price.amount}`);
+      return { amount: this.payable(amount).toString(), asset: price.asset ?? this.token.address, extra: price.extra ?? {} };
+    }
+    return { amount: this.payable(BigInt(dollarBaseUnits(price, this.token))).toString(), asset: this.token.address };
+  }
+
+  /** Clearing counts whole clearing units, at most 2^64 - 1 of them in all.
+   * The unit is the one `Clearing.unit()` derives from the token's decimals
+   * at deploy: a millionth of the token, or its base unit at six decimals or
+   * fewer. */
+  private payable(amount: bigint): bigint {
+    const decimals = this.token.decimals;
+    const unit = decimals > 6 ? 10n ** BigInt(decimals - 6) : 1n;
+    if (amount % unit !== 0n)
+      throw new Error(`a clearing price is a whole number of ${formatUnits(unit, decimals)} ${this.token.symbol}`);
+    if (amount / unit > CLEARING_MAX_AMOUNT)
+      throw new Error(`a clearing price is at most ${formatUnits(CLEARING_MAX_AMOUNT * unit, decimals)} ${this.token.symbol}`);
+    return amount;
+  }
+
+  getAssetDecimals(): number {
+    return this.token.decimals;
+  }
+
+  async enhancePaymentRequirements(requirements: PaymentRequirements, supportedKind: SupportedKind): Promise<PaymentRequirements> {
+    if (requirements.network !== this.network)
+      throw new Error(`this clearing scheme is on ${this.network}; the route offers it on ${requirements.network}`);
+    try {
+      clearingAccount(requirements.payTo as Hex);
+    } catch {
+      throw new Error(
+        `a clearing offer's payTo is the seller's clearing key (signer.publicKey of a wallet from openClearingWallet); got ${requirements.payTo}`,
+      );
+    }
+    if (requirements.asset.toLowerCase() !== this.token.address.toLowerCase())
+      throw new Error(`this clearing scheme prices in ${this.token.address}; the route offers ${requirements.asset}`);
+    const prefix = requirements.extra?.invoicePrefix;
+    if (prefix !== undefined && (typeof prefix !== "string" || !/^0x[0-9a-f]{64}$/.test(prefix)))
+      throw new Error(`a route's invoicePrefix is 32 bytes of lowercase hex; got ${String(prefix)}`);
+    const { settlement, asset, serviceUrl } = supportedKind.extra ?? {};
+    if (
+      typeof settlement !== "string" ||
+      !isAddress(settlement) ||
+      typeof asset !== "string" ||
+      asset.toLowerCase() !== this.token.address.toLowerCase() ||
+      typeof serviceUrl !== "string" ||
+      !URL.canParse(serviceUrl)
+    )
+      throw new Error(`the facilitator settles no clearing deployment in ${this.token.symbol} on ${this.network}`);
+    return { ...requirements, extra: { ...requirements.extra, settlement, serviceUrl } };
+  }
+
+  /** Binds this network's offers' invoices to the resource asked for, at
+   * the challenge and again when a payment for it is verified. A route that
+   * sets its own `invoicePrefix` keeps it. */
+  async enrichPaymentRequiredResponse(ctx: SchemePaymentRequiredContext): Promise<PaymentRequirements[]> {
+    const invoicePrefix = sha256(stringToHex(ctx.resourceInfo.url));
+    return ctx.requirements.map((offer) =>
+      offer.scheme === CLEARING_SCHEME && offer.network === this.network && offer.extra?.invoicePrefix === undefined
+        ? { ...offer, extra: { ...offer.extra, invoicePrefix } }
+        : offer,
+    );
+  }
+}