@phala/pay 0.8.2 → 0.9.0

package/src/react/DepositAddress.tsx

@@ -1,239 +0,0 @@
-"use client";
-
-import { useEffect, useId, useState } from "react";
-import { formatUnits } from "viem";
-import { networkName } from "../chains.js";
-import {
-  retrieveDepositAddress,
-  type ClientDepositAddress,
-  type DepositAddressPayment,
-} from "../deposit-address.js";
-import { CheckoutError, pollDelay } from "../checkout.js";
-import { formatWait } from "../format.js";
-import { depositAddressTransfer, type DepositAddressDetails } from "../payment.js";
-import type { Appearance } from "./appearance.js";
-import { Field } from "./Field.js";
-import { QrCode } from "./QrCode.js";
-
-export interface DepositAddressProps {
-  /** `address` and `networks` from your backend's `POST /v1/deposit_addresses`. */
-  depositAddress: DepositAddressDetails;
-  /** The network shown first; the first of `networks` by default. */
-  chainId?: number;
-  /** The token shown first, for example `pha`; the network's first token by default. */
-  asset?: string;
-  /**
-   * The `client_secret` of the same response. With `apiBase`, the component follows the
-   * address's payments and shows each one within about a block of arriving: received with its
-   * confirmations, then credited, and states each network's typical credit time. Display only;
-   * credit from your `deposit.credited` webhook.
-   */
-  clientSecret?: string;
-  /** The service origin, for example `https://pay.example.com`; needed with `clientSecret`. */
-  apiBase?: string;
-  /** Milliseconds between payment reads; default 3000. */
-  pollInterval?: number;
-  appearance?: Appearance;
-  className?: string;
-}
-
-/**
- * A customer's persistent deposit address: one address for every supported token on every
- * supported network. The payer picks a network and a token; the component shows a QR code of that
- * EIP-681 transfer request and the address and token contract to copy. Any amount of a supported
- * token sent is credited at the market rate when it arrives; follow it from your backend's
- * `deposit.credited` webhook.
- */
-export function DepositAddress({
-  depositAddress,
-  chainId,
-  asset,
-  clientSecret,
-  apiBase,
-  pollInterval,
-  appearance,
-  className,
-}: DepositAddressProps) {
-  const { networks } = depositAddress;
-  const id = useId();
-  const view = useClientView(clientSecret, apiBase, pollInterval ?? 3000);
-  const payments = view?.payments ?? [];
-  const [selectedChain, setSelectedChain] = useState(chainId ?? networks[0]?.chain_id);
-  const [selectedAsset, setSelectedAsset] = useState(asset);
-  const network = networks.find((candidate) => candidate.chain_id === selectedChain) ?? networks[0];
-  if (network === undefined) {
-    throw new TypeError("the deposit address has no network");
-  }
-  const token =
-    network.assets.find((candidate) => candidate.asset === selectedAsset) ?? network.assets[0];
-  if (token === undefined) {
-    throw new TypeError(`the deposit address takes no token on chain ${network.chain_id}`);
-  }
-  const { token: contract, to } = depositAddressTransfer(network, token);
-  const symbol = token.asset.toUpperCase();
-  const name = networkName(network.chain_id);
-  const tokens = [...new Set(networks.flatMap((each) => each.assets.map((a) => a.asset.toUpperCase())))];
-  return (
-    <div
-      className={className === undefined ? "pp-root" : `pp-root ${className}`}
-      data-theme={appearance?.theme ?? "light"}
-    >
-      <p className="pp-subtitle">
-        {depositAddress.address === null
-          ? "Your deposit address for every supported token; it differs on some networks"
-          : "One address for all supported tokens and networks"}
-      </p>
-      {networks.length > 1 && (
-        <fieldset className="pp-choices">
-          <legend>Network</legend>
-          {networks.map((each) => (
-            <label key={each.chain_id}>
-              <input
-                type="radio"
-                name={`${id}-network`}
-                checked={each.chain_id === network.chain_id}
-                onChange={() => setSelectedChain(each.chain_id)}
-              />
-              {networkName(each.chain_id)}
-            </label>
-          ))}
-        </fieldset>
-      )}
-      {network.assets.length > 1 && (
-        <fieldset className="pp-choices">
-          <legend>Token</legend>
-          {network.assets.map((each) => (
-            <label key={each.asset}>
-              <input
-                type="radio"
-                name={`${id}-token`}
-                checked={each.asset === token.asset}
-                onChange={() => setSelectedAsset(each.asset)}
-              />
-              {each.asset.toUpperCase()}
-            </label>
-          ))}
-        </fieldset>
-      )}
-      <div className="pp-qr-panel">
-        <QrCode value={token.payment_uri} label={`Deposit address for ${symbol} on ${name}`} />
-      </div>
-      <dl className="pp-fields">
-        <Field label="Network" value={`${name} (chain ID ${network.chain_id})`} />
-        <Field label={`Token (${symbol}) contract`} value={contract} copy />
-        <Field label="Deposit address" value={to} copy />
-      </dl>
-      {payments.length > 0 && (
-        <ul className="pp-payments" aria-live="polite" aria-label="Payments">
-          {payments.map((payment) => (
-            <li key={`${payment.chain_id}:${payment.tx_hash}:${payment.created}`}>
-              {paymentMessage(payment)}
-            </li>
-          ))}
-        </ul>
-      )}
-      <p className="pp-message">
-        Send only {tokens.join(", ")} on {networks.map((each) => networkName(each.chain_id)).join(", ")}
-        . {creditMessage(networks.map((each) => each.chain_id), view)} Other tokens and networks are not
-        credited. You can reuse this address.
-      </p>
-    </div>
-  );
-}
-
-/** The address's public view, read every `interval` while mounted; `null` without a secret. */
-function useClientView(
-  clientSecret: string | undefined,
-  apiBase: string | undefined,
-  interval: number,
-): ClientDepositAddress | null {
-  const key = clientSecret === undefined || apiBase === undefined ? "" : `${apiBase} ${clientSecret}`;
-  const [current, setCurrent] = useState<{ key: string; view: ClientDepositAddress | null }>({
-    key: "",
-    view: null,
-  });
-  useEffect(() => {
-    if (clientSecret === undefined || apiBase === undefined) {
-      return;
-    }
-    const controller = new AbortController();
-    let stopped = false;
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    let failures = 0;
-    const load = async () => {
-      let failure: CheckoutError | null = null;
-      try {
-        const view = await retrieveDepositAddress({ clientSecret, apiBase, signal: controller.signal });
-        failures = 0;
-        if (!stopped) {
-          setCurrent({ key, view });
-        }
-      } catch (error) {
-        failures += 1;
-        // A secret that is not valid will not become valid: stop, keep showing the address.
-        if (error instanceof CheckoutError && error.code === "invalid_client_secret") {
-          return;
-        }
-        failure = error instanceof CheckoutError ? error : null;
-      }
-      if (!stopped) {
-        timer = setTimeout(() => void load(), pollDelay(interval, failures, failure));
-      }
-    };
-    void load();
-    return () => {
-      stopped = true;
-      controller.abort();
-      clearTimeout(timer);
-    };
-  }, [key, clientSecret, apiBase, interval]);
-  // Another address starts without the previous one's view.
-  return current.key === key && key !== "" ? current.view : null;
-}
-
-/**
- * When a payment on each of `chainIds` is credited, from `view`'s typical credit times, for
- * example "usually in about 30 seconds on Ethereum and about 7 seconds on Base". Before the view
- * is loaded it names no time.
- */
-function creditMessage(chainIds: number[], view: ClientDepositAddress | null): string {
-  const names = new Map<number, string[]>();
-  for (const network of view?.networks ?? []) {
-    if (chainIds.includes(network.chain_id)) {
-      const seconds = network.typical_credit_seconds;
-      names.set(seconds, [...(names.get(seconds) ?? []), networkName(network.chain_id)]);
-    }
-  }
-  if (names.size === 0) {
-    return "Any amount is credited at the market rate once it is confirmed on its network.";
-  }
-  const list = new Intl.ListFormat("en", { type: "conjunction" });
-  const [only, ...others] = names.keys();
-  const usually =
-    only !== undefined && others.length === 0
-      ? formatWait(only)
-      : list.format([...names].map(([seconds, on]) => `${formatWait(seconds)} on ${list.format(on)}`));
-  return `Any amount is credited at the market rate when it arrives, usually in ${usually}.`;
-}
-
-function paymentMessage(payment: DepositAddressPayment): string {
-  const amount =
-    payment.asset === null || payment.decimals === null
-      ? "A payment"
-      : `${formatUnits(BigInt(payment.amount_atomic), payment.decimals)} ${payment.asset.toUpperCase()}`;
-  const on = `on ${networkName(payment.chain_id)}`;
-  switch (payment.status) {
-    case "seen":
-      return payment.confirmations === null
-        ? `${amount} received ${on}, crediting shortly`
-        : `${amount} received ${on}, ${payment.confirmations} confirmation${payment.confirmations === 1 ? "" : "s"}`;
-    case "confirming":
-      return `${amount} confirmed ${on}, crediting…`;
-    case "credited":
-      return `${amount} ${on} credited`;
-    case "rejected":
-      return `${amount} ${on} cannot be credited. Contact support with your transaction.`;
-    case "reversed":
-      return `${amount} ${on} was reversed: its transaction is no longer on the blockchain.`;
-  }
-}

package/src/react/Field.tsx

@@ -1,46 +0,0 @@
-import { useEffect, useState } from "react";
-
-/** `copy` adds a copy button, copying `value`, or the given string when it differs from it. */
-export function Field({
-  label,
-  value,
-  copy = false,
-}: {
-  label: string;
-  value: string;
-  copy?: boolean | string;
-}) {
-  return (
-    <div className="pp-field">
-      <dt>{label}</dt>
-      <dd>
-        <span className={copy === false ? undefined : "pp-value"}>{value}</span>
-        {copy !== false && (
-          <CopyButton value={typeof copy === "string" ? copy : value} label={label} />
-        )}
-      </dd>
-    </div>
-  );
-}
-
-function CopyButton({ value, label }: { value: string; label: string }) {
-  const [copied, setCopied] = useState<boolean | null>(null);
-  useEffect(() => {
-    if (copied === null) {
-      return;
-    }
-    const timer = setTimeout(() => setCopied(null), 2000);
-    return () => clearTimeout(timer);
-  }, [copied]);
-  const onClick = () => {
-    navigator.clipboard.writeText(value).then(
-      () => setCopied(true),
-      () => setCopied(false),
-    );
-  };
-  return (
-    <button type="button" className="pp-copy" onClick={onClick} aria-label={`Copy ${label}`}>
-      <span aria-live="polite">{copied === null ? "Copy" : copied ? "Copied" : "Copy failed"}</span>
-    </button>
-  );
-}

package/src/react/QrCode.tsx

@@ -1,39 +0,0 @@
-import { useMemo } from "react";
-import { encode } from "uqr";
-
-export interface QrCodeProps {
-  value: string;
-  label: string;
-  size?: number;
-}
-
-/** A QR code as an SVG path, one unit per module. */
-export function QrCode({ value, label, size = 208 }: QrCodeProps) {
-  const { path, width } = useMemo(() => {
-    const { data, size: modules } = encode(value, { ecc: "M", border: 2 });
-    let d = "";
-    data.forEach((row, y) => {
-      row.forEach((dark, x) => {
-        if (dark) {
-          d += `M${x} ${y}h1v1h-1z`;
-        }
-      });
-    });
-    return { path: d, width: modules };
-  }, [value]);
-
-  return (
-    <svg
-      className="pp-qr"
-      role="img"
-      aria-label={label}
-      width={size}
-      height={size}
-      viewBox={`0 0 ${width} ${width}`}
-      shapeRendering="crispEdges"
-    >
-      <rect width={width} height={width} fill="#fff" />
-      <path d={path} fill="#000" />
-    </svg>
-  );
-}

package/src/react/appearance.ts

@@ -1,4 +0,0 @@
-/** Base theme; customize CSS properties on `.pp-root` in your stylesheet. */
-export interface Appearance {
-  theme?: "light" | "dark";
-}

package/src/react/index.ts

@@ -1,6 +0,0 @@
-"use client";
-
-export { Checkout, type CheckoutProps } from "./Checkout.js";
-export { DepositAddress, type DepositAddressProps } from "./DepositAddress.js";
-export { useCheckout, type UseCheckoutOptions, type UseCheckoutResult } from "./useCheckout.js";
-export type { Appearance } from "./appearance.js";

package/src/react/useCheckout.ts

@@ -1,58 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from "react";
-import {
-  createCheckout,
-  type CheckoutOptions,
-  type CheckoutSession,
-  type CheckoutState,
-} from "../checkout.js";
-
-export type UseCheckoutOptions = Pick<
-  CheckoutOptions,
-  "clientSecret" | "expectedAddress" | "apiBase" | "pollInterval" | "signal" | "requestTimeout"
->;
-
-export interface UseCheckoutResult extends CheckoutState {
-  /** Reads the quote now, for example right after the wallet broadcast the payment. */
-  refresh: () => void;
-}
-
-const LOADING: CheckoutState = { status: "loading", quote: null, error: null };
-
-/** Follows a quote's public view for as long as the component is mounted. */
-export function useCheckout({
-  clientSecret,
-  expectedAddress,
-  apiBase,
-  pollInterval,
-  signal,
-  requestTimeout,
-}: UseCheckoutOptions): UseCheckoutResult {
-  const [current, setCurrent] = useState({ key: "", state: LOADING });
-  const checkout = useRef<CheckoutSession | null>(null);
-  const key = `${apiBase} ${clientSecret} ${expectedAddress}`;
-
-  useEffect(() => {
-    const instance = createCheckout({
-      clientSecret,
-      expectedAddress,
-      apiBase,
-      ...(pollInterval === undefined ? {} : { pollInterval }),
-      ...(signal === undefined ? {} : { signal }),
-      ...(requestTimeout === undefined ? {} : { requestTimeout }),
-    });
-    checkout.current = instance;
-    const unsubscribe = instance.subscribe((state) => setCurrent({ key, state }));
-    return () => {
-      unsubscribe();
-      instance.destroy();
-      checkout.current = null;
-    };
-  }, [key, clientSecret, expectedAddress, apiBase, pollInterval, signal, requestTimeout]);
-
-  const refresh = useCallback(() => {
-    void checkout.current?.refresh();
-  }, []);
-
-  // A new client secret starts from `loading`, not from the previous quote's state.
-  return { ...(current.key === key ? current.state : LOADING), refresh };
-}

package/src/server/addresses.ts

@@ -1,223 +0,0 @@
-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

@@ -1,38 +0,0 @@
-/**
- * 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";