@phala/pay 0.1.2 → 0.3.0

package/src/react/Checkout.tsx

@@ -1,20 +1,33 @@
 "use client";
 
 import { useEffect, useId, useRef, useState, type KeyboardEvent } from "react";
-import type { Hash } from "viem";
-import type { CheckoutState, CheckoutStatus } from "../checkout.js";
+import type { Hash, WalletClient } from "viem";
+import type { CheckoutErrorCode, CheckoutState, CheckoutStatus } from "../checkout.js";
 import { networkName, transactionUrl } from "../chains.js";
 import { formatAmount, formatCountdown, formatTokenAmount, tokenAmount } from "../format.js";
 import { quoteTransfer } from "../payment.js";
 import type { ClientQuote } from "../quote.js";
-import { WalletError, payWithWallet, watchWallets, type Wallet } from "../wallet.js";
+import {
+  WalletError,
+  payWithWallet,
+  watchWallets,
+  type EthereumProvider,
+  type Wallet,
+} from "../wallet.js";
 import { STYLES, appearanceStyle, type Appearance } from "./appearance.js";
+import { Field } from "./Field.js";
 import { QrCode } from "./QrCode.js";
 import { useCheckout } from "./useCheckout.js";
 
 export interface CheckoutProps {
   /** The quote's `client_secret`, from your backend's `POST /v1/quotes`. */
   clientSecret: string;
+  /**
+   * The quote's `address` as your backend's SDK recomputed it from the pinned forwarder
+   * (`PhalaPay(forwarder=…)` in Python). Required: when the service's quote names another
+   * address, the checkout fails closed and shows nothing to pay.
+   */
+  expectedAddress: string;
   /** The service origin, for example `https://topup.example.com`. */
   apiBase: string;
   /** Called once when the payment is credited. Fulfil from the `deposit.credited` webhook, not here. */
@@ -30,6 +43,9 @@ export interface CheckoutProps {
   className?: string;
   /** The wallet button's label; default "Pay with crypto". */
   buttonText?: string;
+  /** Your page's connected wallet, for example wagmi's `useWalletClient().data`. When set, the
+   * wallet tab pays with it and its account instead of listing the browser's wallets. */
+  walletClient?: WalletClient | undefined;
 }
 
 type Method = "wallet" | "qr" | "manual";
@@ -43,6 +59,7 @@ const METHODS: { id: Method; label: string }[] = [
 /** A checkout for one quote: pay from a browser wallet, by QR code, or manually, with live status. */
 export function Checkout({
   clientSecret,
+  expectedAddress,
   apiBase,
   onSuccess,
   onExpire,
@@ -51,9 +68,11 @@ export function Checkout({
   pollInterval,
   className,
   buttonText = "Pay with crypto",
+  walletClient,
 }: CheckoutProps) {
   const { status, quote, error, refresh } = useCheckout({
     clientSecret,
+    expectedAddress,
     apiBase,
     ...(pollInterval === undefined ? {} : { pollInterval }),
   });
@@ -98,15 +117,17 @@ export function Checkout({
           </p>
           <p className="pp-subtitle">
             {formatAmount(quote)} top-up · {networkName(quote.chain_id)}
+            {!quote.livemode && <span className="pp-badge"> · Test mode</span>}
           </p>
         </>
       )}
-      <StatusLine status={status} quote={quote} now={now} reconnecting={error !== null} />
+      <StatusLine status={status} quote={quote} now={now} error={error} />
       {txHash !== null && quote !== null && <Transaction hash={txHash} chainId={quote.chain_id} />}
       {status === "waiting" && quote !== null && (
         <PaymentOptions
           quote={quote}
           buttonText={buttonText}
+          walletClient={walletClient}
           now={now}
           onSent={(hash) => {
             setTxHash(hash);
@@ -122,24 +143,24 @@ function StatusLine({
   status,
   quote,
   now,
-  reconnecting,
+  error,
 }: {
   status: CheckoutStatus;
   quote: ClientQuote | null;
   now: number;
-  reconnecting: boolean;
+  error: CheckoutState["error"];
 }) {
   const tone =
     status === "credited"
       ? "success"
-      : ["rejected", "expired", "canceled", "error"].includes(status)
+      : ["rejected", "reversed", "expired", "canceled", "error"].includes(status)
         ? "danger"
         : "neutral";
   return (
     <div className="pp-status" data-tone={tone}>
       <span role="status" aria-live="polite">
-        {statusMessage(status, quote)}
-        {reconnecting && status !== "error" ? " (reconnecting…)" : ""}
+        {statusMessage(status, quote, error?.code)}
+        {error !== null && status !== "error" ? " (reconnecting…)" : ""}
       </span>
       {status === "waiting" && quote !== null && (
         <span className="pp-countdown" aria-label="Time left to pay">
@@ -150,7 +171,11 @@ function StatusLine({
   );
 }
 
-function statusMessage(status: CheckoutStatus, quote: ClientQuote | null): string {
+function statusMessage(
+  status: CheckoutStatus,
+  quote: ClientQuote | null,
+  code: CheckoutErrorCode | undefined,
+): string {
   switch (status) {
     case "loading":
       return "Loading payment details…";
@@ -158,20 +183,24 @@ function statusMessage(status: CheckoutStatus, quote: ClientQuote | null): strin
       return "Waiting for your payment";
     case "seen":
       return quote?.confirmations == null
-        ? "Payment received, waiting for confirmations"
-        : `Payment received, ${quote.confirmations} confirmation${quote.confirmations === 1 ? "" : "s"}`;
+        ? "Payment received, crediting in about 30 seconds"
+        : `Payment received, ${quote.confirmations} confirmation${quote.confirmations === 1 ? "" : "s"}. Crediting in about 30 seconds`;
     case "confirming":
       return "Payment confirmed on chain, crediting…";
     case "credited":
       return quote === null ? "Payment credited" : `Payment credited: ${formatAmount(quote)}`;
     case "rejected":
       return "This payment cannot be credited. Contact support with your transaction.";
+    case "reversed":
+      return "This payment was reversed: its transaction is no longer on the blockchain, so it did not happen and its credit was taken back. Check your wallet, then start a new top-up.";
     case "expired":
       return "This quote has expired. Do not send funds to this address; start a new top-up.";
     case "canceled":
       return "This quote was canceled. Do not send funds to this address.";
     case "error":
-      return "This payment link is not valid. Start a new top-up.";
+      return code === "address_mismatch"
+        ? "This payment address could not be verified. Do not send funds; contact support."
+        : "This payment link is not valid. Start a new top-up.";
   }
 }
 
@@ -195,11 +224,13 @@ function PaymentOptions({
   quote,
   now,
   buttonText,
+  walletClient,
   onSent,
 }: {
   quote: ClientQuote;
   now: number;
   buttonText: string;
+  walletClient: WalletClient | undefined;
   onSent: (hash: Hash) => void;
 }) {
   const [method, setMethod] = useState<Method>("wallet");
@@ -261,7 +292,14 @@ function PaymentOptions({
         aria-labelledby={`${id}-tab-${method}`}
         tabIndex={0}
       >
-        {method === "wallet" && <WalletPanel quote={quote} buttonText={buttonText} onSent={onSent} />}
+        {method === "wallet" && (
+          <WalletPanel
+            quote={quote}
+            buttonText={buttonText}
+            walletClient={walletClient}
+            onSent={onSent}
+          />
+        )}
         {method === "qr" && (
           <div className="pp-qr-panel">
             <QrCode value={quote.payment_uri} label={`Payment request for ${amount}`} />
@@ -285,20 +323,29 @@ type WalletStep =
 function WalletPanel({
   quote,
   buttonText,
+  walletClient,
   onSent,
 }: {
   quote: ClientQuote;
   buttonText: string;
+  walletClient: WalletClient | undefined;
   onSent: (hash: Hash) => void;
 }) {
-  const [wallets, setWallets] = useState<Wallet[]>([]);
+  const [discovered, setDiscovered] = useState<Wallet[]>([]);
   const [step, setStep] = useState<WalletStep>({ kind: "idle" });
-  useEffect(() => watchWallets(setWallets), []);
+  useEffect(
+    () => (walletClient === undefined ? watchWallets(setDiscovered) : undefined),
+    [walletClient],
+  );
+  const wallets: { id: string; name: string; icon: string; wallet: WalletClient | EthereumProvider }[] =
+    walletClient === undefined
+      ? discovered.map(({ info: { uuid, name, icon }, provider }) => ({ id: uuid, name, icon, wallet: provider }))
+      : [{ id: "client", name: "your wallet", icon: "", wallet: walletClient }];
 
-  const pay = async (wallet: Wallet) => {
-    setStep({ kind: "pending", wallet: wallet.info.name });
+  const pay = async ({ name, wallet }: (typeof wallets)[number]) => {
+    setStep({ kind: "pending", wallet: name });
     try {
-      onSent(await payWithWallet(wallet.provider, quote));
+      onSent(await payWithWallet(wallet, quote));
       setStep({ kind: "idle" });
     } catch (error) {
       setStep({
@@ -318,18 +365,18 @@ function WalletPanel({
   }
   return (
     <div className="pp-wallets">
-      {wallets.map((wallet) => (
+      {wallets.map((choice) => (
         <button
-          key={wallet.info.uuid}
+          key={choice.id}
           type="button"
           className="pp-button"
           disabled={step.kind === "pending"}
-          onClick={() => void pay(wallet)}
-          aria-label={`${buttonText} (${wallet.info.name})`}
+          onClick={() => void pay(choice)}
+          aria-label={walletClient === undefined ? `${buttonText} (${choice.name})` : buttonText}
         >
-          {wallet.info.icon !== "" && <img src={wallet.info.icon} alt="" />}
+          {choice.icon !== "" && <img src={choice.icon} alt="" />}
           <span>{buttonText}</span>
-          <span className="pp-wallet-name">{wallet.info.name}</span>
+          {walletClient === undefined && <span className="pp-wallet-name">{choice.name}</span>}
         </button>
       ))}
       <p
@@ -357,51 +404,6 @@ function ManualPanel({ quote, now }: { quote: ClientQuote; now: number }) {
   );
 }
 
-/** `copy` adds a copy button, copying `value`, or the given string when it differs from it. */
-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>
-  );
-}
-
 /** The current time in milliseconds, updated every second while `active`. */
 function useNow(active: boolean): number {
   const [now, setNow] = useState(() => Date.now());

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();