@rhinestone/deposit-modal 0.14.0 → 0.15.0

package/dist/{types-Bho4OA03.d.ts → types-CQ0NHqCy.d.ts}

@@ -1,5 +1,5 @@
+import { D as DisplayChainId, d as TargetChain } from './caip-BMi-9t09.js';
 import { TypedDataDefinition, Address, Hex, WalletClient, PublicClient, Chain } from 'viem';
-import { T as TargetChain } from './caip-D8aRWdEY.js';
 
 /**
  * Public config shape exposed on DepositModalProps. Each provider defaults to
@@ -39,8 +39,9 @@ interface SignRecoveryPayload {
      */
     signer: Address;
     /**
-     * The chain the deposit is on, and therefore the chain the signature is
-     * verified against.
+     * The chain the signature is verified against: the deposit's DESTINATION
+     * chain, where the recipient wallet lives. Not the source chain the refund
+     * pays out on — the processor verifies on the target and never falls back.
      *
      * Load-bearing for a smart account: ERC-1271 and ERC-6492 verification are
      * per-chain, so a signature produced against the wrong one is well formed,
@@ -69,6 +70,14 @@ type SignRecovery = (payload: SignRecoveryPayload) => Promise<Hex>;
 /** Structured code from the processor; drives copy and whether a retry helps. */
 type RecoveryErrorCode = "DEPOSIT_NOT_RECOVERABLE" | "RECOVERY_UNSUPPORTED" | "SIGNATURE_INVALID" | "VERIFICATION_UNAVAILABLE" | "REFUND_RECONCILIATION_REQUIRED" | "REFUND_FAILED";
 
+/**
+ * How a `GET /deposits` row reads on screen, and which rows are on screen at
+ * all. Shared rather than private to the history panel: the header's status dot
+ * derives from the same rows the panel lists, and a second copy of either
+ * answer would let the badge and the list disagree.
+ */
+type HistoryStatus = "pending" | "processing" | "completed" | "failed" | "refunded" | "spam";
+
 /**
  * Consumer-supplied RPC URL overrides, scoped to a single modal instance (see
  * {@link RpcUrlsProvider}). Threaded into every client the modal builds — EVM
@@ -84,7 +93,7 @@ type ChainKey = number | "solana";
 type RpcUrlMap = Partial<Record<ChainKey, string>>;
 
 type Caip2ChainId = `eip155:${number}` | `solana:${string}`;
-type ChainId = number | "solana" | "hypercore" | Caip2ChainId;
+type ChainId = DisplayChainId | Caip2ChainId;
 interface DepositModalTheme {
     /**
      * Absent means light, unconditionally — never "follow the OS". `"system"` is
@@ -286,13 +295,39 @@ interface DepositModalProps {
      */
     enableExchangeConnect?: boolean;
     onRequestConnect?: () => void;
+    /**
+     * Signs a refund for a failed deposit the user recovers from its history
+     * row. Supply it to offer recovery; omit it and history behaves exactly as it
+     * does today — a failed row expands to its cause and details with no action.
+     *
+     * The processor verifies the signature against the deposit's `recipient`, on
+     * the deposit's DESTINATION chain, so return whatever that address's own
+     * verifier accepts there:
+     * - **embedded EOA** (Privy, Turnkey, Dynamic) — `signTypedData`, raw 65-byte
+     *   result.
+     * - **deployed smart account** — a signature valid under its ERC-1271
+     *   `isValidSignature`. A raw owner signature is usually not enough; a Safe,
+     *   for one, expects its own message wrapping, so go through your account SDK.
+     * - **undeployed smart account** — wrap per ERC-6492 so it can be verified
+     *   counterfactually. `SignatureErc6492.wrap` from `ox/erc6492` does this and
+     *   ships with viem already.
+     *
+     * Throwing (or returning nothing) is treated as the user declining, which is
+     * retryable.
+     */
+    signRecovery?: SignRecovery;
     theme?: DepositModalTheme;
     uiConfig?: DepositModalUIConfig;
     className?: string;
     onReady?: () => void;
     /** Discriminated stream of deposit lifecycle transitions. */
     onLifecycle?: (event: DepositLifecycleEvent) => void;
-    onEvent?: (event: DepositAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
+    /**
+     * Funnel telemetry. Also delivers `ClaimAnalyticsEvent`: a recovery started
+     * from history opens a claim session inside this modal, and a host that logs
+     * events would otherwise go blind exactly where funds are being recovered.
+     */
+    onEvent?: (event: DepositAnalyticsEvent | ClaimAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
     onError?: (data: ErrorEventData) => void;
     /**
      * Send session analytics to Rhinestone in addition to `onEvent`. Default:
@@ -370,7 +405,8 @@ interface WithdrawModalProps {
     onReady?: () => void;
     /** Discriminated stream of withdraw lifecycle transitions. */
     onLifecycle?: (event: WithdrawLifecycleEvent) => void;
-    onEvent?: (event: WithdrawAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
+    /** Claim events included, on the same terms as the deposit modal's. */
+    onEvent?: (event: WithdrawAnalyticsEvent | ClaimAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
     onError?: (data: ErrorEventData) => void;
     /**
      * Send session analytics to Rhinestone in addition to `onEvent`. Default:
@@ -379,6 +415,31 @@ interface WithdrawModalProps {
     enableAnalyticsIngest?: boolean;
     /** @internal Rhinestone's own dev verification. Not a supported prop. */
     analyticsIngestUrl?: string;
+    /**
+     * Signs a refund for a failed deposit the user recovers from a history row.
+     * Supply it to offer recovery; omit it and the panel is read-only — a failed
+     * row expands to its cause and details with no action.
+     *
+     * History here is the WITHDRAWAL DESTINATION's, so the signer is an address
+     * the user typed into the form rather than a wallet your app issued. Omit
+     * this prop unless your users can sign for the addresses they withdraw to.
+     *
+     * The processor verifies the signature against the deposit's `recipient`, on
+     * the deposit's DESTINATION chain, so return whatever that address's own
+     * verifier accepts there:
+     * - **embedded EOA** (Privy, Turnkey, Dynamic) — `signTypedData`, raw 65-byte
+     *   result.
+     * - **deployed smart account** — a signature valid under its ERC-1271
+     *   `isValidSignature`. A raw owner signature is usually not enough; a Safe,
+     *   for one, expects its own message wrapping, so go through your account SDK.
+     * - **undeployed smart account** — wrap per ERC-6492 so it can be verified
+     *   counterfactually. `SignatureErc6492.wrap` from `ox/erc6492` does this and
+     *   ships with viem already.
+     *
+     * Throwing (or returning nothing) is treated as the user declining, which is
+     * retryable.
+     */
+    signRecovery?: SignRecovery;
     debug?: boolean;
 }
 /**
@@ -649,6 +710,57 @@ interface AnalyticsEventEnvelope<Modal extends "deposit" | "withdraw" | "claim",
     timestamp: string;
     session_properties: SessionProperties;
 }
+/**
+ * Which state the history entry point's dot was in when the panel was opened.
+ * `none` is the quiet state, reported as a value rather than by omission.
+ */
+type HistoryAnalyticsBadge = "needs_you" | "progress" | "none";
+/** Which of history's two entries a recovery attempt started from. */
+type HistoryClaimEntrySource = "history_row" | "history_fallback";
+/**
+ * The history surface reports on the session of the modal the user is in, under
+ * mirrored names — so a deposit and a withdraw visit are the same measurement
+ * of the same panel. Every event of one visit carries its `history_visit_id`;
+ * a close and reopen is a second visit with a different one.
+ *
+ * `deposit_id` is the join key into the claim stream. Amounts, tokens,
+ * recipients and searched transaction hashes are deliberately absent.
+ */
+type HistoryAnalyticsPayloads<Modal extends "deposit" | "withdraw", Step> = {
+    type: `${Modal}_modal_history_open`;
+    history_visit_id: string;
+    /** The host funnel step history was opened from; null before one opened. */
+    step: Step | null;
+    badge: HistoryAnalyticsBadge;
+    badge_count: number;
+}
+/** One per deposit per visit: a row expanded twice still counts once. */
+ | {
+    type: `${Modal}_modal_history_row_view`;
+    history_visit_id: string;
+    deposit_id: string;
+    status: HistoryStatus;
+    recoverable: boolean;
+    /** 0-based index in the list as displayed. */
+    position: number;
+} | {
+    type: `${Modal}_modal_history_load_more`;
+    history_visit_id: string;
+    /** 1-based press count within the visit. */
+    page: number;
+    /** Rows on screen before the press. */
+    loaded_rows: number;
+} | {
+    type: `${Modal}_modal_history_fallback_open`;
+    history_visit_id: string;
+    claim_attempt_id: string;
+} | {
+    type: `${Modal}_modal_history_recovery_start`;
+    history_visit_id: string;
+    claim_attempt_id: string;
+    entry_source: HistoryClaimEntrySource;
+    deposit_id: string;
+};
 type DepositAnalyticsSharedStep = "account_setup" | "funding_method_home";
 type DepositAnalyticsWalletStep = "wallet_connect" | "wallet_source_asset" | "wallet_source_token" | "wallet_amount" | "wallet_review" | "wallet_submit" | "wallet_processing";
 type DepositAnalyticsTransferStep = "transfer_source_selection" | "transfer_address_shown" | "transfer_copy" | "transfer_fee_amount" | "transfer_fee_review" | "transfer_tracking";
@@ -785,7 +897,7 @@ type DepositAnalyticsCommonEventPayload = {
     source: DepositAnalyticsCloseSource;
     step: DepositAnalyticsStep | null;
     after_handoff: boolean;
-};
+} | HistoryAnalyticsPayloads<"deposit", DepositAnalyticsStep>;
 /**
  * Method-aware deposit telemetry. UI outcomes describe only what the widget
  * observed and must not be treated as backend fulfilment truth.
@@ -869,7 +981,9 @@ type WithdrawAnalyticsEventPayload = {
     step: WithdrawAnalyticsStep | null;
     after_handoff: boolean;
     same_route?: boolean;
-};
+} | (HistoryAnalyticsPayloads<"withdraw", WithdrawAnalyticsStep> & {
+    same_route?: boolean;
+});
 type WithdrawAnalyticsEvent = WithdrawAnalyticsEventPayload & AnalyticsEventEnvelope<"withdraw", WithdrawAnalyticsSessionProperties>;
 /**
  * `submit` is the async boundary the review CTA opens rather than a screen of
@@ -879,8 +993,28 @@ type ClaimAnalyticsStep = "lookup" | "select" | "review" | "submit";
 /** Every reason has a call site in the claim flow; none is aspirational. */
 type ClaimAnalyticsFailureReason = RoutableAnalyticsReason<"lookup_transaction_hash_invalid" | "lookup_failed" | "lookup_no_deposits_found" | "lookup_no_eligible_deposits" | "refund_destination_invalid" | "recovery_deposit_data_incomplete" | "signature_rejected" | "signature_invalid" | "recovery_deposit_not_recoverable" | "recovery_unsupported" | "signature_verification_unavailable" | "refund_reconciliation_required" | "refund_failed" | "refund_service_unreachable" | "modal_close_refused_in_flight">;
 type ClaimAnalyticsAbandonmentReason = "back" | "modal_close";
-type ClaimAnalyticsCloseSource = "header_button" | "escape" | "overlay" | "host_controlled" | "success_done" | "failure_cancel";
+type ClaimAnalyticsCloseSource = "header_button" | "escape" | "overlay" | "host_controlled" | "success_done" | "failure_cancel"
+/** The labelled control back to the history list a recovery was started from. */
+ | "history_back";
 type ClaimAnalyticsUiOutcome = "completed" | "failed";
+/**
+ * Where a claim attempt was entered from. Present on every claim session, the
+ * standalone modal's included: segmenting on a value that is there keeps a
+ * standalone claim distinguishable from an older widget that reports nothing.
+ */
+type ClaimAnalyticsEntrySource = "standalone" | HistoryClaimEntrySource;
+/**
+ * What ties a claim attempt back to the history visit that produced it. Carried
+ * on every event of the attempt rather than in `session_properties`, which the
+ * ingest contract compares for equality across a session.
+ */
+interface ClaimAnalyticsCorrelation {
+    entry_source: ClaimAnalyticsEntrySource;
+    /** The deposit or withdraw session the attempt was started inside. */
+    source_session_id?: string;
+    history_visit_id?: string;
+    claim_attempt_id?: string;
+}
 /**
  * Claim funnel telemetry. Identities enter the stream only once a lookup has
  * matched a backend deposit row: the hash the user searched for, the refund
@@ -892,7 +1026,8 @@ type ClaimAnalyticsUiOutcome = "completed" | "failed";
  * no hash, never an empty string: `deposit_id` is the join key, and a blank
  * identity would join to nothing while looking like one that does.
  */
-type ClaimAnalyticsEventPayload = {
+type ClaimAnalyticsEventPayload = ClaimAnalyticsEventDetail & Partial<ClaimAnalyticsCorrelation>;
+type ClaimAnalyticsEventDetail = {
     type: "claim_modal_open";
 } | {
     type: "claim_modal_step_open";
@@ -979,4 +1114,4 @@ interface AnalyticsIngestFailureEvent {
 }
 type ModalAnalyticsEvent = DepositAnalyticsEvent | WithdrawAnalyticsEvent | ClaimAnalyticsEvent | AnalyticsIngestFailureEvent;
 
-export type { WithdrawAnalyticsCloseSource as $, AnalyticsEventEnvelope as A, DepositAnalyticsStep as B, ChainId as C, DepositAnalyticsAbandonmentReason as D, DepositAnalyticsTransferStep as E, DepositAnalyticsUiOutcome as F, DepositAnalyticsWalletStep as G, DepositAssetMigrationMethodIdentifiers as H, DepositCompleteEventData as I, DepositExchangeConnectMethodIdentifiers as J, DepositFailedEventData as K, DepositFiatOnrampMethodIdentifiers as L, DepositFundingMethod as M, DepositLifecycleEvent as N, DepositModalProps as O, DepositModalTheme as P, DepositModalUIConfig as Q, DepositSubmittedEventData as R, DepositTransferHandoffIdentifiers as S, DepositWalletIntegration as T, DepositWalletMethodIdentifiers as U, ErrorEventData as V, FiatMethodsConfig as W, ModalAnalyticsEvent as X, OutputTokenRule as Y, RpcUrlMap as Z, WithdrawAnalyticsAbandonmentReason as _, AnalyticsIngestFailureEvent as a, WithdrawAnalyticsEvent as a0, WithdrawAnalyticsEventPayload as a1, WithdrawAnalyticsFailureReason as a2, WithdrawAnalyticsSessionProperties as a3, WithdrawAnalyticsStep as a4, WithdrawAnalyticsUiOutcome as a5, WithdrawCompleteEventData as a6, WithdrawFailedEventData as a7, WithdrawLifecycleEvent as a8, WithdrawModalProps as a9, WithdrawSubmittedEventData as aa, WithdrawTransferRequest as ab, RecoveryErrorCode as ac, SignRecovery as ad, SignRecoveryPayload as ae, AnalyticsIngestFailureReason as b, AnalyticsReasonFamily as c, AssetMigrationsConfig as d, AssetOption as e, ClaimAnalyticsAbandonmentReason as f, ClaimAnalyticsCloseSource as g, ClaimAnalyticsEvent as h, ClaimAnalyticsEventPayload as i, ClaimAnalyticsFailureReason as j, ClaimAnalyticsSessionProperties as k, ClaimAnalyticsStep as l, ClaimAnalyticsUiOutcome as m, ClaimLifecycleEvent as n, ClaimModalProps as o, ConnectedEventData as p, DepositAnalyticsCloseSource as q, DepositAnalyticsCorrelator as r, DepositAnalyticsEvent as s, DepositAnalyticsEventPayload as t, DepositAnalyticsExchangeStep as u, DepositAnalyticsFailureReason as v, DepositAnalyticsFiatStep as w, DepositAnalyticsMigrationStep as x, DepositAnalyticsSessionProperties as y, DepositAnalyticsSharedStep as z };
+export type { HistoryStatus as $, AnalyticsEventEnvelope as A, DepositAnalyticsSessionProperties as B, ChainId as C, DepositAnalyticsAbandonmentReason as D, DepositAnalyticsSharedStep as E, DepositAnalyticsStep as F, DepositAnalyticsTransferStep as G, DepositAnalyticsUiOutcome as H, DepositAnalyticsWalletStep as I, DepositAssetMigrationMethodIdentifiers as J, DepositCompleteEventData as K, DepositExchangeConnectMethodIdentifiers as L, DepositFailedEventData as M, DepositFiatOnrampMethodIdentifiers as N, DepositFundingMethod as O, DepositLifecycleEvent as P, DepositModalProps as Q, DepositModalTheme as R, DepositModalUIConfig as S, DepositSubmittedEventData as T, DepositTransferHandoffIdentifiers as U, DepositWalletIntegration as V, DepositWalletMethodIdentifiers as W, ErrorEventData as X, FiatMethodsConfig as Y, HistoryAnalyticsBadge as Z, HistoryClaimEntrySource as _, AnalyticsIngestFailureEvent as a, ModalAnalyticsEvent as a0, OutputTokenRule as a1, RecoveryErrorCode as a2, RpcUrlMap as a3, SignRecovery as a4, SignRecoveryPayload as a5, WithdrawAnalyticsAbandonmentReason as a6, WithdrawAnalyticsCloseSource as a7, WithdrawAnalyticsEvent as a8, WithdrawAnalyticsEventPayload as a9, WithdrawAnalyticsFailureReason as aa, WithdrawAnalyticsSessionProperties as ab, WithdrawAnalyticsStep as ac, WithdrawAnalyticsUiOutcome as ad, WithdrawCompleteEventData as ae, WithdrawFailedEventData as af, WithdrawLifecycleEvent as ag, WithdrawModalProps as ah, WithdrawSubmittedEventData as ai, WithdrawTransferRequest as aj, AnalyticsIngestFailureReason as b, AnalyticsReasonFamily as c, AssetMigrationsConfig as d, AssetOption as e, ClaimAnalyticsAbandonmentReason as f, ClaimAnalyticsCloseSource as g, ClaimAnalyticsCorrelation as h, ClaimAnalyticsEntrySource as i, ClaimAnalyticsEvent as j, ClaimAnalyticsEventPayload as k, ClaimAnalyticsFailureReason as l, ClaimAnalyticsSessionProperties as m, ClaimAnalyticsStep as n, ClaimAnalyticsUiOutcome as o, ClaimLifecycleEvent as p, ClaimModalProps as q, ConnectedEventData as r, DepositAnalyticsCloseSource as s, DepositAnalyticsCorrelator as t, DepositAnalyticsEvent as u, DepositAnalyticsEventPayload as v, DepositAnalyticsExchangeStep as w, DepositAnalyticsFailureReason as x, DepositAnalyticsFiatStep as y, DepositAnalyticsMigrationStep as z };

package/dist/{types-DP_3KwlD.d.cts → types-CxiLX5sv.d.cts}

@@ -1,5 +1,5 @@
+import { D as DisplayChainId, d as TargetChain } from './caip-BMi-9t09.cjs';
 import { TypedDataDefinition, Address, Hex, WalletClient, PublicClient, Chain } from 'viem';
-import { T as TargetChain } from './caip-D8aRWdEY.cjs';
 
 /**
  * Public config shape exposed on DepositModalProps. Each provider defaults to
@@ -39,8 +39,9 @@ interface SignRecoveryPayload {
      */
     signer: Address;
     /**
-     * The chain the deposit is on, and therefore the chain the signature is
-     * verified against.
+     * The chain the signature is verified against: the deposit's DESTINATION
+     * chain, where the recipient wallet lives. Not the source chain the refund
+     * pays out on — the processor verifies on the target and never falls back.
      *
      * Load-bearing for a smart account: ERC-1271 and ERC-6492 verification are
      * per-chain, so a signature produced against the wrong one is well formed,
@@ -69,6 +70,14 @@ type SignRecovery = (payload: SignRecoveryPayload) => Promise<Hex>;
 /** Structured code from the processor; drives copy and whether a retry helps. */
 type RecoveryErrorCode = "DEPOSIT_NOT_RECOVERABLE" | "RECOVERY_UNSUPPORTED" | "SIGNATURE_INVALID" | "VERIFICATION_UNAVAILABLE" | "REFUND_RECONCILIATION_REQUIRED" | "REFUND_FAILED";
 
+/**
+ * How a `GET /deposits` row reads on screen, and which rows are on screen at
+ * all. Shared rather than private to the history panel: the header's status dot
+ * derives from the same rows the panel lists, and a second copy of either
+ * answer would let the badge and the list disagree.
+ */
+type HistoryStatus = "pending" | "processing" | "completed" | "failed" | "refunded" | "spam";
+
 /**
  * Consumer-supplied RPC URL overrides, scoped to a single modal instance (see
  * {@link RpcUrlsProvider}). Threaded into every client the modal builds — EVM
@@ -84,7 +93,7 @@ type ChainKey = number | "solana";
 type RpcUrlMap = Partial<Record<ChainKey, string>>;
 
 type Caip2ChainId = `eip155:${number}` | `solana:${string}`;
-type ChainId = number | "solana" | "hypercore" | Caip2ChainId;
+type ChainId = DisplayChainId | Caip2ChainId;
 interface DepositModalTheme {
     /**
      * Absent means light, unconditionally — never "follow the OS". `"system"` is
@@ -286,13 +295,39 @@ interface DepositModalProps {
      */
     enableExchangeConnect?: boolean;
     onRequestConnect?: () => void;
+    /**
+     * Signs a refund for a failed deposit the user recovers from its history
+     * row. Supply it to offer recovery; omit it and history behaves exactly as it
+     * does today — a failed row expands to its cause and details with no action.
+     *
+     * The processor verifies the signature against the deposit's `recipient`, on
+     * the deposit's DESTINATION chain, so return whatever that address's own
+     * verifier accepts there:
+     * - **embedded EOA** (Privy, Turnkey, Dynamic) — `signTypedData`, raw 65-byte
+     *   result.
+     * - **deployed smart account** — a signature valid under its ERC-1271
+     *   `isValidSignature`. A raw owner signature is usually not enough; a Safe,
+     *   for one, expects its own message wrapping, so go through your account SDK.
+     * - **undeployed smart account** — wrap per ERC-6492 so it can be verified
+     *   counterfactually. `SignatureErc6492.wrap` from `ox/erc6492` does this and
+     *   ships with viem already.
+     *
+     * Throwing (or returning nothing) is treated as the user declining, which is
+     * retryable.
+     */
+    signRecovery?: SignRecovery;
     theme?: DepositModalTheme;
     uiConfig?: DepositModalUIConfig;
     className?: string;
     onReady?: () => void;
     /** Discriminated stream of deposit lifecycle transitions. */
     onLifecycle?: (event: DepositLifecycleEvent) => void;
-    onEvent?: (event: DepositAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
+    /**
+     * Funnel telemetry. Also delivers `ClaimAnalyticsEvent`: a recovery started
+     * from history opens a claim session inside this modal, and a host that logs
+     * events would otherwise go blind exactly where funds are being recovered.
+     */
+    onEvent?: (event: DepositAnalyticsEvent | ClaimAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
     onError?: (data: ErrorEventData) => void;
     /**
      * Send session analytics to Rhinestone in addition to `onEvent`. Default:
@@ -370,7 +405,8 @@ interface WithdrawModalProps {
     onReady?: () => void;
     /** Discriminated stream of withdraw lifecycle transitions. */
     onLifecycle?: (event: WithdrawLifecycleEvent) => void;
-    onEvent?: (event: WithdrawAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
+    /** Claim events included, on the same terms as the deposit modal's. */
+    onEvent?: (event: WithdrawAnalyticsEvent | ClaimAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
     onError?: (data: ErrorEventData) => void;
     /**
      * Send session analytics to Rhinestone in addition to `onEvent`. Default:
@@ -379,6 +415,31 @@ interface WithdrawModalProps {
     enableAnalyticsIngest?: boolean;
     /** @internal Rhinestone's own dev verification. Not a supported prop. */
     analyticsIngestUrl?: string;
+    /**
+     * Signs a refund for a failed deposit the user recovers from a history row.
+     * Supply it to offer recovery; omit it and the panel is read-only — a failed
+     * row expands to its cause and details with no action.
+     *
+     * History here is the WITHDRAWAL DESTINATION's, so the signer is an address
+     * the user typed into the form rather than a wallet your app issued. Omit
+     * this prop unless your users can sign for the addresses they withdraw to.
+     *
+     * The processor verifies the signature against the deposit's `recipient`, on
+     * the deposit's DESTINATION chain, so return whatever that address's own
+     * verifier accepts there:
+     * - **embedded EOA** (Privy, Turnkey, Dynamic) — `signTypedData`, raw 65-byte
+     *   result.
+     * - **deployed smart account** — a signature valid under its ERC-1271
+     *   `isValidSignature`. A raw owner signature is usually not enough; a Safe,
+     *   for one, expects its own message wrapping, so go through your account SDK.
+     * - **undeployed smart account** — wrap per ERC-6492 so it can be verified
+     *   counterfactually. `SignatureErc6492.wrap` from `ox/erc6492` does this and
+     *   ships with viem already.
+     *
+     * Throwing (or returning nothing) is treated as the user declining, which is
+     * retryable.
+     */
+    signRecovery?: SignRecovery;
     debug?: boolean;
 }
 /**
@@ -649,6 +710,57 @@ interface AnalyticsEventEnvelope<Modal extends "deposit" | "withdraw" | "claim",
     timestamp: string;
     session_properties: SessionProperties;
 }
+/**
+ * Which state the history entry point's dot was in when the panel was opened.
+ * `none` is the quiet state, reported as a value rather than by omission.
+ */
+type HistoryAnalyticsBadge = "needs_you" | "progress" | "none";
+/** Which of history's two entries a recovery attempt started from. */
+type HistoryClaimEntrySource = "history_row" | "history_fallback";
+/**
+ * The history surface reports on the session of the modal the user is in, under
+ * mirrored names — so a deposit and a withdraw visit are the same measurement
+ * of the same panel. Every event of one visit carries its `history_visit_id`;
+ * a close and reopen is a second visit with a different one.
+ *
+ * `deposit_id` is the join key into the claim stream. Amounts, tokens,
+ * recipients and searched transaction hashes are deliberately absent.
+ */
+type HistoryAnalyticsPayloads<Modal extends "deposit" | "withdraw", Step> = {
+    type: `${Modal}_modal_history_open`;
+    history_visit_id: string;
+    /** The host funnel step history was opened from; null before one opened. */
+    step: Step | null;
+    badge: HistoryAnalyticsBadge;
+    badge_count: number;
+}
+/** One per deposit per visit: a row expanded twice still counts once. */
+ | {
+    type: `${Modal}_modal_history_row_view`;
+    history_visit_id: string;
+    deposit_id: string;
+    status: HistoryStatus;
+    recoverable: boolean;
+    /** 0-based index in the list as displayed. */
+    position: number;
+} | {
+    type: `${Modal}_modal_history_load_more`;
+    history_visit_id: string;
+    /** 1-based press count within the visit. */
+    page: number;
+    /** Rows on screen before the press. */
+    loaded_rows: number;
+} | {
+    type: `${Modal}_modal_history_fallback_open`;
+    history_visit_id: string;
+    claim_attempt_id: string;
+} | {
+    type: `${Modal}_modal_history_recovery_start`;
+    history_visit_id: string;
+    claim_attempt_id: string;
+    entry_source: HistoryClaimEntrySource;
+    deposit_id: string;
+};
 type DepositAnalyticsSharedStep = "account_setup" | "funding_method_home";
 type DepositAnalyticsWalletStep = "wallet_connect" | "wallet_source_asset" | "wallet_source_token" | "wallet_amount" | "wallet_review" | "wallet_submit" | "wallet_processing";
 type DepositAnalyticsTransferStep = "transfer_source_selection" | "transfer_address_shown" | "transfer_copy" | "transfer_fee_amount" | "transfer_fee_review" | "transfer_tracking";
@@ -785,7 +897,7 @@ type DepositAnalyticsCommonEventPayload = {
     source: DepositAnalyticsCloseSource;
     step: DepositAnalyticsStep | null;
     after_handoff: boolean;
-};
+} | HistoryAnalyticsPayloads<"deposit", DepositAnalyticsStep>;
 /**
  * Method-aware deposit telemetry. UI outcomes describe only what the widget
  * observed and must not be treated as backend fulfilment truth.
@@ -869,7 +981,9 @@ type WithdrawAnalyticsEventPayload = {
     step: WithdrawAnalyticsStep | null;
     after_handoff: boolean;
     same_route?: boolean;
-};
+} | (HistoryAnalyticsPayloads<"withdraw", WithdrawAnalyticsStep> & {
+    same_route?: boolean;
+});
 type WithdrawAnalyticsEvent = WithdrawAnalyticsEventPayload & AnalyticsEventEnvelope<"withdraw", WithdrawAnalyticsSessionProperties>;
 /**
  * `submit` is the async boundary the review CTA opens rather than a screen of
@@ -879,8 +993,28 @@ type ClaimAnalyticsStep = "lookup" | "select" | "review" | "submit";
 /** Every reason has a call site in the claim flow; none is aspirational. */
 type ClaimAnalyticsFailureReason = RoutableAnalyticsReason<"lookup_transaction_hash_invalid" | "lookup_failed" | "lookup_no_deposits_found" | "lookup_no_eligible_deposits" | "refund_destination_invalid" | "recovery_deposit_data_incomplete" | "signature_rejected" | "signature_invalid" | "recovery_deposit_not_recoverable" | "recovery_unsupported" | "signature_verification_unavailable" | "refund_reconciliation_required" | "refund_failed" | "refund_service_unreachable" | "modal_close_refused_in_flight">;
 type ClaimAnalyticsAbandonmentReason = "back" | "modal_close";
-type ClaimAnalyticsCloseSource = "header_button" | "escape" | "overlay" | "host_controlled" | "success_done" | "failure_cancel";
+type ClaimAnalyticsCloseSource = "header_button" | "escape" | "overlay" | "host_controlled" | "success_done" | "failure_cancel"
+/** The labelled control back to the history list a recovery was started from. */
+ | "history_back";
 type ClaimAnalyticsUiOutcome = "completed" | "failed";
+/**
+ * Where a claim attempt was entered from. Present on every claim session, the
+ * standalone modal's included: segmenting on a value that is there keeps a
+ * standalone claim distinguishable from an older widget that reports nothing.
+ */
+type ClaimAnalyticsEntrySource = "standalone" | HistoryClaimEntrySource;
+/**
+ * What ties a claim attempt back to the history visit that produced it. Carried
+ * on every event of the attempt rather than in `session_properties`, which the
+ * ingest contract compares for equality across a session.
+ */
+interface ClaimAnalyticsCorrelation {
+    entry_source: ClaimAnalyticsEntrySource;
+    /** The deposit or withdraw session the attempt was started inside. */
+    source_session_id?: string;
+    history_visit_id?: string;
+    claim_attempt_id?: string;
+}
 /**
  * Claim funnel telemetry. Identities enter the stream only once a lookup has
  * matched a backend deposit row: the hash the user searched for, the refund
@@ -892,7 +1026,8 @@ type ClaimAnalyticsUiOutcome = "completed" | "failed";
  * no hash, never an empty string: `deposit_id` is the join key, and a blank
  * identity would join to nothing while looking like one that does.
  */
-type ClaimAnalyticsEventPayload = {
+type ClaimAnalyticsEventPayload = ClaimAnalyticsEventDetail & Partial<ClaimAnalyticsCorrelation>;
+type ClaimAnalyticsEventDetail = {
     type: "claim_modal_open";
 } | {
     type: "claim_modal_step_open";
@@ -979,4 +1114,4 @@ interface AnalyticsIngestFailureEvent {
 }
 type ModalAnalyticsEvent = DepositAnalyticsEvent | WithdrawAnalyticsEvent | ClaimAnalyticsEvent | AnalyticsIngestFailureEvent;
 
-export type { WithdrawAnalyticsCloseSource as $, AnalyticsEventEnvelope as A, DepositAnalyticsStep as B, ChainId as C, DepositAnalyticsAbandonmentReason as D, DepositAnalyticsTransferStep as E, DepositAnalyticsUiOutcome as F, DepositAnalyticsWalletStep as G, DepositAssetMigrationMethodIdentifiers as H, DepositCompleteEventData as I, DepositExchangeConnectMethodIdentifiers as J, DepositFailedEventData as K, DepositFiatOnrampMethodIdentifiers as L, DepositFundingMethod as M, DepositLifecycleEvent as N, DepositModalProps as O, DepositModalTheme as P, DepositModalUIConfig as Q, DepositSubmittedEventData as R, DepositTransferHandoffIdentifiers as S, DepositWalletIntegration as T, DepositWalletMethodIdentifiers as U, ErrorEventData as V, FiatMethodsConfig as W, ModalAnalyticsEvent as X, OutputTokenRule as Y, RpcUrlMap as Z, WithdrawAnalyticsAbandonmentReason as _, AnalyticsIngestFailureEvent as a, WithdrawAnalyticsEvent as a0, WithdrawAnalyticsEventPayload as a1, WithdrawAnalyticsFailureReason as a2, WithdrawAnalyticsSessionProperties as a3, WithdrawAnalyticsStep as a4, WithdrawAnalyticsUiOutcome as a5, WithdrawCompleteEventData as a6, WithdrawFailedEventData as a7, WithdrawLifecycleEvent as a8, WithdrawModalProps as a9, WithdrawSubmittedEventData as aa, WithdrawTransferRequest as ab, RecoveryErrorCode as ac, SignRecovery as ad, SignRecoveryPayload as ae, AnalyticsIngestFailureReason as b, AnalyticsReasonFamily as c, AssetMigrationsConfig as d, AssetOption as e, ClaimAnalyticsAbandonmentReason as f, ClaimAnalyticsCloseSource as g, ClaimAnalyticsEvent as h, ClaimAnalyticsEventPayload as i, ClaimAnalyticsFailureReason as j, ClaimAnalyticsSessionProperties as k, ClaimAnalyticsStep as l, ClaimAnalyticsUiOutcome as m, ClaimLifecycleEvent as n, ClaimModalProps as o, ConnectedEventData as p, DepositAnalyticsCloseSource as q, DepositAnalyticsCorrelator as r, DepositAnalyticsEvent as s, DepositAnalyticsEventPayload as t, DepositAnalyticsExchangeStep as u, DepositAnalyticsFailureReason as v, DepositAnalyticsFiatStep as w, DepositAnalyticsMigrationStep as x, DepositAnalyticsSessionProperties as y, DepositAnalyticsSharedStep as z };
+export type { HistoryStatus as $, AnalyticsEventEnvelope as A, DepositAnalyticsSessionProperties as B, ChainId as C, DepositAnalyticsAbandonmentReason as D, DepositAnalyticsSharedStep as E, DepositAnalyticsStep as F, DepositAnalyticsTransferStep as G, DepositAnalyticsUiOutcome as H, DepositAnalyticsWalletStep as I, DepositAssetMigrationMethodIdentifiers as J, DepositCompleteEventData as K, DepositExchangeConnectMethodIdentifiers as L, DepositFailedEventData as M, DepositFiatOnrampMethodIdentifiers as N, DepositFundingMethod as O, DepositLifecycleEvent as P, DepositModalProps as Q, DepositModalTheme as R, DepositModalUIConfig as S, DepositSubmittedEventData as T, DepositTransferHandoffIdentifiers as U, DepositWalletIntegration as V, DepositWalletMethodIdentifiers as W, ErrorEventData as X, FiatMethodsConfig as Y, HistoryAnalyticsBadge as Z, HistoryClaimEntrySource as _, AnalyticsIngestFailureEvent as a, ModalAnalyticsEvent as a0, OutputTokenRule as a1, RecoveryErrorCode as a2, RpcUrlMap as a3, SignRecovery as a4, SignRecoveryPayload as a5, WithdrawAnalyticsAbandonmentReason as a6, WithdrawAnalyticsCloseSource as a7, WithdrawAnalyticsEvent as a8, WithdrawAnalyticsEventPayload as a9, WithdrawAnalyticsFailureReason as aa, WithdrawAnalyticsSessionProperties as ab, WithdrawAnalyticsStep as ac, WithdrawAnalyticsUiOutcome as ad, WithdrawCompleteEventData as ae, WithdrawFailedEventData as af, WithdrawLifecycleEvent as ag, WithdrawModalProps as ah, WithdrawSubmittedEventData as ai, WithdrawTransferRequest as aj, AnalyticsIngestFailureReason as b, AnalyticsReasonFamily as c, AssetMigrationsConfig as d, AssetOption as e, ClaimAnalyticsAbandonmentReason as f, ClaimAnalyticsCloseSource as g, ClaimAnalyticsCorrelation as h, ClaimAnalyticsEntrySource as i, ClaimAnalyticsEvent as j, ClaimAnalyticsEventPayload as k, ClaimAnalyticsFailureReason as l, ClaimAnalyticsSessionProperties as m, ClaimAnalyticsStep as n, ClaimAnalyticsUiOutcome as o, ClaimLifecycleEvent as p, ClaimModalProps as q, ConnectedEventData as r, DepositAnalyticsCloseSource as s, DepositAnalyticsCorrelator as t, DepositAnalyticsEvent as u, DepositAnalyticsEventPayload as v, DepositAnalyticsExchangeStep as w, DepositAnalyticsFailureReason as x, DepositAnalyticsFiatStep as y, DepositAnalyticsMigrationStep as z };

package/dist/withdraw.cjs

@@ -1,10 +1,10 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkMTFJSE52cjs = require('./chunk-MTFJSE52.cjs');
-require('./chunk-7ICSHJFE.cjs');
-require('./chunk-V2OBGLJD.cjs');
-require('./chunk-6KG642KH.cjs');
-require('./chunk-4KCSH4T3.cjs');
+var _chunkDTVZUBHIcjs = require('./chunk-DTVZUBHI.cjs');
+require('./chunk-X4D52IZK.cjs');
+require('./chunk-3OOY67VJ.cjs');
+require('./chunk-5P2PVLS4.cjs');
+require('./chunk-OY5N3E6L.cjs');
 
 
-exports.WithdrawModal = _chunkMTFJSE52cjs.WithdrawModal;
+exports.WithdrawModal = _chunkDTVZUBHIcjs.WithdrawModal;

package/dist/withdraw.d.cts

@@ -1,9 +1,9 @@
 import * as react from 'react';
-import { a9 as WithdrawModalProps } from './types-DP_3KwlD.cjs';
-export { A as AnalyticsEventEnvelope, a as AnalyticsIngestFailureEvent, b as AnalyticsIngestFailureReason, c as AnalyticsReasonFamily, e as AssetOption, p as ConnectedEventData, V as ErrorEventData, Z as RpcUrlMap, _ as WithdrawAnalyticsAbandonmentReason, $ as WithdrawAnalyticsCloseSource, a0 as WithdrawAnalyticsEvent, a1 as WithdrawAnalyticsEventPayload, a2 as WithdrawAnalyticsFailureReason, a3 as WithdrawAnalyticsSessionProperties, a4 as WithdrawAnalyticsStep, a5 as WithdrawAnalyticsUiOutcome, a6 as WithdrawCompleteEventData, a7 as WithdrawFailedEventData, aa as WithdrawSubmittedEventData, ab as WithdrawTransferRequest } from './types-DP_3KwlD.cjs';
+import { ah as WithdrawModalProps } from './types-CxiLX5sv.cjs';
+export { A as AnalyticsEventEnvelope, a as AnalyticsIngestFailureEvent, b as AnalyticsIngestFailureReason, c as AnalyticsReasonFamily, e as AssetOption, f as ClaimAnalyticsAbandonmentReason, g as ClaimAnalyticsCloseSource, h as ClaimAnalyticsCorrelation, i as ClaimAnalyticsEntrySource, j as ClaimAnalyticsEvent, k as ClaimAnalyticsEventPayload, l as ClaimAnalyticsFailureReason, m as ClaimAnalyticsSessionProperties, n as ClaimAnalyticsStep, o as ClaimAnalyticsUiOutcome, r as ConnectedEventData, X as ErrorEventData, Z as HistoryAnalyticsBadge, _ as HistoryClaimEntrySource, $ as HistoryStatus, a2 as RecoveryErrorCode, a3 as RpcUrlMap, a4 as SignRecovery, a5 as SignRecoveryPayload, a6 as WithdrawAnalyticsAbandonmentReason, a7 as WithdrawAnalyticsCloseSource, a8 as WithdrawAnalyticsEvent, a9 as WithdrawAnalyticsEventPayload, aa as WithdrawAnalyticsFailureReason, ab as WithdrawAnalyticsSessionProperties, ac as WithdrawAnalyticsStep, ad as WithdrawAnalyticsUiOutcome, ae as WithdrawCompleteEventData, af as WithdrawFailedEventData, ai as WithdrawSubmittedEventData, aj as WithdrawTransferRequest } from './types-CxiLX5sv.cjs';
 import { M as ModalUiState } from './modal-ui-state-OD1RmKkK.cjs';
+import './caip-BMi-9t09.cjs';
 import 'viem';
-import './caip-D8aRWdEY.cjs';
 
 /**
  * Not part of `WithdrawModalProps`: the native embed is the only consumer, and
@@ -12,6 +12,6 @@ import './caip-D8aRWdEY.cjs';
 interface WithdrawModalInternalProps {
     onUiState?: (state: ModalUiState) => void;
 }
-declare function WithdrawModal({ accountAddress, sourceChain: sourceChainProp, sourceToken, targetChain: targetChainProp, targetToken, recipient, defaultAmount, isOpen, onClose, inline, closeOnOverlayClick, backendUrl, rpcUrls: rpcUrlsProp, forceRegister, onSendTransaction, theme, uiConfig, className, onReady, onLifecycle, onEvent, onError, enableAnalyticsIngest, analyticsIngestUrl, debug, onUiState, ...removedProps }: WithdrawModalProps & WithdrawModalInternalProps): react.JSX.Element;
+declare function WithdrawModal({ accountAddress, sourceChain: sourceChainProp, sourceToken, targetChain: targetChainProp, targetToken, recipient, defaultAmount, isOpen, onClose, inline, closeOnOverlayClick, backendUrl, rpcUrls: rpcUrlsProp, forceRegister, onSendTransaction, theme, uiConfig, className, onReady, onLifecycle, onEvent, onError, enableAnalyticsIngest, analyticsIngestUrl, signRecovery, debug, onUiState, ...removedProps }: WithdrawModalProps & WithdrawModalInternalProps): react.JSX.Element;
 
 export { WithdrawModal, WithdrawModalProps };

package/dist/withdraw.d.ts

@@ -1,9 +1,9 @@
 import * as react from 'react';
-import { a9 as WithdrawModalProps } from './types-Bho4OA03.js';
-export { A as AnalyticsEventEnvelope, a as AnalyticsIngestFailureEvent, b as AnalyticsIngestFailureReason, c as AnalyticsReasonFamily, e as AssetOption, p as ConnectedEventData, V as ErrorEventData, Z as RpcUrlMap, _ as WithdrawAnalyticsAbandonmentReason, $ as WithdrawAnalyticsCloseSource, a0 as WithdrawAnalyticsEvent, a1 as WithdrawAnalyticsEventPayload, a2 as WithdrawAnalyticsFailureReason, a3 as WithdrawAnalyticsSessionProperties, a4 as WithdrawAnalyticsStep, a5 as WithdrawAnalyticsUiOutcome, a6 as WithdrawCompleteEventData, a7 as WithdrawFailedEventData, aa as WithdrawSubmittedEventData, ab as WithdrawTransferRequest } from './types-Bho4OA03.js';
+import { ah as WithdrawModalProps } from './types-CQ0NHqCy.js';
+export { A as AnalyticsEventEnvelope, a as AnalyticsIngestFailureEvent, b as AnalyticsIngestFailureReason, c as AnalyticsReasonFamily, e as AssetOption, f as ClaimAnalyticsAbandonmentReason, g as ClaimAnalyticsCloseSource, h as ClaimAnalyticsCorrelation, i as ClaimAnalyticsEntrySource, j as ClaimAnalyticsEvent, k as ClaimAnalyticsEventPayload, l as ClaimAnalyticsFailureReason, m as ClaimAnalyticsSessionProperties, n as ClaimAnalyticsStep, o as ClaimAnalyticsUiOutcome, r as ConnectedEventData, X as ErrorEventData, Z as HistoryAnalyticsBadge, _ as HistoryClaimEntrySource, $ as HistoryStatus, a2 as RecoveryErrorCode, a3 as RpcUrlMap, a4 as SignRecovery, a5 as SignRecoveryPayload, a6 as WithdrawAnalyticsAbandonmentReason, a7 as WithdrawAnalyticsCloseSource, a8 as WithdrawAnalyticsEvent, a9 as WithdrawAnalyticsEventPayload, aa as WithdrawAnalyticsFailureReason, ab as WithdrawAnalyticsSessionProperties, ac as WithdrawAnalyticsStep, ad as WithdrawAnalyticsUiOutcome, ae as WithdrawCompleteEventData, af as WithdrawFailedEventData, ai as WithdrawSubmittedEventData, aj as WithdrawTransferRequest } from './types-CQ0NHqCy.js';
 import { M as ModalUiState } from './modal-ui-state-OD1RmKkK.js';
+import './caip-BMi-9t09.js';
 import 'viem';
-import './caip-D8aRWdEY.js';
 
 /**
  * Not part of `WithdrawModalProps`: the native embed is the only consumer, and
@@ -12,6 +12,6 @@ import './caip-D8aRWdEY.js';
 interface WithdrawModalInternalProps {
     onUiState?: (state: ModalUiState) => void;
 }
-declare function WithdrawModal({ accountAddress, sourceChain: sourceChainProp, sourceToken, targetChain: targetChainProp, targetToken, recipient, defaultAmount, isOpen, onClose, inline, closeOnOverlayClick, backendUrl, rpcUrls: rpcUrlsProp, forceRegister, onSendTransaction, theme, uiConfig, className, onReady, onLifecycle, onEvent, onError, enableAnalyticsIngest, analyticsIngestUrl, debug, onUiState, ...removedProps }: WithdrawModalProps & WithdrawModalInternalProps): react.JSX.Element;
+declare function WithdrawModal({ accountAddress, sourceChain: sourceChainProp, sourceToken, targetChain: targetChainProp, targetToken, recipient, defaultAmount, isOpen, onClose, inline, closeOnOverlayClick, backendUrl, rpcUrls: rpcUrlsProp, forceRegister, onSendTransaction, theme, uiConfig, className, onReady, onLifecycle, onEvent, onError, enableAnalyticsIngest, analyticsIngestUrl, signRecovery, debug, onUiState, ...removedProps }: WithdrawModalProps & WithdrawModalInternalProps): react.JSX.Element;
 
 export { WithdrawModal, WithdrawModalProps };

package/dist/withdraw.mjs

@@ -1,10 +1,10 @@
 import {
   WithdrawModal
-} from "./chunk-PKML3XVS.mjs";
-import "./chunk-7SR7ENVJ.mjs";
-import "./chunk-IN77XSWO.mjs";
-import "./chunk-K4H6TGBE.mjs";
-import "./chunk-VUATPOWJ.mjs";
+} from "./chunk-7UQ6OUEE.mjs";
+import "./chunk-UCBUCX2W.mjs";
+import "./chunk-5VONFVQN.mjs";
+import "./chunk-CXBMIZUF.mjs";
+import "./chunk-EAGMY3QE.mjs";
 export {
   WithdrawModal
 };