@metalntwx/metal-pay 0.2.0 → 0.3.0

package/src/clearing-client.ts

@@ -0,0 +1,303 @@
+import { createPublicClient, http, 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";
+
+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;
+  entries: ClearingEntry[];
+  sequence: string;
+  pending?: ClearingPayment | 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;
+}
+
+class PaymentRejected extends Error {}
+
+export function createClearingClient(config: ClearingClientConfig) {
+  const fetcher = config.fetch ?? globalThis.fetch;
+  const chain = createPublicClient({ transport: http(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;
+      if (result?.rejected === true)
+        throw new PaymentRejected(
+          "clearing payment rejected before acknowledgment",
+        );
+      throw new Error(`clearing service returned ${response.status}`);
+    }
+    return (await response.json()) as T;
+  }
+  /** Why this wallet does not pay `invoice`, or undefined when it does. */
+  function refusal(invoice: ClearingInvoice) {
+    if (
+      invoice.network !== config.network ||
+      invoice.asset.toLowerCase() !== config.asset.toLowerCase() ||
+      invoice.settlement.toLowerCase() !== config.settlement.toLowerCase()
+    )
+      return "clearing invoice deployment mismatch";
+    const amount = BigInt(invoice.amount);
+    if (amount <= 0n || amount > config.maxAmount)
+      return "clearing payment exceeds spending limit";
+  }
+  async function pay(invoice: ClearingInvoice) {
+    if (broken)
+      throw new Error("clearing wallet persistence failed; reopen the wallet");
+    const refused = refusal(invoice);
+    if (refused) throw new Error(refused);
+    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)
+    )
+      throw new Error(
+        "an earlier clearing payment has an unknown outcome; retry that invoice first",
+      );
+    if (!state.pending) {
+      const context = await request<{
+        reference: string;
+        network: string;
+        settlement: Hex;
+        asset: Hex;
+        operator: Hex;
+        epoch: string;
+        anchor: Hex;
+      }>("/context");
+      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, chainId, admitted, block, unit] =
+        await 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.getChainId(),
+          chain.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "admittedCount",
+          }),
+          chain.getBlock(),
+          chain.readContract({
+            address: config.settlement,
+            abi: clearingAbi,
+            functionName: "unit",
+          }),
+        ]);
+      if (
+        !registered ||
+        fault ||
+        admitted !== epoch ||
+        block.timestamp >= onchain.admissionDeadline ||
+        `eip155:${chainId}` !== config.network ||
+        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();
+      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),
+          ),
+        },
+      };
+      await save(state);
+    }
+    const pending = state.pending!;
+    let result: ClearingPaid;
+    try {
+      result = await request<ClearingPaid>("/payments", pending);
+    } catch (error) {
+      if (error instanceof PaymentRejected)
+        await save({ ...state, pending: undefined });
+      throw error;
+    }
+    const operator = await chain.readContract({
+      address: config.settlement,
+      abi: clearingAbi,
+      functionName: "operatorKey",
+    });
+    if (
+      result.receipt.body !== pending.body ||
+      result.receipt.payerSignature !== pending.payerSignature ||
+      invoiceMessage(result.invoice, pending.body) !==
+        invoiceMessage(invoice, pending.body) ||
+      !verifyReceipt(result.receipt, operator)
+    )
+      throw new Error(
+        "invalid clearing acknowledgment; retain pending payment",
+      );
+    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;
+    },
+    payable(invoice: ClearingInvoice) {
+      return refusal(invoice) === undefined;
+    },
+    pay(invoice: ClearingInvoice) {
+      const result = tail.then(() => pay(invoice));
+      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();
+  });
+});

package/src/clearing-codec.ts

@@ -0,0 +1,251 @@
+import { p256 } from "@noble/curves/p256";
+import {
+  concatHex,
+  hexToBytes,
+  sha256,
+  stringToHex,
+  toHex,
+  type Hex,
+} from "viem";
+
+export const CLEARING_REFERENCE = "3134e902ccf619987e2731a0c1e63114bcc0b060";
+export const CLEARING_SCHEME = "bajillion";
+const U64_MAX = (1n << 64n) - 1n;
+
+export interface OutgoingEntry {
+  recipient: Hex;
+  cumulative: bigint;
+  count: bigint;
+}
+export interface ClearingSend {
+  anchor: Hex;
+  epoch: bigint;
+  payer: Hex;
+  sequence: bigint;
+  debit: bigint;
+  vector: Hex;
+}
+export interface ClearingReceipt {
+  body: Hex;
+  payerSignature: Hex;
+  operatorSignature: Hex;
+}
+
+/** The clearing units `amount` token base units make, where `unit` is the
+ * deployment's `Clearing.unit()`: Clearing counts whole units, so a fraction
+ * of one is refused rather than rounded. */
+export function clearingUnits(amount: bigint, unit: bigint): bigint {
+  if (unit <= 0n || amount % unit !== 0n)
+    throw new Error(
+      `${amount} base units is not a whole number of clearing units of ${unit}`,
+    );
+  return amount / unit;
+}
+export function clearingUint64(value: bigint): Hex {
+  if (value < 0n || value > U64_MAX)
+    throw new Error("clearing amount exceeds uint64");
+  return toHex(value, { size: 8 });
+}
+function fixed(value: Hex, length: number): Hex {
+  if (!new RegExp(`^0x[0-9a-fA-F]{${length * 2}}$`).test(value))
+    throw new Error("invalid clearing wire length");
+  return value.toLowerCase() as Hex;
+}
+export function clearingAccount(value: Hex): Hex {
+  fixed(value, 33);
+  const point = p256.ProjectivePoint.fromHex(hexToBytes(value));
+  point.assertValidity();
+  // The canonical compressed encoding of the parsed point, not the wire
+  // string: what reaches a receipt URL or a signature check is what the
+  // curve produced, so no byte of the input passes through untouched.
+  return toHex(point.toRawBytes(true));
+}
+function hash(...values: Hex[]): Hex {
+  return sha256(concatHex(values));
+}
+const domain = (name: string) => stringToHex(`_COMMONWARE_CLEARING_${name}`);
+
+/** The exact typed BMT root used by commonware-clearing at CLEARING_REFERENCE. */
+export function outgoingRoot(entries: readonly OutgoingEntry[]): Hex {
+  if (entries.length > 1 << 24) throw new Error("too many clearing entries");
+  const length = toHex(entries.length, { size: 4 });
+  let previous = "";
+  let total = 0n;
+  let count = 0n;
+  let level = entries.map((entry, position) => {
+    const recipient = clearingAccount(entry.recipient);
+    if (
+      recipient <= previous ||
+      entry.count <= 0n ||
+      entry.cumulative < entry.count
+    )
+      throw new Error("noncanonical clearing vector");
+    previous = recipient;
+    total += entry.cumulative;
+    count += entry.count;
+    clearingUint64(total);
+    clearingUint64(count);
+    const encoded = concatHex([
+      recipient,
+      clearingUint64(entry.cumulative),
+      clearingUint64(entry.count),
+    ]);
+    const index = toHex(position, { size: 4 });
+    const leaf = hash(
+      domain("OUT_ENTRY_LEAF"),
+      length,
+      index,
+      clearingUint64(49n),
+      encoded,
+    );
+    return hash(index, leaf);
+  });
+  if (level.length === 0) level = [hash("0x")];
+  while (level.length > 1) {
+    const next: Hex[] = [];
+    for (let i = 0; i < level.length; i += 2)
+      next.push(hash(level[i]!, level[i + 1] ?? level[i]!));
+    level = next;
+  }
+  return hash(domain("OUT_ENTRY_ROOT"), length, hash(length, level[0]!));
+}
+
+export function encodeSend(body: ClearingSend): Hex {
+  return concatHex([
+    fixed(body.anchor, 32),
+    clearingUint64(body.epoch),
+    clearingAccount(body.payer),
+    clearingUint64(body.sequence),
+    clearingUint64(body.debit),
+    fixed(body.vector, 32),
+  ]);
+}
+export function decodeSend(encoded: Hex): ClearingSend {
+  fixed(encoded, 121);
+  const part = (start: number, length: number) =>
+    `0x${encoded.slice(2 + start * 2, 2 + (start + length) * 2)}` as Hex;
+  return {
+    anchor: part(0, 32),
+    epoch: BigInt(part(32, 8)),
+    payer: clearingAccount(part(40, 33)),
+    sequence: BigInt(part(73, 8)),
+    debit: BigInt(part(81, 8)),
+    vector: part(89, 32),
+  };
+}
+export function clearingSignatureDigest(namespace: string, message: Hex): Hex {
+  const bytes = stringToHex(namespace);
+  const length = (bytes.length - 2) / 2;
+  if (length >= 128) throw new Error("unsupported signature namespace length");
+  return hash(toHex(length, { size: 1 }), bytes, message);
+}
+export function verifyClearingSignature(
+  key: Hex,
+  namespace: string,
+  message: Hex,
+  signature: Hex,
+): boolean {
+  try {
+    clearingAccount(key);
+    fixed(signature, 64);
+    return p256.verify(
+      hexToBytes(signature),
+      hexToBytes(clearingSignatureDigest(namespace, message)),
+      hexToBytes(key),
+      { lowS: true, prehash: false },
+    );
+  } catch {
+    return false;
+  }
+}
+export function verifyReceipt(
+  receipt: ClearingReceipt,
+  operator: Hex,
+): boolean {
+  try {
+    const body = decodeSend(receipt.body);
+    return (
+      verifyClearingSignature(
+        body.payer,
+        "_COMMONWARE_CLEARING_VECTOR_SEND",
+        receipt.body,
+        receipt.payerSignature,
+      ) &&
+      verifyClearingSignature(
+        operator,
+        "_COMMONWARE_CLEARING_VECTOR_ACK",
+        receipt.body,
+        receipt.operatorSignature,
+      )
+    );
+  } catch {
+    return false;
+  }
+}
+
+export interface ClearingInvoice {
+  id: string;
+  network: string;
+  settlement: Hex;
+  asset: Hex;
+  recipient: Hex;
+  amount: string;
+}
+
+/** The HTTP invoice is separately signed; it does not alter Bajillion's wire format. */
+export function invoiceMessage(invoice: ClearingInvoice, body: Hex): Hex {
+  if (!/^[a-zA-Z0-9:_./-]{1,256}$/.test(invoice.id))
+    throw new Error("invalid clearing invoice id");
+  if (!/^eip155:[1-9][0-9]*$/.test(invoice.network))
+    throw new Error("invalid clearing network");
+  return stringToHex(
+    JSON.stringify([
+      invoice.id,
+      invoice.network,
+      fixed(invoice.settlement, 20),
+      fixed(invoice.asset, 20),
+      clearingAccount(invoice.recipient),
+      // Invoices count ERC-20 base units; only clearing balances use uint64.
+      toHex(BigInt(invoice.amount), { size: 32 }),
+      sha256(body),
+    ]),
+  );
+}
+
+export function createClearingSigner(privateKey: Hex) {
+  const key = hexToBytes(fixed(privateKey, 32));
+  const publicKey = toHex(p256.getPublicKey(key, true));
+  return {
+    publicKey,
+    sign(namespace: string, message: Hex): Hex {
+      return toHex(
+        p256
+          .sign(hexToBytes(clearingSignatureDigest(namespace, message)), key, {
+            lowS: true,
+            prehash: false,
+          })
+          .toCompactRawBytes(),
+      );
+    },
+  };
+}
+
+export function decodeWithdrawal(encoded: Hex) {
+  const raw = hexToBytes(encoded);
+  if ((raw.length !== 199 && raw.length !== 191) || raw[97] !== 20)
+    throw new Error("invalid native withdrawal");
+  const part = (offset: number, length: number) =>
+    toHex(raw.slice(offset, offset + length));
+  const close = raw[118] === 2;
+  if ((!close && raw[118] !== 1) || raw.length !== (close ? 191 : 199))
+    throw new Error("invalid withdrawal action");
+  return {
+    account: clearingAccount(part(0, 33)),
+    deployment: part(33, 32),
+    state: part(65, 32),
+    destination: part(98, 20),
+    amount: close ? 0n : BigInt(part(119, 8)),
+    deadline: BigInt(part(close ? 119 : 127, 8)),
+    signature: part(close ? 127 : 135, 64),
+  };
+}