@phala/pay 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -6,10 +6,82 @@ All notable changes to `@phala/pay` are recorded here. The format follows
 
 ## [Unreleased]
 
+## [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.
@@ -23,6 +95,12 @@ All notable changes to `@phala/pay` are recorded here. The format follows
 
 ### 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
@@ -38,6 +116,12 @@ All notable changes to `@phala/pay` are recorded here. The format follows
 
 ### 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`).
@@ -49,7 +133,8 @@ All notable changes to `@phala/pay` are recorded here. The format follows
   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.1.2...HEAD
+[unreleased]: https://github.com/Phala-Network/phala-pay/compare/sdk-js-v0.2.0...HEAD
+[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

package/README.md

@@ -11,38 +11,34 @@ Python SDK (`phala-pay`) and fulfils from the signed `deposit.credited` webhook.
 npm install @phala/pay viem
 ```
 
-Peer dependencies: `viem` 2, and `react` 18 or 19 for `@phala/pay/react`. Nothing else:
-wallets are found with EIP-6963 (with a `window.ethereum` fallback), not wagmi or WalletConnect.
-
-Until the first npm release, install from the repository with pnpm. The package builds itself
-on install, which pnpm allows only for listed git dependencies: the first `pnpm add` stops and
-prints an `allowBuilds` entry naming the exact commit; add it to `pnpm-workspace.yaml` and run the
-same command again.
-
-```sh
-pnpm add "github:Phala-Network/phala-pay#main&path:/sdk/js"
-```
-
-```yaml
-# pnpm-workspace.yaml: the entry pnpm printed
-allowBuilds:
-  "@phala/pay@https://codeload.github.com/Phala-Network/phala-pay/tar.gz/<commit>#path:/sdk/js": true
-```
+Peer dependencies: `viem` 2, and `react` 18 or 19 for `@phala/pay/react`. Browser wallets are
+found with EIP-6963 through [mipd](https://github.com/wevm/mipd), wagmi's discovery store (with a
+`window.ethereum` fallback for wallets that do not announce themselves). If your page already
+connects a wallet with wagmi, RainbowKit, ConnectKit, or AppKit, pass it in instead; see
+[Your own wallet connection](#your-own-wallet-connection).
 
 ## Quickstart
 
-1. Your backend creates a quote (`POST /v1/quotes`, signed with the product key) and returns only its
-   `client_secret` to the signed-in user's browser.
-2. Render the checkout with it:
+1. Your backend creates a quote (`POST /v1/quotes` with its secret key, for example
+   `phala-pay`'s `pay.quotes.create`), recomputes its address from the pinned forwarder (the
+   Python SDK does it on every call), and returns only its `client_secret` and that address to
+   the signed-in user's browser.
+2. Render the checkout with them:
 
 ```tsx
 "use client";
 import { Checkout } from "@phala/pay/react";
 
-export function TopUp(props: { clientSecret: string; onPaid: () => void; onRetry: () => void }) {
+export function TopUp(props: {
+  clientSecret: string;
+  expectedAddress: string;
+  onPaid: () => void;
+  onRetry: () => void;
+}) {
   return (
     <Checkout
       clientSecret={props.clientSecret}
+      expectedAddress={props.expectedAddress}
       apiBase="https://pay.example.com"
       onSuccess={props.onPaid}
       onExpire={props.onRetry}
@@ -59,6 +55,10 @@ The component reads `GET /v1/quotes/{id}?client_secret=…` every three seconds.
 public (`Access-Control-Allow-Origin: *`) and shows only what the payer needs: the amount, the
 token, the chain, the deposit address, the EIP-681 payment request, the expiry, and the payment
 status. Keep the client secret out of logs and URLs you share; anyone holding it can see that view.
+`expectedAddress` is required and fails closed: when the quote the service returns names another
+address, the checkout shows "This payment address could not be verified" and nothing to pay (a
+compromised service cannot make the page show its own address). A test-mode quote says "Test
+mode".
 
 ### Statuses
 
@@ -67,9 +67,10 @@ status. Keep the client secret out of logs and URLs you share; anyone holding it
 | `loading` | Loading payment details |
 | `waiting` | Payment options, the exact amount, and the time left |
 | `seen` | Payment in a block, with its confirmations (a reorg can still remove it) |
-| `confirming` | Payment final, being valued and screened |
-| `credited` | Credited; `onSuccess` is called once |
-| `rejected` | Final but will not be credited; the payer contacts support |
+| `confirming` | Payment at the route's confirmation (two blocks on Ethereum), being valued and screened |
+| `credited` | Credited, typically about 30 seconds after paying; `onSuccess` is called once |
+| `rejected` | Will not be credited; the payer contacts support |
+| `reversed` | Credited, then its transaction left the chain before finality: the payment did not happen |
 | `expired`, `canceled` | The address is hidden; `onExpire` is called once |
 | `error` | The client secret is not valid |
 
@@ -77,14 +78,81 @@ status. Keep the client secret out of logs and URLs you share; anyone holding it
 Elements' `onChange`, for example to hide your own "new payment" control while a payment is
 `seen` or `confirming`.
 
+To resume after a reload, keep the client secret in the browser (for example `localStorage`, per
+signed-in account) until the status is `credited`, `expired`, `canceled`, or `error`. Tell a
+payer who is waiting that the payment is credited in about 30 seconds and the credit arrives on
+its own.
+
+A credit is made before Ethereum finality (about 15 minutes). In the rare case that a reorg drops
+the payment's transaction, your backend receives `deposit.reversed` and claws the credit back as
+for `deposit.refunded`; the checkout itself only reflects the quote.
+
 The payment options disappear once a payment is seen, and at `expires_at`. A payment of a different
 amount, or after expiry, is still credited, at the market price instead of the quote's.
 
+### Your own wallet connection
+
+By default the wallet tab lists the browser's wallets. If your page already connects one, pass its
+viem `WalletClient` as `walletClient`: the wallet tab then pays with that client and its account
+(switching its chain to the quote's) and lists nothing else. With wagmi, including RainbowKit,
+ConnectKit, and AppKit, that is `useWalletClient()`:
+
+```tsx
+"use client";
+import { Checkout } from "@phala/pay/react";
+import { useWalletClient } from "wagmi";
+
+export function TopUp({ clientSecret }: { clientSecret: string }) {
+  const { data: walletClient } = useWalletClient();
+  return (
+    <Checkout
+      clientSecret={clientSecret}
+      expectedAddress={expectedAddress}
+      apiBase="https://pay.example.com"
+      walletClient={walletClient}
+    />
+  );
+}
+```
+
+While no wallet is connected (`walletClient` is `undefined`), the tab lists the browser's wallets
+as usual. The QR code and manual tabs do not change.
+
+### A customer's deposit address
+
+For top-ups of any amount, your backend creates the customer's persistent deposit address with
+`POST /v1/deposit_addresses` (secret key) and passes its `address` and `networks` to the page:
+one address for all supported tokens and networks. `<DepositAddress>` lets the payer pick a
+network and a token and shows a QR code of that token's transfer request, the token contract, and
+the address to copy, with "send only supported tokens" and "credited at the market rate when it
+arrives" copy; where a network's address differs (another treasury), it shows that network's own.
+Credit the customer from the `deposit.credited` webhook.
+
+```tsx
+import { DepositAddress } from "@phala/pay/react";
+
+<DepositAddress
+  depositAddress={{ address, networks }}
+  clientSecret={clientSecret} // the same response's client_secret: shows payments as they arrive
+  apiBase="https://pay.example.com"
+  chainId={84532}
+  asset="usdc"
+/>;
+```
+
+With `clientSecret` and `apiBase` it reads the address's public view every three seconds and lists
+its payments of the last 24 hours: "1.5 PHA received on Sepolia, 1 confirmation" within about a
+block of the transfer, then "credited" (or rejected or reversed). Display only.
+
+`depositAddressTransfer(network, asset)` reads and checks one token's amount-less EIP-681
+`payment_uri` without React.
+
 ## Appearance
 
 ```tsx
 <Checkout
   clientSecret={clientSecret}
+  expectedAddress={expectedAddress}
   apiBase={apiBase}
   appearance={{
     theme: "dark",
@@ -121,8 +189,8 @@ readable.
 import { PhalaPay, payWithWallet, watchWallets, type Wallet } from "@phala/pay";
 
 const pay = new PhalaPay({ apiBase: "https://pay.example.com" });
-const quote = await pay.retrieveQuote(clientSecret); // one read of the public view
-const checkout = pay.checkout(clientSecret); // or follow it until it settles
+const quote = await pay.retrieveQuote(clientSecret, expectedAddress); // one read, checked
+const checkout = pay.checkout(clientSecret, { expectedAddress }); // or follow it until it settles
 const unsubscribe = checkout.subscribe(({ status, quote, error }) => render(status, quote, error));
 
 const stop = watchWallets((wallets) => showWalletButtons(wallets));
@@ -142,10 +210,42 @@ unsubscribe();
 checkout.destroy();
 ```
 
-`payWithWallet` connects, switches the wallet to the quote's chain (adding Ethereum, Sepolia,
+`payWithWallet` takes a discovered wallet's EIP-1193 provider or a viem `WalletClient` (such as
+wagmi's `useWalletClient()` or `getWalletClient(config)`; its account is used without asking to
+connect again). It connects, switches the wallet to the quote's chain (adding Ethereum, Sepolia,
 Base, or Base Sepolia when the wallet lacks it), and sends the ERC-20 `transfer` stated by the
 quote's `payment_uri`, after checking that it pays exactly `amount_atomic` to `address`.
 
+## Server helpers
+
+`@phala/pay/server` is for your backend and takes no API key (call the API itself with a
+restricted key, `ppay_rk_…`, from the backend only, never the browser):
+
+```ts
+import { constructEvent, flushTransactions, safeBatch, verifyQuoteAddress } from "@phala/pay/server";
+
+// Your pins, configured on your server and never read from the service. The address is derived
+// from your treasury, not the quote's: a mismatch throws AddressMismatchError, and in live mode a
+// chain without a pinned treasury fails closed.
+const pins = { account: "acct_…", factory: FACTORY, implementation: IMPLEMENTATION, treasuries: { 1: TREASURY } };
+const expectedAddress = verifyQuoteAddress(pins, quote); // pass it to <Checkout expectedAddress>
+
+// Standard Webhooks v1a (ed25519, WebCrypto: Node 20+, Deno, Bun, edge runtimes). Fails closed
+// unless the signature verifies with a pinned key and the event is your account's in this mode.
+const event = await constructEvent(rawBody, request.headers, WEBHOOK_PUBLIC_KEYS, {
+  expectedAccount: "acct_…",
+  expectedLivemode: false,
+});
+
+// Sweeping, offline: forwarders from GET /v1/forwarders?sweepable=<token>.
+const calls = flushTransactions(forwarders, PHA);
+const batchFile = safeBatch(1, TREASURY_SAFE, calls); // Safe Transaction Builder JSON
+```
+
+`verifyDepositAddress(pins, address)` checks every network of a deposit address the same way.
+`quoteAddress`, `depositAddress`, `forwarderAddress`, `quoteSalt`, and `depositAddressSalt`
+recompute an address offline from a treasury you pass, as the Python SDK does.
+
 ## Development
 
 ```sh
@@ -156,7 +256,8 @@ pnpm run e2e:docker  # the same, with Chromium from Playwright's image (as CI ru
 ```
 
 The end-to-end tests start Anvil as Sepolia, deploy a test token, and pay a quote from a mocked
-EIP-6963 wallet backed by the node, then decode the QR code and exercise the manual details.
+EIP-6963 wallet backed by the node (and again through a viem `WalletClient` passed as
+`walletClient`), then decode the QR code and exercise the manual details.
 
 ## Releases
 

package/dist/checkout.d.ts

@@ -3,18 +3,39 @@ import { type ClientQuote } from "./quote.js";
  * What the payer sees:
  * - `loading` until the quote is first read;
  * - `waiting` for a payment, until `expires_at`;
- * - `seen` once a transfer is in a block, `confirming` once it is final and being valued;
- * - `credited`, or `rejected` for a final payment that will not be credited;
+ * - `seen` once a transfer is in a block, `confirming` once it reaches the route's confirmation
+ *   (two blocks on Ethereum) and is being valued;
+ * - `credited` (about 30 seconds after paying), or `rejected` for a payment that will not be
+ *   credited;
+ * - `reversed` when a credited payment's transaction left the chain before finality;
  * - `expired` or `canceled` without a payment;
- * - `error` when the client secret is not valid.
+ * - `error` when the client secret is not valid, or the quote's address is not the one your
+ *   backend expects (`address_mismatch`): nothing is shown to pay.
  */
-export type CheckoutStatus = "loading" | "waiting" | "seen" | "confirming" | "credited" | "rejected" | "expired" | "canceled" | "error";
-export type CheckoutErrorCode = "invalid_client_secret" | "rate_limited" | "network_error" | "invalid_response" | "api_error";
+export type CheckoutStatus = "loading" | "waiting" | "seen" | "confirming" | "credited" | "rejected" | "reversed" | "expired" | "canceled" | "error";
+export type CheckoutErrorCode = "invalid_client_secret" | "address_mismatch" | "rate_limited" | "network_error" | "invalid_response" | "api_error";
+export interface CheckoutErrorOptions extends ErrorOptions {
+    /** The failed response's `Request-Id`, `req_…`, to quote to support. */
+    requestId?: string;
+    /** For `rate_limited`: the seconds the service asked to wait (`Retry-After`). */
+    retryAfter?: number;
+}
 export declare class CheckoutError extends Error {
     readonly code: CheckoutErrorCode;
     readonly name = "CheckoutError";
-    constructor(code: CheckoutErrorCode, message: string, options?: ErrorOptions);
+    /** The failed response's `Request-Id`, when the service answered. */
+    readonly requestId: string | undefined;
+    /** For `rate_limited`: the seconds to wait before the next read. */
+    readonly retryAfter: number | undefined;
+    constructor(code: CheckoutErrorCode, message: string, options?: CheckoutErrorOptions);
 }
+/**
+ * The error of a failed read of a public view, with the response's `Request-Id` and, on `429`,
+ * its `Retry-After`.
+ */
+export declare function responseError(response: Response, notFound: string): CheckoutError;
+/** The delay before the next read after `failures` failed ones, at least what `error` asks. */
+export declare function pollDelay(interval: number, failures: number, error: CheckoutError | null): number;
 export interface CheckoutState {
     status: CheckoutStatus;
     quote: ClientQuote | null;
@@ -24,6 +45,12 @@ export interface CheckoutState {
 export interface CheckoutOptions {
     /** 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. The
+     * checkout fails closed, showing nothing to pay, when the quote read from the service names
+     * another address.
+     */
+    expectedAddress: string;
     /** The service origin, for example `https://topup.example.com`. */
     apiBase: string;
     /** Milliseconds between status reads; default 3000. */
@@ -43,12 +70,15 @@ export interface CheckoutSession {
 }
 export interface RetrieveQuoteOptions {
     clientSecret: string;
+    /** The address your backend recomputed; a quote naming another one is refused. */
+    expectedAddress: string;
     apiBase: string;
     fetch?: typeof globalThis.fetch;
 }
 /**
  * Reads a quote's public view once, as Stripe.js's `retrievePaymentIntent(clientSecret)` does.
- * Rejects with a `CheckoutError`: `invalid_client_secret` for an unknown quote or secret.
+ * Rejects with a `CheckoutError`: `invalid_client_secret` for an unknown quote or secret,
+ * `address_mismatch` for a quote whose address is not `expectedAddress`.
  */
 export declare function retrieveQuote(options: RetrieveQuoteOptions): Promise<ClientQuote>;
 /** The payer-facing status of a quote at `nowSeconds`. */

package/dist/checkout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6C,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzF;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,SAAS,GACT,MAAM,GACN,YAAY,GACZ,UAAU,GACV,UAAU,GACV,SAAS,GACT,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GACzB,uBAAuB,GACvB,cAAc,GACd,eAAe,GACf,kBAAkB,GAClB,WAAW,CAAC;AAEhB,qBAAa,aAAc,SAAQ,KAAK;IAIpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB;IAHlC,SAAkB,IAAI,mBAAmB;gBAG9B,IAAI,EAAE,iBAAiB,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAIzB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,gGAAgG;IAChG,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,IAAI,aAAa,CAAC;IAC1B,gFAAgF;IAChF,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChE,uDAAuD;IACvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,qBAAqB;IACrB,OAAO,IAAI,IAAI,CAAC;CACjB;AAKD,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CAuBvF;AAED,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAWrF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAgGxE"}
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AACA,OAAO,EAA6C,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,SAAS,GACT,MAAM,GACN,YAAY,GACZ,UAAU,GACV,UAAU,GACV,UAAU,GACV,SAAS,GACT,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GACzB,uBAAuB,GACvB,kBAAkB,GAClB,cAAc,GACd,eAAe,GACf,kBAAkB,GAClB,WAAW,CAAC;AAEhB,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAc,SAAQ,KAAK;IAQpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB;IAPlC,SAAkB,IAAI,mBAAmB;IACzC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAG7B,IAAI,EAAE,iBAAiB,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,oBAAoB;CAMjC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAkBjF;AAED,+FAA+F;AAC/F,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,MAAM,CAGjG;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,gGAAgG;IAChG,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,IAAI,aAAa,CAAC;IAC1B,gFAAgF;IAChF,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChE,uDAAuD;IACvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,qBAAqB;IACrB,OAAO,IAAI,IAAI,CAAC;CACjB;AAKD,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CA0BvF;AASD,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAWrF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAqGxE"}

package/dist/checkout.js

@@ -1,42 +1,80 @@
+import { getAddress, isAddress, isAddressEqual } from "viem";
 import { parseClientQuote, quoteIdFromClientSecret } from "./quote.js";
 export class CheckoutError extends Error {
     code;
     name = "CheckoutError";
+    /** The failed response's `Request-Id`, when the service answered. */
+    requestId;
+    /** For `rate_limited`: the seconds to wait before the next read. */
+    retryAfter;
     constructor(code, message, options) {
         super(message, options);
         this.code = code;
+        this.requestId = options?.requestId;
+        this.retryAfter = options?.retryAfter;
     }
 }
+/**
+ * The error of a failed read of a public view, with the response's `Request-Id` and, on `429`,
+ * its `Retry-After`.
+ */
+export function responseError(response, notFound) {
+    const header = response.headers.get("request-id");
+    const requestId = header === null ? {} : { requestId: header };
+    if (response.status === 404) {
+        return new CheckoutError("invalid_client_secret", notFound, requestId);
+    }
+    if (response.status === 429) {
+        const seconds = Number(response.headers.get("retry-after"));
+        return new CheckoutError("rate_limited", "too many status requests", {
+            ...requestId,
+            ...(Number.isFinite(seconds) && seconds > 0 ? { retryAfter: seconds } : {}),
+        });
+    }
+    return new CheckoutError("api_error", `the payment service answered ${response.status}`, requestId);
+}
+/** The delay before the next read after `failures` failed ones, at least what `error` asks. */
+export function pollDelay(interval, failures, error) {
+    const backoff = failures === 0 ? interval : Math.min(interval * 2 ** failures, MAX_BACKOFF);
+    return Math.max(backoff, (error?.retryAfter ?? 0) * 1000);
+}
 const DEFAULT_POLL_INTERVAL = 3000;
 const MAX_BACKOFF = 30_000;
 /**
  * Reads a quote's public view once, as Stripe.js's `retrievePaymentIntent(clientSecret)` does.
- * Rejects with a `CheckoutError`: `invalid_client_secret` for an unknown quote or secret.
+ * Rejects with a `CheckoutError`: `invalid_client_secret` for an unknown quote or secret,
+ * `address_mismatch` for a quote whose address is not `expectedAddress`.
  */
 export async function retrieveQuote(options) {
     const quoteId = quoteIdFromClientSecret(options.clientSecret);
+    const expected = expectedAddress(options.expectedAddress);
     const base = options.apiBase.replace(/\/+$/, "");
     const url = `${base}/v1/quotes/${quoteId}?client_secret=${encodeURIComponent(options.clientSecret)}`;
     const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
     // A simple GET with no custom headers, so the browser sends no CORS preflight.
     const response = await fetchImpl(url, { cache: "no-store", credentials: "omit" });
-    if (response.status === 404) {
-        throw new CheckoutError("invalid_client_secret", "the quote or its client secret is unknown");
-    }
-    if (response.status === 429) {
-        throw new CheckoutError("rate_limited", "too many status requests");
-    }
     if (!response.ok) {
-        throw new CheckoutError("api_error", `the payment service answered ${response.status}`);
+        throw responseError(response, "the quote or its client secret is unknown");
     }
+    let quote;
     try {
-        return parseClientQuote(await response.json());
+        quote = parseClientQuote(await response.json());
     }
     catch (cause) {
         throw new CheckoutError("invalid_response", "unexpected response from the payment service", {
             cause,
         });
     }
+    if (!isAddressEqual(getAddress(quote.address), expected)) {
+        throw new CheckoutError("address_mismatch", "the quote's address is not the one the merchant expects");
+    }
+    return quote;
+}
+function expectedAddress(value) {
+    if (!isAddress(value, { strict: false })) {
+        throw new TypeError("expectedAddress is not an address");
+    }
+    return getAddress(value);
 }
 /** The payer-facing status of a quote at `nowSeconds`. */
 export function checkoutStatus(quote, nowSeconds) {
@@ -59,6 +97,7 @@ export function checkoutStatus(quote, nowSeconds) {
  */
 export function createCheckout(options) {
     quoteIdFromClientSecret(options.clientSecret);
+    expectedAddress(options.expectedAddress);
     const now = options.now ?? Date.now;
     const interval = options.pollInterval ?? DEFAULT_POLL_INTERVAL;
     const listeners = new Set();
@@ -84,6 +123,7 @@ export function createCheckout(options) {
             status === "error" ||
             status === "credited" ||
             status === "rejected" ||
+            status === "reversed" ||
             status === "canceled" ||
             (status === "expired" && quote?.status === "expired"));
     }
@@ -99,7 +139,11 @@ export function createCheckout(options) {
                 : new CheckoutError("network_error", "could not reach the payment service", { cause });
             failures += 1;
             const quote = state.quote;
-            if (error.code === "invalid_client_secret") {
+            if (error.code === "address_mismatch") {
+                // Fail closed: forget the quote, so nothing about its address is shown.
+                setState({ status: "error", quote: null, error });
+            }
+            else if (error.code === "invalid_client_secret") {
                 setState({ status: "error", quote, error });
             }
             else {
@@ -121,7 +165,7 @@ export function createCheckout(options) {
         if (finished()) {
             return;
         }
-        const delay = failures === 0 ? interval : Math.min(interval * 2 ** failures, MAX_BACKOFF);
+        const delay = pollDelay(interval, failures, state.error);
         timer = setTimeout(() => {
             void refresh().then(schedule);
         }, delay);

package/dist/checkout.js.map

@@ -1 +1 @@
-{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -7,20 +7,21 @@ export interface PhalaPayOptions {
 }
 /**
  * The browser client, in the shape of Stripe.js: it holds no key, only the service origin, and
- * works with the `client_secret` your backend got from `POST /v1/quotes`.
+ * works with the `client_secret` your backend got from `POST /v1/quotes` and the `address` its
+ * SDK recomputed (`expectedAddress`).
  *
  *     const pay = new PhalaPay({ apiBase: "https://pay.example.com" });
- *     const quote = await pay.retrieveQuote(clientSecret);
- *     const session = pay.checkout(clientSecret);
+ *     const quote = await pay.retrieveQuote(clientSecret, expectedAddress);
+ *     const session = pay.checkout(clientSecret, { expectedAddress });
  *     session.subscribe(({ status }) => render(status));
  */
 export declare class PhalaPay {
     #private;
     readonly apiBase: string;
     constructor(options: PhalaPayOptions);
-    /** Reads the quote's public view once. */
-    retrieveQuote(clientSecret: string): Promise<ClientQuote>;
-    /** Follows the quote until it is credited, rejected, canceled, or expired. */
-    checkout(clientSecret: string, options?: Pick<CheckoutOptions, "pollInterval">): CheckoutSession;
+    /** Reads the quote's public view once, refusing one whose address is not `expectedAddress`. */
+    retrieveQuote(clientSecret: string, expectedAddress: string): Promise<ClientQuote>;
+    /** Follows the quote until it is credited, rejected, reversed, canceled, or expired. */
+    checkout(clientSecret: string, options: Pick<CheckoutOptions, "expectedAddress" | "pollInterval">): CheckoutSession;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,qBAAa,QAAQ;;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGb,OAAO,EAAE,eAAe;IAKpC,0CAA0C;IAC1C,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAIzD,8EAA8E;IAC9E,QAAQ,CACN,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,cAAc,CAAM,GAClD,eAAe;CAYnB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,qBAAa,QAAQ;;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGb,OAAO,EAAE,eAAe;IAKpC,+FAA+F;IAC/F,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IASlF,wFAAwF;IACxF,QAAQ,CACN,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,iBAAiB,GAAG,cAAc,CAAC,GACjE,eAAe;CAYnB"}