@dynamic-labs-wallet/browser 0.0.338 → 0.0.340

package/index.cjs

@@ -355,6 +355,21 @@ class InvalidPasswordError extends Error {
 };
 
 const GOOGLE_DRIVE_UPLOAD_API = 'https://www.googleapis.com';
+const USER_ACTIONABLE_REASONS = new Set([
+    'auth_denied',
+    'storage_full',
+    // Google Drive credentials are provided per-customer (each project's own
+    // Google Cloud OAuth app), so 429s hit the customer's project quota, not
+    // Dynamic's. From an oncall perspective there is nothing to act on -- the
+    // end user just needs to wait and retry.
+    'rate_limited'
+]);
+/**
+ * Returns true when the failure reason represents a problem the end user
+ * has to wait out or resolve themselves (e.g. grant Drive permission, free
+ * up storage, wait for a per-user/per-project rate limit to clear) and not
+ * a system-side issue oncall should investigate.
+ */ const isUserActionableGoogleDriveBackupErrorReason = (reason)=>USER_ACTIONABLE_REASONS.has(reason);
 const NON_RETRYABLE_AUTH_REASONS = new Set([
     'insufficientPermissions',
     'unauthorized',
@@ -372,7 +387,8 @@ const RATE_LIMIT_REASONS = new Set([
 ]);
 const NETWORK_ERROR = {
     message: 'Could not reach Google Drive. Please check your internet connection and try again.',
-    isRetryable: true
+    isRetryable: true,
+    errorReason: 'network'
 };
 /**
  * Maps a Google Drive API error to an actionable user-facing message and a retry hint.
@@ -385,31 +401,36 @@ const NETWORK_ERROR = {
     if (httpStatus === 401 || reason && NON_RETRYABLE_AUTH_REASONS.has(reason) || detailReason && NON_RETRYABLE_AUTH_DETAIL_REASONS.has(detailReason)) {
         return {
             message: 'Google Drive access denied: missing or insufficient permissions. Make sure the app is requesting Drive permission and that you allowed it during sign-in, then try again.',
-            isRetryable: false
+            isRetryable: false,
+            errorReason: 'auth_denied'
         };
     }
     if (reason === 'storageQuotaExceeded') {
         return {
             message: 'Google Drive storage is full. Free up space in your Google Drive and try again.',
-            isRetryable: false
+            isRetryable: false,
+            errorReason: 'storage_full'
         };
     }
     if (httpStatus === 429 || reason && RATE_LIMIT_REASONS.has(reason)) {
         return {
             message: 'Google Drive is temporarily rate-limited. Please try again in a few moments.',
-            isRetryable: true
+            isRetryable: true,
+            errorReason: 'rate_limited'
         };
     }
     if (httpStatus >= 500 && httpStatus < 600) {
         return {
             message: 'Google Drive is temporarily unavailable. Please try again shortly.',
-            isRetryable: true
+            isRetryable: true,
+            errorReason: 'service_unavailable'
         };
     }
     const detail = reason != null ? reason : error == null ? void 0 : error.status;
     return {
         message: detail ? `Google Drive upload failed (HTTP ${httpStatus}: ${detail}).` : `Google Drive upload failed (HTTP ${httpStatus}).`,
-        isRetryable: false
+        isRetryable: false,
+        errorReason: 'unknown'
     };
 };
 const parseGoogleDriveErrorBody = async (response)=>{
@@ -422,6 +443,7 @@ const parseGoogleDriveErrorBody = async (response)=>{
 const createGoogleDriveError = (mapped)=>{
     const error = new Error(mapped.message);
     error.isRetryable = mapped.isRetryable;
+    error.errorReason = mapped.errorReason;
     return error;
 };
 const uploadFileToGoogleDriveAppStorage = async ({ accessToken, fileName, jsonData })=>{
@@ -586,6 +608,62 @@ const ERROR_REFRESH_NOT_SUPPORTED_FOR_TWO_OF_THREE = '[DynamicWaasWalletClient]:
  * resolve to the same wallet entry.
  */ const normalizeAddress = (address)=>address.toLowerCase();
 
+const ERROR_PASSWORD_MISMATCH = '[DynamicWaasWalletClient]: Password does not match the password used for existing wallets. All wallets must use the same password for encrypted backups.';
+const ERROR_PASSWORD_REQUIRED_FOR_ENCRYPTED_WALLET = '[DynamicWaasWalletClient]: Password is required for refresh/reshare of a password-encrypted wallet.';
+const ERROR_EXISTING_PASSWORD_REQUIRED = '[DynamicWaasWalletClient]: Existing password is required to update the password for encrypted wallets.';
+const ERROR_WALLETS_ALREADY_ENCRYPTED = '[DynamicWaasWalletClient]: Cannot set password: wallets are already password-encrypted. Use updatePassword instead.';
+/**
+ * Checks if password consistency validation is needed.
+ * Returns false if no password provided or password is the environmentId default.
+ */ function shouldValidatePassword(password, environmentId) {
+    if (!password || password === environmentId) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Finds the first password-encrypted wallet in the walletMap.
+ * Returns [normalizedAddress, walletProperties] or undefined.
+ */ function findPasswordEncryptedWallet(walletMap) {
+    for (const [address, wallet] of Object.entries(walletMap)){
+        var _wallet_clientKeySharesBackupInfo;
+        if ((_wallet_clientKeySharesBackupInfo = wallet.clientKeySharesBackupInfo) == null ? void 0 : _wallet_clientKeySharesBackupInfo.passwordEncrypted) {
+            return [
+                address,
+                wallet
+            ];
+        }
+    }
+    return undefined;
+}
+/**
+ * Extracts the first encrypted key share credential from cached encrypted data.
+ * Returns the base64-encoded encrypted credential string, or undefined if none found.
+ */ function extractFirstEncryptedCredential(encryptedData) {
+    try {
+        const parsed = JSON.parse(encryptedData);
+        const keyShares = parsed == null ? void 0 : parsed.keyShares;
+        if (!Array.isArray(keyShares) || keyShares.length === 0) {
+            return undefined;
+        }
+        return keyShares[0].encryptedAccountCredential;
+    } catch (e) {
+        return undefined;
+    }
+}
+/**
+ * Checks if a wallet uses password-based encryption for its key share backups.
+ */ function isWalletPasswordEncrypted(wallet) {
+    var _wallet_clientKeySharesBackupInfo;
+    var _wallet_clientKeySharesBackupInfo_passwordEncrypted;
+    return (_wallet_clientKeySharesBackupInfo_passwordEncrypted = wallet == null ? void 0 : (_wallet_clientKeySharesBackupInfo = wallet.clientKeySharesBackupInfo) == null ? void 0 : _wallet_clientKeySharesBackupInfo.passwordEncrypted) != null ? _wallet_clientKeySharesBackupInfo_passwordEncrypted : false;
+}
+/**
+ * Checks if an error indicates a password mismatch (wrong password during decryption).
+ */ function isPasswordMismatchError(error) {
+    return error instanceof InvalidPasswordError;
+}
+
 const isBrowser = ()=>typeof window !== 'undefined';
 /**
  * Helper function to extract pubkey from potentially nested structure
@@ -643,36 +721,6 @@ const getClientKeyShareBackupInfo = (params)=>{
         passwordEncrypted
     };
 };
-/**
- * Helper function to merge keyshares and remove duplicates based on pubkey and secretShare
- * @param existingKeyShares - Array of existing keyshares
- * @param newKeyShares - Array of new keyshares to merge
- * @returns Array of merged unique keyshares
- */ const mergeUniqueKeyShares = (existingKeyShares, newKeyShares)=>{
-    const hasDegeneratePubkeyToString = [
-        ...existingKeyShares,
-        ...newKeyShares
-    ].some((share)=>{
-        var _share_pubkey;
-        return 'pubkey' in share && ((_share_pubkey = share.pubkey) == null ? void 0 : _share_pubkey.toString()) === '[object Object]' // NOSONAR
-        ;
-    });
-    if (hasDegeneratePubkeyToString) {
-        core.Logger.warn('[mergeUniqueKeyShares] pubkey.toString() returned "[object Object]" — dedup falls back to secretShare-only comparison', {
-            existingCount: existingKeyShares.length,
-            newCount: newKeyShares.length
-        });
-    }
-    const uniqueKeyShares = newKeyShares.filter((newShare)=>!existingKeyShares.some((existingShare)=>{
-            if (!('pubkey' in newShare) || !('pubkey' in existingShare)) return false;
-            if (!newShare.pubkey || !existingShare.pubkey) return false;
-            return newShare.pubkey.toString() === existingShare.pubkey.toString() && newShare.secretShare === existingShare.secretShare;
-        }));
-    return [
-        ...existingKeyShares,
-        ...uniqueKeyShares
-    ];
-};
 const timeoutPromise = ({ timeInMs, activity = 'Ceremony' })=>{
     return new Promise((_, reject)=>setTimeout(()=>reject(new Error(`${activity} did not complete in ${timeInMs}ms`)), timeInMs));
 };
@@ -742,6 +790,31 @@ const logRetryExhausted = (operationName, maxAttempts, errorContext, logContext)
     // TypeScript needs this even though it's unreachable
     throw new Error('Unreachable code');
 }
+/**
+ * Classifies whether a wallet-creation / wallet-import ceremony error is
+ * worth retrying. Returns true for terminal errors that won't get better on
+ * retry (wrong password, missing passcode, public-key mismatch, etc.) so the
+ * caller can mark them with `isRetryable: false` and short-circuit
+ * `retryPromise`.
+ */ const isNonRetryableCeremonyError = (error)=>{
+    if (!error) return false;
+    if ((error == null ? void 0 : error.isRetryable) === false) return true;
+    if (isPasswordMismatchError(error)) return true;
+    if (error instanceof InvalidPasswordError) return true;
+    const message = error instanceof Error ? error.message : '';
+    if (!message) return false;
+    if (message.includes(ERROR_PASSCODE_REQUIRED)) return true;
+    if (message.includes(ERROR_PUBLIC_KEY_MISMATCH)) return true;
+    return false;
+};
+/**
+ * Marks an error as non-retryable in place so `retryPromise` will skip
+ * remaining attempts. Used at ceremony retry boundaries.
+ */ const markCeremonyErrorNonRetryable = (error)=>{
+    if (error && typeof error === 'object' && isNonRetryableCeremonyError(error)) {
+        error.isRetryable = false;
+    }
+};
 const formatEvmMessage = (message)=>{
     if (typeof message === 'string' && message.startsWith('0x')) {
         const serializedTxBytes = Uint8Array.from(Buffer.from(message.slice(2), 'hex'));
@@ -1250,21 +1323,25 @@ const initializeCloudKit = async (config, signInButtonId, onSignInRequired, onSi
  * Processes a single upload result and logs appropriately
  * @returns Failure details if rejected, undefined if successful
  */ const processUploadResult = (result, locationName, logContext, logger)=>{
-    var _result_reason;
     if (result.status === 'fulfilled') {
         logger.info(`[DynamicWaasWalletClient] Successfully uploaded keyshares to ${locationName}`, logContext);
         return undefined;
     }
     const { message, stack } = getErrorDetails(result.reason);
-    const isRetryable = ((_result_reason = result.reason) == null ? void 0 : _result_reason.isRetryable) !== false;
+    const reasonProps = result.reason;
+    const isRetryable = (reasonProps == null ? void 0 : reasonProps.isRetryable) !== false;
+    var _reasonProps_errorReason;
+    const errorReason = (_reasonProps_errorReason = reasonProps == null ? void 0 : reasonProps.errorReason) != null ? _reasonProps_errorReason : 'unknown';
     logger.error(`[DynamicWaasWalletClient] Failed to upload keyshares to ${locationName}`, _extends({}, logContext, {
         error: message,
-        errorStack: stack
+        errorStack: stack,
+        errorReason
     }));
     return {
         locationName,
         message,
-        isRetryable
+        isRetryable,
+        errorReason
     };
 };
 /**
@@ -1310,8 +1387,24 @@ const initializeCloudKit = async (config, signInButtonId, onSignInRequired, onSi
         processUploadResult(results[1], 'Google Drive Personal', logContext, logger)
     ].filter((failure)=>failure !== undefined);
     if (failures.length > 0) {
-        logger.error('[DynamicWaasWalletClient] Google Drive backup failed', _extends({}, logContext, {
+        const uniqueReasons = [
+            ...new Set(failures.map((f)=>f.errorReason))
+        ];
+        const isUserActionable = failures.every((f)=>isUserActionableGoogleDriveBackupErrorReason(f.errorReason));
+        // OAuth scope and storage-quota failures are end-user issues (grant
+        // Drive permission, free up storage) — not anything oncall can fix.
+        // Downgrade them to warn so monitors can filter on status:error and
+        // still catch real system-side failures (5xx/network/unknown) without
+        // the user-side noise drowning out the signal.
+        const logFn = isUserActionable ? logger.warn : logger.error;
+        // When every location failed for the same reason (the dominant case)
+        // surface a single string; otherwise emit the array so consumers can
+        // see the mix.
+        const logErrorReason = uniqueReasons.length === 1 ? uniqueReasons[0] : uniqueReasons;
+        logFn.call(logger, '[DynamicWaasWalletClient] Google Drive backup failed', _extends({}, logContext, {
             errorCount: failures.length,
+            errorReason: logErrorReason,
+            isUserActionable,
             errors: failures.map((f)=>`Failed to backup keyshares to ${f.locationName}: ${f.message}`)
         }));
         // Both upload destinations (appDataFolder + personal) commonly fail with
@@ -1325,67 +1418,12 @@ const initializeCloudKit = async (config, signInButtonId, onSignInRequired, onSi
         const finalMessage = uniqueMessages.length === 1 ? uniqueMessages[0] : failures.map((f)=>`${f.locationName}: ${f.message}`).join(' | ');
         const aggregatedError = new Error(finalMessage);
         aggregatedError.isRetryable = failures.every((f)=>f.isRetryable);
+        aggregatedError.errorReason = uniqueReasons.length === 1 ? uniqueReasons[0] : 'unknown';
         throw aggregatedError;
     }
     logger.info('[DynamicWaasWalletClient] Google Drive backup completed successfully', logContext);
 };
 
-const ERROR_PASSWORD_MISMATCH = '[DynamicWaasWalletClient]: Password does not match the password used for existing wallets. All wallets must use the same password for encrypted backups.';
-const ERROR_PASSWORD_REQUIRED_FOR_ENCRYPTED_WALLET = '[DynamicWaasWalletClient]: Password is required for refresh/reshare of a password-encrypted wallet.';
-const ERROR_EXISTING_PASSWORD_REQUIRED = '[DynamicWaasWalletClient]: Existing password is required to update the password for encrypted wallets.';
-const ERROR_WALLETS_ALREADY_ENCRYPTED = '[DynamicWaasWalletClient]: Cannot set password: wallets are already password-encrypted. Use updatePassword instead.';
-/**
- * Checks if password consistency validation is needed.
- * Returns false if no password provided or password is the environmentId default.
- */ function shouldValidatePassword(password, environmentId) {
-    if (!password || password === environmentId) {
-        return false;
-    }
-    return true;
-}
-/**
- * Finds the first password-encrypted wallet in the walletMap.
- * Returns [normalizedAddress, walletProperties] or undefined.
- */ function findPasswordEncryptedWallet(walletMap) {
-    for (const [address, wallet] of Object.entries(walletMap)){
-        var _wallet_clientKeySharesBackupInfo;
-        if ((_wallet_clientKeySharesBackupInfo = wallet.clientKeySharesBackupInfo) == null ? void 0 : _wallet_clientKeySharesBackupInfo.passwordEncrypted) {
-            return [
-                address,
-                wallet
-            ];
-        }
-    }
-    return undefined;
-}
-/**
- * Extracts the first encrypted key share credential from cached encrypted data.
- * Returns the base64-encoded encrypted credential string, or undefined if none found.
- */ function extractFirstEncryptedCredential(encryptedData) {
-    try {
-        const parsed = JSON.parse(encryptedData);
-        const keyShares = parsed == null ? void 0 : parsed.keyShares;
-        if (!Array.isArray(keyShares) || keyShares.length === 0) {
-            return undefined;
-        }
-        return keyShares[0].encryptedAccountCredential;
-    } catch (e) {
-        return undefined;
-    }
-}
-/**
- * Checks if a wallet uses password-based encryption for its key share backups.
- */ function isWalletPasswordEncrypted(wallet) {
-    var _wallet_clientKeySharesBackupInfo;
-    var _wallet_clientKeySharesBackupInfo_passwordEncrypted;
-    return (_wallet_clientKeySharesBackupInfo_passwordEncrypted = wallet == null ? void 0 : (_wallet_clientKeySharesBackupInfo = wallet.clientKeySharesBackupInfo) == null ? void 0 : _wallet_clientKeySharesBackupInfo.passwordEncrypted) != null ? _wallet_clientKeySharesBackupInfo_passwordEncrypted : false;
-}
-/**
- * Checks if an error indicates a password mismatch (wrong password during decryption).
- */ function isPasswordMismatchError(error) {
-    return error instanceof InvalidPasswordError;
-}
-
 /**
  * Returns true for errors that represent expected user-facing conditions
  * (e.g. wrong password). These are logged at `info` instead of `error`
@@ -2313,7 +2351,18 @@ class DynamicWalletClient {
             clientKeygenResults
         };
     }
-    async keyGen({ chainName, thresholdSignatureScheme, bitcoinConfig, onError, onCeremonyComplete, traceContext, password, signedSessionId }) {
+    async keyGen(args) {
+        return retryPromise(()=>this.runKeyGenAttempt(args), {
+            maxAttempts: 5,
+            retryInterval: 500,
+            operationName: 'keyGen',
+            logContext: _extends({
+                chainName: args.chainName,
+                thresholdSignatureScheme: args.thresholdSignatureScheme
+            }, this.getTraceContext(args.traceContext))
+        });
+    }
+    async runKeyGenAttempt({ chainName, thresholdSignatureScheme, bitcoinConfig, onCeremonyComplete, traceContext, password, signedSessionId }) {
         const dynamicRequestId = uuid.v4();
         try {
             this.assertPasswordRequired(password);
@@ -2375,6 +2424,7 @@ class DynamicWalletClient {
                 clientKeyShares
             };
         } catch (error) {
+            markCeremonyErrorNonRetryable(error);
             logError({
                 message: 'Error in keyGen',
                 error: error,
@@ -2387,7 +2437,18 @@ class DynamicWalletClient {
             throw error;
         }
     }
-    async importRawPrivateKey({ chainName, privateKey, thresholdSignatureScheme, bitcoinConfig, onError, onCeremonyComplete, traceContext, legacyWalletId, password, signedSessionId }) {
+    async importRawPrivateKey(args) {
+        return retryPromise(()=>this.runImportRawPrivateKeyAttempt(args), {
+            maxAttempts: 5,
+            retryInterval: 500,
+            operationName: 'importRawPrivateKey',
+            logContext: _extends({
+                chainName: args.chainName,
+                thresholdSignatureScheme: args.thresholdSignatureScheme
+            }, this.getTraceContext(args.traceContext))
+        });
+    }
+    async runImportRawPrivateKeyAttempt({ chainName, privateKey, thresholdSignatureScheme, bitcoinConfig, onError, onCeremonyComplete, traceContext, legacyWalletId, password, signedSessionId }) {
         const dynamicRequestId = uuid.v4();
         try {
             this.assertPasswordRequired(password);
@@ -2473,6 +2534,7 @@ class DynamicWalletClient {
                 clientKeyShares: clientKeygenResults
             };
         } catch (error) {
+            markCeremonyErrorNonRetryable(error);
             logError({
                 message: 'Error in importRawPrivateKey',
                 error: error,
@@ -2673,11 +2735,9 @@ class DynamicWalletClient {
             mfaToken,
             storeRecoveredShares: false
         });
-        // Overwrite local key shares with recovered ones (not merge)
         await this.setClientKeySharesToStorage({
             accountAddress,
-            clientKeyShares: recoveredKeyShares,
-            overwriteOrMerge: 'overwrite'
+            clientKeyShares: recoveredKeyShares
         });
         this.logger.info('[DynamicWaasWalletClient] Key shares recovered, retrying operation', _extends({
             accountAddress,
@@ -3011,8 +3071,7 @@ class DynamicWalletClient {
             });
             await this.setClientKeySharesToStorage({
                 accountAddress,
-                clientKeyShares: refreshResults,
-                overwriteOrMerge: 'overwrite'
+                clientKeyShares: refreshResults
             });
         } catch (error) {
             // Expected condition — not a server error, no need to page on this.
@@ -3367,8 +3426,7 @@ class DynamicWalletClient {
             // only after backup succeeds.
             await this.setClientKeySharesToStorage({
                 accountAddress,
-                clientKeyShares: distribution.clientShares,
-                overwriteOrMerge: 'overwrite'
+                clientKeyShares: distribution.clientShares
             });
         } catch (error) {
             logError({
@@ -3391,8 +3449,7 @@ class DynamicWalletClient {
             });
             await this.setClientKeySharesToStorage({
                 accountAddress,
-                clientKeyShares: [],
-                overwriteOrMerge: 'overwrite'
+                clientKeyShares: []
             });
             throw error;
         }
@@ -3738,63 +3795,44 @@ class DynamicWalletClient {
    * Helper function to store client key shares in storage.
    * Uses secureStorage when available (mobile), otherwise falls back to localStorage (browser).
    */ /**
-   * Resolves the final array of shares to persist by either replacing
-   * (overwrite) or merging with existing shares (merge), and emits a
-   * persistence-info log so we can audit storage operations from traces.
-   */ async resolveSharesToPersist({ accountAddress, clientKeyShares, overwriteOrMerge, source, readExisting }) {
-        let sharesToStore;
-        let existingCount = 0;
-        if (overwriteOrMerge === 'overwrite') {
-            sharesToStore = clientKeyShares;
-        } else {
-            const existing = await readExisting();
-            existingCount = existing.length;
-            sharesToStore = mergeUniqueKeyShares(existing, clientKeyShares);
-        }
+   * Emits a persistence-info log so storage writes are auditable from traces.
+   */ logSharePersistence({ accountAddress, clientKeyShares, source }) {
         this.logger.info('[DynamicWaasWalletClient] Persisting client key shares', {
             accountAddress,
             source,
-            mode: overwriteOrMerge,
-            inputCount: clientKeyShares.length,
-            existingCount,
-            finalCount: sharesToStore.length
+            inputCount: clientKeyShares.length
         });
-        return sharesToStore;
     }
-    async setClientKeySharesToLocalStorage({ accountAddress, clientKeyShares, overwriteOrMerge = 'merge' }) {
+    async setClientKeySharesToLocalStorage({ accountAddress, clientKeyShares }) {
         accountAddress = normalizeAddress(accountAddress);
-        const sharesToStore = await this.resolveSharesToPersist({
+        this.logSharePersistence({
             accountAddress,
             clientKeyShares,
-            overwriteOrMerge,
-            source: 'localStorage',
-            readExisting: ()=>this.getClientKeySharesFromLocalStorage({
-                    accountAddress
-                })
+            source: 'localStorage'
         });
         const stringifiedClientKeyShares = JSON.stringify({
-            clientKeyShares: sharesToStore
+            clientKeyShares
         });
         await this.storage.setItem(accountAddress, stringifiedClientKeyShares);
     }
     /**
-   * Helper function to store client key shares in storage.
+   * Replaces the client key shares stored for `accountAddress` with `clientKeyShares`.
    * Uses secureStorage when available (mobile), otherwise falls back to localStorage (browser).
-   */ async setClientKeySharesToStorage({ accountAddress, clientKeyShares, overwriteOrMerge = 'merge' }) {
+   *
+   * A WaaS wallet holds exactly one client share per device (see share-distribution
+   * factories in types.ts), so writes are always a full replacement — there is no
+   * merge mode. Callers that need to clear local shares pass `clientKeyShares: []`.
+   */ async setClientKeySharesToStorage({ accountAddress, clientKeyShares }) {
         accountAddress = normalizeAddress(accountAddress);
         // Use secure storage if available (mobile)
         if (this.secureStorage) {
             try {
-                const sharesToStore = await this.resolveSharesToPersist({
+                this.logSharePersistence({
                     accountAddress,
                     clientKeyShares,
-                    overwriteOrMerge,
-                    source: 'secureStorage',
-                    readExisting: ()=>this.getClientKeySharesFromStorage({
-                            accountAddress
-                        })
+                    source: 'secureStorage'
                 });
-                await this.secureStorage.setClientKeyShare(accountAddress, sharesToStore);
+                await this.secureStorage.setClientKeyShare(accountAddress, clientKeyShares);
                 return;
             } catch (error) {
                 logError({
@@ -3810,8 +3848,7 @@ class DynamicWalletClient {
         // Fallback to localStorage (browser)
         await this.setClientKeySharesToLocalStorage({
             accountAddress,
-            clientKeyShares,
-            overwriteOrMerge
+            clientKeyShares
         });
     }
     /**
@@ -4603,8 +4640,7 @@ class DynamicWalletClient {
             if (storeRecoveredShares) {
                 await this.setClientKeySharesToStorage({
                     accountAddress,
-                    clientKeyShares: decryptedKeyShares,
-                    overwriteOrMerge: 'merge'
+                    clientKeyShares: decryptedKeyShares
                 });
                 await this.storage.setItem(this.storageKey, JSON.stringify(this.walletMap));
             }
@@ -5240,13 +5276,8 @@ class DynamicWalletClient {
                     signedSessionId,
                     shareCount
                 });
-                const existingKeyShares = await this.getClientKeySharesFromStorage({
-                    accountAddress
-                });
-                await this.setClientKeySharesToStorage({
-                    accountAddress,
-                    clientKeyShares: mergeUniqueKeyShares(existingKeyShares, decryptedKeyShares)
-                });
+                // recoverEncryptedBackupByWallet (storeRecoveredShares: true by default) has
+                // already written decryptedKeyShares to storage. No further write needed.
                 this.logger.debug('[DynamicWaasWalletClient] Recovered backup', {
                     decryptedKeyShares
                 });
@@ -5331,6 +5362,45 @@ class DynamicWalletClient {
         });
     }
     /**
+   * Fetches the encrypted-shares blob from the server and caches it in this.storage.
+   * Returns the serialized blob, or null if the wallet is unknown or the API returns
+   * no data. Does not decrypt — callers (e.g. unlockWallet, getWallet eager-load)
+   * own the decrypt step.
+   */ async fetchAndCacheEncryptedShares({ accountAddress, signedSessionId, mfaToken }) {
+        const walletData = this.getWalletFromMap(accountAddress);
+        if (!walletData) {
+            return null;
+        }
+        const { shares } = this.recoverStrategy({
+            clientKeyShareBackupInfo: walletData.clientKeySharesBackupInfo,
+            thresholdSignatureScheme: walletData.thresholdSignatureScheme,
+            walletOperation: core.WalletOperation.RECOVER
+        });
+        const externalKeyShareIds = shares[core.BackupLocation.DYNAMIC] || [];
+        this.logger.info('[unlockWallet] cache miss after getWallet, fetching encrypted shares from server', {
+            context: {
+                accountAddress,
+                walletId: walletData.walletId,
+                externalKeyShareIds
+            }
+        });
+        const data = await this.apiClient.recoverEncryptedBackupByWallet({
+            walletId: walletData.walletId,
+            externalKeyShareIds,
+            signedSessionId,
+            mfaToken,
+            requiresSignedSessionId: this.requiresSignedSessionId(),
+            userId: this.userId
+        });
+        if (!data) {
+            return null;
+        }
+        const serialized = JSON.stringify(data);
+        const encryptedStorageKey = `${normalizeAddress(accountAddress)}${core.ENCRYPTED_SHARES_STORAGE_SUFFIX}`;
+        await this.storage.setItem(encryptedStorageKey, serialized);
+        return serialized;
+    }
+    /**
    * Unlocks a password-encrypted wallet by decrypting cached encrypted shares.
    * This method should be called after getWalletRecoveryState returns LOCKED state.
    *
@@ -5338,7 +5408,7 @@ class DynamicWalletClient {
    * @param password - The password to decrypt the shares
    * @param signedSessionId - The signed session ID for authentication
    * @returns The unlocked wallet properties
-   */ async unlockWallet({ accountAddress, password, signedSessionId }) {
+   */ async unlockWallet({ accountAddress, password, signedSessionId, mfaToken }) {
         const dynamicRequestId = uuid.v4();
         try {
             await this.requireWalletFromMap(accountAddress, signedSessionId);
@@ -5358,6 +5428,18 @@ class DynamicWalletClient {
                 });
                 encryptedData = await this.storage.getItem(encryptedStorageKey);
             }
+            // getWallet short-circuits via checkWalletFields when client key shares are
+            // durable but the encrypted-shares cache in this.storage was evicted (e.g. RN
+            // secureStorage survives a WebKit content-process recycle while localStorage
+            // does not). Populate the cache directly so the single decrypt path below
+            // can proceed.
+            if (!encryptedData) {
+                encryptedData = await this.fetchAndCacheEncryptedShares({
+                    accountAddress,
+                    signedSessionId,
+                    mfaToken
+                });
+            }
             if (!encryptedData) {
                 throw new Error('No encrypted shares found for wallet');
             }
@@ -5371,7 +5453,17 @@ class DynamicWalletClient {
             const otherEncryptedWallets = Object.entries(this.walletMap).filter(([addr, w])=>addr !== normalizedAccountAddress && w.walletReadyState !== core.WalletReadyState.READY && isWalletPasswordEncrypted(w));
             const results = await Promise.allSettled(otherEncryptedWallets.map(async ([otherAddr])=>{
                 const otherEncryptedStorageKey = `${otherAddr}${core.ENCRYPTED_SHARES_STORAGE_SUFFIX}`;
-                const otherEncryptedData = await this.storage.getItem(otherEncryptedStorageKey);
+                let otherEncryptedData = await this.storage.getItem(otherEncryptedStorageKey);
+                // Same cache-eviction scenario as the main wallet above: on RN, the
+                // encrypted-shares blob can be gone while client shares survive in
+                // secureStorage. Re-fetch from the server before giving up.
+                if (!otherEncryptedData) {
+                    otherEncryptedData = await this.fetchAndCacheEncryptedShares({
+                        accountAddress: otherAddr,
+                        signedSessionId,
+                        mfaToken
+                    });
+                }
                 if (!otherEncryptedData) {
                     return;
                 }
@@ -5876,11 +5968,12 @@ exports.isBrowser = isBrowser;
 exports.isHeavyQueueOperation = isHeavyQueueOperation;
 exports.isHexString = isHexString;
 exports.isICloudAuthenticated = isICloudAuthenticated;
+exports.isNonRetryableCeremonyError = isNonRetryableCeremonyError;
 exports.isPublicKeyMismatchError = isPublicKeyMismatchError;
 exports.isRecoverQueueOperation = isRecoverQueueOperation;
 exports.isSignQueueOperation = isSignQueueOperation;
 exports.listICloudBackups = listICloudBackups;
-exports.mergeUniqueKeyShares = mergeUniqueKeyShares;
+exports.markCeremonyErrorNonRetryable = markCeremonyErrorNonRetryable;
 exports.readEnvironmentSettings = readEnvironmentSettings;
 exports.retryPromise = retryPromise;
 exports.shouldReshareToSameBackups = shouldReshareToSameBackups;