@phala/pay 0.1.1 → 0.2.0

package/src/server/addresses.ts

@@ -0,0 +1,223 @@
+import {
+  encodeAbiParameters,
+  getAddress,
+  getContractAddress,
+  keccak256,
+  concat,
+  type Address,
+  type Hex,
+} from "viem";
+
+/**
+ * The forwarder `factory` deploys for `treasury` and `salt`: OpenZeppelin 5.x
+ * `Clones.predictDeterministicAddressWithImmutableArgs` with `abi.encodePacked(treasury)`, so the
+ * address commits to the factory, the implementation, the treasury, and the salt.
+ */
+export function forwarderAddress(
+  factory: string,
+  implementation: string,
+  treasury: string,
+  salt: Hex,
+): Address {
+  const initCode = concat([
+    "0x61",
+    "0x0041", // runtime length: the 45-byte proxy and the 20 treasury bytes
+    "0x3d81600a3d39f3",
+    "0x363d3d373d3d3d363d73",
+    getAddress(implementation),
+    "0x5af43d82803e903d91602b57fd5bf3",
+    getAddress(treasury),
+  ]);
+  return getContractAddress({
+    opcode: "CREATE2",
+    from: getAddress(factory),
+    salt,
+    bytecodeHash: keccak256(initCode),
+  });
+}
+
+/** `keccak256(abi.encode(account, client_reference_id, "quote", quote_id))`: a quote's salt. */
+export function quoteSalt(account: string, clientReferenceId: string, quoteId: string): Hex {
+  return keccak256(
+    encodeAbiParameters(
+      [{ type: "string" }, { type: "string" }, { type: "string" }, { type: "string" }],
+      [account, clientReferenceId, "quote", quoteId],
+    ),
+  );
+}
+
+/**
+ * `keccak256(abi.encode(account, livemode, client_reference_id, "deposit_address", version))`:
+ * a deposit address's salt, the same on every chain.
+ */
+export function depositAddressSalt(
+  account: string,
+  livemode: boolean,
+  clientReferenceId: string,
+  version: number | bigint,
+): Hex {
+  return keccak256(
+    encodeAbiParameters(
+      [
+        { type: "string" },
+        { type: "bool" },
+        { type: "string" },
+        { type: "string" },
+        { type: "uint256" },
+      ],
+      [account, livemode, clientReferenceId, "deposit_address", BigInt(version)],
+    ),
+  );
+}
+
+export interface Forwarder {
+  factory: string;
+  implementation: string;
+}
+
+/** The address of a quote over `treasury`, which you pin yourself (see `verifyQuoteAddress`). */
+export function quoteAddress(
+  forwarder: Forwarder,
+  quote: { client_reference_id: string; id: string },
+  treasury: string,
+  account: string,
+): Address {
+  return forwarderAddress(
+    forwarder.factory,
+    forwarder.implementation,
+    treasury,
+    quoteSalt(account, quote.client_reference_id, quote.id),
+  );
+}
+
+/** A deposit address on the network whose treasury is `treasury`, which you pin yourself. */
+export function depositAddress(
+  forwarder: Forwarder,
+  address: { livemode: boolean; client_reference_id: string; version: number },
+  treasury: string,
+  account: string,
+): Address {
+  return forwarderAddress(
+    forwarder.factory,
+    forwarder.implementation,
+    treasury,
+    depositAddressSalt(account, address.livemode, address.client_reference_id, address.version),
+  );
+}
+
+/** An address the service returned is not the one your pins derive: show nothing to pay. */
+export class AddressMismatchError extends Error {
+  override readonly name = "AddressMismatchError";
+}
+
+/**
+ * What every address is recomputed from, configured on your server and never read from the
+ * service: your account id (`acct_…`), the forwarder `factory` and `implementation` of the
+ * attested deployment, and `treasuries`, your own treasury per chain id as you proved it. A
+ * compromised service could return another treasury with the address that really derives from
+ * it, so the response's `treasury` is never trusted.
+ *
+ * Live mode requires `treasuries`: without the chain's treasury the check fails closed. In test
+ * mode an unpinned chain falls back to the response's treasury with a console warning.
+ */
+export interface AddressPins extends Forwarder {
+  account: string;
+  treasuries?: Readonly<Record<number, string>> | undefined;
+}
+
+/**
+ * The treasury an address on `chainId` must pay: the pinned one, which the response must name.
+ */
+function pinnedTreasury(
+  pins: AddressPins,
+  livemode: boolean,
+  chainId: number,
+  treasury: string,
+  where: string,
+): string {
+  const pinned = pins.treasuries?.[chainId];
+  if (pinned === undefined) {
+    if (livemode) {
+      throw new AddressMismatchError(`${where}: live mode requires your pinned treasury of chain ${chainId}`);
+    }
+    console.warn(
+      `${where}: no pinned treasury of chain ${chainId}; the service's ${treasury} is trusted (test mode only)`,
+    );
+    return treasury;
+  }
+  if (!sameAddress(pinned, treasury)) {
+    throw new AddressMismatchError(`${where} pays a treasury that is not the pinned one`);
+  }
+  return pinned;
+}
+
+function requirePins(pins: AddressPins, where: string): void {
+  for (const field of ["account", "factory", "implementation"] as const) {
+    if (typeof pins[field] !== "string" || pins[field] === "") {
+      throw new AddressMismatchError(`${where}: the pinned ${field} is missing`);
+    }
+  }
+}
+
+function sameAddress(a: string, b: string): boolean {
+  return a.toLowerCase() === b.toLowerCase();
+}
+
+/**
+ * Recomputes an open quote's address from your pins and returns it, the `expectedAddress` to
+ * pass to `<Checkout>`. Throws `AddressMismatchError` unless the quote names your pinned
+ * treasury of its chain and its address derives from it; in live mode also when the chain has no
+ * pinned treasury.
+ */
+export function verifyQuoteAddress(
+  pins: AddressPins,
+  quote: {
+    id: string;
+    livemode: boolean;
+    chain_id: number;
+    treasury: string;
+    address: string;
+    client_reference_id: string;
+  },
+): Address {
+  const where = `quote ${quote.id}`;
+  requirePins(pins, where);
+  const treasury = pinnedTreasury(pins, quote.livemode, quote.chain_id, quote.treasury, where);
+  const derived = quoteAddress(pins, quote, treasury, pins.account);
+  if (!sameAddress(derived, quote.address)) {
+    throw new AddressMismatchError(`${where} has an address the account cannot derive`);
+  }
+  return derived;
+}
+
+/**
+ * Recomputes every network of an active deposit address from your pins and returns the address,
+ * the same on every network. Throws `AddressMismatchError` as `verifyQuoteAddress` does, for any
+ * network.
+ */
+export function verifyDepositAddress(
+  pins: AddressPins,
+  address: {
+    id: string;
+    livemode: boolean;
+    client_reference_id: string;
+    version: number;
+    networks: readonly { chain_id: number; treasury: string; address: string }[];
+  },
+): Address {
+  requirePins(pins, `deposit address ${address.id}`);
+  let first: Address | undefined;
+  for (const network of address.networks) {
+    const where = `deposit address ${address.id} on chain ${network.chain_id}`;
+    const treasury = pinnedTreasury(pins, address.livemode, network.chain_id, network.treasury, where);
+    const derived = depositAddress(pins, address, treasury, pins.account);
+    if (!sameAddress(derived, network.address)) {
+      throw new AddressMismatchError(`${where} is not one the account can derive`);
+    }
+    first ??= derived;
+  }
+  if (first === undefined) {
+    throw new AddressMismatchError(`deposit address ${address.id} has no network`);
+  }
+  return first;
+}

package/src/server/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Server-side helpers of `@phala/pay`. Nothing here needs or takes an API key: webhook
+ * verification uses your account's public webhook key, and the address and sweep helpers run
+ * offline. Call the API itself from your backend with a restricted key (the Python SDK, or any
+ * HTTP client with `Authorization: Bearer ppay_rk_…`); never ship a key to a browser. Recompute
+ * every address with `verifyQuoteAddress` or `verifyDepositAddress` from the pins you configure
+ * yourself before you show it.
+ */
+export {
+  WebhookSignatureError,
+  constructEvent,
+  type ConstructEventOptions,
+  type WebhookEvent,
+} from "./webhook.js";
+export {
+  AddressMismatchError,
+  depositAddress,
+  depositAddressSalt,
+  forwarderAddress,
+  quoteSalt,
+  quoteAddress,
+  verifyDepositAddress,
+  verifyQuoteAddress,
+  type AddressPins,
+  type Forwarder,
+} from "./addresses.js";
+export {
+  batchChecksum,
+  flushTransaction,
+  flushTransactions,
+  safeBatch,
+  type BatchFile,
+  type BatchFileMeta,
+  type BatchTransaction,
+  type Call,
+  type ForwarderObject,
+  type SafeBatchOptions,
+} from "./sweeps.js";

package/src/server/sweeps.ts

@@ -0,0 +1,197 @@
+import {
+  encodeFunctionData,
+  getAddress,
+  isHex,
+  keccak256,
+  stringToBytes,
+  type Address,
+  type Hex,
+} from "viem";
+
+const FLUSH_ABI = [
+  {
+    type: "function",
+    name: "flush",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "treasury", type: "address" },
+      { name: "salts", type: "bytes32[]" },
+      { name: "token", type: "address" },
+    ],
+    outputs: [],
+  },
+] as const;
+
+/** A contract call as a wallet or the Safe Transaction Builder takes it. */
+export interface Call {
+  to: Address;
+  data: Hex;
+  /** Native value in wei, a decimal string: `"0"` for a flush. */
+  value: string;
+}
+
+/**
+ * `factory.flush(treasury, salts, token)`, encoded offline from the exported forwarders
+ * (`GET /v1/forwarders`): every listed forwarder's whole balance of `token` moves to `treasury`,
+ * the only address it can pay. Anyone may send it; the sender pays the gas.
+ */
+export function flushTransaction(
+  factory: string,
+  treasury: string,
+  salts: readonly Hex[],
+  token: string,
+): Call {
+  if (salts.length === 0) {
+    throw new TypeError("flush needs at least one salt");
+  }
+  if (!salts.every((salt) => isHex(salt) && salt.length === 66)) {
+    throw new TypeError("a salt is 32 bytes of hex");
+  }
+  return {
+    to: getAddress(factory),
+    data: encodeFunctionData({
+      abi: FLUSH_ABI,
+      functionName: "flush",
+      args: [getAddress(treasury), salts, getAddress(token)],
+    }),
+    value: "0",
+  };
+}
+
+/** A forwarder as `GET /v1/forwarders` returns it. */
+export interface ForwarderObject {
+  chain_id: number;
+  factory: string;
+  treasury: string;
+  salt: string;
+}
+
+/**
+ * Groups forwarders of one chain, such as `GET /v1/forwarders?sweepable=<token>` lists, into
+ * `flushTransaction` calls: one per factory and treasury, of at most `maxSalts` forwarders.
+ */
+export function flushTransactions(
+  forwarders: Iterable<ForwarderObject>,
+  token: string,
+  maxSalts = 200,
+): Call[] {
+  const groups = new Map<string, { factory: string; treasury: string; salts: Hex[] }>();
+  const chains = new Set<number>();
+  for (const forwarder of forwarders) {
+    chains.add(forwarder.chain_id);
+    const factory = getAddress(forwarder.factory);
+    const treasury = getAddress(forwarder.treasury);
+    const key = `${factory}:${treasury}`;
+    const group = groups.get(key) ?? { factory, treasury, salts: [] };
+    if (!isHex(forwarder.salt)) {
+      throw new TypeError("a salt is 32 bytes of hex");
+    }
+    group.salts.push(forwarder.salt);
+    groups.set(key, group);
+  }
+  if (chains.size > 1) {
+    throw new TypeError("a batch of flush calls is for one chain");
+  }
+  const calls: Call[] = [];
+  for (const { factory, treasury, salts } of groups.values()) {
+    for (let start = 0; start < salts.length; start += maxSalts) {
+      calls.push(flushTransaction(factory, treasury, salts.slice(start, start + maxSalts), token));
+    }
+  }
+  return calls;
+}
+
+/**
+ * The Safe Transaction Builder's batch file, its `BatchFile` type
+ * (safe-global/safe-react-apps, `apps/tx-builder/src/typings/models.ts` at commit
+ * e8cccfb9a1042fa2954087988bae59c3b8c81780).
+ */
+export interface BatchFile {
+  version: string;
+  chainId: string;
+  createdAt: number;
+  meta: BatchFileMeta;
+  transactions: BatchTransaction[];
+}
+
+export interface BatchFileMeta {
+  txBuilderVersion?: string;
+  checksum?: string;
+  createdFromSafeAddress?: string;
+  createdFromOwnerAddress?: string;
+  name: string;
+  description?: string;
+}
+
+export interface BatchTransaction {
+  to: string;
+  value: string;
+  data?: string;
+  contractMethod?: { inputs: unknown[]; name: string; payable: boolean };
+  contractInputsValues?: { [key: string]: string };
+}
+
+export interface SafeBatchOptions {
+  name?: string;
+  description?: string;
+  /** Milliseconds; now by default. */
+  createdAt?: number;
+}
+
+/**
+ * A Transaction Builder batch file of `calls` for the Safe `safe` on `chainId`, with the app's
+ * `meta.checksum`, so it imports without the "modified since it was generated" warning. A Safe
+ * owner imports it in Safe{Wallet} > Apps > Transaction Builder; the owners sign and execute it.
+ */
+export function safeBatch(
+  chainId: number,
+  safe: string,
+  calls: readonly Call[],
+  options: SafeBatchOptions = {},
+): BatchFile {
+  if (calls.length === 0) {
+    throw new TypeError("a batch needs at least one call");
+  }
+  const batch: BatchFile = {
+    version: "1.0",
+    chainId: String(chainId),
+    createdAt: options.createdAt ?? Date.now(),
+    meta: {
+      name: options.name ?? "Phala Pay sweep",
+      description: options.description ?? "",
+      createdFromSafeAddress: getAddress(safe),
+    },
+    transactions: calls.map((call) => {
+      if (!/^\d+$/.test(call.value) || !isHex(call.data)) {
+        throw new TypeError("a call needs hex data and a decimal value");
+      }
+      return { to: getAddress(call.to), value: call.value, data: call.data };
+    }),
+  };
+  batch.meta.checksum = batchChecksum(batch);
+  return batch;
+}
+
+/**
+ * The Transaction Builder's `meta.checksum` (`apps/tx-builder/src/lib/checksum.ts`): Keccak-256
+ * of its key-sorted serialization with `meta.name` set to `null`, over the file without its
+ * checksum, as the app's `validateChecksum` recomputes it.
+ */
+export function batchChecksum(batch: BatchFile): Hex {
+  const meta: Record<string, unknown> = { ...batch.meta, name: null };
+  delete meta["checksum"];
+  return keccak256(stringToBytes(serialize({ ...batch, meta })));
+}
+
+/** The app's `serializeJSONObject`. */
+function serialize(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(serialize).join(",")}]`;
+  }
+  if (typeof value === "object" && value !== null) {
+    const record = value as Record<string, unknown>;
+    const keys = Object.keys(record).sort();
+    return `{${JSON.stringify(keys)}${keys.map((key) => `${serialize(record[key])},`).join("")}}`;
+  }
+  return JSON.stringify(value === undefined ? null : value);
+}

package/src/server/webhook.ts

@@ -0,0 +1,202 @@
+/**
+ * Standard Webhooks `v1a` verification of Phala Pay deliveries (design D11): an ed25519 signature
+ * over `{webhook-id}.{webhook-timestamp}.{body}` by your account's webhook key in the endpoint's
+ * mode, pinned from `GET /v1/attestation`. Uses WebCrypto, so it runs on Node 20+, Deno, Bun, and
+ * edge runtimes.
+ */
+
+/** A delivery that did not verify: answer `400` and do nothing. */
+export class WebhookSignatureError extends Error {
+  override readonly name = "WebhookSignatureError";
+}
+
+/** A verified event. `data.object` is the object the event is about, such as a deposit. */
+export interface WebhookEvent {
+  /** `evt_…`, stable across retries and resends: process each id once. */
+  id: string;
+  object: "event";
+  /** Your account, `acct_…`. */
+  account: string;
+  livemode: boolean;
+  /** Such as `deposit.credited`; claw back a `deposit.reversed` deposit's credit. */
+  type: string;
+  created: number;
+  /** Who caused it: an API key id (`key_…`), `admin`, or `system`. */
+  actor?: string;
+  /**
+   * The API request that caused it, with the `Idempotency-Key` it sent; `null` when the
+   * service's own workers did (a payment credited, a quote expired).
+   */
+  request?: { id: string; idempotency_key: string | null } | null;
+  /**
+   * `object` is the object as it was when the event happened, never re-rendered; `*.updated`
+   * events add `previous_attributes`, the former values of what changed.
+   */
+  data: { object: Record<string, unknown>; previous_attributes?: Record<string, unknown> };
+}
+
+export interface ConstructEventOptions {
+  /** Your account id, `acct_…`: an event of another account fails closed. */
+  expectedAccount: string;
+  /** The mode of the endpoint receiving it: an event of the other mode fails closed. */
+  expectedLivemode: boolean;
+  /** Seconds a delivery's timestamp may differ from now; default 300. */
+  tolerance?: number;
+  /** Current time in Unix seconds; for tests. */
+  now?: number;
+}
+
+/**
+ * Verifies a delivery and returns its event, as Stripe's `constructEvent` does, failing closed
+ * unless a `v1a` signature verifies with one of `publicKeys` (hex or base64 raw ed25519 keys; pass
+ * both while a rotation overlaps), the timestamp is within tolerance, the body's id is the
+ * `webhook-id`, and the event is `expectedAccount`'s in `expectedLivemode`.
+ *
+ * `payload` is the raw request body, before any JSON parsing.
+ */
+export async function constructEvent(
+  payload: string | Uint8Array,
+  headers: Headers | Record<string, string | string[] | undefined>,
+  publicKeys: string | readonly string[],
+  options: ConstructEventOptions,
+): Promise<WebhookEvent> {
+  if (options.expectedAccount === "") {
+    throw new TypeError("expectedAccount is required");
+  }
+  const body = typeof payload === "string" ? new TextEncoder().encode(payload) : payload;
+  const id = header(headers, "webhook-id");
+  const timestamp = header(headers, "webhook-timestamp");
+  const signatures = header(headers, "webhook-signature");
+  if (id === undefined || timestamp === undefined || signatures === undefined) {
+    throw new WebhookSignatureError("webhook headers missing");
+  }
+  if (!/^\d+$/.test(timestamp)) {
+    throw new WebhookSignatureError("webhook timestamp malformed");
+  }
+  const now = options.now ?? Math.floor(Date.now() / 1000);
+  if (Math.abs(now - Number(timestamp)) > (options.tolerance ?? 300)) {
+    throw new WebhookSignatureError("webhook timestamp outside tolerance");
+  }
+  const signed = concat(new TextEncoder().encode(`${id}.${timestamp}.`), body);
+  const keys = await Promise.all(
+    (typeof publicKeys === "string" ? [publicKeys] : publicKeys).map(importKey),
+  );
+  if (keys.length === 0) {
+    throw new TypeError("no webhook public key pinned");
+  }
+  let verified = false;
+  for (const entry of signatures.split(" ")) {
+    const [version, encoded] = entry.split(",", 2);
+    const signature = version === "v1a" && encoded !== undefined ? base64(encoded) : undefined;
+    if (signature === undefined) {
+      continue;
+    }
+    for (const key of keys) {
+      if (await crypto.subtle.verify("Ed25519", key, signature, signed)) {
+        verified = true;
+      }
+    }
+  }
+  if (!verified) {
+    throw new WebhookSignatureError("no valid webhook signature");
+  }
+  let event: unknown;
+  try {
+    event = JSON.parse(new TextDecoder().decode(body));
+  } catch {
+    throw new TypeError("webhook body is not an event");
+  }
+  if (typeof event !== "object" || event === null) {
+    throw new TypeError("webhook body is not an event");
+  }
+  const e = event as Record<string, unknown>;
+  const data = e["data"];
+  const object: unknown =
+    typeof data === "object" && data !== null ? (data as Record<string, unknown>)["object"] : null;
+  const { id: eventId, type, account, livemode, created, actor } = e;
+  if (
+    e["object"] !== "event" ||
+    typeof eventId !== "string" ||
+    typeof type !== "string" ||
+    typeof account !== "string" ||
+    typeof livemode !== "boolean" ||
+    typeof created !== "number" ||
+    !Number.isSafeInteger(created) ||
+    typeof object !== "object" ||
+    object === null ||
+    !(actor === undefined || typeof actor === "string")
+  ) {
+    throw new TypeError("webhook body is not an event");
+  }
+  if (eventId !== id) {
+    throw new WebhookSignatureError("webhook id does not match the event");
+  }
+  if (account !== options.expectedAccount) {
+    throw new WebhookSignatureError("webhook event is for another account");
+  }
+  if (livemode !== options.expectedLivemode) {
+    throw new WebhookSignatureError("webhook event is for the other mode");
+  }
+  const previous = (data as Record<string, unknown>)["previous_attributes"];
+  return {
+    id: eventId,
+    object: "event",
+    account,
+    livemode,
+    type,
+    created,
+    ...(actor === undefined ? {} : { actor }),
+    data: {
+      object: object as Record<string, unknown>,
+      ...(typeof previous === "object" && previous !== null
+        ? { previous_attributes: previous as Record<string, unknown> }
+        : {}),
+    },
+  };
+}
+
+function header(
+  headers: Headers | Record<string, string | string[] | undefined>,
+  name: string,
+): string | undefined {
+  if (headers instanceof Headers) {
+    return headers.get(name)?.trim() ?? undefined;
+  }
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name) {
+      return (Array.isArray(value) ? value.join(" ") : value)?.trim();
+    }
+  }
+  return undefined;
+}
+
+async function importKey(encoded: string): Promise<CryptoKey> {
+  const value = encoded.trim().replace(/^0x/, "");
+  const raw = /^[0-9a-fA-F]{64}$/.test(value) ? hex(value) : base64(value);
+  if (raw?.length !== 32) {
+    throw new TypeError("a webhook public key is 32 bytes of hex or base64");
+  }
+  return crypto.subtle.importKey("raw", raw, "Ed25519", false, ["verify"]);
+}
+
+function hex(value: string): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(value.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+function base64(value: string): Uint8Array<ArrayBuffer> | undefined {
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 !== 0) {
+    return undefined;
+  }
+  return Uint8Array.from(atob(value), (char) => char.charCodeAt(0));
+}
+
+function concat(left: Uint8Array, right: Uint8Array): Uint8Array<ArrayBuffer> {
+  const joined = new Uint8Array(left.length + right.length);
+  joined.set(left);
+  joined.set(right, left.length);
+  return joined;
+}