@phala/pay 0.1.1 → 0.2.0

package/src/client.ts

@@ -14,11 +14,12 @@ 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 class PhalaPay {
@@ -30,15 +31,20 @@ export class PhalaPay {
     this.#fetch = options.fetch;
   }
 
-  /** Reads the quote's public view once. */
-  retrieveQuote(clientSecret: string): Promise<ClientQuote> {
-    return retrieveQuote({ clientSecret, apiBase: this.apiBase, ...this.#fetchOption() });
+  /** Reads the quote's public view once, refusing one whose address is not `expectedAddress`. */
+  retrieveQuote(clientSecret: string, expectedAddress: string): Promise<ClientQuote> {
+    return retrieveQuote({
+      clientSecret,
+      expectedAddress,
+      apiBase: this.apiBase,
+      ...this.#fetchOption(),
+    });
   }
 
-  /** Follows the quote until it is credited, rejected, canceled, or expired. */
+  /** Follows the quote until it is credited, rejected, reversed, canceled, or expired. */
   checkout(
     clientSecret: string,
-    options: Pick<CheckoutOptions, "pollInterval"> = {},
+    options: Pick<CheckoutOptions, "expectedAddress" | "pollInterval">,
   ): CheckoutSession {
     return createCheckout({
       clientSecret,

package/src/deposit-address.ts

@@ -0,0 +1,138 @@
+import { CheckoutError, responseError } from "./checkout.js";
+
+/** A payment to a deposit address as the customer's page sees it. Display only. */
+export interface DepositAddressPayment {
+  /**
+   * `seen` (in a block, may still disappear), `confirming` (at the route's confirmation, being
+   * valued and screened), `credited`, `rejected` (contact support), or `reversed` (its
+   * transaction left the chain before finality: the payment did not happen).
+   */
+  status: "seen" | "confirming" | "credited" | "rejected" | "reversed";
+  chain_id: number;
+  /** The token's code, or `null` for a token without a route. */
+  asset: string | null;
+  decimals: number | null;
+  /** Token amount in the smallest unit, as a decimal string. */
+  amount_atomic: string;
+  tx_hash: string;
+  /** Block confirmations while `seen`, otherwise `null`. */
+  confirmations: number | null;
+  /** Unix seconds. */
+  created: number;
+}
+
+/**
+ * The public view of a deposit address, as `GET /v1/deposit_addresses/{id}?client_secret=…`
+ * returns it to a browser: its payments in the last 24 hours, newest first.
+ */
+export interface ClientDepositAddress {
+  id: string;
+  object: "deposit_address";
+  livemode: boolean;
+  status: "active" | "retired";
+  payments: DepositAddressPayment[];
+}
+
+export interface RetrieveDepositAddressOptions {
+  /** A `client_secret` from your backend's `POST /v1/deposit_addresses` or `…/rotate`. */
+  clientSecret: string;
+  apiBase: string;
+  fetch?: typeof globalThis.fetch;
+}
+
+const PAYMENT_STATUSES = ["seen", "confirming", "credited", "rejected", "reversed"] as const;
+
+/** Returns the deposit address a client secret belongs to (`da_…_secret_…`), or throws. */
+export function depositAddressIdFromClientSecret(clientSecret: string): string {
+  const match = /^(da_[0-9a-f]{32})_secret_[0-9a-f]+$/.exec(clientSecret);
+  if (match?.[1] === undefined) {
+    throw new TypeError("clientSecret is not a deposit address client secret");
+  }
+  return match[1];
+}
+
+/**
+ * Reads a deposit address's public view once. Rejects with a `CheckoutError`:
+ * `invalid_client_secret` for an unknown address or secret.
+ */
+export async function retrieveDepositAddress(
+  options: RetrieveDepositAddressOptions,
+): Promise<ClientDepositAddress> {
+  const id = depositAddressIdFromClientSecret(options.clientSecret);
+  const base = options.apiBase.replace(/\/+$/, "");
+  const url = `${base}/v1/deposit_addresses/${id}?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.ok) {
+    throw responseError(response, "the address or its client secret is unknown");
+  }
+  try {
+    return parseClientDepositAddress(await response.json());
+  } catch (cause) {
+    throw new CheckoutError("invalid_response", "unexpected response from the payment service", {
+      cause,
+    });
+  }
+}
+
+/** Validates a response body against the public deposit address view; throws on anything else. */
+export function parseClientDepositAddress(value: unknown): ClientDepositAddress {
+  const v = record(value);
+  const payments = v["payments"];
+  if (
+    typeof v["id"] !== "string" ||
+    v["object"] !== "deposit_address" ||
+    typeof v["livemode"] !== "boolean" ||
+    (v["status"] !== "active" && v["status"] !== "retired") ||
+    !Array.isArray(payments)
+  ) {
+    throw new TypeError("response does not match the public deposit address view");
+  }
+  return {
+    id: v["id"],
+    object: "deposit_address",
+    livemode: v["livemode"],
+    status: v["status"],
+    payments: payments.map(parsePayment),
+  };
+}
+
+function parsePayment(value: unknown): DepositAddressPayment {
+  const p = record(value);
+  const status = p["status"];
+  const asset = p["asset"];
+  const decimals = p["decimals"];
+  const confirmations = p["confirmations"];
+  if (
+    typeof status !== "string" ||
+    !(PAYMENT_STATUSES as readonly string[]).includes(status) ||
+    !Number.isSafeInteger(p["chain_id"]) ||
+    !(asset === null || typeof asset === "string") ||
+    !(decimals === null || Number.isSafeInteger(decimals)) ||
+    typeof p["amount_atomic"] !== "string" ||
+    !/^\d+$/.test(p["amount_atomic"]) ||
+    typeof p["tx_hash"] !== "string" ||
+    !(confirmations === null || Number.isSafeInteger(confirmations)) ||
+    !Number.isSafeInteger(p["created"])
+  ) {
+    throw new TypeError("payment does not match the public deposit address view");
+  }
+  return {
+    status: status as DepositAddressPayment["status"],
+    chain_id: p["chain_id"] as number,
+    asset,
+    decimals: decimals as number | null,
+    amount_atomic: p["amount_atomic"],
+    tx_hash: p["tx_hash"],
+    confirmations: confirmations as number | null,
+    created: p["created"] as number,
+  };
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError("response is not an object");
+  }
+  return value as Record<string, unknown>;
+}

package/src/index.ts

@@ -4,6 +4,7 @@ export {
   createCheckout,
   retrieveQuote,
   type CheckoutErrorCode,
+  type CheckoutErrorOptions,
   type CheckoutOptions,
   type CheckoutSession,
   type CheckoutState,
@@ -11,9 +12,26 @@ export {
   type RetrieveQuoteOptions,
 } from "./checkout.js";
 export { PhalaPay, type PhalaPayOptions } from "./client.js";
+export {
+  depositAddressIdFromClientSecret,
+  parseClientDepositAddress,
+  retrieveDepositAddress,
+  type ClientDepositAddress,
+  type DepositAddressPayment,
+  type RetrieveDepositAddressOptions,
+} from "./deposit-address.js";
 export { knownChain, networkName, transactionUrl } from "./chains.js";
 export { formatAmount, formatCountdown, formatTokenAmount, tokenAmount } from "./format.js";
-export { quoteTransfer, type TokenTransfer } from "./payment.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 {
   INJECTED_WALLET_UUID,

package/src/payment.ts

@@ -6,22 +6,54 @@ export interface TokenTransfer {
   chainId: number;
   /** The token contract. */
   token: Address;
-  /** The recipient: the quote's deposit address. */
+  /** The recipient: the quote's or the customer's deposit address. */
   to: Address;
   /** Token amount in the smallest unit. */
   amount: bigint;
 }
 
+/** An EIP-681 ERC-20 transfer request whose amount the payer may choose. */
+export type TransferRequest = Omit<TokenTransfer, "amount"> & { amount: bigint | undefined };
+
+/** A token a deposit address takes on one network. */
+export interface DepositAddressAsset {
+  /** The token's code, for example `pha`. */
+  asset: string;
+  /** The ERC-20 contract. */
+  contract: string;
+  decimals: number;
+  /** The EIP-681 transfer request of this token to the network's address, without an amount. */
+  payment_uri: string;
+}
+
+/** A deposit address on one network (EVM chain), with the tokens it takes there. */
+export interface DepositAddressNetwork {
+  chain_id: number;
+  /** The address on this chain: the same on every chain whose treasury is the same. */
+  address: string;
+  assets: DepositAddressAsset[];
+}
+
+/**
+ * The fields of a deposit address that a payer's page shows: pass them from your backend's
+ * `POST /v1/deposit_addresses` response. One address takes every supported token on every
+ * supported network; any amount of a supported token sent is credited at the market rate.
+ */
+export interface DepositAddressDetails {
+  /** The address shared by every network, or `null` when a network's address differs. */
+  address: string | null;
+  networks: DepositAddressNetwork[];
+}
+
 const EIP681_TRANSFER =
   /^ethereum:(?:pay-)?(0x[0-9a-fA-F]{40})@([1-9][0-9]*)\/transfer\?([^#]*)$/;
 
 /**
- * Reads the token transfer from a quote's EIP-681 `payment_uri`, and checks that it pays exactly
- * the quote's `amount_atomic` to the quote's `address` on the quote's chain, so the wallet, the QR
- * code, and the manual instructions all state the same payment.
+ * Parses an EIP-681 ERC-20 transfer URI, `ethereum:<token>@<chainId>/transfer?address=<to>`, with
+ * an optional `uint256=<amount>`. Throws on anything else.
  */
-export function quoteTransfer(quote: ClientQuote): TokenTransfer {
-  const match = EIP681_TRANSFER.exec(quote.payment_uri);
+export function parseTransferUri(uri: string): TransferRequest {
+  const match = EIP681_TRANSFER.exec(uri);
   const params = new URLSearchParams(match?.[3] ?? "");
   const to = params.get("address");
   const amount = params.get("uint256");
@@ -30,23 +62,53 @@ export function quoteTransfer(quote: ClientQuote): TokenTransfer {
     match[2] === undefined ||
     to === null ||
     !/^0x[0-9a-fA-F]{40}$/.test(to) ||
-    amount === null ||
-    !/^\d+$/.test(amount)
+    (amount !== null && !/^\d+$/.test(amount))
   ) {
     throw new TypeError("payment_uri is not an EIP-681 ERC-20 transfer");
   }
-  const transfer: TokenTransfer = {
+  return {
     chainId: Number(match[2]),
     token: getAddress(match[1]),
     to: getAddress(to),
-    amount: BigInt(amount),
+    amount: amount === null ? undefined : BigInt(amount),
   };
+}
+
+/**
+ * Reads the token transfer from a quote's EIP-681 `payment_uri`, and checks that it pays exactly
+ * the quote's `amount_atomic` to the quote's `address` on the quote's chain, so the wallet, the QR
+ * code, and the manual instructions all state the same payment.
+ */
+export function quoteTransfer(quote: ClientQuote): TokenTransfer {
+  const transfer = parseTransferUri(quote.payment_uri);
   if (
+    transfer.amount === undefined ||
     transfer.chainId !== quote.chain_id ||
     !isAddressEqual(transfer.to, getAddress(quote.address)) ||
     transfer.amount !== BigInt(quote.amount_atomic)
   ) {
     throw new TypeError("payment_uri does not match the quote");
   }
+  return { ...transfer, amount: transfer.amount };
+}
+
+/**
+ * Reads the token transfer from a deposit address's EIP-681 `payment_uri` for one token on one
+ * network, and checks that it pays the network's address in that token on that chain and names no
+ * amount, so the QR code and the copied address and contract state the same destination.
+ */
+export function depositAddressTransfer(
+  network: DepositAddressNetwork,
+  asset: DepositAddressAsset,
+): TransferRequest {
+  const transfer = parseTransferUri(asset.payment_uri);
+  if (
+    transfer.amount !== undefined ||
+    transfer.chainId !== network.chain_id ||
+    !isAddressEqual(transfer.to, getAddress(network.address)) ||
+    !isAddressEqual(transfer.token, getAddress(asset.contract))
+  ) {
+    throw new TypeError("payment_uri does not match the deposit address");
+  }
   return transfer;
 }

package/src/quote.ts

@@ -4,6 +4,8 @@
 export interface ClientQuote {
   id: string;
   object: "quote";
+  /** `false` for a test-mode quote, paid on a testnet; the page says so. */
+  livemode: boolean;
   /** `open` until a matching payment completes it, it expires by chain time, or it is canceled. */
   status: "open" | "complete" | "expired" | "canceled";
   /** Credit in the currency's minor unit (US cents). */
@@ -22,16 +24,18 @@ export interface ClientQuote {
   /** Unix seconds; after this the address must no longer be shown. */
   expires_at: number;
   /**
-   * `seen` before finality (a reorg can remove it), `confirming` while a final payment is valued
-   * and screened, `credited` once it is credited, `rejected` when it is final but will not be.
+   * `seen` once in a block (a reorg can remove it), `confirming` while a payment at the route's
+   * confirmation is valued and screened, `credited` once it is credited (about 30 seconds after
+   * paying), `rejected` when it will not be, `reversed` when a credited payment's transaction
+   * left the chain before finality (the payment did not happen).
    */
-  payment_status: "none" | "seen" | "confirming" | "credited" | "rejected";
+  payment_status: "none" | "seen" | "confirming" | "credited" | "rejected" | "reversed";
   /** Block confirmations while `payment_status` is `seen`, otherwise `null`. */
   confirmations: number | null;
 }
 
 const QUOTE_STATUSES = ["open", "complete", "expired", "canceled"] as const;
-const PAYMENT_STATUSES = ["none", "seen", "confirming", "credited", "rejected"] as const;
+const PAYMENT_STATUSES = ["none", "seen", "confirming", "credited", "rejected", "reversed"] as const;
 
 /** Returns the quote id a client secret belongs to (`qt_…_secret_…`), or throws. */
 export function quoteIdFromClientSecret(clientSecret: string): string {
@@ -52,6 +56,7 @@ export function parseClientQuote(value: unknown): ClientQuote {
   if (
     typeof v["id"] !== "string" ||
     v["object"] !== "quote" ||
+    typeof v["livemode"] !== "boolean" ||
     !oneOf(v["status"], QUOTE_STATUSES) ||
     !isSafeInteger(v["amount"]) ||
     typeof v["currency"] !== "string" ||
@@ -72,6 +77,7 @@ export function parseClientQuote(value: unknown): ClientQuote {
   return {
     id: v["id"],
     object: "quote",
+    livemode: v["livemode"],
     status: v["status"],
     amount: v["amount"],
     currency: v["currency"],