@metalntwx/metal-pay 0.2.0 → 0.3.1

package/src/node.ts

@@ -0,0 +1,96 @@
+import { DatabaseSync } from "node:sqlite";
+import { mkdir, open, readFile, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { createClearingSigner } from "./clearing-codec.js";
+import type {
+  ClearingClientState,
+  ClearingClientStore,
+} from "./clearing-client.js";
+import type { Hex } from "viem";
+
+/** A persistent P-256 account and receipt journal for a single server process. */
+export async function openClearingWallet(directory: string) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  // SQLite holds an OS lock for the wallet lifetime and releases it on crash.
+  const owner = new DatabaseSync(join(directory, "owner.sqlite"));
+  try {
+    owner.exec(
+      "PRAGMA locking_mode=EXCLUSIVE; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS owner (id INTEGER)",
+    );
+  } catch (error) {
+    owner.close();
+    throw new Error("clearing wallet is already in use", { cause: error });
+  }
+  try {
+    const keyPath = join(directory, "account.key");
+    let key: Hex;
+    try {
+      key = (await readFile(keyPath, "utf8")).trim() as Hex;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      for (;;) {
+        key = `0x${randomBytes(32).toString("hex")}`;
+        try {
+          createClearingSigner(key);
+          break;
+        } catch {
+          /* Rejection sample the scalar. */
+        }
+      }
+      const file = await open(keyPath, "wx", 0o600);
+      try {
+        await file.writeFile(key);
+        await file.sync();
+      } finally {
+        await file.close();
+      }
+    }
+    const parent = await open(directory, "r");
+    try {
+      await parent.sync();
+    } finally {
+      await parent.close();
+    }
+    const signer = createClearingSigner(key);
+    const statePath = join(directory, "payments.json");
+    const store: ClearingClientStore = {
+      async load() {
+        try {
+          return JSON.parse(
+            await readFile(statePath, "utf8"),
+          ) as ClearingClientState;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+          throw error;
+        }
+      },
+      async save(state) {
+        const file = await open(statePath + ".next", "w", 0o600);
+        try {
+          await file.writeFile(JSON.stringify(state));
+          await file.sync();
+        } finally {
+          await file.close();
+        }
+        await rename(statePath + ".next", statePath);
+        const parent = await open(directory, "r");
+        try {
+          await parent.sync();
+        } finally {
+          await parent.close();
+        }
+      },
+    };
+    return {
+      signer,
+      store,
+      async close() {
+        owner.close();
+      },
+    };
+  } catch (error) {
+    owner.close();
+    throw error;
+  }
+}

package/src/server.test.ts

@@ -0,0 +1,223 @@
+import { createServer, type Server } from "node:http";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { Hono } from "hono";
+import { paymentMiddleware } from "@x402/hono";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
+import {
+  decodePaymentRequiredHeader,
+  decodePaymentResponseHeader,
+  encodePaymentSignatureHeader,
+} from "@x402/core/http";
+import type { PaymentPayload, PaymentRequirements } from "@x402/core/types";
+import { USDZ } from "./networks.js";
+import { metalUsd, registerMetalScheme } from "./server.js";
+
+const PAY_TO = "0x000000000000000000000000000000000000b22b";
+const TX = `0x${"ab".repeat(32)}`;
+
+const verified: PaymentPayload[] = [];
+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 & { payload: { authorization?: { from?: string } } };
+    };
+    const payer = body.paymentPayload?.payload.authorization?.from;
+    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: "eip155:1337" }],
+        extensions: [],
+        signers: { "eip155:*": ["0x00000000000000000000000000000000000000fa"] },
+      });
+    }
+    if (req.url === "/verify") {
+      if (body.paymentPayload) verified.push(body.paymentPayload);
+      if (payer?.endsWith("dead")) return reply(200, { isValid: false, invalidReason: "insufficient_funds", payer });
+      return reply(200, { isValid: true, payer });
+    }
+    if (req.url === "/settle") {
+      if (payer?.endsWith("f00d")) {
+        return reply(200, {
+          success: false,
+          errorReason: "transaction_failed",
+          errorMessage: "transferWithAuthorization reverted",
+          transaction: TX,
+          network: "eip155:1337",
+          payer,
+        });
+      }
+      return reply(200, { success: true, transaction: TX, network: "eip155:1337", payer });
+    }
+    reply(404, {});
+  });
+});
+
+let app: Hono;
+
+beforeAll(async () => {
+  const facilitatorUrl = await listen(facilitator);
+  const server = registerMetalScheme(
+    new x402ResourceServer(new HTTPFacilitatorClient({ url: facilitatorUrl })),
+    { networks: ["devnet"] },
+  );
+  app = new Hono();
+  app.use(
+    paymentMiddleware(
+      {
+        "GET /quote": {
+          accepts: { scheme: "exact", network: "eip155:1337", payTo: PAY_TO, price: "0.01", maxTimeoutSeconds: 60 },
+          description: "a quote",
+        },
+      },
+      server,
+    ),
+  );
+  app.get("/quote", (c) => c.json({ quote: "hono" }));
+  app.get("/free", (c) => c.json({ free: true }));
+});
+
+afterAll(() => new Promise<void>((resolve) => facilitator.close(() => resolve())));
+
+const fetchQuote = async (headers?: Record<string, string>) => app.request("http://seller.local/quote", { headers });
+
+function paymentFor(requirements: PaymentRequirements, from: string): PaymentPayload {
+  return {
+    x402Version: 2,
+    accepted: requirements,
+    payload: {
+      signature: `0x${"11".repeat(65)}`,
+      authorization: {
+        from,
+        to: requirements.payTo,
+        value: requirements.amount,
+        validAfter: "0",
+        validBefore: "9999999999",
+        nonce: `0x${"22".repeat(32)}`,
+      },
+    },
+  };
+}
+
+async function challenge(): Promise<PaymentRequirements> {
+  const unpaid = await fetchQuote();
+  expect(unpaid.status).toBe(402);
+  const required = decodePaymentRequiredHeader(unpaid.headers.get("payment-required") as string);
+  expect(required.accepts).toHaveLength(1);
+  expect(required.accepts[0]).toMatchObject({
+    scheme: "exact",
+    network: "eip155:1337",
+    asset: USDZ.address,
+    amount: "10000000000000000",
+    payTo: PAY_TO,
+    maxTimeoutSeconds: 60,
+    extra: { name: USDZ.name, version: USDZ.version, primaryType: "TransferWithAuthorization" },
+  });
+  return required.accepts[0] as PaymentRequirements;
+}
+
+describe("registerMetalScheme under @x402/hono", () => {
+  it("leaves free routes alone", async () => {
+    const res = await app.request("http://seller.local/free");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ free: true });
+  });
+
+  it("challenges in *USDZ, then serves and settles a verified payment", async () => {
+    const offer = await challenge();
+    const paid = await fetchQuote({
+      "payment-signature": encodePaymentSignatureHeader(
+        paymentFor(offer, "0x000000000000000000000000000000000000beef"),
+      ),
+    });
+    expect(paid.status).toBe(200);
+    expect(await paid.json()).toEqual({ quote: "hono" });
+    const settlement = decodePaymentResponseHeader(paid.headers.get("payment-response") as string);
+    expect(settlement).toMatchObject({ success: true, transaction: TX, network: "eip155:1337" });
+    expect(verified.at(-1)?.payload).toMatchObject({
+      authorization: { from: "0x000000000000000000000000000000000000beef", to: PAY_TO },
+    });
+  });
+
+  it("returns the facilitator's reason as a 402", async () => {
+    const offer = await challenge();
+    const refused = await fetchQuote({
+      "payment-signature": encodePaymentSignatureHeader(paymentFor(offer, "0x000000000000000000000000000000000000dead")),
+    });
+    expect(refused.status).toBe(402);
+    expect(decodePaymentRequiredHeader(refused.headers.get("payment-required") as string).error).toBe(
+      "insufficient_funds",
+    );
+  });
+
+  it("returns a settle refusal as a 402 whose payment-response header carries the reason", async () => {
+    const offer = await challenge();
+    const refused = await fetchQuote({
+      "payment-signature": encodePaymentSignatureHeader(paymentFor(offer, "0x000000000000000000000000000000000000f00d")),
+    });
+    expect(refused.status).toBe(402);
+    expect(refused.headers.get("payment-required")).toBeNull();
+    expect(await refused.json()).toEqual({});
+    expect(decodePaymentResponseHeader(refused.headers.get("payment-response") as string)).toMatchObject({
+      success: false,
+      errorReason: "transaction_failed",
+      errorMessage: "transferWithAuthorization reverted",
+      transaction: TX,
+      network: "eip155:1337",
+    });
+  });
+
+  it("refuses an unknown network name", () => {
+    expect(() => registerMetalScheme(new x402ResourceServer(), { networks: ["mainnet" as never] })).toThrow(
+      /unknown Metal network/,
+    );
+  });
+});
+
+describe("metalUsd on the stock exact scheme", () => {
+  const scheme = new ExactEvmScheme().registerMoneyParser(metalUsd("eip155:1337"));
+
+  it("prices dollars on its network in *USDZ under USDZ's EIP-712 domain, as a transfer authorization", async () => {
+    expect(await scheme.parsePrice("$0.001", "eip155:1337")).toEqual({
+      amount: (10n ** 15n).toString(),
+      asset: USDZ.address,
+      extra: { name: USDZ.name, version: USDZ.version, primaryType: "TransferWithAuthorization" },
+    });
+    expect(await scheme.parsePrice(1.5, "eip155:1337")).toMatchObject({ amount: (15n * 10n ** 17n).toString() });
+    expect(await scheme.parsePrice(1e-7, "eip155:1337")).toMatchObject({ amount: "100000000000" });
+  });
+
+  it("leaves every other network to the scheme's defaults", async () => {
+    expect(await scheme.parsePrice("$0.01", "eip155:8453")).toMatchObject({
+      amount: "10000",
+      asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    });
+  });
+
+  it("prices in another dollar token with its own decimals", async () => {
+    const usdc = { ...USDZ, address: "0x2222222222222222222222222222222222222222", symbol: "USDC", decimals: 6 } as const;
+    const six = new ExactEvmScheme().registerMoneyParser(metalUsd("eip155:1337", usdc));
+    expect(await six.parsePrice("$0.01", "eip155:1337")).toMatchObject({ amount: "10000", asset: usdc.address });
+  });
+
+  it("refuses a price the token cannot carry exactly, and a price of zero", async () => {
+    await expect(scheme.parsePrice(1e-19, "eip155:1337")).rejects.toThrow(/decimals/);
+    await expect(scheme.parsePrice(0, "eip155:1337")).rejects.toThrow("not a price: 0");
+  });
+});
+
+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/server.ts

@@ -0,0 +1,77 @@
+import type { x402ResourceServer } from "@x402/core/server";
+import type { AssetAmount, MoneyParser, Network } from "@x402/core/types";
+import { numberToDecimalString } from "@x402/core/utils";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import {
+  METAL_NETWORKS,
+  USDZ,
+  baseUnits,
+  resolveNetwork,
+  type DollarToken,
+  type MetalNetwork,
+  type MetalNetworkName,
+} from "./networks.js";
+
+/**
+ * A dollar price (`"$0.01"`, `"0.01"`, `0.01`) in base units of `token`.
+ * Refuses a price the token cannot carry exactly, and one of zero.
+ */
+export function dollarBaseUnits(price: string | number, token: DollarToken): string {
+  const units = baseUnits(typeof price === "number" ? numberToDecimalString(price) : price, token);
+  if (BigInt(units) === 0n) throw new Error(`not a price: ${String(price)}`);
+  return units;
+}
+
+/**
+ * A money parser that prices dollar amounts on `network` in `token`, and
+ * leaves every other network to the scheme's own defaults. The stock seller
+ * scheme looks dollar prices up in a table of networks it ships, and Metal is
+ * not in it; this is the hook the scheme provides for that:
+ *
+ *     new ExactEvmScheme().registerMoneyParser(metalUsd("eip155:<chain id>"))
+ */
+export function metalUsd(network: Network, token: DollarToken = USDZ): MoneyParser {
+  return async (amount, on): Promise<AssetAmount | null> =>
+    on === network
+      ? {
+          amount: dollarBaseUnits(amount, token),
+          asset: token.address,
+          // `primaryType` names the ERC-3009 message the payer signs, so a
+          // client need not probe the token for which one it supports.
+          extra: { name: token.name, version: token.version, primaryType: "TransferWithAuthorization" },
+        }
+      : null;
+}
+
+/**
+ * The `createAuthHeaders` option of the stock `HTTPFacilitatorClient`, for
+ * the token Metal's facilitator issued to this seller.
+ */
+export function sellerToken(token: string) {
+  return async () => {
+    const headers = { Authorization: `Bearer ${token}` };
+    return { verify: headers, settle: headers };
+  };
+}
+
+export interface RegisterMetalSchemeConfig {
+  /** Which Metal networks to price offers on; both by default. */
+  networks?: readonly (MetalNetworkName | MetalNetwork)[];
+}
+
+/**
+ * Register the stock `exact` scheme on Metal's devnet and testnet (or the
+ * named ones) with a resource server, pricing dollar amounts in `*USDZ`, so
+ * the official middleware issues Metal offers and settles through the
+ * server's facilitator client.
+ */
+export function registerMetalScheme(
+  server: x402ResourceServer,
+  { networks }: RegisterMetalSchemeConfig = {},
+): x402ResourceServer {
+  for (const entry of networks ?? Object.values(METAL_NETWORKS)) {
+    const { network } = resolveNetwork(entry);
+    server.register(network, new ExactEvmScheme().registerMoneyParser(metalUsd(network)));
+  }
+  return server;
+}

package/dist/clearing.d.ts

@@ -1,204 +0,0 @@
-import { type Address, type Hex, type TypedDataDomain } from "viem";
-/** A Debit as it travels in a payment: uint values as decimal strings. */
-export interface DebitWire {
-    payer: Address;
-    recipient: Address;
-    epoch: string;
-    index: string;
-    cumulativeDebit: string;
-    ref: Hex;
-}
-/** The x402 scheme name of Metal's clearing lane. */
-export declare const CLEARING_DEBIT = "clearing-debit";
-export declare const CLEARING_DOMAIN_NAME = "MetalClearing";
-export declare const DEBIT_TYPES: {
-    readonly Debit: readonly [{
-        readonly name: "payer";
-        readonly type: "address";
-    }, {
-        readonly name: "recipient";
-        readonly type: "address";
-    }, {
-        readonly name: "epoch";
-        readonly type: "uint64";
-    }, {
-        readonly name: "index";
-        readonly type: "uint64";
-    }, {
-        readonly name: "cumulativeDebit";
-        readonly type: "uint256";
-    }, {
-        readonly name: "ref";
-        readonly type: "bytes32";
-    }];
-};
-export declare const RECEIPT_TYPES: {
-    readonly Receipt: readonly [{
-        readonly name: "recipient";
-        readonly type: "address";
-    }, {
-        readonly name: "epoch";
-        readonly type: "uint64";
-    }, {
-        readonly name: "shard";
-        readonly type: "uint64";
-    }, {
-        readonly name: "index";
-        readonly type: "uint64";
-    }, {
-        readonly name: "cumulativeCredit";
-        readonly type: "uint256";
-    }, {
-        readonly name: "prevReceiptDigest";
-        readonly type: "bytes32";
-    }, {
-        readonly name: "debitDigest";
-        readonly type: "bytes32";
-    }];
-};
-/** The payer's cumulative outgoing authorization for one epoch. */
-export interface Debit {
-    payer: Address;
-    recipient: Address;
-    epoch: bigint;
-    index: bigint;
-    cumulativeDebit: bigint;
-    ref: Hex;
-}
-/** The operator's acknowledgment crediting a recipient's receive shard. */
-export interface Receipt {
-    recipient: Address;
-    epoch: bigint;
-    shard: bigint;
-    index: bigint;
-    cumulativeCredit: bigint;
-    prevReceiptDigest: Hex;
-    debitDigest: Hex;
-}
-export declare function clearingDomain(chainId: number, contract: Address): TypedDataDomain;
-export declare function debitFromWire(wire: DebitWire): Debit;
-export declare function debitTypedData(domain: TypedDataDomain, debit: Debit): {
-    readonly domain: TypedDataDomain;
-    readonly types: {
-        readonly Debit: readonly [{
-            readonly name: "payer";
-            readonly type: "address";
-        }, {
-            readonly name: "recipient";
-            readonly type: "address";
-        }, {
-            readonly name: "epoch";
-            readonly type: "uint64";
-        }, {
-            readonly name: "index";
-            readonly type: "uint64";
-        }, {
-            readonly name: "cumulativeDebit";
-            readonly type: "uint256";
-        }, {
-            readonly name: "ref";
-            readonly type: "bytes32";
-        }];
-    };
-    readonly primaryType: "Debit";
-    readonly message: Debit;
-};
-export declare function receiptTypedData(domain: TypedDataDomain, receipt: Receipt): {
-    readonly domain: TypedDataDomain;
-    readonly types: {
-        readonly Receipt: readonly [{
-            readonly name: "recipient";
-            readonly type: "address";
-        }, {
-            readonly name: "epoch";
-            readonly type: "uint64";
-        }, {
-            readonly name: "shard";
-            readonly type: "uint64";
-        }, {
-            readonly name: "index";
-            readonly type: "uint64";
-        }, {
-            readonly name: "cumulativeCredit";
-            readonly type: "uint256";
-        }, {
-            readonly name: "prevReceiptDigest";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "debitDigest";
-            readonly type: "bytes32";
-        }];
-    };
-    readonly primaryType: "Receipt";
-    readonly message: Receipt;
-};
-export declare function debitDigest(domain: TypedDataDomain, debit: Debit): Hex;
-export declare function receiptDigest(domain: TypedDataDomain, receipt: Receipt): Hex;
-/** An account's request to take funds out of clearing custody. Only the
- * account can sign it, and it names where the funds go. */
-export declare const EXIT_TYPES: {
-    readonly Exit: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }, {
-        readonly name: "destination";
-        readonly type: "address";
-    }, {
-        readonly name: "amount";
-        readonly type: "uint256";
-    }, {
-        readonly name: "deadline";
-        readonly type: "uint64";
-    }];
-};
-export interface Exit {
-    account: Address;
-    destination: Address;
-    amount: bigint;
-    deadline: bigint;
-}
-export declare function exitTypedData(domain: TypedDataDomain, exit: Exit): {
-    readonly domain: TypedDataDomain;
-    readonly types: {
-        readonly Exit: readonly [{
-            readonly name: "account";
-            readonly type: "address";
-        }, {
-            readonly name: "destination";
-            readonly type: "address";
-        }, {
-            readonly name: "amount";
-            readonly type: "uint256";
-        }, {
-            readonly name: "deadline";
-            readonly type: "uint64";
-        }];
-    };
-    readonly primaryType: "Exit";
-    readonly message: Exit;
-};
-export declare function exitDigest(domain: TypedDataDomain, exit: Exit): Hex;
-export declare function recoverExitSigner(domain: TypedDataDomain, exit: Exit, signature: Hex): Promise<Address | null>;
-/** An account asking the facilitator about itself: where its next Debit
- * starts, or what it can withdraw. Signed under the clearing domain so that
- * only the account can read its own position; the deadline keeps a request
- * someone else has seen from being used for long. Never sent on chain. */
-export declare const ACCOUNT_REQUEST_TYPES: {
-    readonly AccountRequest: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }, {
-        readonly name: "deadline";
-        readonly type: "uint64";
-    }];
-};
-export declare function recoverAccountRequestSigner(domain: TypedDataDomain, request: {
-    account: Address;
-    deadline: bigint;
-}, signature: Hex): Promise<Address | null>;
-export declare function recoverDebitSigner(domain: TypedDataDomain, debit: Debit, signature: Hex): Promise<Address | null>;
-/** Receive shards spread a hot recipient over parallel credit lanes. The
- * shard is a pure function of `ref`, so a replayed debit lands on the same
- * one. Same formula as the café's. */
-export declare const REVENUE_SHARDS = 8n;
-export declare function shardFor(ref: Hex): bigint;