@phala/pay 0.10.10 → 0.11.1

package/README.md

@@ -57,6 +57,9 @@ connects a wallet with wagmi, RainbowKit, ConnectKit, or AppKit, pass it in inst
 3. Credit the account when your webhook endpoint receives `deposit.credited`. `onSuccess` is for the
    UI only: the browser is not a trusted source of payment.
 
+To let the payer choose the token and network first and create the quote only when they submit,
+render [`<PaymentElement>`](#the-payment-element) instead.
+
 The component reads `GET /v1/quotes/{id}?client_secret=…` about every three seconds. That endpoint is
 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
@@ -154,12 +157,99 @@ export function TopUp(props: { clientSecret: string; expectedAddress: string })
 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.
 
+### The payment element
+
+`<PaymentElement>` is the whole payment in one component, like Stripe's Payment Element with a
+deferred intent: it offers your tokens and networks, creates nothing until the payer submits, then
+calls your `createQuote` with the chosen option and an idempotency key, and shows that quote's
+`<Checkout>`. Your backend creates the quote with its API key, for the chosen `chain_id` and
+`asset`, with that key as its `Idempotency-Key`, and returns its checkout params
+(`pay.checkoutParams(quote)` in `@phala/pay-server`).
+
+```tsx
+import { paymentOptions } from "@phala/pay";
+import { PaymentElement } from "@phala/pay-react";
+
+<PaymentElement
+  options={paymentOptions(config.assets)} // GET /v1/config's assets, from your backend
+  amount={2500} // minor units of `currency` (default "usd"): "Pay $25.00 in USDC"
+  createQuote={(option, { idempotencyKey }) =>
+    api.createTopUp({ amount: 2500, chain_id: option.chain_id, asset: option.asset, idempotencyKey })
+  }
+  createDepositAddress={() => api.depositAddress()} // optional: "Use a deposit address"
+  apiBase="https://pay.example.com"
+  renderDetail={(option) => (option.asset === "usdc" ? "$1.00" : "Market rate")}
+  onSuccess={() => router.refresh()}
+/>;
+```
+
+- `createQuote(option, { idempotencyKey })` is called once per submit, with the very object of
+  `options` the payer chose; a submit while one is pending is ignored. It resolves with
+  `{ clientSecret, expectedAddress, apiBase? }`; `apiBase` falls back to the prop. A rejection
+  shows "Could not start the payment. Try again." and calls `onError(error)`. To show your own
+  reason in that alert instead, pass `errorMessage(cause)`: a non-empty string replaces the text,
+  and `null` or `undefined` keeps it. It applies to `createDepositAddress` too.
+- Create the quote with `idempotencyKey` as its `Idempotency-Key`, not an order id of yours: the
+  key is a new random UUID for each quote the payer asks for (another option or amount, or a new
+  quote after going back from one) and the same only when they retry after `createQuote` failed
+  with the same option, `amount`, and `currency`, so that a retry returns the quote a lost response
+  created. One key per order would answer another option with `400 idempotency_key_reused`, and a
+  new quote with the expired one. If your quote varies by anything else between attempts (a field
+  of your own form, say), pass it as `amount` or give the element a new `key` when it changes, or
+  a retry would reuse a key with another body.
+- After the quote: the checkout, and a way back to the options ("Choose another token or
+  network") until a payment is on its way, then "Start over" if it does not complete or "Start a
+  new payment" once credited.
+- `createDepositAddress(option)` adds "Use a deposit address", for payers sending from an exchange
+  or any wallet: it resolves with the deposit address's `address` and `networks` and, to follow its
+  payments, `clientSecret`; the element shows `<DepositAddress>` at the chosen option. Under the
+  link it states the chosen option's per-transfer limits when it carries them, as a
+  `GET /v1/config` asset does: "Send at least $5.00 and up to 10,100 USDC per transfer on Base from
+  an exchange or another wallet." Without them it says the address shows its limits.
+- Your own button: pass `hideSubmit` and an `id`, and give your button `type="submit" form={id}`
+  (or call `requestSubmit()` on the form with that id). The element is a `<form>`: do not nest it
+  in another one.
+- `value` and `onOptionChange` control the choice (`defaultValue` sets the first one otherwise);
+  `onChange({ step, checkout })` reports each step (`options`, `creating`, `checkout`,
+  `deposit_address`) and, while paying, each checkout status change; `onSuccess`, `onExpire`,
+  `onWalletError`, `walletClient`, `pollInterval`, and `appearance` are `<Checkout>`'s.
+
+### Payment options
+
+`<PaymentOptionPicker>` is the element's choice on its own, as exchanges and wallets ask for it:
+a "Token" field, then a "Network" field listing only the networks that take the chosen token,
+side by side where the container is 480px or wider and stacked below that. Each is a select-only
+combobox (WAI-ARIA Authoring Practices): a quiet field showing the chosen item's icon and name,
+whose listbox opens under it (over it where there is more room above), by pointer or keyboard
+(arrows, Home, End, Page Up and Down, typing the name, Enter or Space to choose, Escape or a
+press elsewhere to close); its label focuses it. Where the browser has popovers, the open listbox
+is in the top layer, so a card or modal with `overflow: hidden` does not clip it, while it stays
+inside your dialog in the document (a modal library does not take a press on it for one outside
+the dialog). Changing the token keeps the network
+when it takes the new token, else takes the first that does. A test network shows a muted
+"Testnet" after its name; `renderDetail(option)` is one muted line under the fields, about the
+chosen option. Both fields show even with one option. It is controlled (`value`, `onChange`), and
+`onChange` receives the very object of `options` the payer chose; `label` (default "Pay with")
+names the group for assistive technology.
+
+```tsx
+<PaymentOptionPicker options={options} value={option} onChange={setOption} label="Pay with" />
+```
+
+`paymentOptions(source)` builds the options, in order and each once: from a flat list such as
+`GET /v1/config`'s `assets` (the same objects), or from networks with their tokens such as a
+deposit address's `networks` (each option then carries its `network` and `token`).
+`samePaymentOption(a, b)` compares by chain and case-insensitive asset code;
+`paymentOptionLabel(option)` is `USDC · Ethereum`; `assetName("usdc")` is `USD Coin`,
+`assetSymbol` the upper-case code, `networkName(chainId)` the chain's name, `isTestnet(chainId)`
+whether it is a known test network, and `transactionUrl` / `addressUrl` its block explorer links.
+
 ### A customer's deposit address
 
 For top-ups within your deposit limits, your backend creates the customer's persistent deposit address with
 `POST /v1/deposit_addresses` (its API 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
+one address for all supported tokens and networks. `<DepositAddress>` lets the payer pick a token
+and its network (the payment options' two fields, shown even when there is only one of each) and shows a QR code of that token's transfer request, the token contract, and
 the address to copy, with the selected token’s per-transfer USD credit minimum (`min_amount`,
 in cents) and token maximum (`max_deposit_atomic`). A positive `min_deposit_atomic` adds the
 independent token minimum; a zero atomic minimum is omitted. Atomic-unit strings are formatted
@@ -223,14 +313,14 @@ the theme (or map the colors) that suits its background.
 
 | CSS custom property             | Light default     | Dark default | Use                                                 |
 | ------------------------------- | ----------------- | ------------ | --------------------------------------------------- |
-| `--pp-color-surface`            | `#f4f4f5`         | `#18181b`    | Status row, loading placeholder, copy button hover  |
+| `--pp-color-surface`            | `#f4f4f5`         | `#18181b`    | Status row, placeholders, listboxes, copy hover     |
 | `--pp-color-text`               | `#18181b`         | `#fafafa`    | Text                                                |
 | `--pp-color-text-muted`         | `#52525b`         | `#a1a1aa`    | Labels, hints, in-progress status icon              |
 | `--pp-color-border`             | `#e4e4e7`         | `#27272a`    | Dividers and the QR code's frame                    |
-| `--pp-color-input`              | `#8a8a93`         | `#71717a`    | Edges of the network and token choices              |
+| `--pp-color-input`              | `#8a8a93`         | `#71717a`    | Edges of the token and network fields               |
 | `--pp-color-primary`            | `#171717`         | `#fafafa`    | Pay button                                          |
 | `--pp-color-primary-foreground` | `#fafafa`         | `#18181b`    | Text on the primary color                           |
-| `--pp-color-selected`           | primary           | primary      | Selected tab's underline, checked choice's border   |
+| `--pp-color-selected`           | primary           | primary      | Selected tab's underline                            |
 | `--pp-color-focus`              | `#2563eb`         | `#60a5fa`    | Keyboard focus ring                                 |
 | `--pp-color-success`            | `#15803d`         | `#4ade80`    | Credited icon                                       |
 | `--pp-color-warning`            | `#b45309`         | `#fbbf24`    | "Test mode"                                         |
@@ -239,7 +329,7 @@ the theme (or map the colors) that suits its background.
 | `--pp-font-family-mono`         | `ui-monospace, …` | same         | Addresses, amounts to copy, hashes                  |
 | `--pp-font-size`                | `14px`            | `14px`       | Root text size; other text sizes are relative to it |
 | `--pp-radius`                   | `8px`             | `8px`        | Corner radius of controls and the status row        |
-| `--pp-control-height`           | `44px`            | `44px`       | Minimum height of the pay button, tabs, and choices |
+| `--pp-control-height`           | `44px`            | `44px`       | Minimum height of buttons, tabs, and fields         |
 
 Import the static stylesheet once in your application entry point:
 
@@ -287,13 +377,15 @@ group by group with what their wallet shows; selecting and copying it gives the
 spaces. The QR code keeps the standard quiet zone of four modules inside 8px of white, so it scans
 on a dark page too. The status row's text stays the body color on a neutral surface; its icon
 carries the tone. Transitions and the loading placeholder's pulse stop under
-`prefers-reduced-motion: reduce`, and the selected choice and tab keep a system color in
-forced-colors mode.
+`prefers-reduced-motion: reduce`, and the selected tab and a listbox's active option keep a system
+color in forced-colors mode.
 
 ### Content Security Policy
 
-The components inject no style elements or style attributes. Serve the bundled CSS from your
-own origin with `style-src 'self'`; no `unsafe-inline` style permission is needed. Allow the
+The components inject no style elements or style attributes in their markup. Serve the bundled
+CSS from your own origin with `style-src 'self'`; no `unsafe-inline` style permission is needed.
+An open token or network listbox is placed beside its field through the CSSOM
+(`element.style.setProperty`), which that policy allows. Allow the
 payment service origin in `connect-src` for public status reads and `img-src data:` for browser
 wallet icons. Configure script and font sources for your application's own bundles.
 
@@ -340,7 +432,7 @@ holding less of the token than that sends nothing: `WalletError` with `code`
 
 ## React components
 
-Install `@phala/pay-react` for `Checkout`, `DepositAddress`, hooks, icons, and styles:
+Install `@phala/pay-react` for `PaymentElement`, `Checkout`, `DepositAddress`, `PaymentOptionPicker`, hooks, icons, and styles:
 
 ```sh
 npm install @phala/pay-react react react-dom @phala/pay viem

package/dist/chains.d.ts

@@ -4,6 +4,10 @@ export declare function networkIconName(chainId: number): "ethereum" | "base" |
 export declare function knownChain(chainId: number): Chain | undefined;
 /** A human name for the network, for example `Sepolia`. */
 export declare function networkName(chainId: number): string;
+/** Whether the chain is a known test network, such as Sepolia; false for an unknown chain. */
+export declare function isTestnet(chainId: number): boolean;
 /** The block explorer link for a transaction, when the chain is known. */
 export declare function transactionUrl(chainId: number, hash: string): string | undefined;
+/** The block explorer link for an address or token contract, when the chain is known. */
+export declare function addressUrl(chainId: number, address: string): string | undefined;
 //# sourceMappingURL=chains.d.ts.map

package/dist/chains.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAWlC,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAEhF;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAE7D;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGhF"}
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAWlC,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAEhF;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAE7D;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,8FAA8F;AAC9F,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhF;AAED,yFAAyF;AACzF,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE/E"}

package/dist/chains.js

@@ -17,9 +17,20 @@ export function knownChain(chainId) {
 export function networkName(chainId) {
     return knownChain(chainId)?.name ?? `Chain ${chainId}`;
 }
+/** Whether the chain is a known test network, such as Sepolia; false for an unknown chain. */
+export function isTestnet(chainId) {
+    return knownChain(chainId)?.testnet === true;
+}
 /** The block explorer link for a transaction, when the chain is known. */
 export function transactionUrl(chainId, hash) {
+    return explorerUrl(chainId, "tx", hash);
+}
+/** The block explorer link for an address or token contract, when the chain is known. */
+export function addressUrl(chainId, address) {
+    return explorerUrl(chainId, "address", address);
+}
+function explorerUrl(chainId, kind, value) {
     const explorer = knownChain(chainId)?.blockExplorers?.default.url;
-    return explorer === undefined ? undefined : `${explorer}/tx/${hash}`;
+    return explorer === undefined ? undefined : `${explorer}/${kind}/${value}`;
 }
 //# sourceMappingURL=chains.js.map

package/dist/chains.js.map

@@ -1 +1 @@
-{"version":3,"file":"chains.js","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAElE,0FAA0F;AAC1F,MAAM,MAAM,GAA2D;IACrE,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE;IACpC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE;IACpC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE;IAC7B,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE;CACrC,CAAC;AAEF,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,IAAI,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,KAAK,CAAC;AACjE,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,IAAI,SAAS,OAAO,EAAE,CAAC;AACzD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,IAAY;IAC1D,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC;IAClE,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,OAAO,IAAI,EAAE,CAAC;AACvE,CAAC"}
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAElE,0FAA0F;AAC1F,MAAM,MAAM,GAA2D;IACrE,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE;IACpC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE;IACpC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE;IAC7B,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE;CACrC,CAAC;AAEF,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,IAAI,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,KAAK,CAAC;AACjE,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,IAAI,SAAS,OAAO,EAAE,CAAC;AACzD,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAC/C,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,IAAY;IAC1D,OAAO,WAAW,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,OAAe;IACzD,OAAO,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,WAAW,CAAC,OAAe,EAAE,IAAsB,EAAE,KAAa;IACzE,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC;IAClE,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;AAC7E,CAAC"}

package/dist/icon-names.d.ts

@@ -2,6 +2,10 @@ import type { ICON_SVG } from "./icon-svg.js";
 export type IconName = keyof typeof ICON_SVG;
 /** Case-insensitive token symbol; unrecognized symbols use a neutral monogram. */
 export declare function assetIconName(asset: string): IconName | undefined;
+/** The token's symbol as payers read it, for example `USDC` for `usdc`. */
+export declare function assetSymbol(asset: string): string;
+/** The token's full name, for example `USD Coin`, or its symbol when the SDK does not know it. */
+export declare function assetName(asset: string): string;
 /** First character for a neutral fallback, including an empty-symbol placeholder. */
 export declare function iconMonogram(label: string): string;
 //# sourceMappingURL=icon-names.d.ts.map

package/dist/icon-names.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"icon-names.d.ts","sourceRoot":"","sources":["../src/icon-names.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,QAAQ,CAAC;AAE7C,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAQjE;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD"}
+{"version":3,"file":"icon-names.d.ts","sourceRoot":"","sources":["../src/icon-names.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,QAAQ,CAAC;AAe7C,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAEjE;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/icon-names.js

@@ -1,12 +1,25 @@
+/** The tokens the SDK knows, by lowercase code: their icon and full name. */
+const ASSETS = {
+    usdc: { icon: "usdc", name: "USD Coin" },
+    usdt: { icon: "usdt", name: "Tether USD" },
+    pha: { icon: "pha", name: "Phala Network" },
+    eth: { icon: "eth", name: "Ether" },
+};
+function knownAsset(asset) {
+    const code = asset.trim().toLowerCase();
+    return Object.hasOwn(ASSETS, code) ? ASSETS[code] : undefined;
+}
 /** Case-insensitive token symbol; unrecognized symbols use a neutral monogram. */
 export function assetIconName(asset) {
-    switch (asset.trim().toLowerCase()) {
-        case "usdc": return "usdc";
-        case "usdt": return "usdt";
-        case "pha": return "pha";
-        case "eth": return "eth";
-        default: return undefined;
-    }
+    return knownAsset(asset)?.icon;
+}
+/** The token's symbol as payers read it, for example `USDC` for `usdc`. */
+export function assetSymbol(asset) {
+    return asset.trim().toUpperCase();
+}
+/** The token's full name, for example `USD Coin`, or its symbol when the SDK does not know it. */
+export function assetName(asset) {
+    return knownAsset(asset)?.name ?? assetSymbol(asset);
 }
 /** First character for a neutral fallback, including an empty-symbol placeholder. */
 export function iconMonogram(label) {

package/dist/icon-names.js.map

@@ -1 +1 @@
-{"version":3,"file":"icon-names.js","sourceRoot":"","sources":["../src/icon-names.ts"],"names":[],"mappings":"AAIA,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,CAAC,OAAO,MAAM,CAAC;QAC3B,KAAK,MAAM,CAAC,CAAC,OAAO,MAAM,CAAC;QAC3B,KAAK,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC;QACzB,KAAK,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC;QACzB,OAAO,CAAC,CAAC,OAAO,SAAS,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,GAAG,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"icon-names.js","sourceRoot":"","sources":["../src/icon-names.ts"],"names":[],"mappings":"AAIA,6EAA6E;AAC7E,MAAM,MAAM,GAA+D;IACzE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE;IACxC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE;IAC1C,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE;IAC3C,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE;CACpC,CAAC;AAEF,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxC,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,UAAU,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC;AACjC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACpC,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,UAAU,CAAC,KAAK,CAAC,EAAE,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,GAAG,CAAC;AAC3D,CAAC"}

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 export { CheckoutError, checkoutStatus, pollDelay, createCheckout, retrieveQuote, type CheckoutErrorCode, type CheckoutErrorOptions, type CheckoutOptions, type CheckoutSession, type CheckoutState, type CheckoutStatus, type RetrieveQuoteOptions, } from "./checkout.js";
 export { PhalaPay, type PhalaPayOptions } from "./client.js";
 export { depositAddressIdFromClientSecret, parseClientDepositAddress, retrieveDepositAddress, type ClientDepositAddress, type ClientDepositAddressNetwork, type DepositAddressPayment, type RetrieveDepositAddressOptions, } from "./deposit-address.js";
-export { knownChain, networkName, transactionUrl, networkIconName } from "./chains.js";
+export { addressUrl, isTestnet, knownChain, networkName, transactionUrl, networkIconName } from "./chains.js";
 export { formatAmount, formatCountdown, formatMinorAmount, formatTokenAmount, formatUnitsGrouped, formatWait, tokenAmount } from "./format.js";
 export { depositAddressTransfer, parseTransferUri, quoteTransfer, type DepositAddressAsset, type DepositAddressDetails, type DepositAddressNetwork, type TokenTransfer, type TransferRequest, } from "./payment.js";
 export { parseClientQuote, quoteIdFromClientSecret, type ClientQuote } from "./quote.js";
-export { assetIconName, iconMonogram, type IconName } from "./icon-names.js";
+export { assetIconName, assetName, assetSymbol, iconMonogram, type IconName } from "./icon-names.js";
+export { paymentOptionLabel, paymentOptions, samePaymentOption, type NetworkPaymentOption, type PaymentNetwork, type PaymentOption, } from "./options.js";
 export { INJECTED_WALLET_UUID, WalletError, payWithWallet, watchWallets, type EthereumProvider, type Wallet, type WalletErrorCode, type WalletInfo, } from "./wallet.js";
 export { networkIcon, assetIcon } from "./icons.js";
 export type { CheckoutParams } from "./shared/checkout-params.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,cAAc,EACd,SAAS,EACT,cAAc,EACd,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,gCAAgC,EAChC,yBAAyB,EACzB,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,GACnC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/I,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,MAAM,EACX,KAAK,eAAe,EACpB,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,cAAc,EACd,SAAS,EACT,cAAc,EACd,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,gCAAgC,EAChC,yBAAyB,EACzB,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,GACnC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9G,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/I,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACrG,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,MAAM,EACX,KAAK,eAAe,EACpB,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,11 +1,12 @@
 export { CheckoutError, checkoutStatus, pollDelay, createCheckout, retrieveQuote, } from "./checkout.js";
 export { PhalaPay } from "./client.js";
 export { depositAddressIdFromClientSecret, parseClientDepositAddress, retrieveDepositAddress, } from "./deposit-address.js";
-export { knownChain, networkName, transactionUrl, networkIconName } from "./chains.js";
+export { addressUrl, isTestnet, knownChain, networkName, transactionUrl, networkIconName } from "./chains.js";
 export { formatAmount, formatCountdown, formatMinorAmount, formatTokenAmount, formatUnitsGrouped, formatWait, tokenAmount } from "./format.js";
 export { depositAddressTransfer, parseTransferUri, quoteTransfer, } from "./payment.js";
 export { parseClientQuote, quoteIdFromClientSecret } from "./quote.js";
-export { assetIconName, iconMonogram } from "./icon-names.js";
+export { assetIconName, assetName, assetSymbol, iconMonogram } from "./icon-names.js";
+export { paymentOptionLabel, paymentOptions, samePaymentOption, } from "./options.js";
 export { INJECTED_WALLET_UUID, WalletError, payWithWallet, watchWallets, } from "./wallet.js";
 export { networkIcon, assetIcon } from "./icons.js";
 export { submitTransaction } from "./transactions.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,cAAc,EACd,SAAS,EACT,cAAc,EACd,aAAa,GAQd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,QAAQ,EAAwB,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,gCAAgC,EAChC,yBAAyB,EACzB,sBAAsB,GAKvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/I,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,aAAa,GAMd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAoB,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,YAAY,EAAiB,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,YAAY,GAKb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGpD,OAAO,EAAE,iBAAiB,EAAiC,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,cAAc,EACd,SAAS,EACT,cAAc,EACd,aAAa,GAQd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,QAAQ,EAAwB,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,gCAAgC,EAChC,yBAAyB,EACzB,sBAAsB,GAKvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9G,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/I,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,aAAa,GAMd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAoB,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAiB,MAAM,iBAAiB,CAAC;AACrG,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,GAIlB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,YAAY,GAKb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGpD,OAAO,EAAE,iBAAiB,EAAiC,MAAM,mBAAmB,CAAC"}

package/dist/options.d.ts

@@ -0,0 +1,30 @@
+/** A token on a network that a payer can pay with, for example `usdc` on chain 8453. */
+export interface PaymentOption {
+    chain_id: number;
+    /** The token's code, for example `usdc`. */
+    asset: string;
+}
+/** A network with the tokens it takes, as a deposit address's `networks` list them. */
+export interface PaymentNetwork {
+    chain_id: number;
+    assets: readonly {
+        asset: string;
+    }[];
+}
+/** One token of a `PaymentNetwork`, with the network and token objects it came from. */
+export type NetworkPaymentOption<N extends PaymentNetwork> = PaymentOption & {
+    network: N;
+    token: N["assets"][number];
+};
+/**
+ * The options to offer, in the order given and each once (the first of any duplicate): either a
+ * flat list such as `GET /v1/config`'s `assets`, returned as the same objects, or networks with
+ * their tokens such as a deposit address's `networks`, flattened network by network.
+ */
+export declare function paymentOptions<T extends PaymentOption>(options: readonly T[]): T[];
+export declare function paymentOptions<N extends PaymentNetwork>(networks: readonly N[]): NetworkPaymentOption<N>[];
+/** Whether `a` and `b` are the same token on the same network; asset codes are case-insensitive. */
+export declare function samePaymentOption(a: PaymentOption | null | undefined, b: PaymentOption | null | undefined): boolean;
+/** The option as one line of text, for example `USDC · Ethereum`. */
+export declare function paymentOptionLabel(option: PaymentOption): string;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAGA,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtC;AAED,wFAAwF;AACxF,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,cAAc,IAAI,aAAa,GAAG;IAC3E,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;CAC5B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AACpF,wBAAgB,cAAc,CAAC,CAAC,SAAS,cAAc,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,GAAG,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;AAY5G,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAOnH;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAEhE"}

package/dist/options.js

@@ -0,0 +1,20 @@
+import { networkName } from "./chains.js";
+import { assetSymbol } from "./icon-names.js";
+export function paymentOptions(source) {
+    const flat = source.flatMap((each) => "assets" in each
+        ? each.assets.map((token) => ({ chain_id: each.chain_id, asset: token.asset, network: each, token }))
+        : [each]);
+    return flat.filter((option, index) => flat.findIndex((other) => samePaymentOption(option, other)) === index);
+}
+/** Whether `a` and `b` are the same token on the same network; asset codes are case-insensitive. */
+export function samePaymentOption(a, b) {
+    return (a != null &&
+        b != null &&
+        a.chain_id === b.chain_id &&
+        a.asset.trim().toLowerCase() === b.asset.trim().toLowerCase());
+}
+/** The option as one line of text, for example `USDC · Ethereum`. */
+export function paymentOptionLabel(option) {
+    return `${assetSymbol(option.asset)} · ${networkName(option.chain_id)}`;
+}
+//# sourceMappingURL=options.js.map

package/dist/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA4B9C,MAAM,UAAU,cAAc,CAC5B,MAAmD;IAEnD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CACnC,QAAQ,IAAI,IAAI;QACd,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACrG,CAAC,CAAC,CAAC,IAAI,CAAC,CACX,CAAC;IACF,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;AAC/G,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,iBAAiB,CAAC,CAAmC,EAAE,CAAmC;IACxG,OAAO,CACL,CAAC,IAAI,IAAI;QACT,CAAC,IAAI,IAAI;QACT,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;QACzB,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAC9D,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;AAC1E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phala/pay",
-  "version": "0.10.10",
+  "version": "0.11.1",
   "description": "Phala Pay framework-free browser client",
   "keywords": [
     "crypto",

package/src/chains.ts

@@ -23,8 +23,22 @@ export function networkName(chainId: number): string {
   return knownChain(chainId)?.name ?? `Chain ${chainId}`;
 }
 
+/** Whether the chain is a known test network, such as Sepolia; false for an unknown chain. */
+export function isTestnet(chainId: number): boolean {
+  return knownChain(chainId)?.testnet === true;
+}
+
 /** The block explorer link for a transaction, when the chain is known. */
 export function transactionUrl(chainId: number, hash: string): string | undefined {
+  return explorerUrl(chainId, "tx", hash);
+}
+
+/** The block explorer link for an address or token contract, when the chain is known. */
+export function addressUrl(chainId: number, address: string): string | undefined {
+  return explorerUrl(chainId, "address", address);
+}
+
+function explorerUrl(chainId: number, kind: "tx" | "address", value: string): string | undefined {
   const explorer = knownChain(chainId)?.blockExplorers?.default.url;
-  return explorer === undefined ? undefined : `${explorer}/tx/${hash}`;
+  return explorer === undefined ? undefined : `${explorer}/${kind}/${value}`;
 }

package/src/icon-names.ts

@@ -2,19 +2,35 @@ import type { ICON_SVG } from "./icon-svg.js";
 
 export type IconName = keyof typeof ICON_SVG;
 
+/** The tokens the SDK knows, by lowercase code: their icon and full name. */
+const ASSETS: Readonly<Record<string, { icon: IconName; name: string }>> = {
+  usdc: { icon: "usdc", name: "USD Coin" },
+  usdt: { icon: "usdt", name: "Tether USD" },
+  pha: { icon: "pha", name: "Phala Network" },
+  eth: { icon: "eth", name: "Ether" },
+};
+
+function knownAsset(asset: string) {
+  const code = asset.trim().toLowerCase();
+  return Object.hasOwn(ASSETS, code) ? ASSETS[code] : undefined;
+}
+
 /** Case-insensitive token symbol; unrecognized symbols use a neutral monogram. */
 export function assetIconName(asset: string): IconName | undefined {
-  switch (asset.trim().toLowerCase()) {
-    case "usdc": return "usdc";
-    case "usdt": return "usdt";
-    case "pha": return "pha";
-    case "eth": return "eth";
-    default: return undefined;
-  }
+  return knownAsset(asset)?.icon;
+}
+
+/** The token's symbol as payers read it, for example `USDC` for `usdc`. */
+export function assetSymbol(asset: string): string {
+  return asset.trim().toUpperCase();
+}
+
+/** The token's full name, for example `USD Coin`, or its symbol when the SDK does not know it. */
+export function assetName(asset: string): string {
+  return knownAsset(asset)?.name ?? assetSymbol(asset);
 }
 
 /** First character for a neutral fallback, including an empty-symbol placeholder. */
 export function iconMonogram(label: string): string {
   return Array.from(label.trim())[0]?.toUpperCase() ?? "?";
 }
-

package/src/index.ts

@@ -22,7 +22,7 @@ export {
   type DepositAddressPayment,
   type RetrieveDepositAddressOptions,
 } from "./deposit-address.js";
-export { knownChain, networkName, transactionUrl, networkIconName } from "./chains.js";
+export { addressUrl, isTestnet, knownChain, networkName, transactionUrl, networkIconName } from "./chains.js";
 export { formatAmount, formatCountdown, formatMinorAmount, formatTokenAmount, formatUnitsGrouped, formatWait, tokenAmount } from "./format.js";
 export {
   depositAddressTransfer,
@@ -35,7 +35,15 @@ export {
   type TransferRequest,
 } from "./payment.js";
 export { parseClientQuote, quoteIdFromClientSecret, type ClientQuote } from "./quote.js";
-export { assetIconName, iconMonogram, type IconName } from "./icon-names.js";
+export { assetIconName, assetName, assetSymbol, iconMonogram, type IconName } from "./icon-names.js";
+export {
+  paymentOptionLabel,
+  paymentOptions,
+  samePaymentOption,
+  type NetworkPaymentOption,
+  type PaymentNetwork,
+  type PaymentOption,
+} from "./options.js";
 export {
   INJECTED_WALLET_UUID,
   WalletError,

package/src/options.ts

@@ -0,0 +1,54 @@
+import { networkName } from "./chains.js";
+import { assetSymbol } from "./icon-names.js";
+
+/** A token on a network that a payer can pay with, for example `usdc` on chain 8453. */
+export interface PaymentOption {
+  chain_id: number;
+  /** The token's code, for example `usdc`. */
+  asset: string;
+}
+
+/** A network with the tokens it takes, as a deposit address's `networks` list them. */
+export interface PaymentNetwork {
+  chain_id: number;
+  assets: readonly { asset: string }[];
+}
+
+/** One token of a `PaymentNetwork`, with the network and token objects it came from. */
+export type NetworkPaymentOption<N extends PaymentNetwork> = PaymentOption & {
+  network: N;
+  token: N["assets"][number];
+};
+
+/**
+ * The options to offer, in the order given and each once (the first of any duplicate): either a
+ * flat list such as `GET /v1/config`'s `assets`, returned as the same objects, or networks with
+ * their tokens such as a deposit address's `networks`, flattened network by network.
+ */
+export function paymentOptions<T extends PaymentOption>(options: readonly T[]): T[];
+export function paymentOptions<N extends PaymentNetwork>(networks: readonly N[]): NetworkPaymentOption<N>[];
+export function paymentOptions(
+  source: readonly (PaymentOption | PaymentNetwork)[],
+): (PaymentOption | NetworkPaymentOption<PaymentNetwork>)[] {
+  const flat = source.flatMap((each) =>
+    "assets" in each
+      ? each.assets.map((token) => ({ chain_id: each.chain_id, asset: token.asset, network: each, token }))
+      : [each],
+  );
+  return flat.filter((option, index) => flat.findIndex((other) => samePaymentOption(option, other)) === index);
+}
+
+/** Whether `a` and `b` are the same token on the same network; asset codes are case-insensitive. */
+export function samePaymentOption(a: PaymentOption | null | undefined, b: PaymentOption | null | undefined): boolean {
+  return (
+    a != null &&
+    b != null &&
+    a.chain_id === b.chain_id &&
+    a.asset.trim().toLowerCase() === b.asset.trim().toLowerCase()
+  );
+}
+
+/** The option as one line of text, for example `USDC · Ethereum`. */
+export function paymentOptionLabel(option: PaymentOption): string {
+  return `${assetSymbol(option.asset)} · ${networkName(option.chain_id)}`;
+}