@phala/pay-server 0.0.0 → 0.9.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,215 @@
 # @phala/pay-server
 
-Placeholder. Use the real release from https://github.com/Phala-Network/phala-pay.
+Merchant server SDK for Node.js >=20.3, Bun, and Deno. It contains the keyed `PhalaPay` client, transport, generated server types, bound and standalone webhook verification, pins, address helpers, ledger helpers, and sweep/Safe builders. It has no React dependency.
+
+`viem` is the only runtime dependency because the offline EVM address derivation and Safe/sweep
+builders use its ABI, hashing, and checksum primitives.
+
+```sh
+npm install @phala/pay-server
+```
+
+## Merchant server client
+
+Import `PhalaPay` from `@phala/pay-server` on Node.js >=20.3, Bun or Deno. Server runtimes
+must provide `fetch`, `AbortSignal.any` and WebCrypto (including `randomUUID`). The `@phala/pay` package remains keyless and browser-safe. The server entry rejects browser-like
+environments before reading credentials; keep this package out of browser bundles.
+
+```ts
+import { PhalaPay, ApiError, SignatureVerificationError } from "@phala/pay-server";
+import type { CheckoutParams } from "@phala/pay";
+
+// Reads exactly PHALA_PAY_API_KEY and PHALA_PAY_PINS from process.env.
+const pay = PhalaPay.fromEnv();
+// Or: new PhalaPay({ apiKey, pins, timeoutMs: 15000, maxAttempts: 4,
+//                   requestDeadlineMs: 60000, fetch });
+
+try {
+  const quote = await pay.quotes.create(
+    { client_reference_id: "team-42", amount: 2500, currency: "usd", chain_id: 11155111, asset: "pha" },
+    { idempotencyKey: "persisted-order-42" },
+  );
+  const checkout: CheckoutParams = pay.checkoutParams(quote);
+  // Return checkout only to this order's authenticated browser; spread it into <Checkout>.
+  // Fulfill from the verified webhook, never from browser success.
+  const event = await pay.webhooks.constructEvent(originalBodyBytes, requestHeaders);
+  // Atomically commit your ledger snapshot and balance delta before acknowledging delivery.
+  await applyVerifiedEvent(event);
+} catch (error) {
+  if (error instanceof SignatureVerificationError) {
+    // Return 400 for an invalid webhook, without exposing exception text.
+  } else if (error instanceof ApiError) {
+    // Use statusCode/code/requestId internally; return a generic payment error to the caller.
+  } else {
+    // Return 5xx for failures before the ledger transaction commits.
+  }
+} finally {
+  await pay.close();
+}
+```
+
+`pins` accepts the versioned `ppay_pins_v1.…` string or a `Pins` value returned by
+`parsePins`. `encodePins` produces its canonical encoding. Pins are recursively frozen and bind
+the normalized API origin, account, mode, forwarder contracts, chain treasuries and public webhook
+keys. Both test and live clients require pins. An explicit `apiBase` must match that origin;
+HTTP is permitted only for explicitly configured test loopback origins. No trust discovery occurs.
+`fromEnv(env, { apiBase })` reads no other variables and loads no files or dotenv configuration.
+
+Every open quote and active deposit-address network is checked against the pinned treasury and
+recomputed address, including list pages, actions and expanded objects. Historical objects cannot
+be handed to checkout. `checkoutParams` requires a create/replay quote from this client with its
+original `client_secret`; retrieval cannot manufacture a checkout secret. It rechecks pins and
+payability and returns `{ clientSecret, expectedAddress, apiBase }`.
+
+### Resources and types
+
+Wire fields remain snake_case. Params and responses, including `QuoteCreateParams`, `Quote` and
+`Deposit`, are aliases of the generated OpenAPI definitions. Response fields and future enums are
+retained; unsafe JSON integers are rejected before rounding.
+
+| Resource | Methods |
+| --- | --- |
+| `quotes` | `create`, `retrieve`, `listPage`, `list`, `update`, `cancel` |
+| `depositAddresses` | `create`, `retrieve`, `listPage`, `list`, `update`, `rotate` |
+| `deposits` | `retrieve`, `listPage`, `list`, `update` |
+| `refunds` | `create`, `retrieve`, `listPage`, `list`, `update`, `cancel`, `markPaid` |
+| `paymentSettings` | `retrieve`, `update` |
+| `config`, `balance` | `retrieve` |
+| `account` | `retrieve`, `pauseQuotes`, `resumeQuotes`, `rollWebhookKey` |
+| `treasuries` | `challenge`, `create`, `retrieve`, `listPage`, `list`, `cancel`, `pause`, `resume` |
+| `apiKeys` | `create`, `retrieve`, `listPage`, `list`, `roll`, `revoke` |
+| `webhookEndpoints` | `create`, `retrieve`, `listPage`, `list`, `update`, `delete`, `test` |
+| `events` | `retrieve`, `listPage`, `list`, `resend` |
+| `sweeps`, `forwarders` | `listPage`, `list` |
+
+Create/singleton-update/challenge use `(params, options?)`; resource updates and actions with
+bodies use `(id, params, options?)`. Actions without bodies use `(id, options?)`. Retrieve uses
+`(id, params?, options?)` (pass `undefined` for endpoints without query params); singleton retrieve
+uses `(options?)`. Lists accept `(params?, options?)`. `listPage` returns `{ data, has_more, … }`;
+`list` is an `AsyncIterable` that validates every page and rejects empty continuing pages or
+repeated cursors. Omitting `apiKeys.create` permissions creates a secret key; supplying a list
+creates a restricted key.
+
+### Transport and errors
+
+Per-call options are `{ idempotencyKey?, signal?, requestDeadlineMs?, upgradeTolerance? }`.
+Defaults are a 15-second attempt timeout (including body reads), four total attempts, and a 60-second overall deadline
+(including sleeps). POST requests freeze their body and one automatically generated UUID across
+retries; persist an explicit order key to survive process restarts. Keys have a 255-character limit.
+Retries cover network/timeouts, 429, 500/502/503/504, and only `409 idempotency_key_in_use`, with
+bounded exponential jitter and Retry-After as a minimum. A delay that exceeds the remaining budget
+returns the last error immediately. Replayed errors, DELETE, cancellation and redirects do not
+retry. Redirects are refused. `close()` aborts outstanding requests without closing injected fetch.
+
+Set `upgradeTolerance: true` on the client or per call for backend work that can wait through a
+CVM upgrade. A maintenance 503, gateway 502/503/504 (even a non-JSON body), or network/attempt
+timeout allows up to five minutes of retries from the original request start, with backoff capped
+at 10 seconds. This applies only to GET and replayable POST and preserves the same body/key.
+Explicit deadlines, cancellation, and replayed-error handling still take precedence. The option
+defaults to false so interactive requests keep the existing timeout/attempt budget. See
+[planned upgrades](../../docs/integration.md#planned-upgrades-and-reconnecting).
+
+Errors inherit `PhalaPayError`: `ApiError`, `TransportError`, `ConfigurationError`,
+`ResponseValidationError`, `AddressMismatchError`, `AttestationError`,
+`SignatureVerificationError` (also exported as `WebhookSignatureError`) and `LedgerSnapshotError`.
+`ApiError` exposes `statusCode`, `code`, `message`, `errorType`, `param`, `docUrl`, `requestId` and
+`retryAfter` in seconds; absent optional fields are null. `TransportError.code` is `network`,
+`timeout` or `cancelled`. Malformed responses expose status/request ID without raw bodies or causes.
+
+### Bound webhooks and pure ledger helpers
+
+`pay.webhooks.constructEvent(body, headers, { tolerance: 300 })` uses only this client's pinned
+public keys, account and mode. Pass original bytes or exact UTF-8, before JSON middleware. Headers
+are case-insensitive; duplicate signing headers fail. Ed25519 v1a verification, the envelope and ID
+must pass. The inclusive time window is bilateral; tolerance zero requires an exact timestamp.
+Known deposit events expose the typed `event.deposit`; unknown event types retain their raw object
+and should be ignored before accessing it. Change overlapping webhook pins manually after
+attestation; security notices never modify trust.
+
+`depositNetAmount(deposit)` returns integer minor units. `balanceDelta(previousSnapshot, deposit)`
+returns `{ snapshot, contribution, delta }` without IO or mutation. Commit the returned snapshot
+and delta together in your own transaction before acknowledging a webhook. Duplicate and reordered
+snapshots converge through monotone statuses and cumulative deductions. Refund events retain
+`status: "credited"`; unknown statuses, identity/valuation conflicts and impossible deductions
+raise `LedgerSnapshotError`. These helpers provide no SQL adapter or authorization policy.
+
+## Server helpers
+
+Keyless pins, ledger, address, signature and sweep builders live at `@phala/pay-server/helpers`, including for
+WebCrypto-capable non-Node runtimes. Existing exports from `/server` remain available on supported server runtimes;
+browser callers must move to `/server/helpers`:
+
+```ts
+import { constructEvent, flushTransactions, safeBatch, verifyQuoteAddress } from "@phala/pay-server/helpers";
+
+// 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.3+, Deno, Bun, edge runtimes). Fails closed
+// unless the signature verifies with a pinned key and the event is your account's in this mode.
+// WEBHOOK_PUBLIC_KEYS: your account's keys in this mode, `whpk_…`, pinned from GET /v1/attestation.
+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.
+
+## Chain and token icons
+
+`Checkout` and `DepositAddress` include compact inline icons for Ethereum, Base, USDC, USDT,
+PHA, and ETH. Testnets reuse their mainnet family artwork. Unknown chains
+and assets show a neutral first-letter monogram. Symbols are case-insensitive.
+
+```tsx
+import { NetworkIcon, AssetIcon } from "@phala/pay-react";
+
+<NetworkIcon chainId={8453} size={16} />; // decorative beside visible "Base" text
+<AssetIcon asset="usdc" size={20} decorative={false} />; // accessible when used alone
+```
+
+Import `@phala/pay-react/styles.css` for alignment. The default
+size is 18px. Icons use SVG width/height attributes and React elements, so they need no inline
+styles, data URI allowance, or extra CSP directives, including with `style-src 'self'`.
+
+Framework-free hosts can call `networkIcon(chainId)` or `assetIcon(symbol)` from `@phala/pay`
+for decorative SVG markup. Keep the
+name visible alongside it; when used alone, supply an accessible label on the host wrapper.
+
+Only six branded SVGs from `@web3icons/core@4.0.57` are vendored, under the MIT license in
+`THIRD_PARTY_NOTICES`. Regenerate both the markup and JSX modules with
+`npx -y pnpm@12.6.0 run icons:generate`; the script packs the pinned package into a temporary
+directory, rejects unexpected SVG tags/attributes, and cleans up. No web3icons runtime package
+is installed.
+
+## Development
+
+```sh
+pnpm install
+pnpm run check   # typecheck, lint, unit tests, build
+pnpm run e2e     # Playwright against Anvil; needs Foundry (anvil, forge) on PATH
+pnpm run e2e:docker  # the same, with Chromium from Playwright's image (as CI runs it)
+```
+
+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 (and again through a viem `WalletClient` passed as
+`walletClient`), then decode the QR code and exercise the manual details.
+
+## Releases
+
+`@phala/pay` is released with the service: the `v<version>` tag's Release workflow publishes it to
+npm (environment `npm`) with trusted publishing and provenance
+([CONTRIBUTING.md, "Releasing"](../../CONTRIBUTING.md#releasing)). Its changes are in the top-level
+[CHANGELOG.md](https://github.com/Phala-Network/phala-pay/blob/main/CHANGELOG.md), under "JS SDK";
+[its releases before v0.5.0](https://github.com/Phala-Network/phala-pay/blob/main/sdk/js/CHANGELOG.md),
+versioned on their own, stay in `sdk/js`.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,25 @@
+web3icons (@web3icons/core@4.0.57)
+https://github.com/0xa3k5/web3icons
+Vendored branded token and network SVGs.
+
+MIT License
+
+Copyright (c) 2024 0xa3k5
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/js/src/shared/checkout-params.d.ts

@@ -0,0 +1,7 @@
+/** The only server-to-browser checkout handoff; contains no merchant credentials or pins. */
+export interface CheckoutParams {
+    clientSecret: string;
+    expectedAddress: string;
+    apiBase: string;
+}
+//# sourceMappingURL=checkout-params.d.ts.map

package/dist/js/src/shared/checkout-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-params.d.ts","sourceRoot":"","sources":["../../../../../js/src/shared/checkout-params.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/js/src/shared/checkout-params.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=checkout-params.js.map

package/dist/js/src/shared/checkout-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-params.js","sourceRoot":"","sources":["../../../../../js/src/shared/checkout-params.ts"],"names":[],"mappings":""}

package/dist/js-server/src/addresses.d.ts

@@ -0,0 +1,76 @@
+import { type Address, type Hex } from "viem";
+/**
+ * The forwarder `factory` deploys for `treasury` and `salt`: OpenZeppelin 5.x
+ * `Clones.predictDeterministicAddressWithImmutableArgs` with `abi.encodePacked(treasury)`, so the
+ * address commits to the factory, the implementation, the treasury, and the salt.
+ */
+export declare function forwarderAddress(factory: string, implementation: string, treasury: string, salt: Hex): Address;
+/** `keccak256(abi.encode(account, client_reference_id, "quote", quote_id))`: a quote's salt. */
+export declare function quoteSalt(account: string, clientReferenceId: string, quoteId: string): Hex;
+/**
+ * `keccak256(abi.encode(account, livemode, client_reference_id, "deposit_address", version))`:
+ * a deposit address's salt, the same on every chain.
+ */
+export declare function depositAddressSalt(account: string, livemode: boolean, clientReferenceId: string, version: number | bigint): Hex;
+export interface Forwarder {
+    factory: string;
+    implementation: string;
+}
+/** The address of a quote over `treasury`, which you pin yourself (see `verifyQuoteAddress`). */
+export declare function quoteAddress(forwarder: Forwarder, quote: {
+    client_reference_id: string;
+    id: string;
+}, treasury: string, account: string): Address;
+/** A deposit address on the network whose treasury is `treasury`, which you pin yourself. */
+export declare function depositAddress(forwarder: Forwarder, address: {
+    livemode: boolean;
+    client_reference_id: string;
+    version: number;
+}, treasury: string, account: string): Address;
+/** An address the service returned is not the one your pins derive: show nothing to pay. */
+export { AddressMismatchError } from "./errors.js";
+/**
+ * What every address is recomputed from, configured on your server and never read from the
+ * service: your account id (`acct_…`), the forwarder `factory` and `implementation` of the
+ * attested deployment, and `treasuries`, your own treasury per chain id as you proved it. A
+ * compromised service could return another treasury with the address that really derives from
+ * it, so the response's `treasury` is never trusted.
+ *
+ * Live mode requires `treasuries`: without the chain's treasury the check fails closed. In test
+ * mode an unpinned chain falls back to the response's treasury with a console warning.
+ */
+export interface AddressPins extends Forwarder {
+    account: string;
+    treasuries?: Readonly<Record<number, string>> | undefined;
+}
+/**
+ * Recomputes an open quote's address from your pins and returns it, the `expectedAddress` to
+ * pass to `<Checkout>`. Throws `AddressMismatchError` unless the quote names your pinned
+ * treasury of its chain and its address derives from it; in live mode also when the chain has no
+ * pinned treasury.
+ */
+export declare function verifyQuoteAddress(pins: AddressPins, quote: {
+    id: string;
+    livemode: boolean;
+    chain_id: number;
+    treasury: string;
+    address: string;
+    client_reference_id: string;
+}): Address;
+/**
+ * Recomputes every network of an active deposit address from your pins and returns the address,
+ * the same on every network. Throws `AddressMismatchError` as `verifyQuoteAddress` does, for any
+ * network.
+ */
+export declare function verifyDepositAddress(pins: AddressPins, address: {
+    id: string;
+    livemode: boolean;
+    client_reference_id: string;
+    version: number;
+    networks: readonly {
+        chain_id: number;
+        treasury: string;
+        address: string;
+    }[];
+}): Address;
+//# sourceMappingURL=addresses.d.ts.map

package/dist/js-server/src/addresses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addresses.d.ts","sourceRoot":"","sources":["../../../src/addresses.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,OAAO,EACZ,KAAK,GAAG,EACT,MAAM,MAAM,CAAC;AAEd;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,GAAG,GACR,OAAO,CAgBT;AAED,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAO1F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,OAAO,EACjB,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,MAAM,GAAG,MAAM,GACvB,GAAG,CAaL;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,iGAAiG;AACjG,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE;IAAE,mBAAmB,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAClD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAOT;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC5E,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAOT;AAED,4FAA4F;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;CAC3D;AAwCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE;IACL,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,GACA,OAAO,CAST;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE;IACP,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9E,GACA,OAAO,CAgBT"}