@rhinestone/deposit-modal 0.12.2 → 0.14.0

package/README.md

@@ -50,6 +50,17 @@ 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.
 
+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:
+
+```
+connect-src 'self' https://v1.orchestrator.rhinestone.dev;
+```
+
+A blocked origin is reported on `onEvent` as an `analytics_ingest_failure`, not
+surfaced to the user.
+
 ## Example
 
 ```tsx
@@ -97,6 +108,19 @@ export function DepositButton({ walletClient, publicClient, recipient }) {
 }
 ```
 
+Set `enableGaslessDeposit` on `DepositModal` to offer off-chain token
+authorization on eligible cross-chain ERC-20 deposits. It defaults to `false`.
+The processor selects ERC-3009 first, ERC-2612 second, and Permit2 third; the
+Permit2 route is available only when the owner already approved the token to
+Permit2. If no gasless route is available, or submission is definitively
+rejected, the modal explicitly offers the ordinary token transfer. The backend
+proxy must forward `/deposits/permit/prepare` and `/deposits/permit`, and the
+processor deployment must have its global permit endpoint switch enabled.
+Because a permit submission has no source-chain transaction at submission
+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.
+
 ## 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.
@@ -143,25 +167,25 @@ import { ClaimModal } from "@rhinestone/deposit-modal/claim";
   defaultTxHash={depositTxHash}
   defaultRefundDestination={knownSelfCustodialAddress}
   onLifecycle={(event) => console.log(event)}
-/>
+/>;
 ```
 
 ### Why the user signs
 
 Deposit accounts are owned by the Rhinestone service, so the account holding the
 funds has no user key and cannot sign for its own refund. But the deposit's
-`recipient` — the in-app wallet the funds were headed to — *is* a key your user
+`recipient` — the in-app wallet the funds were headed to — _is_ a key your user
 holds. So that is what authorizes the recovery.
 
 `signRecovery` is handed the exact typed data to sign plus the `signer` address the
 processor will verify against, and returns a signature. Return whatever that
 address's own verifier accepts:
 
-| recipient is | return |
-|---|---|
-| embedded EOA (Privy, Turnkey, Dynamic) | `signTypedData` — the raw 65-byte signature |
-| deployed smart account | a signature valid under its ERC-1271 `isValidSignature` |
-| undeployed smart account | an ERC-6492 wrapper — `SignatureErc6492.wrap` from `ox/erc6492`, which ships with viem |
+| recipient is                           | return                                                                                 |
+| -------------------------------------- | -------------------------------------------------------------------------------------- |
+| embedded EOA (Privy, Turnkey, Dynamic) | `signTypedData` — the raw 65-byte signature                                            |
+| deployed smart account                 | a signature valid under its ERC-1271 `isValidSignature`                                |
+| undeployed smart account               | an ERC-6492 wrapper — `SignatureErc6492.wrap` from `ox/erc6492`, which ships with viem |
 
 A raw owner signature is usually **not** enough for a smart account: a Safe expects
 its own message wrapping, so go through your account SDK rather than signing the
@@ -181,7 +205,7 @@ Two properties fall out of signing that are worth knowing:
 
 - **The destination is inside the signed struct.** The processor cannot pay anywhere
   else, so the success screen states what the user signed rather than trusting the
-  endpoint to report where the money went. `defaultRefundDestination` only *seeds*
+  endpoint to report where the money went. `defaultRefundDestination` only _seeds_
   the field; whatever the user submits is what they sign.
 - **Failures carry a structured code**, so the modal knows when a retry helps. A
   verification outage is retryable; a rejected signature or a deposit already
@@ -248,6 +272,7 @@ The flow: user picks a fiat option → modal registers a Rhinestone smart accoun
 **Destination guarantees.** The user picks the fiat amount inside Swapped's widget, but the destination is fixed server-side: every order receives **USDC on Base** delivered to the **registered Rhinestone smart account**. The frontend cannot override these; the backend signs the Swapped URL with `currencyCode=USDC_BASE` and `walletAddress=<smartAccount>`.
 
 **Fees.** Rhinestone does not charge a markup by default. The client (dapp) controls the user-facing experience via the orchestrator's sponsorship config:
+
 - **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.
 
@@ -259,11 +284,11 @@ frame-src https://widget.swapped.com https://sandbox.swapped.com https://connect
 
 **Submerchant attribution.** Swapped orders are tagged with a `submerchant` for multi-tenant reporting. This is derived automatically server-side from the embedding page's domain (the request `Origin` header) — no configuration is required. In local development the domain resolves to `localhost`.
 
-| Prop                 | Type                          | Default | Description |
-| -------------------- | ----------------------------- | ------- | ----------- |
-| `enableFiatOnramp`   | `boolean`                     | `false` | Show fiat on-ramp option(s). Requires backend Swapped keys. Needs no wallet. |
-| `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. |
+| Prop               | Type                | Default  | Description                                                                                                              |
+| ------------------ | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `enableFiatOnramp` | `boolean`           | `false`  | Show fiat on-ramp option(s). Requires backend Swapped keys. Needs no wallet.                                             |
+| `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. |
 
 ## Fund from Exchange (Swapped Connect)
 
@@ -278,14 +303,44 @@ Pass `enableExchangeConnect` to expose a "Fund from Exchange" row alongside the
 
 Flow: user picks Fund from Exchange → backend returns supported exchanges + logos from Swapped using a 24-hour cache → user picks an exchange → modal registers a Rhinestone smart account → backend mints a server-signed Swapped Connect URL with the selected `connection` → user authenticates with their CEX inside the iframe → Swapped pushes crypto on-chain → existing on-chain detection fires `onLifecycle({ type: "complete" })`.
 
-| Prop                     | Type      | Default | Description |
-| ------------------------ | --------- | ------- | ----------- |
-| `enableExchangeConnect`  | `boolean` | `false` | Show the "Fund from Exchange" row. Requires backend Swapped keys. Needs no wallet. Can be combined with `enableFiatOnramp`. |
+| Prop                    | Type      | Default | Description                                                                                                                 |
+| ----------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `enableExchangeConnect` | `boolean` | `false` | Show the "Fund from Exchange" row. Requires backend Swapped keys. Needs no wallet. Can be combined with `enableFiatOnramp`. |
+
+## Analytics
+
+`onEvent` receives the deposit, withdraw and claim funnels as a session-scoped
+stream:
+every event carries the session id, the modal, the widget version and a snapshot
+of the session's configuration.
+
+The same events are also sent to Rhinestone, batched, in the background, and
+flushed when the modal closes or the page goes away. Delivery never affects the
+flow and never changes what `onEvent` receives. Sessions are attributed to your
+project through a short-lived token minted at `POST /analytics/ingest-token` on
+your proxy; a proxy that does not forward that route still collects, just
+unattributed.
+
+| Prop                     | Type      | Default | Description                                                     |
+| ------------------------ | --------- | ------- | --------------------------------------------------------------- |
+| `enableAnalyticsIngest`  | `boolean` | `true`  | Set `false` to stop sending analytics to Rhinestone. `onEvent` is unaffected. |
+
+When a batch cannot be delivered, `onEvent` receives one
+`analytics_ingest_failure` per distinct reason per session, naming the reason
+(`network` — which includes a CSP block — `rejected`, `conflict`,
+`unauthorized`, `throttled`, `unavailable`, `token_unavailable`, `unsupported`),
+the HTTP status when there was one, and how many events the session has lost so
+far.
 
 ## Upgrading
 
-Upgrading from 0.8.x is a breaking change on both modals. See
-[`MIGRATION.md`](./MIGRATION.md), or the same guide
+Upgrading from 0.13.x changes what `onEvent` delivers: the deposit events are
+replaced by a method-aware taxonomy, the five flat claim events are replaced by
+a claim funnel, and every event gains a session envelope. A claim-only
+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).
 
 ## Contributing