@phala/pay 0.1.2 → 0.2.0

package/src/react/DepositAddress.tsx

@@ -0,0 +1,213 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { formatUnits } from "viem";
+import { networkName } from "../chains.js";
+import {
+  retrieveDepositAddress,
+  type DepositAddressPayment,
+} from "../deposit-address.js";
+import { CheckoutError, pollDelay } from "../checkout.js";
+import { depositAddressTransfer, type DepositAddressDetails } from "../payment.js";
+import { STYLES, appearanceStyle, 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. 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 payments = usePayments(clientSecret, apiBase, pollInterval ?? 3000);
+  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"}
+      style={appearanceStyle(appearance)}
+    >
+      <style>{STYLES}</style>
+      <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 && (
+        <div className="pp-tabs" role="tablist" aria-label="Network">
+          {networks.map((each) => (
+            <button
+              key={each.chain_id}
+              type="button"
+              role="tab"
+              className="pp-tab"
+              aria-selected={each.chain_id === network.chain_id}
+              onClick={() => {
+                setSelectedChain(each.chain_id);
+              }}
+            >
+              {networkName(each.chain_id)}
+            </button>
+          ))}
+        </div>
+      )}
+      {network.assets.length > 1 && (
+        <div className="pp-tabs" role="tablist" aria-label="Token">
+          {network.assets.map((each) => (
+            <button
+              key={each.asset}
+              type="button"
+              role="tab"
+              className="pp-tab"
+              aria-selected={each.asset === token.asset}
+              onClick={() => {
+                setSelectedAsset(each.asset);
+              }}
+            >
+              {each.asset.toUpperCase()}
+            </button>
+          ))}
+        </div>
+      )}
+      <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(", ")}
+        . Any amount is credited at the market rate when it arrives, usually in about 30 seconds.
+        Other tokens and networks are not credited. You can reuse this address.
+      </p>
+    </div>
+  );
+}
+
+/** The address's recent payments, read every `interval` while mounted; empty without a secret. */
+function usePayments(
+  clientSecret: string | undefined,
+  apiBase: string | undefined,
+  interval: number,
+): DepositAddressPayment[] {
+  const key = clientSecret === undefined || apiBase === undefined ? "" : `${apiBase} ${clientSecret}`;
+  const [current, setCurrent] = useState<{ key: string; payments: DepositAddressPayment[] }>({
+    key: "",
+    payments: [],
+  });
+  useEffect(() => {
+    if (clientSecret === undefined || apiBase === undefined) {
+      return;
+    }
+    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 });
+        failures = 0;
+        if (!stopped) {
+          setCurrent({ key, payments: view.payments });
+        }
+      } 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;
+      clearTimeout(timer);
+    };
+  }, [key, clientSecret, apiBase, interval]);
+  // Another address starts without the previous one's payments.
+  return current.key === key && key !== "" ? current.payments : [];
+}
+
+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

@@ -0,0 +1,46 @@
+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/appearance.ts

@@ -83,6 +83,9 @@ export const STYLES = `
 .pp-root *, .pp-root *::before, .pp-root *::after { box-sizing: inherit; }
 .pp-amount { margin: 0; overflow-wrap: anywhere; font-size: 22px; font-weight: 600; }
 .pp-subtitle { margin: 2px 0 16px; color: var(--pp-color-text-secondary); }
+.pp-badge { font-weight: 600; }
+.pp-payments { list-style: none; margin: 12px 0 0; padding: 0; }
+.pp-payments li { margin: 4px 0; }
 .pp-status { display: flex; gap: 8px; align-items: baseline; justify-content: space-between;
   margin-bottom: 12px; padding: 10px 12px; border-radius: var(--pp-border-radius);
   border: 1px solid var(--pp-color-border); }

package/src/react/index.ts

@@ -1,5 +1,6 @@
 "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

@@ -3,6 +3,8 @@ import { createCheckout, type CheckoutSession, type CheckoutState } from "../che
 
 export interface UseCheckoutOptions {
   clientSecret: string;
+  /** The quote's address as your backend recomputed it; another one fails closed. */
+  expectedAddress: string;
   apiBase: string;
   pollInterval?: number;
 }
@@ -17,16 +19,18 @@ 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,
 }: UseCheckoutOptions): UseCheckoutResult {
   const [current, setCurrent] = useState({ key: "", state: LOADING });
   const checkout = useRef<CheckoutSession | null>(null);
-  const key = `${apiBase} ${clientSecret}`;
+  const key = `${apiBase} ${clientSecret} ${expectedAddress}`;
 
   useEffect(() => {
     const instance = createCheckout({
       clientSecret,
+      expectedAddress,
       apiBase,
       ...(pollInterval === undefined ? {} : { pollInterval }),
     });
@@ -37,7 +41,7 @@ export function useCheckout({
       instance.destroy();
       checkout.current = null;
     };
-  }, [key, clientSecret, apiBase, pollInterval]);
+  }, [key, clientSecret, expectedAddress, apiBase, pollInterval]);
 
   const refresh = useCallback(() => {
     void checkout.current?.refresh();

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";