@rhinestone/deposit-modal 0.13.0 → 0.14.0

package/dist/types-DP_3KwlD.d.cts

@@ -0,0 +1,982 @@
+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
+ * off — clients must explicitly opt in.
+ *
+ * A key controls VISIBILITY only. A provider that is enabled but has no
+ * implementation yet renders as a disabled "Coming soon" row; one that is not
+ * enabled is not shown at all.
+ */
+interface AssetMigrationsConfig {
+    polymarket?: boolean;
+    hyperliquid?: boolean;
+    aave?: boolean;
+    morpho?: boolean;
+}
+
+declare const RECOVER_TYPES: {
+    readonly RecoverDeposit: readonly [{
+        readonly name: "depositId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "destination";
+        readonly type: "address";
+    }];
+};
+/** What `signRecovery` is handed. */
+interface SignRecoveryPayload {
+    /**
+     * Sign this exactly. Pass it to `signTypedData` on the wallet that owns
+     * `signer` — or to your account SDK, if `signer` is a smart account.
+     */
+    typedData: TypedDataDefinition<typeof RECOVER_TYPES, "RecoverDeposit">;
+    /**
+     * The address whose signature the processor will verify: the deposit's
+     * `recipient`. Whatever you return must be a signature this address's own
+     * verifier accepts.
+     */
+    signer: Address;
+    /**
+     * The chain the deposit is on, and therefore the chain the signature is
+     * verified against.
+     *
+     * 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,
+     * rejected remotely, and reported to the user as a signature their wallet
+     * cannot make. An EOA signature does not depend on it.
+     */
+    chainId: number;
+    /** Deposit being recovered, for your own logging or confirmation UI. */
+    depositId: string;
+    /** Where the funds will go. Covered by the signature. */
+    destination: Address;
+}
+/**
+ * Produces a signature the recipient's verifier accepts.
+ *
+ * - **embedded EOA** (Privy, Turnkey, Dynamic): `signTypedData` and return the raw
+ *   65-byte result.
+ * - **deployed smart account**: return a signature valid under its ERC-1271
+ *   `isValidSignature`. A raw owner signature is usually *not* enough — a Safe, for
+ *   instance, expects its own message wrapping — so go through your account SDK.
+ * - **undeployed smart account**: wrap it per ERC-6492 so the processor can verify
+ *   counterfactually. `ox/erc6492`'s `SignatureErc6492.wrap` does this, and ships
+ *   with viem already.
+ */
+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";
+
+/**
+ * Consumer-supplied RPC URL overrides, scoped to a single modal instance (see
+ * {@link RpcUrlsProvider}). Threaded into every client the modal builds — EVM
+ * public clients (`public-client.ts`), the wallet adapter's transports
+ * (`reown.tsx`), and the Solana connection (`solana.ts`).
+ *
+ * Keyed by the same `number | "solana"` chain identifier the rest of the modal
+ * uses (see `core/constants.ts`), so a single `rpcUrls` prop covers every
+ * chain — EVM mainnets, Polygon (137, also feeds Polymarket reads), HyperEVM
+ * (999), and Solana.
+ */
+type ChainKey = number | "solana";
+type RpcUrlMap = Partial<Record<ChainKey, string>>;
+
+type Caip2ChainId = `eip155:${number}` | `solana:${string}`;
+type ChainId = number | "solana" | "hypercore" | Caip2ChainId;
+interface DepositModalTheme {
+    /**
+     * Absent means light, unconditionally — never "follow the OS". `"system"` is
+     * opt-in because an app that is single-appearance by design would otherwise
+     * get a dark funding sheet inside a light app the moment the user flips
+     * their phone.
+     */
+    mode?: "light" | "dark" | "system";
+    radius?: "none" | "sm" | "md" | "lg" | "full";
+    fontColor?: string;
+    iconColor?: string;
+    ctaColor?: string;
+    ctaHoverColor?: string;
+    borderColor?: string;
+    backgroundColor?: string;
+}
+interface DepositModalUIConfig {
+    showBackButton?: boolean;
+    maxDepositUsd?: number;
+    minDepositUsd?: number;
+    /**
+     * When true the network/protocol fee is sponsored — the Review / Processing /
+     * Success / Failure screens render the fee line-through and surface a
+     * tooltip on the info icon explaining the sponsorship.
+     */
+    feeSponsored?: boolean;
+    /**
+     * Custom tooltip copy for the fee info icon. Defaults to a generic
+     * "Fees are sponsored" / "Fees apply" message based on `feeSponsored`.
+     */
+    feeTooltip?: string;
+}
+interface ConnectedEventData {
+    address: Address;
+    smartAccount: Address;
+}
+interface DepositSubmittedEventData {
+    txHash: string;
+    sourceChain: ChainId | "unknown";
+    amount: string;
+}
+interface DepositCompleteEventData {
+    txHash: string;
+    destinationTxHash?: string;
+    amount: string;
+    sourceChain: ChainId | "unknown";
+    sourceToken?: string;
+    targetChain: TargetChain;
+    targetToken: string;
+}
+interface DepositFailedEventData {
+    txHash: string;
+    error?: string;
+}
+interface WithdrawSubmittedEventData {
+    txHash: Hex;
+    sourceChain: number;
+    amount: string;
+    accountAddress: Address;
+}
+interface WithdrawCompleteEventData {
+    txHash: Hex;
+    destinationTxHash?: Hex;
+    amount: string;
+    sourceChain: number;
+    sourceToken: Address;
+    targetChain: number;
+    targetToken: Address;
+}
+interface WithdrawFailedEventData {
+    txHash: Hex;
+    error?: string;
+}
+interface ErrorEventData {
+    message: string;
+    code?: string;
+    /**
+     * The underlying wallet/RPC error, verbatim. `message` is written for the
+     * end user and drops the detail a bug report needs — log this instead. Never
+     * render it: it is unsanitized and can carry RPC URLs.
+     */
+    cause?: string;
+}
+interface OutputTokenRule {
+    match: {
+        chain?: string;
+        token?: string;
+        symbol?: string;
+    };
+    outputToken: string;
+}
+/**
+ * Which Swapped payment groups the fiat on-ramp offers. Keys are Swapped
+ * `payment_group` values; omit the object to offer all of them.
+ *
+ * Deliberately booleans rather than a list of row descriptors: the label,
+ * sublabel and icon belong to the modal, so subsetting cannot drift from — or
+ * freeze a stale copy of — Swapped's own limits and naming.
+ */
+interface FiatMethodsConfig {
+    creditcard?: boolean;
+    "bank-transfer"?: boolean;
+    "apple-pay"?: boolean;
+}
+interface DepositModalProps {
+    /**
+     * A wallet the host app already has connected. Pass this to reuse the user's
+     * existing session — the modal reads the address off `.account`, so it cannot
+     * disagree with what your app thinks the user is. Also what lets the modal
+     * skip its own connect step when the wallet is the only funding feature.
+     *
+     * Omit it and pass `reownAppId` instead to have the modal connect a wallet
+     * itself.
+     */
+    walletClient?: WalletClient | null;
+    /** Read client paired with `walletClient`. Defaults to the modal's own. */
+    publicClient?: PublicClient | null;
+    targetChain: Chain | TargetChain;
+    targetToken: Address | string;
+    isOpen: boolean;
+    onClose: () => void;
+    inline?: boolean;
+    closeOnOverlayClick?: boolean;
+    sourceChain?: Chain | number;
+    sourceToken?: Address;
+    /**
+     * Pre-fills the deposit amount. Either a USD-denominated number string
+     * (e.g. "25") or the case-insensitive sentinel `"max"`, which fills the
+     * full available balance once it loads (same as the Max preset).
+     */
+    defaultAmount?: string;
+    recipient: Address | string;
+    /**
+     * The user's current in-app balance, in USD, as the consuming app displays
+     * it. When provided, the amount screen shows a "Balance after deposit" row
+     * (`appBalanceUsd + amount`) so the user sees their post-deposit app
+     * balance. The row is hidden when this is omitted.
+     */
+    appBalanceUsd?: number;
+    outputTokenRules?: OutputTokenRule[];
+    rejectUnmapped?: boolean;
+    backendUrl: string;
+    /**
+     * Per-chain RPC URL overrides, keyed by EVM chain id plus the literal
+     * `"solana"` key. Applied everywhere the modal reads chain state — EVM
+     * public clients, the connected wallet's transports (avoiding the
+     * rate-limited public defaults), Polygon/Polymarket reads, HyperEVM (999),
+     * and the Solana connection. Chains left unset use their default RPC.
+     */
+    rpcUrls?: RpcUrlMap;
+    forceRegister?: boolean;
+    reownAppId?: string;
+    /**
+     * Enable importing balances from third-party dapps. Each dapp defaults to
+     * off — clients must explicitly opt in. When a dapp is enabled and the
+     * connected wallet has a balance there, a new row appears on the deposit
+     * entry screen.
+     */
+    assetMigrations?: AssetMigrationsConfig;
+    /**
+     * Open the modal pre-routed into a dapp-import provider, skipping the
+     * deposit-method home screen. Must name an enabled `assetMigrations` key
+     * (e.g. "polymarket"); disabled/unknown values are a no-op. While the
+     * provider's balances are checked the modal shows a loading skeleton;
+     * if the flow turns out to be unreachable (no account, no balance, no
+     * wallet) it falls back to the home screen.
+     */
+    initialAssetMigration?: keyof AssetMigrationsConfig;
+    /** Show fiat on-ramp option(s) that embed Swapped's iframe. Default: false. */
+    /**
+     * Offer the connected wallet as a funding source. Default: true. Turn off to
+     * present a wallet-free flow (QR / fiat / exchange only) even when a wallet
+     * client or `reownAppId` is supplied.
+     */
+    enableWallet?: boolean;
+    enableFiatOnramp?: boolean;
+    /** Show the Transfer Crypto / QR row. Default: true. */
+    enableQrTransfer?: boolean;
+    /**
+     * Offer gasless ERC-20 deposits from the connected wallet: instead of an
+     * on-chain transfer, the user signs the highest-priority token authorization
+     * supported by the backend (ERC-3009, ERC-2612, then Permit2). Opt-in and
+     * purely additive — the plain transfer stays the default and the automatic
+     * fallback whenever the gasless path is unavailable (older proxy, feature
+     * disabled, missing Permit2 allowance, rejected signature). Default: false.
+     */
+    enableGaslessDeposit?: boolean;
+    /**
+     * Restrict Cash to an exact subset of the standard payment groups. Providing
+     * the map opts this modal instance out of regional personalization; omit it
+     * to use backend-resolved methods with the built-in global fallback.
+     * An empty or all-false map disables Cash.
+     */
+    fiatMethods?: FiatMethodsConfig;
+    /**
+     * Show a "Connect exchange" row that opens Swapped Connect — the user
+     * picks their CEX (Coinbase, Binance, Kraken…) or wallet inside the iframe
+     * and Swapped pulls the crypto on-chain to the smart account. Default: false.
+     */
+    enableExchangeConnect?: boolean;
+    onRequestConnect?: () => void;
+    theme?: DepositModalTheme;
+    uiConfig?: DepositModalUIConfig;
+    className?: string;
+    onReady?: () => void;
+    /** Discriminated stream of deposit lifecycle transitions. */
+    onLifecycle?: (event: DepositLifecycleEvent) => void;
+    onEvent?: (event: DepositAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
+    onError?: (data: ErrorEventData) => void;
+    /**
+     * Send session analytics to Rhinestone in addition to `onEvent`. Default:
+     * true. Turning it off changes nothing about what `onEvent` receives.
+     */
+    enableAnalyticsIngest?: boolean;
+    /** @internal Rhinestone's own dev verification. Not a supported prop. */
+    analyticsIngestUrl?: string;
+    debug?: boolean;
+}
+/**
+ * One transfer the host app must execute to fund a withdrawal.
+ *
+ * `to` is authoritative: it is the Rhinestone deposit account the processor
+ * watches, except on a same-route withdrawal (source chain+token identical to
+ * the target) where the modal skips the bridge and `to` is the end recipient.
+ * Either way the app's job is identical — move `amount` of `token` to `to` on
+ * `chainId` — so it must never substitute an address of its own.
+ */
+interface WithdrawTransferRequest {
+    /** Source chain to send from. */
+    chainId: number;
+    /** Source token; `NATIVE_TOKEN_ADDRESS` for the chain's native asset. */
+    token: Address;
+    /** Amount in the token's base units. */
+    amount: bigint;
+    /** Destination for this transfer. Send here. */
+    to: Address;
+}
+interface WithdrawModalProps {
+    /**
+     * Account holding the funds being withdrawn. Used to read the withdrawable
+     * balance and to keep the user from sending to themselves; the modal never
+     * transacts from it — `onSendTransaction` does.
+     */
+    accountAddress: Address;
+    sourceChain: Chain | number;
+    sourceToken: Address;
+    /**
+     * Initial destination, not a constraint. The withdraw form lets the user pick
+     * any supported chain/token/recipient, so these only seed the fields — pass
+     * them to open on a particular destination, omit them to let the user choose.
+     */
+    targetChain?: Chain | number;
+    targetToken?: Address;
+    recipient?: Address;
+    defaultAmount?: string;
+    isOpen: boolean;
+    onClose: () => void;
+    inline?: boolean;
+    closeOnOverlayClick?: boolean;
+    backendUrl: string;
+    /**
+     * Per-chain RPC URL overrides, keyed by EVM chain id plus the literal
+     * `"solana"` key. Applied to every chain read (EVM public clients and the
+     * connected wallet's transports). Chains left unset use their default RPC.
+     */
+    rpcUrls?: RpcUrlMap;
+    forceRegister?: boolean;
+    /**
+     * Executes the transfer that funds the withdrawal, using whatever account
+     * model the host app has (EOA, smart account, in-app wallet, relayer).
+     *
+     * Must resolve with the **on-chain transaction hash** — not a userOp hash or
+     * bundler id. Progress is tracked by looking the deposit up by that hash, so
+     * anything else leaves the modal waiting on a withdrawal that already
+     * succeeded. Reject to surface a failure in the modal.
+     */
+    onSendTransaction: (request: WithdrawTransferRequest) => Promise<{
+        txHash: Hex;
+    }>;
+    theme?: DepositModalTheme;
+    uiConfig?: DepositModalUIConfig;
+    className?: string;
+    onReady?: () => void;
+    /** Discriminated stream of withdraw lifecycle transitions. */
+    onLifecycle?: (event: WithdrawLifecycleEvent) => void;
+    onEvent?: (event: WithdrawAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
+    onError?: (data: ErrorEventData) => void;
+    /**
+     * Send session analytics to Rhinestone in addition to `onEvent`. Default:
+     * true. Turning it off changes nothing about what `onEvent` receives.
+     */
+    enableAnalyticsIngest?: boolean;
+    /** @internal Rhinestone's own dev verification. Not a supported prop. */
+    analyticsIngestUrl?: string;
+    debug?: boolean;
+}
+/**
+ * Self-service recovery modal. Returns a failed or rejected deposit's
+ * source-chain funds to an address the user names. The deposit is looked up by
+ * transaction hash.
+ *
+ * The user's own wallet authorizes it: the deposit's `recipient` — the in-app
+ * wallet the funds were headed to — signs an EIP-712 struct naming the deposit and
+ * the destination, and the processor verifies that signature against the same
+ * `recipient` before moving anything. Your app needs no backend and no shared
+ * secret; the request goes from the browser through your `deposit-widget-proxy`,
+ * which adds only the project API key.
+ *
+ * Note the signer is the recipient, not the deposit account — deposit accounts are
+ * service-owned and cannot sign for themselves.
+ */
+interface ClaimModalProps {
+    /**
+     * Signs the recovery authorization. Called with the exact typed data to sign and
+     * the `signer` address whose signature the processor will verify — the deposit's
+     * `recipient`.
+     *
+     * Return whatever that address's own verifier accepts:
+     * - **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.
+     *
+     * If your users can't sign — a lost embedded wallet, or a recipient your app
+     * controls rather than the user — use `createRefundHandler` from
+     * `@rhinestone/deposit-modal/server` against your own backend instead, and drive
+     * your own UI. That path authorizes on your say-so rather than a signature.
+     */
+    signRecovery: SignRecovery;
+    isOpen: boolean;
+    onClose: () => void;
+    inline?: boolean;
+    closeOnOverlayClick?: boolean;
+    backendUrl: string;
+    rpcUrls?: RpcUrlMap;
+    /** Optional prefills for the lookup form and destination. */
+    defaultTxHash?: string;
+    /**
+     * Prefills the refund destination. Left empty otherwise — the modal
+     * deliberately does NOT default to the deposit's sender, because returning
+     * funds to an exchange's hot wallet can lose them.
+     *
+     * Matches `refundDestination` on `RefundAuthorization` in `./server`, which
+     * is the authoritative version: this one only seeds the field and the user can
+     * edit it. Not related to the deposit's `recipient`.
+     */
+    defaultRefundDestination?: Address;
+    theme?: DepositModalTheme;
+    uiConfig?: DepositModalUIConfig;
+    className?: string;
+    onReady?: () => void;
+    onLifecycle?: (event: ClaimLifecycleEvent) => void;
+    onEvent?: (event: ClaimAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
+    onError?: (data: ErrorEventData) => void;
+    /**
+     * Sends claim session analytics to Rhinestone in addition to `onEvent`.
+     * Defaults to on; `false` turns collection off entirely.
+     */
+    enableAnalyticsIngest?: boolean;
+    /** @internal Rhinestone's own dev verification. Not a supported prop. */
+    analyticsIngestUrl?: string;
+    debug?: boolean;
+}
+interface AssetOption {
+    id: string;
+    chainId: number;
+    token: Address;
+    symbol: string;
+    name: string;
+    decimals: number;
+    balance?: string;
+    balanceUsd?: number;
+}
+/**
+ * Discriminated union covering every deposit flow state transition the
+ * consumer can observe. Consumers handle additions in a single switch; the
+ * modal can add new event variants without changing the prop surface.
+ */
+type DepositLifecycleEvent = {
+    type: "connected";
+    address: Address;
+    smartAccount: Address;
+} | {
+    type: "submitted";
+    /** Real source-chain transaction hash; not emitted for permit deposits before settlement. */
+    txHash: string;
+    sourceChain: ChainId | "unknown";
+    /** Source-token base units (e.g. "1100000" for 1.10 USDC). */
+    amount: string;
+    /**
+     * Decimals of the source token, for converting `amount` to a
+     * human-readable value. Omitted when the token is not recognised
+     * (e.g. a QR deposit of an unlisted token).
+     */
+    sourceDecimals?: number;
+    /**
+     * USD equivalent of the deposit as entered in the modal (token units
+     * for unpriced non-stablecoins). Omitted for flows without an amount
+     * input (QR transfer, fiat onramp, exchange connect).
+     */
+    amountUsd?: string;
+} | {
+    type: "complete";
+    txHash: string;
+    destinationTxHash?: string;
+    /** Source-token base units (e.g. "1100000" for 1.10 USDC). */
+    amount: string;
+    sourceChain: ChainId | "unknown";
+    sourceToken?: string;
+    /**
+     * Decimals of the source token, for converting `amount` to a
+     * human-readable value. Omitted when the token is not recognised
+     * (e.g. a QR deposit of an unlisted token).
+     */
+    sourceDecimals?: number;
+    /**
+     * USD equivalent of the deposit as entered in the modal (token units
+     * for unpriced non-stablecoins). Omitted for flows without an amount
+     * input (QR transfer, fiat onramp, exchange connect).
+     */
+    amountUsd?: string;
+    targetChain: TargetChain;
+    targetToken: string;
+} | {
+    type: "failed";
+    txHash: string;
+    error?: string;
+} | {
+    type: "balance-changed";
+    totalUsd: number;
+} | {
+    type: "smart-account-changed";
+    evm: Address | null;
+    solana: string | null;
+};
+type WithdrawLifecycleEvent = 
+/** The deposit account for the chosen target is registered and fundable. */
+{
+    type: "connected";
+    address: Address;
+    smartAccount: Address;
+} | {
+    type: "submitted";
+    txHash: Hex;
+    sourceChain: number;
+    amount: string;
+    accountAddress: Address;
+} | {
+    type: "complete";
+    txHash: Hex;
+    destinationTxHash?: Hex;
+    amount: string;
+    sourceChain: number;
+    sourceToken: Address;
+    targetChain: number;
+    targetToken: Address;
+} | {
+    type: "failed";
+    txHash: Hex;
+    error?: string;
+};
+type ClaimLifecycleEvent = {
+    type: "lookup";
+    txHash: string;
+    matches: number;
+} | {
+    type: "refund_requested";
+    account: Address;
+    /** Where the funds were asked to go, on the source chain. */
+    destination: Address;
+    chain: number;
+} | {
+    type: "complete";
+    txHash: string;
+    account: Address;
+    destination: Address;
+    chain: number;
+    token: string;
+    amount: string;
+} | {
+    type: "failed";
+    /** HTTP status from the refund endpoint; 0 if it was unreachable. */
+    status?: number;
+    error?: string;
+};
+type DepositFundingMethod = "wallet" | "transfer" | "fiat_onramp" | "exchange_connect" | "asset_migration";
+type DepositWalletIntegration = "modal_connected" | "host_supplied" | "none";
+interface DepositAnalyticsSessionProperties {
+    readonly enabled_funding_methods: readonly DepositFundingMethod[];
+    readonly wallet_integration: DepositWalletIntegration;
+    readonly fiat_methods: {
+        readonly source: "backend_resolved";
+    } | {
+        readonly source: "configured";
+        readonly identifiers: readonly string[];
+    };
+    readonly asset_migration_providers: readonly string[];
+    readonly initial_asset_migration: string | null;
+    readonly gasless_wallet_flow_enabled: boolean;
+    readonly presentation: "inline" | "overlay";
+    readonly overlay_close_enabled: boolean;
+    readonly prefills: {
+        readonly source_chain: boolean;
+        readonly source_token: boolean;
+        readonly amount: boolean;
+        readonly initial_asset_migration: boolean;
+    };
+    /**
+     * The target the session opened with, as CAIP-2 and on-chain token identity.
+     * Optional because a value the ingest contract would refuse is omitted
+     * rather than sent — a refused envelope would cost the whole session.
+     */
+    readonly target_chain?: string;
+    readonly target_token?: string;
+}
+/**
+ * Fixed by the ingest contract: it is validated strictly and compared for
+ * equality across every event in a session, so anything added here that can
+ * vary mid-session rejects the whole batch. Route classification therefore
+ * lives on the event payload, not in this envelope.
+ */
+interface WithdrawAnalyticsSessionProperties {
+    readonly presentation: "inline" | "overlay";
+    readonly overlay_close_enabled: boolean;
+    readonly prefills: {
+        readonly target_chain: boolean;
+        readonly target_token: boolean;
+        readonly recipient: boolean;
+        readonly amount: boolean;
+    };
+    /**
+     * The destination the form opened on — the configured target, or the source
+     * it falls back to. `prefills.target_*` stay the record of which of the two
+     * it was. Optional on the same terms as the deposit envelope's.
+     */
+    readonly target_chain?: string;
+    readonly target_token?: string;
+}
+/**
+ * Fixed by the ingest contract, exactly as the withdraw one is: strictly
+ * validated and compared for equality across every event in a session.
+ */
+interface ClaimAnalyticsSessionProperties {
+    readonly presentation: "inline" | "overlay";
+    readonly overlay_close_enabled: boolean;
+    readonly prefills: {
+        readonly transaction_hash: boolean;
+        readonly refund_destination: boolean;
+    };
+}
+interface AnalyticsEventEnvelope<Modal extends "deposit" | "withdraw" | "claim", SessionProperties> {
+    session_id: string;
+    modal: Modal;
+    widget_version: string;
+    timestamp: string;
+    session_properties: SessionProperties;
+}
+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";
+type DepositAnalyticsFiatStep = "fiat_regional_payment_method" | "fiat_provider_mint" | "fiat_provider_handoff" | "fiat_tracking" | "fiat_receipt";
+type DepositAnalyticsExchangeStep = "exchange_selection" | "exchange_fee_acknowledgement" | "exchange_provider_mint" | "exchange_provider_handoff" | "exchange_tracking" | "exchange_finalising" | "exchange_receipt";
+type DepositAnalyticsMigrationStep = "migration_boot_resolve" | "migration_provider_selection" | "migration_asset_selection" | "migration_amount" | "migration_review" | "migration_submit" | "migration_processing";
+type DepositAnalyticsStep = DepositAnalyticsSharedStep | DepositAnalyticsWalletStep | DepositAnalyticsTransferStep | DepositAnalyticsFiatStep | DepositAnalyticsExchangeStep | DepositAnalyticsMigrationStep;
+type AnalyticsReasonFamily = "account_setup" | "amount" | "exchange" | "lookup" | "migration" | "modal" | "processor" | "provider" | "quote" | "recipient" | "recovery" | "refund" | "regional_methods" | "registration" | "route" | "signature" | "submission" | "swapped" | "transfer" | "wallet";
+/**
+ * Reason prefixes are stable downstream routing keys. Multiword families are
+ * matched from this declared list, not by splitting at the first underscore.
+ */
+type RoutableAnalyticsReason<Reason extends `${AnalyticsReasonFamily}_${string}`> = Reason;
+type DepositAnalyticsFailureReason = RoutableAnalyticsReason<"account_setup_pending" | "account_setup_stale_response" | "account_setup_failed" | "wallet_connection_requested" | "wallet_connection_rejected" | "wallet_connection_failed" | "wallet_disconnected" | "wallet_portfolio_load_failed" | "wallet_no_supported_assets" | "wallet_no_funded_assets" | "amount_invalid" | "amount_insufficient_balance" | "amount_below_minimum" | "amount_above_maximum" | "quote_source_price_unavailable" | "quote_target_price_unavailable" | "quote_unavailable" | "wallet_chain_switch_rejected" | "wallet_chain_switch_failed" | "wallet_permit_preparation_unavailable" | "wallet_signature_rejected" | "submission_rejected" | "submission_failed" | "submission_missing_hash" | "submission_uncertain" | "transfer_source_unavailable" | "transfer_address_unavailable" | "transfer_clipboard_failed" | "processor_status_poll_failed" | "regional_methods_timeout" | "regional_methods_failed" | "regional_methods_fallback" | "regional_methods_empty" | "exchange_list_failed" | "exchange_list_empty" | "exchange_setup_unavailable" | "exchange_fee_changed" | "exchange_fee_not_acknowledged" | "swapped_mint_failed" | "swapped_url_untrusted" | "swapped_iframe_timeout" | "swapped_browser_open_failed" | "provider_cancelled" | "provider_failed" | "processor_failed" | "migration_wallet_required" | "migration_availability_loading" | "migration_availability_failed" | "migration_unavailable" | "migration_no_balance" | "migration_partial_availability" | "migration_coming_soon">;
+type DepositAnalyticsAbandonmentReason = "back" | "modal_close" | "provider_back" | "wallet_disconnect" | "method_replacement" | "initial_migration_fallback";
+type DepositAnalyticsCloseSource = "header_button" | "escape" | "overlay" | "host_controlled" | "provider_back" | "native_dismiss_request" | "success_done" | "failure_cancel" | "new_deposit_reset";
+type DepositAnalyticsUiOutcome = "completed" | "failed" | "cancelled";
+type DepositAnalyticsCorrelator = {
+    type: "deposit_address";
+    value: string;
+} | {
+    type: "transaction_hash";
+    value: string;
+} | {
+    type: "deposit_id";
+    value: string;
+} | {
+    type: "swapped_external_customer_id";
+    value: string;
+};
+interface DepositWalletMethodIdentifiers {
+    readonly network: "evm" | "solana";
+    readonly integration: DepositWalletIntegration;
+}
+interface DepositFiatOnrampMethodIdentifiers {
+    readonly payment_method: string;
+    readonly source: "personalized" | "fallback" | "configured";
+}
+interface DepositExchangeConnectMethodIdentifiers {
+    readonly exchange: string;
+}
+interface DepositAssetMigrationMethodIdentifiers {
+    readonly provider: string;
+}
+interface DepositTransferHandoffIdentifiers {
+    readonly source_chain: string;
+    readonly source_token: string;
+}
+type DepositAnalyticsMethodSelectedPayload = {
+    type: "deposit_modal_method_selected";
+    funding_method: "wallet";
+    entry_source: "user" | "initial_config";
+    identifiers: DepositWalletMethodIdentifiers;
+} | {
+    type: "deposit_modal_method_selected";
+    funding_method: "transfer";
+    entry_source: "user" | "initial_config";
+    identifiers?: never;
+} | {
+    type: "deposit_modal_method_selected";
+    funding_method: "fiat_onramp";
+    entry_source: "user" | "initial_config";
+    identifiers: DepositFiatOnrampMethodIdentifiers;
+} | {
+    type: "deposit_modal_method_selected";
+    funding_method: "exchange_connect";
+    entry_source: "user" | "initial_config";
+    identifiers?: DepositExchangeConnectMethodIdentifiers;
+} | {
+    type: "deposit_modal_method_selected";
+    funding_method: "asset_migration";
+    entry_source: "user" | "initial_config";
+    identifiers?: DepositAssetMigrationMethodIdentifiers;
+};
+type DepositAnalyticsNonTransferHandoffPayload = {
+    [Method in Exclude<DepositFundingMethod, "transfer">]: {
+        type: "deposit_modal_handoff";
+        funding_method: Method;
+        step: DepositAnalyticsStep;
+        correlator: Exclude<DepositAnalyticsCorrelator, {
+            type: "deposit_address";
+        }>;
+        identifiers?: never;
+    };
+}[Exclude<DepositFundingMethod, "transfer">];
+type DepositAnalyticsHandoffPayload = {
+    type: "deposit_modal_handoff";
+    funding_method: "transfer";
+    step: DepositAnalyticsStep;
+    correlator: Extract<DepositAnalyticsCorrelator, {
+        type: "deposit_address";
+    }>;
+    identifiers: DepositTransferHandoffIdentifiers;
+} | DepositAnalyticsNonTransferHandoffPayload;
+type DepositAnalyticsCommonEventPayload = {
+    type: "deposit_modal_open";
+} | {
+    type: "deposit_modal_step_open";
+    step: DepositAnalyticsStep;
+} | {
+    type: "deposit_modal_step_complete";
+    step: DepositAnalyticsStep;
+}
+/** Progress is blocked, but no attempted operation failed. */
+ | {
+    type: "deposit_modal_friction";
+    step: DepositAnalyticsStep;
+    reason: DepositAnalyticsFailureReason;
+}
+/** An attempted operation failed or the flow reached a terminal condition. */
+ | {
+    type: "deposit_modal_failure";
+    step: DepositAnalyticsStep;
+    reason: DepositAnalyticsFailureReason;
+    retryable: boolean;
+} | {
+    type: "deposit_modal_retry";
+    step: DepositAnalyticsStep;
+    reason: DepositAnalyticsFailureReason;
+} | {
+    type: "deposit_modal_correlator_observed";
+    step: DepositAnalyticsStep;
+    correlator: DepositAnalyticsCorrelator;
+} | {
+    type: "deposit_modal_ui_outcome";
+    step: DepositAnalyticsStep;
+    outcome: DepositAnalyticsUiOutcome;
+} | {
+    type: "deposit_modal_method_abandoned";
+    step: DepositAnalyticsStep;
+    reason: DepositAnalyticsAbandonmentReason;
+} | {
+    type: "deposit_modal_close";
+    source: DepositAnalyticsCloseSource;
+    step: DepositAnalyticsStep | null;
+    after_handoff: boolean;
+};
+/**
+ * Method-aware deposit telemetry. UI outcomes describe only what the widget
+ * observed and must not be treated as backend fulfilment truth.
+ */
+type DepositAnalyticsEventPayload = DepositAnalyticsMethodSelectedPayload | DepositAnalyticsHandoffPayload | (DepositAnalyticsCommonEventPayload & {
+    funding_method: DepositFundingMethod | null;
+});
+/** Deposit funnel telemetry, as delivered to `onEvent`. */
+type DepositAnalyticsEvent = DepositAnalyticsEventPayload & AnalyticsEventEnvelope<"deposit", DepositAnalyticsSessionProperties>;
+/**
+ * `submit` is the async boundary the review CTA opens rather than a screen of
+ * its own, so submit-time failures and the handoff have somewhere to attach.
+ */
+type WithdrawAnalyticsStep = "form" | "review" | "submit" | "processing";
+/** Every reason has a call site in the withdraw flow; none is aspirational. */
+type WithdrawAnalyticsFailureReason = RoutableAnalyticsReason<"submission_handler_missing" | "wallet_balance_unavailable" | "route_target_tokens_unavailable" | "recipient_invalid" | "recipient_not_allowed" | "amount_invalid" | "amount_insufficient_balance" | "registration_pending" | "registration_stale" | "registration_failed" | "registration_target_changed" | "submission_rejected" | "submission_failed" | "submission_missing_hash" | "submission_uncertain" | "processor_status_poll_failed" | "processor_failed">;
+type WithdrawAnalyticsAbandonmentReason = "back" | "modal_close";
+type WithdrawAnalyticsCloseSource = "header_button" | "escape" | "overlay" | "host_controlled" | "success_done" | "failure_cancel";
+type WithdrawAnalyticsUiOutcome = "completed" | "failed";
+/**
+ * Withdraw funnel telemetry. `same_route` is pinned at submit and stamped onto
+ * every later event, so a target prop change mid-flight still reports the route
+ * the withdrawal actually took. UI outcomes describe only what the widget
+ * observed — a same-route withdrawal has no backend record at all.
+ */
+type WithdrawAnalyticsEventPayload = {
+    type: "withdraw_modal_open";
+} | {
+    type: "withdraw_modal_step_open";
+    step: WithdrawAnalyticsStep;
+    same_route?: boolean;
+} | {
+    type: "withdraw_modal_step_complete";
+    step: WithdrawAnalyticsStep;
+    same_route?: boolean;
+}
+/** Progress is blocked, but no attempted operation failed. */
+ | {
+    type: "withdraw_modal_friction";
+    step: WithdrawAnalyticsStep;
+    reason: WithdrawAnalyticsFailureReason;
+    same_route?: boolean;
+}
+/** An attempted operation failed or the flow reached a terminal condition. */
+ | {
+    type: "withdraw_modal_failure";
+    step: WithdrawAnalyticsStep;
+    reason: WithdrawAnalyticsFailureReason;
+    retryable: boolean;
+    same_route?: boolean;
+} | {
+    type: "withdraw_modal_retry";
+    step: WithdrawAnalyticsStep;
+    reason: WithdrawAnalyticsFailureReason;
+    same_route?: boolean;
+}
+/**
+ * The submitted withdrawal, once. Flat by contract: these are the field
+ * names the warehouse join reads to match a widget session against its
+ * backend record.
+ */
+ | {
+    type: "withdraw_modal_handoff";
+    step: WithdrawAnalyticsStep;
+    transaction_hash: string;
+    managed_account: string;
+    same_route: boolean;
+} | {
+    type: "withdraw_modal_ui_outcome";
+    step: WithdrawAnalyticsStep;
+    outcome: WithdrawAnalyticsUiOutcome;
+    same_route?: boolean;
+} | {
+    type: "withdraw_modal_abandoned";
+    step: WithdrawAnalyticsStep;
+    reason: WithdrawAnalyticsAbandonmentReason;
+    same_route?: boolean;
+} | {
+    type: "withdraw_modal_close";
+    source: WithdrawAnalyticsCloseSource;
+    step: WithdrawAnalyticsStep | null;
+    after_handoff: boolean;
+    same_route?: boolean;
+};
+type WithdrawAnalyticsEvent = WithdrawAnalyticsEventPayload & AnalyticsEventEnvelope<"withdraw", WithdrawAnalyticsSessionProperties>;
+/**
+ * `submit` is the async boundary the review CTA opens rather than a screen of
+ * its own, so submit-time failures and the handoff have somewhere to attach.
+ */
+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 ClaimAnalyticsUiOutcome = "completed" | "failed";
+/**
+ * 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
+ * destination they typed and the amount are never sent.
+ *
+ * `transaction_hash` is always the *deposit's* source transaction hash — the
+ * same meaning it has on the deposit and withdraw handoffs. The refund's own
+ * hash is `refund_transaction_hash`. It is `null` when the backend row carried
+ * 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: "claim_modal_open";
+} | {
+    type: "claim_modal_step_open";
+    step: ClaimAnalyticsStep;
+} | {
+    type: "claim_modal_step_complete";
+    step: ClaimAnalyticsStep;
+}
+/** How many deposits the hash resolved to, and how many were recoverable. */
+ | {
+    type: "claim_modal_lookup_result";
+    matches: number;
+    eligible: number;
+} | {
+    type: "claim_modal_deposit_selected";
+    deposit_id: string;
+    transaction_hash: string | null;
+    auto_selected: boolean;
+}
+/** Progress is blocked, but no attempted operation failed. */
+ | {
+    type: "claim_modal_friction";
+    step: ClaimAnalyticsStep;
+    reason: ClaimAnalyticsFailureReason;
+}
+/** An attempted operation failed or the flow reached a terminal condition. */
+ | {
+    type: "claim_modal_failure";
+    step: ClaimAnalyticsStep;
+    reason: ClaimAnalyticsFailureReason;
+    retryable: boolean;
+} | {
+    type: "claim_modal_retry";
+    step: ClaimAnalyticsStep;
+    reason: ClaimAnalyticsFailureReason;
+}
+/**
+ * The submitted refund, once. Flat by contract: these are the field names the
+ * warehouse join reads to match a widget session against its backend record.
+ */
+ | {
+    type: "claim_modal_handoff";
+    step: ClaimAnalyticsStep;
+    deposit_id: string;
+    transaction_hash: string | null;
+    refund_transaction_hash: string;
+} | {
+    type: "claim_modal_ui_outcome";
+    step: ClaimAnalyticsStep;
+    outcome: ClaimAnalyticsUiOutcome;
+} | {
+    type: "claim_modal_abandoned";
+    step: ClaimAnalyticsStep;
+    reason: ClaimAnalyticsAbandonmentReason;
+} | {
+    type: "claim_modal_close";
+    source: ClaimAnalyticsCloseSource;
+    step: ClaimAnalyticsStep | null;
+    after_handoff: boolean;
+};
+type ClaimAnalyticsEvent = ClaimAnalyticsEventPayload & AnalyticsEventEnvelope<"claim", ClaimAnalyticsSessionProperties>;
+/**
+ * Why a batch of analytics events could not be delivered to Rhinestone.
+ * `network` also covers a Content-Security-Policy `connect-src` block, which a
+ * browser reports to JavaScript as an ordinary fetch failure.
+ */
+type AnalyticsIngestFailureReason = "network" | "rejected" | "conflict" | "unauthorized" | "throttled" | "unavailable" | "token_unavailable" | "unsupported";
+/**
+ * Delivery diagnostic, not a funnel event: it reports that analytics could not
+ * be sent, and is never itself sent. Emitted at most once per distinct reason
+ * per session — a blocked origin reports once, not once per attempt.
+ */
+interface AnalyticsIngestFailureEvent {
+    type: "analytics_ingest_failure";
+    session_id: string;
+    modal: "deposit" | "withdraw" | "claim";
+    widget_version: string;
+    timestamp: string;
+    reason: AnalyticsIngestFailureReason;
+    /** HTTP status when there was a response; absent when the request failed. */
+    status?: number;
+    /** Events lost in this session so far, at the time of emission. */
+    dropped_events: number;
+}
+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 };