@dynamic-labs/sdk-react-core 5.0.0-rc.4 → 5.0.0

package/CHANGELOG.md

@@ -1,4 +1,77 @@
 
+## [5.0.0](https://github.com/dynamic-labs/dynamic-auth/compare/v5.0.0-rc.4...v5.0.0) (2026-07-29)
+
+## 🚀 Dynamic SDK v5 is live
+
+This release has been a long time coming. We've cleaned up the architecture, cut support for v1 and v2 embedded wallets from core, shipped a migration path for legacy wallets, and made the SDK story a lot cleaner for both web and mobile devs.
+
+### 🔥 Embedded Wallet clean up
+
+V1/V2 embedded wallets support has been removed from `@dynamic-labs/sdk-react-core`. Dynamic WaaS (V3) is now the one and only embedded wallet type, all new embedded wallets are V3.
+
+### 📦 New: `@dynamic-labs/legacy-embedded-wallet-migration`
+
+For users still on V1/V2 embedded wallets, we've got you covered with a dedicated migration package. It owns all the logic for upgrading to V3. This includes recovery flow, session keys, private key export, and the migration UI.
+
+Two paths available:
+
+- **UI-based** (recommended): Mount `LegacyWalletMigrationProvider` and the upgrade modal opens automatically when a legacy wallet is detected at login. It handles the full flow end-to-end.
+- **Headless**: Call `upgradeToDynamicWaas()` directly if you want a custom migration UX.
+
+### 📱 JS SDK for web and React Native are the new default
+
+Going forward, we're encouraging all developers building for web and React Native to use the JS SDK. It's the direction we're investing in. Ideally v5 is our final version of the old React SDK. To be clear: **no new features will be added to the old SDKs, including v5. All new feature development is happening in the JS SDK.**
+
+### ✏️ Legacy package renames
+
+The old packages have been renamed to make their status explicit. Update your `package.json` accordingly:
+
+```
+@dynamic-labs/client                 → @dynamic-labs/legacy-client
+@dynamic-labs/react-hooks            → @dynamic-labs/legacy-react-hooks
+@dynamic-labs/react-native-extension → @dynamic-labs/legacy-react-native-extension
+@dynamic-labs/web-extension          → @dynamic-labs/legacy-web-extension
+@dynamic-labs/solana-extension       → @dynamic-labs/legacy-solana-extension
+@dynamic-labs/sui-extension          → @dynamic-labs/legacy-sui-extension
+@dynamic-labs/viem-extension         → @dynamic-labs/legacy-viem-extension
+@dynamic-labs/zerodev-extension      → @dynamic-labs/legacy-zerodev-extension
+```
+
+### :book: Full migration guide
+
+Everything you need to upgrade from v4 → v5: [Upgrade SDK from V4 to V5 - Dynamic](https://www.dynamic.xyz/docs/react/reference/upgrade/v5)
+
+Huge props to everyone who contributed to this.  :tada:
+
+------------------------------------------
+
+### ⚠ BREAKING CHANGES
+
+* **waas:** move the client key-share store onto the core storage API (#12096)
+* **react-native-extension:** store sensitive information with react-native-keychain (#12092)
+
+### Features
+
+* **bitcoin:** add sendBitcoinWithConfirmation to show confirm modal on BTC sends ([#12025](https://github.com/dynamic-labs/dynamic-auth/issues/12025)) ([5f992f5](https://github.com/dynamic-labs/dynamic-auth/commit/5f992f5fdaf805f07870ab9248ea2fe06a2fd3bf))
+* **waas:** delegate key shares with initial signer rules [DYNT-1675] ([#12028](https://github.com/dynamic-labs/dynamic-auth/issues/12028)) ([6b1ffc5](https://github.com/dynamic-labs/dynamic-auth/commit/6b1ffc5ee7070d639916a65b6a0aa6ada0167cb8)), closes [dynamic-labs/dynamic-waas-sdk#1500](https://github.com/dynamic-labs/dynamic-waas-sdk/issues/1500) [#10754](https://github.com/dynamic-labs/dynamic-auth/issues/10754) [#10772](https://github.com/dynamic-labs/dynamic-auth/issues/10772) [#646](https://github.com/dynamic-labs/dynamic-auth/issues/646) [#649](https://github.com/dynamic-labs/dynamic-auth/issues/649) [#1500](https://github.com/dynamic-labs/dynamic-auth/issues/1500) [dynamic-labs/dynamic-waas-sdk#1500](https://github.com/dynamic-labs/dynamic-waas-sdk/issues/1500)
+* **waas:** expose rawSign sha256/blake2b in SignMessageContext ([#12075](https://github.com/dynamic-labs/dynamic-auth/issues/12075)) ([20e3d2f](https://github.com/dynamic-labs/dynamic-auth/commit/20e3d2f40d18aa0bdb77e9b00fa4a5dc5dd6e9de))
+
+
+### Bug Fixes
+
+* **bitcoin:** resolve the public key of the active wallet, not the first ([#12091](https://github.com/dynamic-labs/dynamic-auth/issues/12091)) ([ebad70c](https://github.com/dynamic-labs/dynamic-auth/commit/ebad70c37ab9a771ad7051ca8f3c68d52c1d32fa)), closes [#11970](https://github.com/dynamic-labs/dynamic-auth/issues/11970) [#11970](https://github.com/dynamic-labs/dynamic-auth/issues/11970) [#11970](https://github.com/dynamic-labs/dynamic-auth/issues/11970)
+* fallback to local wallet balance when token balances API returns no tokens ([#12059](https://github.com/dynamic-labs/dynamic-auth/issues/12059)) ([26c9022](https://github.com/dynamic-labs/dynamic-auth/commit/26c9022da3371b0da0498ec641157aa9fed356aa))
+* security updates ([#12114](https://github.com/dynamic-labs/dynamic-auth/issues/12114)) ([a4f9bc1](https://github.com/dynamic-labs/dynamic-auth/commit/a4f9bc19870156903b76996c55ecd46a3417f004)) ([#12050](https://github.com/dynamic-labs/dynamic-auth/issues/12050)) ([8eeec92](https://github.com/dynamic-labs/dynamic-auth/commit/8eeec923d0f2f688ade60440e1f92bb1fd646201)) ([#12088](https://github.com/dynamic-labs/dynamic-auth/issues/12088)) ([f11f1f3](https://github.com/dynamic-labs/dynamic-auth/commit/f11f1f384201fa31f58753c0854eaf17f420fb09))
+* replace deprecated polygon-rpc.com RPC with polygon.drpc.org ([#12032](https://github.com/dynamic-labs/dynamic-auth/issues/12032)) ([e1ece53](https://github.com/dynamic-labs/dynamic-auth/commit/e1ece538aedf6127048ca64daf9f9f3cf3a7026e))
+* **sui:** stop using Sui Foundation fullnode URLs in WaaS and extension connectors ([#12108](https://github.com/dynamic-labs/dynamic-auth/issues/12108)) ([b23c85b](https://github.com/dynamic-labs/dynamic-auth/commit/b23c85b7c06f3147705a026ba23f5e8ae1f03b68))
+* **wallet-book:** use Backpack universal link for iOS in-app browser ([#12053](https://github.com/dynamic-labs/dynamic-auth/issues/12053)) ([afba6b1](https://github.com/dynamic-labs/dynamic-auth/commit/afba6b192e4be50aaeca9f5fad88b44808a034a0))
+* **wallet-connect:** recover WalletConnect IndexedDB store when object store is missing ([#12048](https://github.com/dynamic-labs/dynamic-auth/issues/12048)) ([96ff80e](https://github.com/dynamic-labs/dynamic-auth/commit/96ff80e40b28740de15b1702b85f954100fd5f25))
+
+
+* **react-native-extension:** store sensitive information with react-native-keychain ([#12092](https://github.com/dynamic-labs/dynamic-auth/issues/12092)) ([10c0f2f](https://github.com/dynamic-labs/dynamic-auth/commit/10c0f2f6c281e300e4a0455aaaa0d452808dcb87))
+* **waas:** move the client key-share store onto the core storage API ([#12096](https://github.com/dynamic-labs/dynamic-auth/issues/12096)) ([778f993](https://github.com/dynamic-labs/dynamic-auth/commit/778f993c5528ec03a7f1446dcb81a041a22db89b)), closes [#12094](https://github.com/dynamic-labs/dynamic-auth/issues/12094) [#12094](https://github.com/dynamic-labs/dynamic-auth/issues/12094) [#12092](https://github.com/dynamic-labs/dynamic-auth/issues/12092) [#12094](https://github.com/dynamic-labs/dynamic-auth/issues/12094)
+
+
 ## [5.0.0-rc.4](https://github.com/dynamic-labs/dynamic-auth/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-07-20)
 
 

package/package.cjs

@@ -3,11 +3,11 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var version = "5.0.0-rc.4";
+var version = "5.0.0";
 var dependencies = {
-	"@dynamic-labs/sdk-api-core": "0.0.1082",
+	"@dynamic-labs/sdk-api-core": "0.0.1093",
 	"@dynamic-labs-sdk/client": "1.20.0",
-	"@dynamic-labs-wallet/browser-wallet-client": "1.0.74",
+	"@dynamic-labs-wallet/browser-wallet-client": "1.0.79",
 	"@dynamic-labs-wallet/forward-mpc-client": "1.0.1",
 	"@hcaptcha/react-hcaptcha": "1.4.4",
 	"@marsidev/react-turnstile": "1.5.2",

package/package.js

@@ -1,9 +1,9 @@
 'use client'
-var version = "5.0.0-rc.4";
+var version = "5.0.0";
 var dependencies = {
-	"@dynamic-labs/sdk-api-core": "0.0.1082",
+	"@dynamic-labs/sdk-api-core": "0.0.1093",
 	"@dynamic-labs-sdk/client": "1.20.0",
-	"@dynamic-labs-wallet/browser-wallet-client": "1.0.74",
+	"@dynamic-labs-wallet/browser-wallet-client": "1.0.79",
 	"@dynamic-labs-wallet/forward-mpc-client": "1.0.1",
 	"@hcaptcha/react-hcaptcha": "1.4.4",
 	"@marsidev/react-turnstile": "1.5.2",

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dynamic-labs/sdk-react-core",
-  "version": "5.0.0-rc.4",
+  "version": "5.0.0",
   "dependencies": {
-    "@dynamic-labs/sdk-api-core": "0.0.1082",
+    "@dynamic-labs/sdk-api-core": "0.0.1093",
     "@dynamic-labs-sdk/client": "1.20.0",
-    "@dynamic-labs-wallet/browser-wallet-client": "1.0.74",
+    "@dynamic-labs-wallet/browser-wallet-client": "1.0.79",
     "@dynamic-labs-wallet/forward-mpc-client": "1.0.1",
     "@hcaptcha/react-hcaptcha": "1.4.4",
     "@marsidev/react-turnstile": "1.5.2",
@@ -18,17 +18,18 @@
     "react-i18next": "13.5.0",
     "react-international-phone": "4.5.0",
     "yup": "0.32.11",
-    "@dynamic-labs/assert-package-version": "5.0.0-rc.4",
-    "@dynamic-labs/iconic": "5.0.0-rc.4",
-    "@dynamic-labs/locale": "5.0.0-rc.4",
-    "@dynamic-labs/logger": "5.0.0-rc.4",
-    "@dynamic-labs/multi-wallet": "5.0.0-rc.4",
-    "@dynamic-labs/rpc-providers": "5.0.0-rc.4",
-    "@dynamic-labs/store": "5.0.0-rc.4",
-    "@dynamic-labs/types": "5.0.0-rc.4",
-    "@dynamic-labs/utils": "5.0.0-rc.4",
-    "@dynamic-labs/wallet-book": "5.0.0-rc.4",
-    "@dynamic-labs/wallet-connector-core": "5.0.0-rc.4",
+    "@dynamic-labs/assert-package-version": "5.0.0",
+    "@dynamic-labs/iconic": "5.0.0",
+    "@dynamic-labs/legacy-client": "5.0.0",
+    "@dynamic-labs/locale": "5.0.0",
+    "@dynamic-labs/logger": "5.0.0",
+    "@dynamic-labs/multi-wallet": "5.0.0",
+    "@dynamic-labs/rpc-providers": "5.0.0",
+    "@dynamic-labs/store": "5.0.0",
+    "@dynamic-labs/types": "5.0.0",
+    "@dynamic-labs/utils": "5.0.0",
+    "@dynamic-labs/wallet-book": "5.0.0",
+    "@dynamic-labs/wallet-connector-core": "5.0.0",
     "eventemitter3": "5.0.1"
   },
   "devDependencies": {

package/src/lib/context/DynamicContext/hooks/useRegisterStorageService/useRegisterStorageService.cjs

@@ -10,12 +10,15 @@ var isSSR = require('../../../../shared/utils/functions/isSSR/isSSR.cjs');
 /**
  * Registers the storage service for the SDK.
  * When on server side rendering, the storage service is not available, so we need to register a dummy storage service.
+ *
+ * Every platform registers the same web storages. A native mobile host runs the
+ * SDK inside a webview that has its own `localStorage`/`sessionStorage`, and its
+ * secure values are routed by the client's storage adapter rather than through
+ * this registry.
  * @param storagePostfix - The postfix for the storage services.
  */
 const useRegisterStorageService = ({ storagePostfix, }) => {
     const lastPostfix = React.useRef(storagePostfix);
-    if (!isSSR.isSSR() && utils.PlatformService.isNativeMobile)
-        return;
     const storageForSSR = {
         clear: () => undefined,
         getItem: () => null,

package/src/lib/context/DynamicContext/hooks/useRegisterStorageService/useRegisterStorageService.d.ts

@@ -4,6 +4,11 @@ type UseRegisterStorageServiceProps = {
 /**
  * Registers the storage service for the SDK.
  * When on server side rendering, the storage service is not available, so we need to register a dummy storage service.
+ *
+ * Every platform registers the same web storages. A native mobile host runs the
+ * SDK inside a webview that has its own `localStorage`/`sessionStorage`, and its
+ * secure values are routed by the client's storage adapter rather than through
+ * this registry.
  * @param storagePostfix - The postfix for the storage services.
  */
 export declare const useRegisterStorageService: ({ storagePostfix, }: UseRegisterStorageServiceProps) => void;

package/src/lib/context/DynamicContext/hooks/useRegisterStorageService/useRegisterStorageService.js

@@ -1,17 +1,20 @@
 'use client'
 import { useRef } from 'react';
-import { PlatformService, StorageService, applyPostfixToStorageService, createStorageService } from '@dynamic-labs/utils';
+import { StorageService, applyPostfixToStorageService, createStorageService } from '@dynamic-labs/utils';
 import { isSSR } from '../../../../shared/utils/functions/isSSR/isSSR.js';
 
 /**
  * Registers the storage service for the SDK.
  * When on server side rendering, the storage service is not available, so we need to register a dummy storage service.
+ *
+ * Every platform registers the same web storages. A native mobile host runs the
+ * SDK inside a webview that has its own `localStorage`/`sessionStorage`, and its
+ * secure values are routed by the client's storage adapter rather than through
+ * this registry.
  * @param storagePostfix - The postfix for the storage services.
  */
 const useRegisterStorageService = ({ storagePostfix, }) => {
     const lastPostfix = useRef(storagePostfix);
-    if (!isSSR() && PlatformService.isNativeMobile)
-        return;
     const storageForSSR = {
         clear: () => undefined,
         getItem: () => null,

package/src/lib/utils/hooks/useStepUpAuthentication/useStepUpMfa.cjs

@@ -23,7 +23,7 @@ const useStepUpMfa = ({ stateActions }) => {
                 ? error.message
                 : 'Failed to authenticate passkey for step-up authentication';
             setError(errorMessage);
-            return null;
+            throw error;
         }
     }), [setError, setLoading, setSuccess]);
     const verifyTotpMfa = React.useCallback((_b) => _tslib.__awaiter(void 0, [_b], void 0, function* ({ code, deviceId, requestedScopes, }) {
@@ -42,7 +42,7 @@ const useStepUpMfa = ({ stateActions }) => {
                 ? error.message
                 : 'Failed to authenticate TOTP device for step-up authentication';
             setError(errorMessage);
-            return null;
+            throw error;
         }
     }), [setError, setLoading, setSuccess]);
     const verifyRecoveryCode = React.useCallback((_c) => _tslib.__awaiter(void 0, [_c], void 0, function* ({ code, requestedScopes, }) {
@@ -60,7 +60,7 @@ const useStepUpMfa = ({ stateActions }) => {
                 ? error.message
                 : 'Failed to authenticate recovery code for step-up authentication';
             setError(errorMessage);
-            return null;
+            throw error;
         }
     }), [setError, setLoading, setSuccess]);
     return { verifyPasskeyMfa, verifyRecoveryCode, verifyTotpMfa };

package/src/lib/utils/hooks/useStepUpAuthentication/useStepUpMfa.js

@@ -19,7 +19,7 @@ const useStepUpMfa = ({ stateActions }) => {
                 ? error.message
                 : 'Failed to authenticate passkey for step-up authentication';
             setError(errorMessage);
-            return null;
+            throw error;
         }
     }), [setError, setLoading, setSuccess]);
     const verifyTotpMfa = useCallback((_b) => __awaiter(void 0, [_b], void 0, function* ({ code, deviceId, requestedScopes, }) {
@@ -38,7 +38,7 @@ const useStepUpMfa = ({ stateActions }) => {
                 ? error.message
                 : 'Failed to authenticate TOTP device for step-up authentication';
             setError(errorMessage);
-            return null;
+            throw error;
         }
     }), [setError, setLoading, setSuccess]);
     const verifyRecoveryCode = useCallback((_c) => __awaiter(void 0, [_c], void 0, function* ({ code, requestedScopes, }) {
@@ -56,7 +56,7 @@ const useStepUpMfa = ({ stateActions }) => {
                 ? error.message
                 : 'Failed to authenticate recovery code for step-up authentication';
             setError(errorMessage);
-            return null;
+            throw error;
         }
     }), [setError, setLoading, setSuccess]);
     return { verifyPasskeyMfa, verifyRecoveryCode, verifyTotpMfa };

package/src/lib/utils/hooks/useSyncDynamicWaas/useSyncDynamicWaas.cjs

@@ -44,6 +44,14 @@ var useWalletDelegation = require('../useWalletDelegation/useWalletDelegation.cj
 require('../useWalletDelegation/DelegationError.cjs');
 var instrumentWalletCreation = require('./instrumentWalletCreation.cjs');
 
+const DEFAULT_SDK_LOAD_STATE = {
+    attempt: 0,
+    error: null,
+    maxAttempts: 0,
+    nextRetryAt: null,
+    phase: null,
+    status: 'idle',
+};
 // Validate if all required conditions are met for wallet creation
 const useWalletCreationValidation = () => {
     const user = useOnboardingCompleteUser.useOnboardingCompleteUser();
@@ -160,6 +168,71 @@ const useSyncDynamicWaas = () => {
     const hasWaasInitializedRef = React.useRef(false);
     const sessionIdRef = React.useRef(undefined);
     const initializingWaasRef = React.useRef(false);
+    const sdkLoadStateCacheRef = React.useRef(DEFAULT_SDK_LOAD_STATE);
+    // Track the SDK webview load state so WaaS init can be gated on whether the
+    // webview/iframe is ready, and can be retried after a recovery. Using
+    // useSyncExternalStore instead of useEffect/useState avoids the race between
+    // initial state read and subscription, handles server/client snapshots, and
+    // gives React the standard external-store integration for concurrent renders.
+    const client$1 = client.getDynamicClient();
+    const sdkModule = client$1.sdk;
+    const getSdkLoadState = React.useCallback(() => {
+        if (!sdkModule) {
+            return DEFAULT_SDK_LOAD_STATE;
+        }
+        const next = sdkModule.loadState;
+        const prev = sdkLoadStateCacheRef.current;
+        // The production store allocates a new object on every read, but
+        // useSyncExternalStore requires referential stability between store events.
+        // Return the cached snapshot unless a field actually changed.
+        if (next.status === prev.status &&
+            next.phase === prev.phase &&
+            next.attempt === prev.attempt &&
+            next.maxAttempts === prev.maxAttempts &&
+            next.nextRetryAt === prev.nextRetryAt &&
+            next.error === prev.error) {
+            return prev;
+        }
+        sdkLoadStateCacheRef.current = next;
+        return next;
+    }, [sdkModule]);
+    const subscribeToSdkLoadState = React.useCallback((onStoreChange) => {
+        if (!sdkModule) {
+            return () => { };
+        }
+        const handleLoadStateChanged = () => {
+            onStoreChange();
+        };
+        sdkModule.on('loadStateChanged', handleLoadStateChanged);
+        return () => {
+            sdkModule.off('loadStateChanged', handleLoadStateChanged);
+        };
+    }, [sdkModule]);
+    const sdkLoadState = React.useSyncExternalStore(subscribeToSdkLoadState, getSdkLoadState, getSdkLoadState);
+    const isSdkReadyForWaas = React.useCallback(() => {
+        // No SDK webview load controller is present (e.g. web platform using the
+        // standard React SDK client). WaaS uses its own iframe lifecycle there, so
+        // do not block initialization based on a non-existent webview load state.
+        if (!sdkModule || sdkLoadState.maxAttempts === 0) {
+            return true;
+        }
+        // The webview/iframe is loaded and ready. This covers platforms (RN) whose
+        // load controller reaches the ready state.
+        if (sdkLoadState.status === 'ready') {
+            return true;
+        }
+        return false;
+    }, [sdkLoadState, sdkModule]);
+    React.useEffect(() => {
+        if (sdkLoadState.status === 'failed') {
+            // Mark WaaS as not initialized so a retry can re-run it once the webview
+            // recovers. Do not reset initializingWaasRef here: if an initializeWaas
+            // call is already in flight, the existing guard should remain until its
+            // .finally clears it, otherwise a quick failure-then-recovery could start
+            // a duplicate initialization.
+            hasWaasInitializedRef.current = false;
+        }
+    }, [sdkLoadState.status]);
     useDynamicEvents.useInternalDynamicEvents('logout', () => {
         triggeredCreate.current = false;
         triggeredSettingsProcessing.current = false;
@@ -226,7 +299,7 @@ const useSyncDynamicWaas = () => {
             initializingWaasRef.current = false;
             clearRecoveredWallets();
         }
-        if (shouldInitializeWaas && (user === null || user === void 0 ? void 0 : user.sessionId)) {
+        if (shouldInitializeWaas && (user === null || user === void 0 ? void 0 : user.sessionId) && isSdkReadyForWaas()) {
             const { sessionId, id: userId } = user;
             const shouldInitialize = !initializingWaasRef.current &&
                 (!hasWaasInitializedRef.current || sessionIdRef.current !== sessionId);
@@ -277,7 +350,14 @@ const useSyncDynamicWaas = () => {
                 });
             }
         }
-    }, [initializeWaas, shouldInitializeWaas, user]);
+    }, [
+        initializeWaas,
+        shouldInitializeWaas,
+        user,
+        isSdkReadyForWaas,
+        clearRecoveredWallets,
+        environmentId,
+    ]);
     React.useEffect(() => {
         if (shouldCreateWallets()) {
             handleWalletCreation();

package/src/lib/utils/hooks/useSyncDynamicWaas/useSyncDynamicWaas.js

@@ -1,6 +1,6 @@
 'use client'
 import { __awaiter } from '../../../../../_virtual/_tslib.js';
-import { useRef, useCallback, useEffect } from 'react';
+import { useRef, useCallback, useSyncExternalStore, useEffect } from 'react';
 import { getDynamicClient } from '../../../client/client.js';
 import '@dynamic-labs-sdk/client/core';
 import '@dynamic-labs/sdk-api-core';
@@ -40,6 +40,14 @@ import { useWalletDelegation } from '../useWalletDelegation/useWalletDelegation.
 import '../useWalletDelegation/DelegationError.js';
 import { instrumentWalletCreation } from './instrumentWalletCreation.js';
 
+const DEFAULT_SDK_LOAD_STATE = {
+    attempt: 0,
+    error: null,
+    maxAttempts: 0,
+    nextRetryAt: null,
+    phase: null,
+    status: 'idle',
+};
 // Validate if all required conditions are met for wallet creation
 const useWalletCreationValidation = () => {
     const user = useOnboardingCompleteUser();
@@ -156,6 +164,71 @@ const useSyncDynamicWaas = () => {
     const hasWaasInitializedRef = useRef(false);
     const sessionIdRef = useRef(undefined);
     const initializingWaasRef = useRef(false);
+    const sdkLoadStateCacheRef = useRef(DEFAULT_SDK_LOAD_STATE);
+    // Track the SDK webview load state so WaaS init can be gated on whether the
+    // webview/iframe is ready, and can be retried after a recovery. Using
+    // useSyncExternalStore instead of useEffect/useState avoids the race between
+    // initial state read and subscription, handles server/client snapshots, and
+    // gives React the standard external-store integration for concurrent renders.
+    const client = getDynamicClient();
+    const sdkModule = client.sdk;
+    const getSdkLoadState = useCallback(() => {
+        if (!sdkModule) {
+            return DEFAULT_SDK_LOAD_STATE;
+        }
+        const next = sdkModule.loadState;
+        const prev = sdkLoadStateCacheRef.current;
+        // The production store allocates a new object on every read, but
+        // useSyncExternalStore requires referential stability between store events.
+        // Return the cached snapshot unless a field actually changed.
+        if (next.status === prev.status &&
+            next.phase === prev.phase &&
+            next.attempt === prev.attempt &&
+            next.maxAttempts === prev.maxAttempts &&
+            next.nextRetryAt === prev.nextRetryAt &&
+            next.error === prev.error) {
+            return prev;
+        }
+        sdkLoadStateCacheRef.current = next;
+        return next;
+    }, [sdkModule]);
+    const subscribeToSdkLoadState = useCallback((onStoreChange) => {
+        if (!sdkModule) {
+            return () => { };
+        }
+        const handleLoadStateChanged = () => {
+            onStoreChange();
+        };
+        sdkModule.on('loadStateChanged', handleLoadStateChanged);
+        return () => {
+            sdkModule.off('loadStateChanged', handleLoadStateChanged);
+        };
+    }, [sdkModule]);
+    const sdkLoadState = useSyncExternalStore(subscribeToSdkLoadState, getSdkLoadState, getSdkLoadState);
+    const isSdkReadyForWaas = useCallback(() => {
+        // No SDK webview load controller is present (e.g. web platform using the
+        // standard React SDK client). WaaS uses its own iframe lifecycle there, so
+        // do not block initialization based on a non-existent webview load state.
+        if (!sdkModule || sdkLoadState.maxAttempts === 0) {
+            return true;
+        }
+        // The webview/iframe is loaded and ready. This covers platforms (RN) whose
+        // load controller reaches the ready state.
+        if (sdkLoadState.status === 'ready') {
+            return true;
+        }
+        return false;
+    }, [sdkLoadState, sdkModule]);
+    useEffect(() => {
+        if (sdkLoadState.status === 'failed') {
+            // Mark WaaS as not initialized so a retry can re-run it once the webview
+            // recovers. Do not reset initializingWaasRef here: if an initializeWaas
+            // call is already in flight, the existing guard should remain until its
+            // .finally clears it, otherwise a quick failure-then-recovery could start
+            // a duplicate initialization.
+            hasWaasInitializedRef.current = false;
+        }
+    }, [sdkLoadState.status]);
     useInternalDynamicEvents('logout', () => {
         triggeredCreate.current = false;
         triggeredSettingsProcessing.current = false;
@@ -222,7 +295,7 @@ const useSyncDynamicWaas = () => {
             initializingWaasRef.current = false;
             clearRecoveredWallets();
         }
-        if (shouldInitializeWaas && (user === null || user === void 0 ? void 0 : user.sessionId)) {
+        if (shouldInitializeWaas && (user === null || user === void 0 ? void 0 : user.sessionId) && isSdkReadyForWaas()) {
             const { sessionId, id: userId } = user;
             const shouldInitialize = !initializingWaasRef.current &&
                 (!hasWaasInitializedRef.current || sessionIdRef.current !== sessionId);
@@ -273,7 +346,14 @@ const useSyncDynamicWaas = () => {
                 });
             }
         }
-    }, [initializeWaas, shouldInitializeWaas, user]);
+    }, [
+        initializeWaas,
+        shouldInitializeWaas,
+        user,
+        isSdkReadyForWaas,
+        clearRecoveredWallets,
+        environmentId,
+    ]);
     useEffect(() => {
         if (shouldCreateWallets()) {
             handleWalletCreation();

package/src/lib/utils/hooks/useWalletDelegation/useWalletDelegation.cjs

@@ -161,7 +161,9 @@ const useWalletDelegation = () => {
             .filter((wallet) => wallet !== null)
             .filter((wallet) => wallet.chain === sdkApiCore.ChainEnum.Evm || wallet.chain === sdkApiCore.ChainEnum.Sol);
     }, [user === null || user === void 0 ? void 0 : user.verifiedCredentials, userWallets]);
-    const delegateKeyShares = React.useCallback((wallets, password) => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+    const delegateKeyShares = React.useCallback((wallets, password, 
+    // Seeds the delegated signer's policy layer with rules at delegation time.
+    initialSignerRules) => _tslib.__awaiter(void 0, void 0, void 0, function* () {
         if (!delegatedAccessEnabled) {
             throw new Error('Wallet delegation is not enabled for this project environment. Please check the project settings.');
         }
@@ -185,7 +187,7 @@ const useWalletDelegation = () => {
                 continue;
             }
             try {
-                yield walletConnector.delegateKeyShares(Object.assign({ accountAddress: wallet.accountAddress }, (password && { password })));
+                yield walletConnector.delegateKeyShares(Object.assign(Object.assign({ accountAddress: wallet.accountAddress }, (password && { password })), (initialSignerRules && { initialSignerRules })));
                 successfulWallets.push(wallet);
             }
             catch (error) {

package/src/lib/utils/hooks/useWalletDelegation/useWalletDelegation.d.ts

@@ -1,4 +1,4 @@
-import { ChainEnum } from '@dynamic-labs/sdk-api-core';
+import { ChainEnum, WaasPolicyRule } from '@dynamic-labs/sdk-api-core';
 import { Wallet } from '../../../shared';
 export type WalletDelegationStatus = 'delegated' | 'denied' | 'pending';
 export type WalletWithStatus = Wallet & {
@@ -27,7 +27,7 @@ export declare const useWalletDelegation: () => {
     readonly delegateKeyShares: (wallets?: {
         chainName: ChainEnum;
         accountAddress: string;
-    }[], password?: string) => Promise<void>;
+    }[], password?: string, initialSignerRules?: WaasPolicyRule[]) => Promise<void>;
     readonly delegatedAccessEnabled: boolean | undefined;
     readonly denyWalletDelegation: (walletId: string) => Promise<void>;
     readonly dismissDelegationPrompt: (walletId?: string) => void;

package/src/lib/utils/hooks/useWalletDelegation/useWalletDelegation.js

@@ -157,7 +157,9 @@ const useWalletDelegation = () => {
             .filter((wallet) => wallet !== null)
             .filter((wallet) => wallet.chain === ChainEnum.Evm || wallet.chain === ChainEnum.Sol);
     }, [user === null || user === void 0 ? void 0 : user.verifiedCredentials, userWallets]);
-    const delegateKeyShares = useCallback((wallets, password) => __awaiter(void 0, void 0, void 0, function* () {
+    const delegateKeyShares = useCallback((wallets, password, 
+    // Seeds the delegated signer's policy layer with rules at delegation time.
+    initialSignerRules) => __awaiter(void 0, void 0, void 0, function* () {
         if (!delegatedAccessEnabled) {
             throw new Error('Wallet delegation is not enabled for this project environment. Please check the project settings.');
         }
@@ -181,7 +183,7 @@ const useWalletDelegation = () => {
                 continue;
             }
             try {
-                yield walletConnector.delegateKeyShares(Object.assign({ accountAddress: wallet.accountAddress }, (password && { password })));
+                yield walletConnector.delegateKeyShares(Object.assign(Object.assign({ accountAddress: wallet.accountAddress }, (password && { password })), (initialSignerRules && { initialSignerRules })));
                 successfulWallets.push(wallet);
             }
             catch (error) {

package/src/lib/widgets/DynamicWidget/components/ActiveWalletBalance/ActiveWalletBalance.cjs

@@ -460,13 +460,18 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
         (_c = projectSettings === null || projectSettings === void 0 ? void 0 : projectSettings.sdk.featureFlags) === null || _c === void 0 ? void 0 : _c.connectOnlyMultiAsset,
         multiAsset,
     ]);
+    const hasTokenBalances = React.useMemo(() => filteredTokenBalances.length > 0, [filteredTokenBalances]);
     const isTooManyRequests = errorTokenBalances === 'Too many requests fetching balances';
     const showMultiAsset = !isTooManyRequests && enableMultiAsset;
     const currencyFormatter = new Intl.NumberFormat('en-US', {
         currency: 'USD',
         style: 'currency',
     });
-    const canShowFiat = React.useMemo(() => !testnet && showFiat && showMultiAsset && !errorTokenBalances, [testnet, showFiat, showMultiAsset, errorTokenBalances]);
+    const canShowFiat = React.useMemo(() => !testnet &&
+        showFiat &&
+        showMultiAsset &&
+        !errorTokenBalances &&
+        hasTokenBalances, [testnet, showFiat, showMultiAsset, errorTokenBalances, hasTokenBalances]);
     const handleScroll = () => {
         if (contentRef.current) {
             setHasShadow(contentRef.current.scrollTop > 0);

package/src/lib/widgets/DynamicWidget/components/ActiveWalletBalance/ActiveWalletBalance.js

@@ -456,13 +456,18 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
         (_c = projectSettings === null || projectSettings === void 0 ? void 0 : projectSettings.sdk.featureFlags) === null || _c === void 0 ? void 0 : _c.connectOnlyMultiAsset,
         multiAsset,
     ]);
+    const hasTokenBalances = useMemo(() => filteredTokenBalances.length > 0, [filteredTokenBalances]);
     const isTooManyRequests = errorTokenBalances === 'Too many requests fetching balances';
     const showMultiAsset = !isTooManyRequests && enableMultiAsset;
     const currencyFormatter = new Intl.NumberFormat('en-US', {
         currency: 'USD',
         style: 'currency',
     });
-    const canShowFiat = useMemo(() => !testnet && showFiat && showMultiAsset && !errorTokenBalances, [testnet, showFiat, showMultiAsset, errorTokenBalances]);
+    const canShowFiat = useMemo(() => !testnet &&
+        showFiat &&
+        showMultiAsset &&
+        !errorTokenBalances &&
+        hasTokenBalances, [testnet, showFiat, showMultiAsset, errorTokenBalances, hasTokenBalances]);
     const handleScroll = () => {
         if (contentRef.current) {
             setHasShadow(contentRef.current.scrollTop > 0);