@dynamic-labs-wallet/browser 0.0.257 → 0.0.259

package/index.cjs.js

@@ -9,6 +9,7 @@ var sdkApiCore = require('@dynamic-labs/sdk-api-core');
 var loadArgon2idWasm = require('argon2id');
 var axios = require('axios');
 var createHttpError = require('http-errors');
+var PQueue = require('p-queue');
 
 function _extends() {
     _extends = Object.assign || function assign(target) {
@@ -21,6 +22,33 @@ function _extends() {
     return _extends.apply(this, arguments);
 }
 
+/**
+ * Infers the Bitcoin address type from a BIP-44 derivation path
+ *
+ * @param derivationPathStr - The derivation path string as JSON (e.g. '{"0":84,"1":0,"2":0,"3":0,"4":0}')
+ * @returns The inferred BitcoinAddressType, or undefined if it cannot be determined
+ */ const getBitcoinAddressTypeFromDerivationPath = (derivationPathStr)=>{
+    try {
+        const derivationPathObj = JSON.parse(derivationPathStr);
+        const path = Object.values(derivationPathObj).map(Number);
+        if (path.length < 2) return undefined;
+        const purpose = path[0];
+        // Handle both raw and hardened purpose values
+        // 84 = Native SegWit (BIP-84), 86 = Taproot (BIP-86)
+        // Hardened values have 0x80000000 added
+        const purposeIndex = purpose >= 0x80000000 ? purpose - 0x80000000 : purpose;
+        switch(purposeIndex){
+            case 84:
+                return core.BitcoinAddressType.NATIVE_SEGWIT;
+            case 86:
+                return core.BitcoinAddressType.TAPROOT;
+            default:
+                return undefined;
+        }
+    } catch (e) {
+        return undefined;
+    }
+};
 const getMPCSignatureScheme = ({ signingAlgorithm, baseRelayUrl = core.MPC_RELAY_PROD_API_URL })=>{
     switch(signingAlgorithm){
         case core.SigningAlgorithm.ECDSA:
@@ -465,7 +493,6 @@ const SIGNED_SESSION_ID_MIN_VERSION_BY_NAMESPACE = {
 };
 const ROOM_EXPIRATION_TIME = 1000 * 60 * 10; // 10 minutes
 const ROOM_CACHE_COUNT = 5;
-const WALLET_BUSY_LOCK_TIMEOUT_MS = 20000; // 20 seconds
 
 const ERROR_KEYGEN_FAILED = '[DynamicWaasWalletClient]: Error with keygen';
 const ERROR_CREATE_WALLET_ACCOUNT = '[DynamicWaasWalletClient]: Error creating wallet account';
@@ -1084,6 +1111,341 @@ const initializeCloudKit = async (config, signInButtonId, onSignInRequired, onSi
     }
 };
 
+class WalletNotReadyError extends Error {
+    constructor(accountAddress, walletReadyState){
+        super(`Wallet ${accountAddress} is not ready and requires password to be unlocked`);
+        this.name = 'WalletNotReadyError';
+        this.accountAddress = accountAddress;
+        this.walletReadyState = walletReadyState;
+    }
+}
+/**
+ * Set of allowed heavy queue operations for runtime validation.
+ */ const HEAVY_QUEUE_OPERATIONS = new Set([
+    core.WalletOperation.REFRESH,
+    core.WalletOperation.RESHARE,
+    core.WalletOperation.RECOVER
+]);
+/**
+ * Type guard to validate that an operation is a valid heavy queue operation.
+ */ const isHeavyQueueOperation = (operation)=>HEAVY_QUEUE_OPERATIONS.has(operation);
+/**
+ * Set of allowed sign queue operations for runtime validation.
+ */ const SIGN_QUEUE_OPERATIONS = new Set([
+    core.WalletOperation.SIGN_MESSAGE,
+    core.WalletOperation.SIGN_TRANSACTION
+]);
+/**
+ * Type guard to validate that an operation is a valid sign queue operation.
+ */ const isSignQueueOperation = (operation)=>SIGN_QUEUE_OPERATIONS.has(operation);
+/**
+ * Set of allowed recover queue operations for runtime validation.
+ */ const RECOVER_QUEUE_OPERATIONS = new Set([
+    core.WalletOperation.RECOVER
+]);
+/**
+ * Type guard to validate that an operation is a valid recover queue operation.
+ */ const isRecoverQueueOperation = (operation)=>RECOVER_QUEUE_OPERATIONS.has(operation);
+class WalletBusyError extends Error {
+    constructor(accountAddress, operation){
+        super(`Wallet ${accountAddress} is currently performing a ${operation} operation`);
+        this.name = 'WalletBusyError';
+        this.operation = operation;
+        this.accountAddress = accountAddress;
+    }
+}
+/**
+ * Creates distribution where shares go to specified cloud providers
+ * Last share goes to cloud providers, rest to Dynamic backend
+ * @param providers - Array of cloud providers to backup to
+ * @param allShares - All key shares to distribute
+ */ const createCloudProviderDistribution = ({ providers, allShares })=>{
+    const cloudProviderShares = {};
+    // Last share goes to cloud providers, rest to Dynamic
+    const sharesForCloud = allShares.slice(-1);
+    providers.forEach((provider)=>{
+        cloudProviderShares[provider] = sharesForCloud;
+    });
+    return {
+        clientShares: allShares.slice(0, -1),
+        cloudProviderShares
+    };
+};
+/**
+ * Creates distribution with delegation + cloud backup
+ * Client shares backed up to Dynamic AND cloud providers
+ * Delegated share goes to webhook
+ */ const createDelegationWithCloudProviderDistribution = ({ providers, existingShares, delegatedShare })=>{
+    const cloudProviderShares = {};
+    providers.forEach((provider)=>{
+        cloudProviderShares[provider] = existingShares;
+    });
+    return {
+        clientShares: existingShares,
+        cloudProviderShares,
+        delegatedShare
+    };
+};
+/**
+ * Creates distribution for adding cloud backup to existing delegation
+ * Client shares go to both Dynamic AND cloud providers
+ * delegatedShare is undefined - we don't re-publish, but preserve the location
+ */ const createAddCloudProviderToExistingDelegationDistribution = ({ providers, clientShares })=>{
+    const cloudProviderShares = {};
+    providers.forEach((provider)=>{
+        cloudProviderShares[provider] = clientShares;
+    });
+    return {
+        clientShares,
+        cloudProviderShares
+    };
+};
+/**
+ * Checks if wallet has backup on any of the specified providers
+ */ const hasCloudProviderBackup = (backupInfo, providers)=>{
+    if (!(backupInfo == null ? void 0 : backupInfo.backups)) return false;
+    return providers.some((provider)=>{
+        var _backupInfo_backups_provider;
+        var _backupInfo_backups_provider_length;
+        return ((_backupInfo_backups_provider_length = (_backupInfo_backups_provider = backupInfo.backups[provider]) == null ? void 0 : _backupInfo_backups_provider.length) != null ? _backupInfo_backups_provider_length : 0) > 0;
+    });
+};
+/**
+ * Gets all cloud providers that have backups for this wallet
+ */ const getActiveCloudProviders = (backupInfo)=>{
+    if (!(backupInfo == null ? void 0 : backupInfo.backups)) return [];
+    return Object.entries(backupInfo.backups).filter(([location, backups])=>location !== core.BackupLocation.DYNAMIC && location !== core.BackupLocation.DELEGATED && backups.length > 0).map(([location])=>location);
+};
+const createDelegationOnlyDistribution = ({ existingShares, delegatedShare })=>({
+        clientShares: existingShares,
+        cloudProviderShares: {},
+        delegatedShare
+    });
+const createDynamicOnlyDistribution = ({ allShares })=>({
+        clientShares: allShares,
+        cloudProviderShares: {}
+    });
+const hasDelegatedBackup = (backupInfo)=>{
+    var _backupInfo_backups_BackupLocation_DELEGATED, _backupInfo_backups;
+    var _backupInfo_backups_BackupLocation_DELEGATED_length;
+    return ((_backupInfo_backups_BackupLocation_DELEGATED_length = backupInfo == null ? void 0 : (_backupInfo_backups = backupInfo.backups) == null ? void 0 : (_backupInfo_backups_BackupLocation_DELEGATED = _backupInfo_backups[core.BackupLocation.DELEGATED]) == null ? void 0 : _backupInfo_backups_BackupLocation_DELEGATED.length) != null ? _backupInfo_backups_BackupLocation_DELEGATED_length : 0) > 0;
+};
+
+/**
+ * Queue manager for wallet operations.
+ * Manages heavy operation queues (refresh/reshare/recover) and sign queues per wallet.
+ */ class WalletQueueManager {
+    /**
+   * Get or create the heavy operation queue for a wallet.
+   * Heavy operations (refresh/reshare/recover) run with concurrency=1.
+   */ static getHeavyOpQueue(accountAddress) {
+        if (!this.heavyOpQueues.has(accountAddress)) {
+            const queue = new PQueue({
+                concurrency: 1,
+                timeout: 20000
+            });
+            queue.on('error', (error)=>{
+                logger.error('[WalletQueueManager] Heavy operation queue error', {
+                    accountAddress,
+                    error: error instanceof Error ? error.message : error
+                });
+            });
+            this.heavyOpQueues.set(accountAddress, queue);
+        }
+        return this.heavyOpQueues.get(accountAddress);
+    }
+    /**
+   * Get or create the sign queue for a wallet.
+   * Sign operations run with unlimited concurrency (they're read-only on key shares).
+   */ static getSignQueue(accountAddress) {
+        if (!this.signQueues.has(accountAddress)) {
+            const queue = new PQueue({
+                concurrency: Infinity,
+                timeout: 20000
+            });
+            queue.on('error', (error)=>{
+                logger.error('[WalletQueueManager] Sign queue error', {
+                    accountAddress,
+                    error: error instanceof Error ? error.message : error
+                });
+            });
+            this.signQueues.set(accountAddress, queue);
+        }
+        return this.signQueues.get(accountAddress);
+    }
+    /**
+   * Check if wallet has heavy operations in progress
+   */ static isHeavyOpInProgress(accountAddress) {
+        const queue = this.heavyOpQueues.get(accountAddress);
+        return queue ? queue.size > 0 || queue.pending > 0 : false;
+    }
+    /**
+   * Check if wallet has operations in any queue (heavy or sign)
+   */ static isWalletBusy(accountAddress) {
+        const heavyQueue = this.heavyOpQueues.get(accountAddress);
+        const signQueue = this.signQueues.get(accountAddress);
+        const heavyBusy = heavyQueue ? heavyQueue.size > 0 || heavyQueue.pending > 0 : false;
+        const signBusy = signQueue ? signQueue.size > 0 || signQueue.pending > 0 : false;
+        return heavyBusy || signBusy;
+    }
+    /**
+   * Check if recovery is in progress for a wallet
+   */ static isRecoveryInProgress(accountAddress) {
+        return this.pendingRecoveryPromises.has(accountAddress);
+    }
+    /**
+   * Get existing pending recovery promise if one exists
+   */ static getPendingRecoveryPromise(accountAddress) {
+        return this.pendingRecoveryPromises.get(accountAddress);
+    }
+    /**
+   * Track a pending recovery promise
+   */ static setPendingRecoveryPromise(accountAddress, promise) {
+        this.pendingRecoveryPromises.set(accountAddress, promise);
+    }
+    /**
+   * Clear pending recovery promise for a wallet
+   */ static clearPendingRecoveryPromise(accountAddress) {
+        this.pendingRecoveryPromises.delete(accountAddress);
+    }
+    /**
+   * Queue a heavy operation with type validation.
+   * Ensures only valid heavy operations (REFRESH, RESHARE, RECOVER) can be queued.
+   * Waits for sign operations to complete before executing.
+   *
+   * @param accountAddress - The wallet address
+   * @param operation - The operation type (must be a valid HeavyQueueOperation)
+   * @param callback - The operation to execute
+   * @throws Error if operation is not a valid heavy queue operation
+   */ static async queueHeavyOperation(accountAddress, operation, callback) {
+        // Runtime validation to catch any type assertion bypasses
+        if (!isHeavyQueueOperation(operation)) {
+            throw new Error(`Invalid heavy queue operation: ${operation}. Must be REFRESH, RESHARE, or RECOVER.`);
+        }
+        const heavyQueue = this.getHeavyOpQueue(accountAddress);
+        const signQueue = this.getSignQueue(accountAddress);
+        // Wait for any in-progress sign operations to complete
+        await signQueue.onIdle();
+        // Add to heavy queue - will wait if other heavy operations are in progress
+        return heavyQueue.add(async ()=>{
+            this.walletsWithActiveHeavyOp.set(accountAddress, true);
+            try {
+                return await callback();
+            } finally{
+                this.walletsWithActiveHeavyOp.delete(accountAddress);
+            }
+        });
+    }
+    /**
+   * Queue a sign operation with type validation.
+   * Ensures only valid sign operations (SIGN_MESSAGE, SIGN_TRANSACTION) can be queued.
+   * Waits for heavy operations to complete before executing.
+   * Allows concurrent sign operations.
+   *
+   * @param accountAddress - The wallet address
+   * @param operation - The operation type (must be a valid SignQueueOperation)
+   * @param callback - The sign operation to execute
+   * @throws Error if operation is not a valid sign queue operation
+   * @returns Promise resolving to the sign result
+   */ static async queueSignOperation(accountAddress, operation, callback) {
+        // Runtime validation to catch any type assertion bypasses
+        if (!isSignQueueOperation(operation)) {
+            throw new Error(`Invalid sign queue operation: ${operation}. Must be SIGN_MESSAGE or SIGN_TRANSACTION.`);
+        }
+        const heavyQueue = this.getHeavyOpQueue(accountAddress);
+        const signQueue = this.getSignQueue(accountAddress);
+        // Wait for any running heavy operations to complete before signing.
+        // This prevents signing with stale key shares during refresh/reshare/recover.
+        // Note: There's a small race window between this check and adding to signQueue,
+        // but if a collision occurs, the MPC protocol will detect the public key mismatch
+        // and our recovery handler will automatically retry with fresh key shares.
+        if (heavyQueue.pending > 0 || heavyQueue.size > 0) {
+            await heavyQueue.onIdle();
+        }
+        // Add to sign queue - allows concurrent signing
+        return signQueue.add(async ()=>{
+            this.walletsWithActiveSignOp.set(accountAddress, true);
+            try {
+                return await callback();
+            } finally{
+                this.walletsWithActiveSignOp.delete(accountAddress);
+            }
+        });
+    }
+    /**
+   * Queue a recovery operation with deduplication and type validation.
+   * If a recovery is already in progress for the wallet, returns that promise.
+   * If called from within a heavy operation, executes directly to avoid deadlock.
+   *
+   * @param accountAddress - The wallet address
+   * @param operation - The operation type (must be RECOVER)
+   * @param callback - The recovery operation to execute
+   * @throws Error if operation is not a valid recover queue operation
+   * @returns Promise resolving to the recovery result
+   */ static async queueRecoverOperation(accountAddress, operation, callback) {
+        // Runtime validation to catch any type assertion bypasses
+        if (!isRecoverQueueOperation(operation)) {
+            throw new Error(`Invalid recover queue operation: ${operation}. Must be RECOVER.`);
+        }
+        // Deduplication: if recovery already in progress, return that promise
+        const existing = this.getPendingRecoveryPromise(accountAddress);
+        if (existing) {
+            logger.debug(`[WalletQueueManager] Recovery already in progress for ${accountAddress}, returning existing promise`);
+            return existing;
+        }
+        // If we're already inside a heavy or sign operation for this wallet, execute directly
+        // to avoid deadlock (heavy queue has concurrency=1, sign queue waits for idle)
+        if (this.walletsWithActiveHeavyOp.get(accountAddress) || this.walletsWithActiveSignOp.get(accountAddress)) {
+            logger.debug(`[WalletQueueManager] Recovery called from within active op for ${accountAddress}, executing directly`);
+            const directPromise = (async ()=>{
+                try {
+                    return await callback();
+                } finally{
+                    this.clearPendingRecoveryPromise(accountAddress);
+                }
+            })();
+            this.setPendingRecoveryPromise(accountAddress, directPromise);
+            return directPromise;
+        }
+        const heavyQueue = this.getHeavyOpQueue(accountAddress);
+        const signQueue = this.getSignQueue(accountAddress);
+        // Create promise and track it
+        const recoveryPromise = (async ()=>{
+            // Wait for any in-progress sign operations to complete
+            await signQueue.onIdle();
+            // Add to heavy queue - will wait if other heavy operations are in progress
+            return heavyQueue.add(async ()=>{
+                try {
+                    return await callback();
+                } finally{
+                    // Clean up tracking when done
+                    this.clearPendingRecoveryPromise(accountAddress);
+                }
+            });
+        })();
+        // Track this recovery
+        this.setPendingRecoveryPromise(accountAddress, recoveryPromise);
+        return recoveryPromise;
+    }
+    /**
+   * Reset static state for testing purposes.
+   * This clears all wallet queues and pending recovery promises.
+   */ static resetForTesting() {
+        this.heavyOpQueues.clear();
+        this.signQueues.clear();
+        this.pendingRecoveryPromises.clear();
+        this.walletsWithActiveHeavyOp.clear();
+        this.walletsWithActiveSignOp.clear();
+    }
+}
+/** Heavy operation queues per wallet address. These run with concurrency=1. */ WalletQueueManager.heavyOpQueues = new Map();
+/** Sign queues per wallet address. These allow concurrent operations. */ WalletQueueManager.signQueues = new Map();
+/** Track pending recovery promises for deduplication */ WalletQueueManager.pendingRecoveryPromises = new Map();
+/** Track which wallets are currently executing inside a heavy operation.
+   * Used to prevent deadlocks when recovery is called from within a heavy op. */ WalletQueueManager.walletsWithActiveHeavyOp = new Map();
+/** Track which wallets are currently executing inside a sign operation.
+   * Used to prevent deadlocks when recovery is called from within a sign op. */ WalletQueueManager.walletsWithActiveSignOp = new Map();
+
 const ALG_LABEL_RSA = 'HYBRID-RSA-AES-256';
 /**
  * Convert base64 to base64url encoding
@@ -1231,99 +1593,6 @@ const localStorageWriteTest = {
         }
     });
 
-class WalletNotReadyError extends Error {
-    constructor(accountAddress, walletReadyState){
-        super(`Wallet ${accountAddress} is not ready and requires password to be unlocked`);
-        this.name = 'WalletNotReadyError';
-        this.accountAddress = accountAddress;
-        this.walletReadyState = walletReadyState;
-    }
-}
-class WalletBusyError extends Error {
-    constructor(accountAddress, operation){
-        super(`Wallet ${accountAddress} is currently performing a ${operation} operation`);
-        this.name = 'WalletBusyError';
-        this.operation = operation;
-        this.accountAddress = accountAddress;
-    }
-}
-/**
- * Creates distribution where shares go to specified cloud providers
- * Last share goes to cloud providers, rest to Dynamic backend
- * @param providers - Array of cloud providers to backup to
- * @param allShares - All key shares to distribute
- */ const createCloudProviderDistribution = ({ providers, allShares })=>{
-    const cloudProviderShares = {};
-    // Last share goes to cloud providers, rest to Dynamic
-    const sharesForCloud = allShares.slice(-1);
-    providers.forEach((provider)=>{
-        cloudProviderShares[provider] = sharesForCloud;
-    });
-    return {
-        clientShares: allShares.slice(0, -1),
-        cloudProviderShares
-    };
-};
-/**
- * Creates distribution with delegation + cloud backup
- * Client shares backed up to Dynamic AND cloud providers
- * Delegated share goes to webhook
- */ const createDelegationWithCloudProviderDistribution = ({ providers, existingShares, delegatedShare })=>{
-    const cloudProviderShares = {};
-    providers.forEach((provider)=>{
-        cloudProviderShares[provider] = existingShares;
-    });
-    return {
-        clientShares: existingShares,
-        cloudProviderShares,
-        delegatedShare
-    };
-};
-/**
- * Creates distribution for adding cloud backup to existing delegation
- * Client shares go to both Dynamic AND cloud providers
- * delegatedShare is undefined - we don't re-publish, but preserve the location
- */ const createAddCloudProviderToExistingDelegationDistribution = ({ providers, clientShares })=>{
-    const cloudProviderShares = {};
-    providers.forEach((provider)=>{
-        cloudProviderShares[provider] = clientShares;
-    });
-    return {
-        clientShares,
-        cloudProviderShares
-    };
-};
-/**
- * Checks if wallet has backup on any of the specified providers
- */ const hasCloudProviderBackup = (backupInfo, providers)=>{
-    if (!(backupInfo == null ? void 0 : backupInfo.backups)) return false;
-    return providers.some((provider)=>{
-        var _backupInfo_backups_provider;
-        var _backupInfo_backups_provider_length;
-        return ((_backupInfo_backups_provider_length = (_backupInfo_backups_provider = backupInfo.backups[provider]) == null ? void 0 : _backupInfo_backups_provider.length) != null ? _backupInfo_backups_provider_length : 0) > 0;
-    });
-};
-/**
- * Gets all cloud providers that have backups for this wallet
- */ const getActiveCloudProviders = (backupInfo)=>{
-    if (!(backupInfo == null ? void 0 : backupInfo.backups)) return [];
-    return Object.entries(backupInfo.backups).filter(([location, backups])=>location !== core.BackupLocation.DYNAMIC && location !== core.BackupLocation.DELEGATED && backups.length > 0).map(([location])=>location);
-};
-const createDelegationOnlyDistribution = ({ existingShares, delegatedShare })=>({
-        clientShares: existingShares,
-        cloudProviderShares: {},
-        delegatedShare
-    });
-const createDynamicOnlyDistribution = ({ allShares })=>({
-        clientShares: allShares,
-        cloudProviderShares: {}
-    });
-const hasDelegatedBackup = (backupInfo)=>{
-    var _backupInfo_backups_BackupLocation_DELEGATED, _backupInfo_backups;
-    var _backupInfo_backups_BackupLocation_DELEGATED_length;
-    return ((_backupInfo_backups_BackupLocation_DELEGATED_length = backupInfo == null ? void 0 : (_backupInfo_backups = backupInfo.backups) == null ? void 0 : (_backupInfo_backups_BackupLocation_DELEGATED = _backupInfo_backups[core.BackupLocation.DELEGATED]) == null ? void 0 : _backupInfo_backups_BackupLocation_DELEGATED.length) != null ? _backupInfo_backups_BackupLocation_DELEGATED_length : 0) > 0;
-};
-
 /**
  * Determines the recovery state of a wallet based on backup info and local shares.
  *
@@ -1376,48 +1645,27 @@ class DynamicWalletClient {
             });
         }
     }
-    getWalletBusyOperation(accountAddress) {
-        return DynamicWalletClient.walletBusyMap[accountAddress];
+    /**
+   * Check if wallet has heavy operations in progress
+   */ static isHeavyOpInProgress(accountAddress) {
+        return WalletQueueManager.isHeavyOpInProgress(accountAddress);
     }
-    isWalletBusy(accountAddress) {
-        return DynamicWalletClient.walletBusyMap[accountAddress] !== undefined;
+    /**
+   * Check if wallet has operations in any queue (heavy or sign)
+   */ static isWalletBusy(accountAddress) {
+        return WalletQueueManager.isWalletBusy(accountAddress);
     }
-    async waitForWalletNotBusy(accountAddress) {
-        const busyPromise = DynamicWalletClient.walletBusyPromiseMap[accountAddress];
-        if (!busyPromise) {
-            return;
-        }
-        const currentOperation = DynamicWalletClient.walletBusyMap[accountAddress];
-        this.logger.debug(`[DynamicWaasWalletClient] Waiting for wallet ${accountAddress} to complete ${currentOperation} operation`);
-        try {
-            await busyPromise;
-        } catch (e) {
-            // Intentionally swallowing the error - we proceed with the queued operation regardless of whether the previous one succeeded or failed
-            this.logger.debug(`[DynamicWaasWalletClient] Previous ${currentOperation} operation on wallet ${accountAddress} failed, proceeding with queued operation`);
-        }
+    /**
+   * Check if recovery is in progress for a wallet
+   */ static isRecoveryInProgress(accountAddress) {
+        return WalletQueueManager.isRecoveryInProgress(accountAddress);
     }
-    async withWalletBusyLock({ accountAddress, operation, fn, timeoutMs = WALLET_BUSY_LOCK_TIMEOUT_MS }) {
-        const existingOperation = DynamicWalletClient.walletBusyMap[accountAddress];
-        if (existingOperation) {
-            throw new WalletBusyError(accountAddress, existingOperation);
-        }
-        DynamicWalletClient.walletBusyMap[accountAddress] = operation;
-        const executionPromise = (async ()=>{
-            try {
-                return await Promise.race([
-                    fn(),
-                    timeoutPromise({
-                        timeInMs: timeoutMs,
-                        activity: `${operation} operation`
-                    })
-                ]);
-            } finally{
-                delete DynamicWalletClient.walletBusyMap[accountAddress];
-                delete DynamicWalletClient.walletBusyPromiseMap[accountAddress];
-            }
-        })();
-        DynamicWalletClient.walletBusyPromiseMap[accountAddress] = executionPromise.then(()=>undefined, ()=>undefined);
-        return executionPromise;
+    /**
+   * Reset static state for testing purposes.
+   * This clears all wallet queues and in-flight recovery tracking.
+   * @internal For testing only
+   */ static resetStaticState() {
+        WalletQueueManager.resetForTesting();
     }
     getAuthMode() {
         return this.authMode;
@@ -1938,7 +2186,8 @@ class DynamicWalletClient {
             dynamicRequestId
         }, this.getTraceContext(traceContext)));
         // Recover key shares from backup (don't auto-store, we'll overwrite below)
-        const recoveredKeyShares = await this.recoverEncryptedBackupByWallet({
+        // Use internal method directly to bypass queueing - we're already inside a queued operation
+        const recoveredKeyShares = await this.internalRecoverEncryptedBackupByWallet({
             accountAddress,
             password: password != null ? password : this.environmentId,
             walletOperation,
@@ -1961,24 +2210,23 @@ class DynamicWalletClient {
     }
     //todo: need to modify with imported flag
     async sign({ accountAddress, message, chainName, password = undefined, isFormatted = false, signedSessionId, mfaToken, context, onError, traceContext, bitcoinConfig }) {
-        return this.internalSign({
-            accountAddress,
-            message,
-            chainName,
-            password,
-            isFormatted,
-            signedSessionId,
-            mfaToken,
-            context,
-            onError,
-            traceContext,
-            bitcoinConfig
-        });
+        return WalletQueueManager.queueSignOperation(accountAddress, core.WalletOperation.SIGN_MESSAGE, ()=>this.internalSign({
+                accountAddress,
+                message,
+                chainName,
+                password,
+                isFormatted,
+                signedSessionId,
+                mfaToken,
+                context,
+                onError,
+                traceContext,
+                bitcoinConfig
+            }));
     }
     async internalSign({ accountAddress, message, chainName, password = undefined, isFormatted = false, signedSessionId, mfaToken, context, onError, traceContext, bitcoinConfig, hasAttemptedKeyShareRecovery = false }) {
         const dynamicRequestId = uuid.v4();
         try {
-            await this.waitForWalletNotBusy(accountAddress);
             await this.verifyPassword({
                 accountAddress,
                 password,
@@ -2103,18 +2351,29 @@ class DynamicWalletClient {
         }
     }
     async refreshWalletAccountShares({ accountAddress, chainName, password = undefined, signedSessionId, mfaToken, traceContext }) {
-        return this.withWalletBusyLock({
-            accountAddress,
-            operation: core.WalletOperation.REFRESH,
-            fn: ()=>this.internalRefreshWalletAccountShares({
-                    accountAddress,
-                    chainName,
-                    password,
-                    signedSessionId,
-                    mfaToken,
-                    traceContext
-                })
-        });
+        return WalletQueueManager.queueHeavyOperation(accountAddress, core.WalletOperation.REFRESH, ()=>this.internalRefreshWalletAccountShares({
+                accountAddress,
+                chainName,
+                password,
+                signedSessionId,
+                mfaToken,
+                traceContext
+            }));
+    }
+    /**
+   * Gets the Bitcoin config for MPC operations by looking up addressType
+   * from walletMap, with fallback to deriving it from derivationPath.
+   */ getBitcoinConfigForChain(chainName, accountAddress) {
+        if (chainName !== 'BTC') return undefined;
+        const walletProperties = this.walletMap[accountAddress];
+        let addressType = walletProperties == null ? void 0 : walletProperties.addressType;
+        // Fallback: derive addressType from derivationPath if not explicitly set
+        if (!addressType && (walletProperties == null ? void 0 : walletProperties.derivationPath)) {
+            addressType = getBitcoinAddressTypeFromDerivationPath(walletProperties.derivationPath);
+        }
+        return addressType ? {
+            addressType: addressType
+        } : undefined;
     }
     async internalRefreshWalletAccountShares({ accountAddress, chainName, password = undefined, signedSessionId, mfaToken, traceContext, hasAttemptedKeyShareRecovery = false }) {
         const dynamicRequestId = uuid.v4();
@@ -2131,13 +2390,7 @@ class DynamicWalletClient {
                 password,
                 signedSessionId
             });
-            const walletProperties = this.walletMap[accountAddress];
-            let bitcoinConfig;
-            if (chainName === 'BTC' && (walletProperties == null ? void 0 : walletProperties.addressType)) {
-                bitcoinConfig = {
-                    addressType: walletProperties.addressType
-                };
-            }
+            const bitcoinConfig = this.getBitcoinConfigForChain(chainName, accountAddress);
             const mpcSigner = getMPCSigner({
                 chainName,
                 baseRelayUrl: this.baseMPCRelayApiUrl,
@@ -2281,22 +2534,18 @@ class DynamicWalletClient {
         };
     }
     async reshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, cloudProviders = [], delegateToProjectEnvironment = false, mfaToken, revokeDelegation = false }) {
-        return this.withWalletBusyLock({
-            accountAddress,
-            operation: core.WalletOperation.RESHARE,
-            fn: ()=>this.internalReshare({
-                    chainName,
-                    accountAddress,
-                    oldThresholdSignatureScheme,
-                    newThresholdSignatureScheme,
-                    password,
-                    signedSessionId,
-                    cloudProviders,
-                    delegateToProjectEnvironment,
-                    mfaToken,
-                    revokeDelegation
-                })
-        });
+        return WalletQueueManager.queueHeavyOperation(accountAddress, core.WalletOperation.RESHARE, ()=>this.internalReshare({
+                chainName,
+                accountAddress,
+                oldThresholdSignatureScheme,
+                newThresholdSignatureScheme,
+                password,
+                signedSessionId,
+                cloudProviders,
+                delegateToProjectEnvironment,
+                mfaToken,
+                revokeDelegation
+            }));
     }
     async internalReshare({ chainName, accountAddress, oldThresholdSignatureScheme, newThresholdSignatureScheme, password = undefined, signedSessionId, cloudProviders = [], delegateToProjectEnvironment = false, mfaToken, revokeDelegation = false, hasAttemptedKeyShareRecovery = false }) {
         const dynamicRequestId = uuid.v4();
@@ -2353,13 +2602,7 @@ class DynamicWalletClient {
                 ...serverKeygenIds,
                 ...newServerKeygenIds
             ];
-            const walletProperties = this.walletMap[accountAddress];
-            let bitcoinConfig;
-            if (chainName === 'BTC' && (walletProperties == null ? void 0 : walletProperties.addressType)) {
-                bitcoinConfig = {
-                    addressType: walletProperties.addressType
-                };
-            }
+            const bitcoinConfig = this.getBitcoinConfigForChain(chainName, accountAddress);
             const mpcSigner = getMPCSigner({
                 chainName,
                 baseRelayUrl: this.baseMPCRelayApiUrl,
@@ -2851,7 +3094,10 @@ class DynamicWalletClient {
     /**
    * Ensures that client key shares exist for the given account address.
    * Throws an error if no shares are found.
-   * This method enforces share presence before sensitive operations.
+   *
+   * Note: This method only checks for existing shares in storage.
+   * Auto-recovery logic has been removed in favor of the queue pattern.
+   * Callers should handle recovery explicitly if needed.
    */ async ensureClientShare(accountAddress) {
         const shares = await this.getClientKeySharesFromStorage({
             accountAddress
@@ -3178,6 +3424,17 @@ class DynamicWalletClient {
         };
     }
     async recoverEncryptedBackupByWallet({ accountAddress, password, walletOperation, signedSessionId, shareCount = undefined, storeRecoveredShares = true, mfaToken }) {
+        return WalletQueueManager.queueRecoverOperation(accountAddress, core.WalletOperation.RECOVER, ()=>this.internalRecoverEncryptedBackupByWallet({
+                accountAddress,
+                password,
+                walletOperation,
+                signedSessionId,
+                shareCount,
+                storeRecoveredShares,
+                mfaToken
+            }));
+    }
+    async internalRecoverEncryptedBackupByWallet({ accountAddress, password, walletOperation, signedSessionId, shareCount = undefined, storeRecoveredShares = true, mfaToken }) {
         try {
             const wallet = this.walletMap[accountAddress];
             this.logger.debug(`recoverEncryptedBackupByWallet wallet: ${walletOperation}`, wallet);
@@ -3777,20 +4034,55 @@ class DynamicWalletClient {
         }
     }
     /**
-   * Gets the recovery state of a wallet without attempting to decrypt shares.
+   * Gets the recovery state of a wallet, optionally recovering shares if not available.
    * This method is useful for detecting if a wallet is password-encrypted
    * and needs unlocking before use.
    *
+   * If shares are not available locally and recovery parameters are provided,
+   * this method will call getWallet with RECOVER operation to fetch shares.
+   * The underlying recoverEncryptedBackupByWallet handles deduplication via
+   * inFlightRecovery, so concurrent calls won't start multiple recoveries.
+   *
    * @param accountAddress - The account address of the wallet
+   * @param signedSessionId - Optional signed session ID for triggering recovery if shares not available
+   * @param password - Optional password for decrypting recovered shares
    * @returns WalletRecoveryState indicating the wallet's lock state and share availability
-   */ async getWalletRecoveryState({ accountAddress }) {
+   * @throws Error if recovery fails or no shares available after recovery
+   */ async getWalletRecoveryState({ accountAddress, signedSessionId, password }) {
         const walletData = this.walletMap[accountAddress];
         if (!walletData) {
             throw new Error(`Wallet not found for address: ${accountAddress}`);
         }
-        const clientKeyShares = await this.getClientKeySharesFromStorage({
+        let clientKeyShares = await this.getClientKeySharesFromStorage({
             accountAddress
         });
+        // If no local shares and signedSessionId provided, trigger recovery via getWallet
+        // getWallet -> recoverEncryptedBackupByWallet handles deduplication via inFlightRecovery
+        if (clientKeyShares.length === 0 && signedSessionId) {
+            var _walletData_clientKeySharesBackupInfo;
+            await this.getWallet({
+                accountAddress,
+                walletOperation: core.WalletOperation.RECOVER,
+                signedSessionId,
+                password
+            });
+            // Re-fetch shares after recovery
+            clientKeyShares = await this.getClientKeySharesFromStorage({
+                accountAddress
+            });
+            var _walletData_clientKeySharesBackupInfo_passwordEncrypted;
+            // For password-encrypted wallets, also check for cached encrypted shares
+            const isPasswordEncrypted = (_walletData_clientKeySharesBackupInfo_passwordEncrypted = (_walletData_clientKeySharesBackupInfo = walletData.clientKeySharesBackupInfo) == null ? void 0 : _walletData_clientKeySharesBackupInfo.passwordEncrypted) != null ? _walletData_clientKeySharesBackupInfo_passwordEncrypted : false;
+            let hasEncryptedShares = false;
+            if (isPasswordEncrypted && clientKeyShares.length === 0) {
+                const encryptedStorageKey = `${accountAddress}${core.ENCRYPTED_SHARES_STORAGE_SUFFIX}`;
+                const encryptedData = await this.storage.getItem(encryptedStorageKey);
+                hasEncryptedShares = !!encryptedData;
+            }
+            if (clientKeyShares.length === 0 && !hasEncryptedShares) {
+                throw new Error(`No key shares available for wallet ${accountAddress} after recovery`);
+            }
+        }
         return determineWalletRecoveryState({
             clientKeySharesBackupInfo: walletData.clientKeySharesBackupInfo,
             hasLocalShares: clientKeyShares.length > 0
@@ -4086,8 +4378,6 @@ class DynamicWalletClient {
 }
 DynamicWalletClient.rooms = {};
 DynamicWalletClient.roomsInitializing = {};
-DynamicWalletClient.walletBusyMap = {};
-DynamicWalletClient.walletBusyPromiseMap = {};
 
 Object.defineProperty(exports, "BIP340", {
     enumerable: true,
@@ -4152,6 +4442,9 @@ exports.ERROR_SIGN_MESSAGE = ERROR_SIGN_MESSAGE;
 exports.ERROR_SIGN_TYPED_DATA = ERROR_SIGN_TYPED_DATA;
 exports.ERROR_VERIFY_MESSAGE_SIGNATURE = ERROR_VERIFY_MESSAGE_SIGNATURE;
 exports.ERROR_VERIFY_TRANSACTION_SIGNATURE = ERROR_VERIFY_TRANSACTION_SIGNATURE;
+exports.HEAVY_QUEUE_OPERATIONS = HEAVY_QUEUE_OPERATIONS;
+exports.RECOVER_QUEUE_OPERATIONS = RECOVER_QUEUE_OPERATIONS;
+exports.SIGN_QUEUE_OPERATIONS = SIGN_QUEUE_OPERATIONS;
 exports.WalletBusyError = WalletBusyError;
 exports.WalletNotReadyError = WalletNotReadyError;
 exports.cancelICloudAuth = cancelICloudAuth;
@@ -4167,6 +4460,7 @@ exports.extractPubkey = extractPubkey;
 exports.formatEvmMessage = formatEvmMessage;
 exports.formatMessage = formatMessage;
 exports.getActiveCloudProviders = getActiveCloudProviders;
+exports.getBitcoinAddressTypeFromDerivationPath = getBitcoinAddressTypeFromDerivationPath;
 exports.getClientKeyShareBackupInfo = getClientKeyShareBackupInfo;
 exports.getClientKeyShareExportFileName = getClientKeyShareExportFileName;
 exports.getGoogleOAuthAccountId = getGoogleOAuthAccountId;
@@ -4177,9 +4471,12 @@ exports.hasCloudProviderBackup = hasCloudProviderBackup;
 exports.hasDelegatedBackup = hasDelegatedBackup;
 exports.initializeCloudKit = initializeCloudKit;
 exports.isBrowser = isBrowser;
+exports.isHeavyQueueOperation = isHeavyQueueOperation;
 exports.isHexString = isHexString;
 exports.isICloudAuthenticated = isICloudAuthenticated;
 exports.isPublicKeyMismatchError = isPublicKeyMismatchError;
+exports.isRecoverQueueOperation = isRecoverQueueOperation;
+exports.isSignQueueOperation = isSignQueueOperation;
 exports.listICloudBackups = listICloudBackups;
 exports.mergeUniqueKeyShares = mergeUniqueKeyShares;
 exports.retryPromise = retryPromise;