@phala/pay 0.3.0 → 0.5.0

package/src/react/DepositAddress.tsx

@@ -5,9 +5,11 @@ 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 { STYLES, appearanceStyle, type Appearance } from "./appearance.js";
 import { Field } from "./Field.js";
@@ -23,7 +25,8 @@ export interface DepositAddressProps {
   /**
    * 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.
+   * 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`. */
@@ -52,7 +55,8 @@ export function DepositAddress({
   className,
 }: DepositAddressProps) {
   const { networks } = depositAddress;
-  const payments = usePayments(clientSecret, apiBase, pollInterval ?? 3000);
+  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];
@@ -135,23 +139,23 @@ export function DepositAddress({
       )}
       <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.
+        . {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 recent payments, read every `interval` while mounted; empty without a secret. */
-function usePayments(
+/** The address's public view, read every `interval` while mounted; `null` without a secret. */
+function useClientView(
   clientSecret: string | undefined,
   apiBase: string | undefined,
   interval: number,
-): DepositAddressPayment[] {
+): ClientDepositAddress | null {
   const key = clientSecret === undefined || apiBase === undefined ? "" : `${apiBase} ${clientSecret}`;
-  const [current, setCurrent] = useState<{ key: string; payments: DepositAddressPayment[] }>({
+  const [current, setCurrent] = useState<{ key: string; view: ClientDepositAddress | null }>({
     key: "",
-    payments: [],
+    view: null,
   });
   useEffect(() => {
     if (clientSecret === undefined || apiBase === undefined) {
@@ -166,7 +170,7 @@ function usePayments(
         const view = await retrieveDepositAddress({ clientSecret, apiBase });
         failures = 0;
         if (!stopped) {
-          setCurrent({ key, payments: view.payments });
+          setCurrent({ key, view });
         }
       } catch (error) {
         failures += 1;
@@ -186,8 +190,33 @@ function usePayments(
       clearTimeout(timer);
     };
   }, [key, clientSecret, apiBase, interval]);
-  // Another address starts without the previous one's payments.
-  return current.key === key && key !== "" ? current.payments : [];
+  // 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 {

package/src/wallet.ts

@@ -6,10 +6,13 @@ import {
   erc20Abi,
   SwitchChainError,
   UserRejectedRequestError,
+  type Address,
   type Hash,
   type WalletClient,
 } from "viem";
+import { readContract } from "viem/actions";
 import { knownChain, networkName } from "./chains.js";
+import { formatTokenAmount, formatUnitsGrouped } from "./format.js";
 import { quoteTransfer } from "./payment.js";
 import type { ClientQuote } from "./quote.js";
 
@@ -83,7 +86,12 @@ function isProvider(value: unknown): value is EthereumProvider {
   return typeof (value as Partial<EthereumProvider> | null | undefined)?.request === "function";
 }
 
-export type WalletErrorCode = "rejected" | "no_account" | "wrong_chain" | "failed";
+export type WalletErrorCode =
+  | "rejected"
+  | "no_account"
+  | "wrong_chain"
+  | "insufficient_balance"
+  | "failed";
 
 export class WalletError extends Error {
   override readonly name = "WalletError";
@@ -101,8 +109,10 @@ export class WalletError extends Error {
  * Pays a quote from a wallet: a viem `WalletClient` (for example wagmi's `useWalletClient()`), or an
  * EIP-1193 provider such as a discovered `Wallet`'s. Connects (unless the client already has an
  * account), switches to (or adds) the quote's chain, and sends the ERC-20 `transfer` that the quote's
- * `payment_uri` states. Resolves with the transaction hash once the wallet has broadcast it; the
- * checkout's status follows the payment from there.
+ * `payment_uri` states. Before sending, it reads the account's token balance and, when it is below
+ * the quote's amount, sends nothing and throws `WalletError` `insufficient_balance`: the transfer
+ * would revert and still cost gas. Resolves with the transaction hash once the wallet has broadcast
+ * it; the checkout's status follows the payment from there.
  */
 export async function payWithWallet(
   wallet: WalletClient | EthereumProvider,
@@ -116,6 +126,16 @@ export async function payWithWallet(
       throw new WalletError("no_account", "The wallet shared no account");
     }
     await ensureChain(client, transfer.chainId);
+    const address = typeof account === "string" ? account : account.address;
+    const balance = await tokenBalance(client, transfer.token, address);
+    if (balance !== undefined && balance < transfer.amount) {
+      const symbol = quote.asset.toUpperCase();
+      throw new WalletError(
+        "insufficient_balance",
+        `Your wallet holds ${formatUnitsGrouped(balance, quote.decimals)} ${symbol}, less than the ` +
+          `${formatTokenAmount(quote)} ${symbol} to pay. Nothing was sent.`,
+      );
+    }
     return await client.writeContract({
       account,
       chain: knownChain(transfer.chainId) ?? null,
@@ -135,6 +155,19 @@ export async function payWithWallet(
   }
 }
 
+/**
+ * The account's balance of `token`, read through the wallet on its current chain; `undefined` when
+ * the wallet cannot read it. The check only spares the payer a reverting transfer, so a wallet that
+ * does not serve `eth_call` still pays.
+ */
+async function tokenBalance(wallet: WalletClient, token: Address, owner: Address): Promise<bigint | undefined> {
+  try {
+    return await readContract(wallet, { address: token, abi: erc20Abi, functionName: "balanceOf", args: [owner] });
+  } catch {
+    return undefined;
+  }
+}
+
 function isWalletClient(wallet: WalletClient | EthereumProvider): wallet is WalletClient {
   return "writeContract" in wallet;
 }

package/CHANGELOG.md

@@ -1,160 +0,0 @@
-# Changelog
-
-All notable changes to `@phala/pay` are recorded here. The format follows
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
-[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.3.0] - 2026-10-01
-
-### Changed (breaking)
-
-- `constructEvent` takes webhook public keys only in Standard Webhooks' `whpk_` form (`whpk_` and
-  the standard base64 of the key), as `GET /v1/attestation` lists them; a hex or bare base64 key
-  is refused.
-- `parseClientQuote` requires `confirmations`, an integer or `null`, as the service always sends
-  it.
-- `constructEvent` requires the event's `actor` and `request` (`null` or the causing request), as
-  the service always sends them, and refuses an envelope without them; `WebhookEvent.actor` and
-  `request` are no longer optional.
-
-### Fixed
-
-- `constructEvent` returns the event's `request` (the causing API request's `id` and
-  `idempotency_key`, or `null`), as `WebhookEvent` declares; it was dropped. A malformed `request`
-  is refused like any malformed event.
-
-## [0.2.0] - 2026-09-29
-
-### Changed (breaking)
-
-- `quoteAddress(forwarder, quote, treasury, account)` takes the treasury explicitly, like
-  `depositAddress`; it no longer reads the quote's own `treasury`, which a compromised service
-  could set to an attacker's with that treasury's valid address.
-
-- `quoteSalt(account, clientReferenceId, quoteId)` replaces `lockSalt`: a quote's address salt is
-  tagged `"quote"` (design D3; it was `"lock"`), so `quoteAddress` recomputes the service's
-  addresses again.
-
-- `<Checkout expectedAddress>` is required, as are `expectedAddress` in `createCheckout`,
-  `useCheckout`, `PhalaPay.checkout(clientSecret, { expectedAddress })`, and the second argument of
-  `retrieveQuote`/`PhalaPay.retrieveQuote`: the address your backend recomputed. A quote naming
-  another address fails closed with `CheckoutError` `address_mismatch`; the component shows
-  nothing to pay.
-- `ClientQuote` has `livemode` (the checkout shows "Test mode") and `payment_status: "reversed"`;
-  `CheckoutStatus` gains `reversed`, with "reversed" copy.
-
-### Added
-
-- `verifyQuoteAddress(pins, quote)` and `verifyDepositAddress(pins, address)` in
-  `@phala/pay/server` recompute an address from `AddressPins` you configure (`account`, `factory`,
-  `implementation`, `treasuries` per chain), never from the response's treasury, and throw
-  `AddressMismatchError`; in live mode a chain without a pinned treasury fails closed, and test mode
-  falls back to the response's treasury with a console warning.
-
-- `CheckoutError.requestId` (the failed response's `Request-Id`) and, for `rate_limited`,
-  `retryAfter` (its `Retry-After`, in seconds), which `createCheckout` and `<DepositAddress>` wait
-  before reading again.
-- `WebhookEvent.request` (the request that caused the event, or `null` for the service's
-  workers) and the documented `data.previous_attributes` of `*.updated` events.
-
-- `<DepositAddress clientSecret apiBase pollInterval?>` follows the address's payments and shows
-  each within about a block of arriving ("1.5 PHA received on Sepolia, 1 confirmation"), then
-  credited, rejected, or reversed; `retrieveDepositAddress`, `parseClientDepositAddress`, and
-  `depositAddressIdFromClientSecret` read the same public view.
-- `@phala/pay/server`, which takes no secret key: `constructEvent(payload, headers, publicKeys,
-  { expectedAccount, expectedLivemode })` verifies Standard Webhooks `v1a` deliveries with
-  WebCrypto (Node 20+, Deno, Bun, edge runtimes), failing closed for another account or mode;
-  `forwarderAddress`, `quoteSalt`, `depositAddressSalt`, `quoteAddress`, and `depositAddress`
-  recompute addresses; `flushTransaction`, `flushTransactions`, `safeBatch`, and `batchChecksum`
-  build sweeps offline, with the Transaction Builder's `BatchFile` type.
-
-- `<DepositAddress depositAddress chainId? asset?>` (`@phala/pay/react`): a customer's persistent
-  deposit address, one address for all supported tokens and networks. The payer picks a network
-  and a token; it shows a QR code of that token's EIP-681 request, the token contract and address
-  to copy (each network's own address where they differ), and "send only supported tokens; any
-  amount, credited at the market rate when it arrives" copy. `depositAddressTransfer(network,
-  asset)` reads and checks one token's amount-less `payment_uri`, and `parseTransferUri(uri)` is
-  the EIP-681 ERC-20 transfer parser `quoteTransfer` uses.
-
-- `<Checkout walletClient>` and `payWithWallet(walletClient, quote)`: pay with the page's own viem
-  `WalletClient`, such as wagmi's `useWalletClient()` (RainbowKit, ConnectKit, AppKit). The wallet
-  tab then uses its account and switches its chain, without listing the browser's wallets.
-
-### Changed
-
-- `<Checkout>` copy for fast credit: a seen payment reads "Payment received, N confirmations.
-  Crediting in about 30 seconds"; `confirming` and `credited` are documented for crediting at the
-  route's confirmation (two blocks on Ethereum) instead of finality.
-- `watchWallets` discovers EIP-6963 wallets through [mipd](https://github.com/wevm/mipd), wagmi's
-  discovery store, now a dependency; the `window.ethereum` fallback stays. Wallet errors are
-  classified with viem's `UserRejectedRequestError` and `SwitchChainError`.
-
-## [0.1.2] - 2026-09-27
-
-### Added
-
-- `CheckoutError.requestId` (the failed response's `Request-Id`) and, for `rate_limited`,
-  `retryAfter` (its `Retry-After`, in seconds), which `createCheckout` and `<DepositAddress>` wait
-  before reading again.
-- `WebhookEvent.request` (the request that caused the event, or `null` for the service's
-  workers) and the documented `data.previous_attributes` of `*.updated` events.
-
-- `<Checkout onChange>`: called once per status change with `{ status, quote, error }`, like
-  Stripe Elements' `onChange`, so the page can react to `seen` or `confirming` without its own
-  polling.
-
-### Fixed
-
-- The transaction link in `<Checkout>` uses the text color with an underline instead of
-  `colorPrimary`, so it stays readable with a light brand color.
-
-## [0.1.1] - 2026-09-27
-
-### Added
-
-- `CheckoutError.requestId` (the failed response's `Request-Id`) and, for `rate_limited`,
-  `retryAfter` (its `Retry-After`, in seconds), which `createCheckout` and `<DepositAddress>` wait
-  before reading again.
-- `WebhookEvent.request` (the request that caused the event, or `null` for the service's
-  workers) and the documented `data.previous_attributes` of `*.updated` events.
-
-- `appearance.variables.accessibleColorOnColorPrimary` (`--pp-accessible-color-on-color-primary`,
-  default `#ffffff`): the color of text on a `colorPrimary` background, such as the pay button's
-  label, so a light brand primary stays readable. Same name and meaning as Stripe's current
-  Appearance API variable.
-
-### Fixed
-
-- `<Checkout>` shows the full transaction hash after a wallet payment, wrapping in monospace,
-  instead of truncating it, so a payer can verify every character; a long token amount wraps
-  instead of overflowing.
-
-## [0.1.0] - 2026-09-27
-
-### Added
-
-- `CheckoutError.requestId` (the failed response's `Request-Id`) and, for `rate_limited`,
-  `retryAfter` (its `Retry-After`, in seconds), which `createCheckout` and `<DepositAddress>` wait
-  before reading again.
-- `WebhookEvent.request` (the request that caused the event, or `null` for the service's
-  workers) and the documented `data.previous_attributes` of `*.updated` events.
-
-- `PhalaPay({ apiBase })`: `retrieveQuote(clientSecret)` reads a quote's public view
-  (`GET /v1/quotes/{id}?client_secret=…`) and `checkout(clientSecret)` follows it, exposing the
-  payer-facing status (also `createCheckout` and `retrieveQuote`).
-- `watchWallets` (EIP-6963, `window.ethereum` fallback) and `payWithWallet`: pay a quote's EIP-681
-  ERC-20 transfer from a browser wallet, switching or adding the chain.
-- `@phala/pay/react`: `<Checkout>` with wallet ("Pay with crypto", `buttonText`), QR code, and
-  manual payment, live status, and Stripe-style `appearance`; `useCheckout`.
-- `formatTokenAmount(quote, locale?)` shows the exact token amount grouped for the locale and
-  without trailing zeros (`1,273.9185`); `tokenAmount(quote)` is the plain decimal a wallet
-  accepts, which `<Checkout>`'s "Exact amount" copies.
-
-[Unreleased]: https://github.com/Phala-Network/phala-pay/compare/sdk-js-v0.3.0...HEAD
-[0.3.0]: https://github.com/Phala-Network/phala-pay/compare/sdk-js-v0.2.0...sdk-js-v0.3.0
-[0.2.0]: https://github.com/Phala-Network/phala-pay/compare/sdk-js-v0.1.2...sdk-js-v0.2.0
-[0.1.2]: https://github.com/Phala-Network/phala-pay/compare/sdk-js-v0.1.1...sdk-js-v0.1.2
-[0.1.1]: https://github.com/Phala-Network/phala-pay/compare/sdk-js-v0.1.0...sdk-js-v0.1.1
-[0.1.0]: https://github.com/Phala-Network/phala-pay/releases/tag/sdk-js-v0.1.0