@metalntwx/metal-pay 0.2.0 → 0.3.1

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),
+  };
+}