@rhinestone/deposit-modal 0.18.0 → 0.20.0

package/README.md

@@ -1,12 +1,12 @@
 # @rhinestone/deposit-modal
 
-React modal for cross-chain deposits and withdrawals via Rhinestone smart accounts.
+React modal for Rhinestone Deposits: accept deposits from any chain, asset or payment method, and let users withdraw the same way.
 
-**[Documentation](https://docs.rhinestone.dev/deposits/widget/quickstart)** ·
-[Deposit modal](https://docs.rhinestone.dev/deposits/widget/deposit-modal) ·
-[Withdraw modal](https://docs.rhinestone.dev/deposits/widget/withdraw-modal) ·
-[Backend proxy](https://docs.rhinestone.dev/deposits/widget/backend) ·
-[Migration guide](https://docs.rhinestone.dev/deposits/widget/migration)
+**[Documentation](https://docs.rhinestone.dev/deposits/overview/widget/quickstart)** ·
+[Deposit modal](https://docs.rhinestone.dev/deposits/overview/widget/widget-configuration) ·
+[Withdraw modal](https://docs.rhinestone.dev/deposits/crypto/withdraw-funds) ·
+[Backend proxy](https://docs.rhinestone.dev/deposits/overview/widget/backend-setup) ·
+[Migration guide](https://docs.rhinestone.dev/deposits/overview/widget/migration-guide)
 
 This README covers the common integrations. The full props reference lives in the
 docs.
@@ -43,6 +43,22 @@ console error pointing at the CSP. Hosts without an explicit `img-src` (or with
 > sufficient. They now come from the CDN, which drops ~20 kB (brotli) from the
 > bundle and gives every Rhinestone surface one source of truth.
 
+### Token metadata (`/assets`)
+
+Token symbols, decimals, logos and USD prices come from the processor's asset
+endpoint, looked up by exact chain and token address. **Your proxy must forward
+both `GET /assets` and `QUERY /assets`** for new modal metadata and price
+lookups. Explicit CORS `allowMethods` must include `GET` and `QUERY`. Small
+batches use GET; larger ones use QUERY; a failed QUERY retries as GET sub-batches.
+The browser modal does not use an API key.
+
+Without `/assets`, prices are unavailable: request failures no longer fall
+back to `GET /prices` or invent a price. Token logos render as text badges,
+and symbols still come from the chain catalog and your QR token list. A
+withdrawal of a token neither the catalog nor `/assets` knows is blocked
+rather than signed with guessed decimals. Older modal releases may still use
+the supported public `/prices` proxy route; do not remove it for those clients.
+
 All three modals also post session analytics to Rhinestone (see
 [Analytics](#analytics)), so a host with an explicit `connect-src` must allow the
 orchestrator alongside its own proxy:
@@ -114,6 +130,31 @@ time, it does not emit the `submitted` lifecycle event with the processor's
 internal tracking key. Its `complete` event reports the settled source and
 destination transaction hashes once they exist.
 
+## Checkout payments
+
+Pass `payment` when the modal funds one merchant order:
+
+```tsx
+<DepositModal
+  {...depositProps}
+  payment={{ salt: order.accountSalt, amount: order.amountBaseUnits }}
+/>
+```
+
+Register the order's managed account on your server first, then pass its 32-byte
+salt to the modal. The same salt must resolve to the account address stored with
+the order. `amount` is the required **destination token amount in base units**,
+not a USD amount. The modal asks `/quotes/preview` for an `exactOut` quote and
+shows the source amount the payer should send; the backend proxy must forward
+that route to a processor with `exactOut` support.
+
+Reconcile using the account on processor webhooks or `GET /deposits?account=`.
+`destinationAmount` on the `complete` event is the amount actually delivered in
+destination token base units. Quotes are estimates, and a payer using a QR,
+exchange, or card can send a different amount, so compare the delivered amount
+with the order amount before marking it paid. Checkout mode withholds the
+recipient's deposit history from the payer.
+
 ## Withdraw
 
 `WithdrawModal` lives at `@rhinestone/deposit-modal/withdraw` and reports through the same `onLifecycle` + `onError` callbacks. It needs no wallet: you give it the account holding the funds and a function that performs one transfer.
@@ -191,7 +232,7 @@ signature, so there is no privilege for a page to borrow.
 
 **Your proxy must forward `POST /deposits/recover`**, alongside the `GET /deposits`
 used for the lookup. Both are in the
-[reference proxy](https://docs.rhinestone.dev/deposits/widget/backend); a proxy
+[reference proxy](https://docs.rhinestone.dev/deposits/overview/widget/backend-setup); a proxy
 missing the recover route 404s the recovery rather than degrading.
 
 Two properties fall out of signing that are worth knowing:
@@ -269,6 +310,14 @@ The flow: user picks a fiat option → modal registers a Rhinestone smart accoun
 - **Sponsored** (client has a funded sponsor pool for the source chain): user receives 1:1 — the on-ramped amount lands on the target chain exactly.
 - **Unsponsored**: the bridging cost is deducted from the on-ramped amount and shown as a "Bridging cost" line on the success screen.
 
+> **Proxy routes.** Card and exchange checkouts use the unified ramp routes with
+> your API key attached: `POST /onramp/orders`,
+> `GET /onramp/options?provider=swapped` and `GET /onramp/orders/:id`. The last
+> two are also bank customer routes: forward them with the key only when the
+> request carries no `Authorization` header, and never key-forward the list
+> `GET /onramp/orders`. [`deposit-widget-proxy`](https://github.com/rhinestonewtf/deposit-widget-proxy)
+> does this from #38. Keep the `/onramp/swapped/*` routes for older modal versions.
+
 Host CSP must allow Swapped's domains:
 
 ```
@@ -283,9 +332,92 @@ frame-src https://widget.swapped.com https://sandbox.swapped.com https://connect
 | `enableQrTransfer` | `boolean`           | `true`   | Show the Transfer Crypto / QR row. Set false for fiat-only.                                                              |
 | `fiatMethods`      | `FiatMethodsConfig` | regional | Optional exact subset of standard `payment_group`s. Providing it opts out of regional personalization; empty means none. |
 
+### Bank transfer accounts (Noah)
+
+> **Preview.** Your proxy must forward these on the customer bearer before you ship
+> a modal with `bankOnramp`: `GET /compliance/status`, `POST /compliance/verification`,
+> `GET /onramp/options`, `POST`/`GET /onramp/accounts`,
+> `GET /onramp/accounts/:id[/details]` and `GET /onramp/orders[/:id]`. A missing one
+> 404s at the proxy. [`deposit-widget-proxy`](https://github.com/rhinestonewtf/deposit-widget-proxy)
+> forwards all of them.
+>
+> The prop is opt-in and inert unless you pass it. Treat it as unstable until
+> this note is removed.
+
+Pass `bankOnramp` to use reusable USD/EUR account details when Noah is provisioned
+for your organization. Integrator KYB happens directly with Noah; Rhinestone
+enables provisioning after Noah confirms it. Card and Apple Pay continue through Swapped. A customer who has
+not been verified is taken through hosted verification first; an existing active
+account is resumed; otherwise the account is configured once. There is no account
+selection: the customer's one account opens directly.
+
+Rhinestone chooses the currency from the residence the customer declares during
+verification: EUR inside SEPA, USD elsewhere. It is not configurable, and it does
+not follow the customer's location. The options are read again once the customer
+is approved, because only then is the residence known.
+
+The modal checks `GET /onramp/options?provider=noah` before customer verification. A 404
+(provisioning disabled, a declared residence Noah doesn't serve, or an older proxy)
+routes bank transfer through Swapped. When Swapped's regional list has no bank transfer
+either, the customer returns to the Cash methods with a notice and the row hidden.
+A successful response keeps Noah exclusive, even when no currencies are available.
+Authentication and service errors show a retry instead of switching providers.
+
+Bank transfers appear in History, including transfers that never become chain
+deposits. The History icon stays available during Noah verification and bank details;
+new activity adds a dot without navigating away.
+Opening History acknowledges that activity and clears the bank notification;
+only a subsequent new transfer or stage change adds it again.
+After entering the bank journey, History refreshes `GET /onramp/orders?provider=noah` every 30 seconds while the modal
+is open and visible, and on focus or opening History. Discovery continues after a
+transfer finishes so the next one is detected. A linked deposit shares the entry
+and shows final settlement separately from the provider's delivery.
+Each bank-transfer entry shows its amount, date and latest status rather than
+individual provider stages. "Settled" means crypto reached the deposit account;
+"Completed" requires the linked deposit's final settlement to complete.
+Expanded fiat entries use the same explorer links as crypto History: the
+incoming crypto deposit and, when available, final settlement on its destination
+chain. No on-chain link is shown for a fiat-only or sub-fee transfer.
+
+```tsx
+<DepositModal
+  bankOnramp={{
+    supportUrl: "https://your-app.example/support", // Optional bank-transfer help.
+    getSession: (smartAccount) =>
+      authenticatedSessionClient.getCustomerSession({ smartAccount }),
+  }}
+  // ...
+/>
+```
+
+`getSession` must call your authenticated server endpoint, which mints a
+short-lived customer session with `createCustomerSessionHandler`. It is called
+for every request; do not put the Rhinestone API key in the browser.
+
+Bank instructions render inside the modal from `GET /onramp/accounts/:id/details`
+on the customer bearer: separate transfer rails (SWIFT, ACH, Wire, SEPA), copy
+controls, an optional payment reference, and the last-quoted fee with its
+capture date. The modal holds coordinates only in component state and clears
+them on exit. Do not send them to analytics or persist them in the host
+application. A `409` means the account predates snapshot capture and the
+processor backfill has not run; the customer is told to check back. Only identity
+verification uses Noah's hosted page.
+
+`bankOnramp` enables Cash when `fiatMethods` is omitted. When an exact
+`fiatMethods` subset is provided, it must include
+`{ "bank-transfer": true }`. The proxy must forward the `/onramp/options`,
+`/onramp/accounts` and `/onramp/orders` customer routes with the bearer token
+and without attaching its API key.
+
+Hosts with a strict CSP must allow Noah Checkout:
+
+```
+frame-src https://checkout.noah.com https://checkout.sandbox.noah.com;
+```
+
 ## Fund from Exchange (Swapped Connect)
 
-Pass `enableExchangeConnect` to expose a "Fund from Exchange" row alongside the existing options. Clicking it opens an exchange picker backed by `/onramp/swapped/connect-exchanges`; after the user picks an exchange, the modal embeds Swapped's Connect iframe for that selected `connection`, signs in, and Swapped pulls the crypto on-chain to the smart account.
+Pass `enableExchangeConnect` to expose a "Fund from Exchange" row alongside the existing options. Clicking it opens an exchange picker backed by `GET /onramp/options?provider=swapped&kind=exchange` (see the proxy routes under [Fiat on-ramp](#fiat-on-ramp-swapped)); after the user picks an exchange, the modal embeds Swapped's Connect iframe for that selected `connection`, signs in, and Swapped pulls the crypto on-chain to the smart account.
 
 ```tsx
 <DepositModal
@@ -337,7 +469,7 @@ integration now posts analytics too, so it needs the `connect-src` above.
 Upgrading from 0.8.x is a breaking change on both modals.
 
 See [`MIGRATION.md`](./MIGRATION.md), or the same guide
-[in the docs](https://docs.rhinestone.dev/deposits/widget/migration).
+[in the docs](https://docs.rhinestone.dev/deposits/overview/widget/migration-guide).
 
 ## Contributing
 
@@ -348,9 +480,9 @@ Local setup, the release process and where the docs live are in
 
 MIT
 
-## Onramp and offramp services
+## Onramp service
 
-Deploy an updated `deposit-widget-proxy` before enabling these opt-in clients.
+Deploy an updated `deposit-widget-proxy` before enabling this opt-in client.
 Custom proxies must allow Authorization in CORS and forward customer routes
 without injecting `x-api-key`. Never proxy `POST /compliance/sessions` publicly.
 
@@ -361,12 +493,11 @@ and returns `{ externalCustomerId, smartAccount? }` from trusted server state.
 Mount its returned handler on your authenticated POST endpoint. It returns only
 the 15-minute `token` and `expiresAt`, with no-store response headers.
 
-Use separate scoped clients for onramp and offramp. The transport is internal;
-the package does not expose a generic customer service or arbitrary request method.
+The client is scoped to the customer's bearer. The transport is internal; the
+package does not expose a generic customer service or arbitrary request method.
 
 ```ts
 import { createOnrampService } from '@rhinestone/deposit-modal/onramp';
-import { createOfframpService } from '@rhinestone/deposit-modal/offramp';
 import { getComplianceStatus } from '@rhinestone/deposit-modal/compliance';
 
 const options = {
@@ -374,44 +505,44 @@ const options = {
   getSession: () => authenticatedSessionClient.getCustomerSession(),
 };
 const onramp = createOnrampService(options);
-const offramp = createOfframpService(options);
-const interaction = await onramp.createSession({
-  purpose: 'account_setup',
-  country: 'DE',
-  currency: 'EUR',
-  paymentMethod: 'bank_transfer',
-});
-// The hosted journey handles verification through interaction.nextAction.
+// Exactly one option, by region: EUR inside SEPA, USD elsewhere.
+const { options: available } = await onramp.getOptions();
+const { account } = await onramp.createAccount({ currency: available[0].currency });
+// Setup completes in this call and returns the account it configured.
+// Show the customer their bank details through a separate, repeatable call:
+const { bankDetails } = await onramp.getAccountDetails(account.id);
+// Each transfer into the account becomes an order, tracked stage by stage:
+const { items: orders } = await onramp.listOrders({ limit: 10 });
 const status = await getComplianceStatus(options);
 ```
 
-The onramp client has `createSession`, `getSession`, `getOptions`, `listAccounts`,
-`getAccount`, `listPayments` and `getPayment`. The offramp client has the same
-session/options/payment methods, without accounts. `getComplianceStatus` retains
-the existing `/compliance/status` read separately; it is not a preliminary step.
-Shared types include `RampSession`, `RampOption` and `RampCurrency`.
-`CustomerSession` remains the browser bearer/expiry pair. Catch `ScopedRequestError`
-and inspect its `status` for HTTP failures; response bodies are not included.
+The client has `getOptions`, `createAccount`, `listAccounts`, `getAccount`,
+`getAccountDetails` and `listOrders`, on the unified
+`/onramp/options`, `/onramp/accounts` and `/onramp/orders` routes.
+`getComplianceStatus` retains the existing `/compliance/status` read separately;
+it is not a preliminary step. Shared types include `OnrampOrder` (with its
+`ReceiptStage`, `ConversionStage`, `DeliveryStage` and `ReturnStage`),
+`OnrampAccount`, `RampOption` and `RampCurrency`. `CustomerSession` remains the
+browser bearer/expiry pair. Catch `ScopedRequestError` and inspect its `status`
+for HTTP failures; response bodies are not included.
 
-The three lightweight subpaths replace the unpublished `/customer` entry point.
-They do not import React, wallet connectors or the server-only token helper.
+The lightweight subpaths do not import React, wallet connectors or the
+server-only token helper.
 
 `getSession` is called per request. Keep tokens in memory, scoped to the logged-in
-user, and refresh them through your authenticated server. The clients reject
-expired sessions and never fall back to an application key. They make no calls
+user, and refresh them through your authenticated server. The client rejects
+expired sessions and never falls back to an application key. It makes no calls
 until explicitly invoked, so existing modals and Swapped flows remain unchanged.
-There is no preliminary capability request. Support/recovery methods belong to
-the future provider lifecycle implementation and are not exposed here.
-
-The initial contracts support EUR/USD bank transfers only. Onramp hosted setup
-uses `purpose: 'account_setup'` without an amount; the actual transfer determines
-fiat sent. Offramp hosted beneficiary collection uses
-`purpose: 'beneficiary_collection'`, separately from quoting and funding.
-Offramp options use `amount` as decimal fiat major units the recipient receives.
-No crypto-input quoting is exposed. Accounts return safe references/config/status,
-not bank instructions. Hosted interaction completion never means payment
-settlement; funding, payout and late returns have independent status fields.
-
-The provider adapter and journey execution are not connected by this release.
-Expect 503 until those implementations are deployed. Render hosted URLs only
-after the journey's iframe presentation has been verified; do not log/store URLs.
+
+**An account setup is not a session.** It completes in the call that creates it
+and returns `{ account }` — no status to poll, no expiry, no `nextAction`. Bank
+details are read separately through `getAccountDetails`, because a customer
+reads them before every transfer while setup happens once; that call returns
+the stored instructions (`OnrampBankDetails`) and never calls the provider.
+
+**An order is complete only once its crypto landed.** `stages.delivery` is
+`submitted` when the provider reports the transfer and `completed`, with a
+`depositId`, only once chain ingestion saw it. Show "delivered" for nothing
+weaker. The initial contracts support EUR/USD bank transfers only; setup takes
+a currency and no amount, because the actual transfer determines fiat sent. Do
+not log or store hosted URLs.