Migration guide

​

v0.11.x → v0.12.0

​

Forward GET /chains

​

Delete uiConfig.showHistoryButton

  uiConfig={{
-   showHistoryButton: true,
    showBackButton: true,
  }}

​

v0.8.x → v0.9.0

​

Deploy your proxy first

  <WithdrawModal
-   safeAddress={userSafe}
+   accountAddress={userAccount}
-   dappWalletClient={walletClient}
-   dappPublicClient={publicClient}
-   dappAddress={ownerEoa}
-   reownAppId={projectId}
-   onSignTransaction={async (request) => ({
-     signature: await signer.signTypedData(request.typedData),
-   })}
+   onSendTransaction={async ({ chainId, token, amount, to }) => ({
+     txHash: await myWallet.sendTransfer({ chainId, token, amount, to }),
+   })}
  />

​

Renamed and removed props

  <DepositModal
-   dappWalletClient={walletClient}
-   dappPublicClient={publicClient}
-   dappAddress={userAddress}
+   walletClient={walletClient}
+   publicClient={publicClient}
-   dappImports={{ polymarket: true }}
-   initialDappImport="polymarket"
+   assetMigrations={{ polymarket: true }}
+   initialAssetMigration="polymarket"
  />

  <DepositModal
    targetChain={8453}
    targetToken={USDC}
    recipient={userAddress}
+   backendUrl={process.env.NEXT_PUBLIC_DEPOSIT_PROXY_URL}
  />

  <DepositModal
    enableFiatOnramp
-   fiatOnrampMethods={[
-     { method: "creditcard", label: "Debit/Credit card", sublabel: "Instant - $10,000 limit", icon: "card" },
-   ]}
+   fiatMethods={{ creditcard: true }}
  />

​

Optional where it was mandatory

​

New

• enableWallet?: boolean (default true) on <DepositModal> — turn off to present a flow with no wallet even when a walletClient or reownAppId is supplied.
• <ClaimModal> and the ./claim subpath — a user pastes a failed or rejected deposit’s transaction hash and gets the funds returned. The user’s own signature authorizes it, so this needs no backend of your own: pass signRecovery and forward POST /deposits/recover on your proxy. For recipients that can’t sign, @rhinestone/deposit-modal/server exports createRefundHandler to authorize against your own session instead.

​

Behavior changes worth checking

• connected no longer fires for flows with no wallet (QR, fiat, exchange). It previously reported the declared address as though a wallet had connected. If you used it as a “flow started” signal, switch to onReady.
• A QR-only integration no longer auto-locks to the wallet. The connect step’s auto-skip never accounted for enableQrTransfer or asset migrations, so it could skip past the only funding option you had enabled.
• Logos load from Rhinestone’s asset CDN. Apps with an explicit img-src CSP must allow https://s3.rhinestone.dev — a blocked image fails silently. See content security policy.
• HYPERCORE_RECIPIENT_NOT_EOA is no longer emitted. HyperCore deposits now accept a smart-account recipient, and the pre-screen that blocked one is gone. If you branch on that onError code, the branch is dead.
• A chain your deposit whitelist allows nothing on is no longer offered in the QR flow’s chain picker, instead of appearing with built-in tokens the deposit would then be rejected for. Chains the shortlist says nothing about keep their existing set.
• Fiat payment methods are personalized by region unless you pass fiatMethods. See regional payment methods.
• The deposit review shows a single “Fees” row. The per-category breakdown and its tooltips are gone; uiConfig.feeSponsored and uiConfig.feeTooltip still apply on the processing and result screens.

​

Removed prop warnings

​

v0.1.x / v0.2.x → v0.3.0

​

Callback collapse — onLifecycle

 <DepositModal
   ...
-  onConnected={({ address, smartAccount }) => trackConnected(address, smartAccount)}
-  onDepositSubmitted={({ txHash, sourceChain, amount }) => trackSubmitted(txHash, sourceChain, amount)}
-  onDepositComplete={({ txHash, destinationTxHash }) => trackComplete(txHash, destinationTxHash)}
-  onDepositFailed={({ txHash, error }) => trackFailed(txHash, error)}
-  onTotalBalanceChange={(total) => setBalance(total)}
-  onSmartAccountChange={({ evm, solana }) => setSmartAccount({ evm, solana })}
-  connectButtonLabel="Connect wallet"
+  onLifecycle={(event) => {
+    switch (event.type) {
+      case "connected":
+        trackConnected(event.address, event.smartAccount);
+        break;
+      case "submitted":
+        trackSubmitted(event.txHash, event.sourceChain, event.amount);
+        break;
+      case "complete":
+        trackComplete(event.txHash, event.destinationTxHash);
+        break;
+      case "failed":
+        trackFailed(event.txHash, event.error);
+        break;
+      case "balance-changed":
+        setBalance(event.totalUsd);
+        break;
+      case "smart-account-changed":
+        setSmartAccount({ evm: event.evm, solana: event.solana });
+        break;
+    }
+  }}
 />

 <WithdrawModal
   ...
-  onConnected={({ address, smartAccount }) => trackConnected(address, smartAccount)}
-  onWithdrawSubmitted={({ txHash, sourceChain, amount, safeAddress }) => trackSubmitted(txHash, sourceChain, amount, safeAddress)}
-  onWithdrawComplete={({ txHash, destinationTxHash }) => trackComplete(txHash, destinationTxHash)}
-  onWithdrawFailed={({ txHash, error }) => trackFailed(txHash, error)}
-  connectButtonLabel="Connect wallet"
+  onLifecycle={(event) => {
+    switch (event.type) {
+      case "connected":
+        trackConnected(event.address, event.smartAccount);
+        break;
+      case "submitted":
+        trackSubmitted(event.txHash, event.sourceChain, event.amount, event.accountAddress);
+        break;
+      case "complete":
+        trackComplete(event.txHash, event.destinationTxHash);
+        break;
+      case "failed":
+        trackFailed(event.txHash, event.error);
+        break;
+    }
+  }}
 />

​

Asymmetries

​

Analytics type rename

- import type { DepositEvent, WithdrawEvent, ModalEvent } from "@rhinestone/deposit-modal";
+ import type {
+   DepositAnalyticsEvent,
+   WithdrawAnalyticsEvent,
+   ModalAnalyticsEvent,
+ } from "@rhinestone/deposit-modal";

​

Removed

• connectButtonLabel — gone from both modals. The connect-step copy is controlled internally; delete any consumer-side label, there is no replacement.
• /reown and /safe subpath imports — they re-exported nothing that isn’t already on the root entry point.
  - import { DepositModal, disconnectWallet } from "@rhinestone/deposit-modal/reown";
  + import { DepositModal, disconnectWallet } from "@rhinestone/deposit-modal";
  
  - import type { WithdrawModalProps } from "@rhinestone/deposit-modal/safe";
  + import type { WithdrawModalProps } from "@rhinestone/deposit-modal";
  
  The ./deposit, ./withdraw, ./constants, and ./styles.css subpaths remain for tree-shaking.

​

Additive — no action required

• appBalanceUsd?: number on <DepositModal> — renders a “Balance after deposit” row (appBalanceUsd + amount) instead of fetching a portfolio balance.
• dappImports?: DappImportsConfig on <DepositModal> — pull balances from third-party apps. See migrating assets.
• defaultAmount: "max" — defaults the input to the user’s full source-token balance.
• Solana destinations — targetChain: Chain | number | "solana", targetToken: Address | string, recipient: Address | string.
• New root exports — DepositLifecycleEvent, WithdrawLifecycleEvent, DappImportsConfig, OutputTokenRule, plus the renamed analytics types.

​

Unchanged